Documentation

Send a message to Vox, create a new session if needed

POST
/api/v1/external/vox/run

Scope requis : write:vox.

AutorisationBearer <jeton>

JWT d'organisation obtenu via le flow OIDC. Voir le guide d'intégration.

Dans: header

Corps de requête

application/json

Définitions TypeScript

Utilisez le type request body en TypeScript.

prompt*string

The message to send to Vox

sessionId?string

Existing session to continue, a new one is created when omitted

agentIds?array<string>|

Agents Vox is allowed to delegate to

stream*boolean

Stream the answer as server-sent events

attachmentIds?array<string>
fileIds?array<string>
folderIds?array<string>
integrationIds?array<string>
temporarySession?boolean

Do not persist the session

allowBonusOrbsUse*boolean

Allow the run to consume bonus orbs when free orbs are exhausted

Défautfalse
timezone?string

Corps de réponse

application/json

curl -X POST "https://example.com/api/v1/external/vox/run" \  -H "Content-Type: application/json" \  -d '{    "prompt": "string",    "stream": true,    "allowBonusOrbsUse": false  }'
{  "run_id": "d8230914-a244-4444-ad8b-bcd6a8e6ebe7",  "team_id": "vox-team",  "team_name": "Vox",  "session_id": "hello",  "parent_run_id": null,  "user_id": "q55sdliutspa",  "input": {    "input_content": "what is in this image ?",    "images": [      {        "url": "https://minio.dev2.dev-id.fr/oreus/sessions/q55sdliutspa/attachment-1769090974450?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=FDpYtzB8giHfC3clP9SS%2F20260122%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260122T145219Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=6245dc87449edce615e13a71862481e5bd0fbabe6d57787eadb5469ec32c656c",        "filepath": null,        "content": null,        "id": "69722f9f207f36a576652bf2",        "format": null,        "mime_type": null,        "detail": null,        "original_prompt": null,        "revised_prompt": null,        "alt_text": null      }    ],    "videos": null,    "audios": null,    "files": null  },  "content": "The image displays the grand interior of a large, historic train station hall. The space is defined by its impressive scale and architectural details:\n\n*   **Architecture:** The dominant feature is a series of massive, symmetrical arches that stretch across the length of the hall. These arches frame large, arched windows at the top, allowing natural light to illuminate the space from above. Below these are smaller, matching arches that contain dark, glass-paneled doors.\n*   **Lighting and Atmosphere:** The lighting creates a dramatic contrast. Bright sunlight streams through the high windows, casting strong diagonal shadows across the polished stone floor. This leaves much of the hall in deep shadow, creating a moody and atmospheric scene.\n*   **People:** Several people can be seen moving through the hall. They appear as silhouettes or figures with motion blur, suggesting they are walking past the camera during a long-exposure photograph.\n*   **Details:** Ornate clocks are visible on the pillars between the main arches, and decorative elements like small lanterns hang along the walls.\n\nOverall, the image captures the majestic and spacious feeling of a 19th-century railway station.",  "content_type": "str",  "messages": [    {      "id": "b9996c1f-e055-4dad-bd73-a55c41f63bfe",      "role": "system",      "content": "You are the leader of a team and sub-teams of AI Agents.\nYour task is to coordinate the team to complete the user's request.\n\nHere are the members in your team:\n<team_members>\n</team_members>\n\n<how_to_respond>\n- Your role is to delegate tasks to members in your team with the highest likelihood of completing the user's request.\n- Carefully analyze the tools available to the members and their roles before delegating tasks.\n- You cannot use a member tool directly. You can only delegate tasks to members.\n- When you delegate a task to another member, make sure to include:\n  - member_id (str): The ID of the member to delegate the task to. Use only the ID of the member, not the ID of the team followed by the ID of the member.\n  - task (str): A clear description of the task.\n- You can delegate tasks to multiple members at once.\n- You must always analyze the responses from members before responding to the user.\n- After analyzing the responses from the members, if you feel the task has been completed, you can stop and respond to the user.\n- If you are not satisfied with the responses from the members, you should re-assign the task.\n- For simple greetings, thanks, or questions about the team itself, you should respond directly.\n- For all work requests, tasks, or questions requiring expertise, route to appropriate team members.\n</how_to_respond>\n\n<attached_media>\nYou have the following media attached to your message:\n - Images\n</attached_media>\n\n<description>\nVox is the intelligent orchestrator that leads conversations across multiple agents and organization-specific teams. It analyzes requests, delegates strategically, and synthesizes responses from diverse sources.\n</description>\n\n<instructions>\n- You are Vox, the orchestration intelligence leading this team. Your role is to understand user intent, route requests optimally, and deliver cohesive responses.\n- When you receive an EXECUTION PLAN, follow it exactly.\n- Delegate tasks in order, respecting dependencies.\n- For parallel tasks (no dependencies), delegate concurrently.\n- \n- ## User Context\n- \n- Current user: {'name': 'John Doe', 'preferences': {'communication_style': 'professional', 'topics_of_interest': ['AI/ML', 'Software Engineering', 'Finance'], 'experience_level': 'senior'}, 'location': 'San Francisco, CA', 'role': 'Senior Software Engineer', 'organization': 'Oreus'}\n- Current context: {'current_time': '2026-01-22 15:51:44', 'timezone': 'PST', 'day_of_week': 'Thursday'}\n- \n- Use this context to personalize responses and make informed delegation decisions.\n- \n- ## Delegation Priority Rule (CRITICAL)\n- \n- **Before responding to ANY request, check your available members.**\n- \n- Each member has a `name`, `description`, and defined specialty. If a member's specialty matches the task → **DELEGATE. Always.**\n- \n- You are an **orchestrator, not an executor**. Even if you have tools that *could* do the job, specialists have optimized prompts and domain context you lack.\n- \n- **Only handle directly when:**\n- 1. It's purely conversational (greetings, meta-questions about yourself)\n- 2. It's general knowledge requiring NO tools\n- 3. **No member's specialty matches the request**\n- \n- When in doubt: **delegate > do it yourself**\n- \n- ## Core Principles\n- \n- 1. **Delegate-First**: If a member can do it, they should. Your job is orchestration, not execution.\n- 2. **User-First**: Every decision serves the user's actual need. Consider their role, preferences, and experience level.\n- 3. **Synthesis**: When delegating, integrate responses into a coherent whole, not just relay them.\n- \n- ## Decision Framework\n- \n- ### Step 1: Check Members First\n- \n- Before acting, scan your available members' descriptions. Ask: **Does any member specialize in this?**\n- \n- | Type | Signal | Action |\n- |------|--------|--------|\n- | **Member Specialty Match** | Any member's description matches the task | **DELEGATE immediately** |\n- | **Conversational** | Greetings, clarifications, meta-questions | Respond directly |\n- | **General Knowledge** | Simple facts, NO tools needed | Respond directly |\n- | **Cross-Domain** | Multiple members needed | Coordinate parallel delegations |\n- | **No Match + Tools Needed** | No specialist exists but requires tools | Use your tools as fallback |\n- | **Ambiguous** | Unclear which member or unclear intent | Ask one clarifying question |\n- \n- ### Step 2: Select Delegation Target\n- \n- When delegation is needed, match based on member descriptions:\n- \n- - **Single Agent**: When one member's specialty clearly matches\n- - **Team**: When the task requires coordinated effort within an organization's context\n- - **Multiple Members**: When the task spans specialties or needs diverse perspectives\n- \n- ### Step 3: Delegate Effectively\n- \n- When delegating:\n- \n- 1. **Frame the task clearly**: Provide context the delegate needs, strip what they don't.\n- 2. **Specify the output**: What format, depth, and focus do you need back?\n- 3. **Set boundaries**: If only partial information is needed, say so.\n- \n- ### Step 4: Synthesize Results\n- \n- After receiving delegated responses:\n- \n- 1. **Integrate**: Weave multiple responses into a unified answer.\n- 2. **Resolve conflicts**: If sources disagree, acknowledge it and provide your assessment.\n- 3. **Fill gaps**: Add context or transitions that make the combined response coherent.\n- 4. **Quality check**: Ensure the final response actually answers the user's question.\n- \n- ## Response Style\n- \n- - **Direct**: Lead with the answer, then elaborate.\n- - **Structured**: Use headers, lists, and formatting for complex responses.\n- - **Transparent**: When you've delegated, briefly note which team/agent contributed (if relevant to user).\n- - **Conversational**: Maintain a natural flow; don't sound like a router.\n- - **Personalized**: Adapt tone and depth based on user's experience level and communication preferences.\n- \n- ## Anti-Patterns to Avoid\n- \n- - **Self-Handling When Specialist Exists**: If a member can do it, delegate. Don't use your own tools when a specialist is available.\n- - **Under-synthesis**: Don't just concatenate team responses; integrate them.\n- - **Excessive meta-commentary**: Don't narrate your routing decisions unless asked.\n- - **Blind relay**: Never pass through a response you haven't reviewed for quality and relevance.\n- \n- ## Memory & Context\n- \n- - Track user preferences and prior interactions across the conversation.\n- - Remember which teams/agents provided useful responses for similar queries.\n- - Maintain continuity: reference earlier parts of the conversation when relevant.\n- \n- ## When Uncertain\n- \n- If you're unsure whether to delegate or which target to choose:\n- \n- 1. **Check members first**: Before doing anything yourself, ask: 'Does any member specialize in this?'\n- 2. **Lean toward delegation**: If a specialist exists, delegate even if you *could* handle it.\n- 3. **Ask if truly ambiguous**: If no clear specialist and you're unsure, clarify with the user.\n</instructions>\n\n<additional_information>\n- Use markdown to format your answers.\n</additional_information>",      "compressed_content": null,      "name": null,      "tool_call_id": null,      "tool_calls": null,      "audio": null,      "images": null,      "videos": null,      "files": null,      "audio_output": null,      "image_output": null,      "video_output": null,      "file_output": null,      "redacted_reasoning_content": null,      "provider_data": null,      "citations": null,      "reasoning_content": null,      "tool_name": null,      "tool_args": null,      "tool_call_error": null,      "stop_after_tool_call": false,      "add_to_agent_memory": true,      "from_history": false,      "metrics": {        "input_tokens": 0,        "output_tokens": 0,        "total_tokens": 0,        "cost": null,        "audio_input_tokens": 0,        "audio_output_tokens": 0,        "audio_total_tokens": 0,        "cache_read_tokens": 0,        "cache_write_tokens": 0,        "reasoning_tokens": 0,        "timer": null,        "time_to_first_token": null,        "duration": null,        "provider_metrics": null,        "additional_metrics": null      },      "references": null,      "created_at": 1769093539,      "temporary": false    },    {      "id": "19668437-81fd-47bd-8ff9-93a8b9d5eb49",      "role": "user",      "content": "what is in this image ?",      "compressed_content": null,      "name": null,      "tool_call_id": null,      "tool_calls": null,      "audio": null,      "images": [        {          "url": "https://minio.dev2.dev-id.fr/oreus/sessions/q55sdliutspa/attachment-1769090974450?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=FDpYtzB8giHfC3clP9SS%2F20260122%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260122T145219Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=6245dc87449edce615e13a71862481e5bd0fbabe6d57787eadb5469ec32c656c",          "filepath": null,          "content": null,          "id": "69722f9f207f36a576652bf2",          "format": null,          "mime_type": null,          "detail": null,          "original_prompt": null,          "revised_prompt": null,          "alt_text": null        }      ],      "videos": null,      "files": null,      "audio_output": null,      "image_output": null,      "video_output": null,      "file_output": null,      "redacted_reasoning_content": null,      "provider_data": null,      "citations": null,      "reasoning_content": null,      "tool_name": null,      "tool_args": null,      "tool_call_error": null,      "stop_after_tool_call": false,      "add_to_agent_memory": true,      "from_history": false,      "metrics": {        "input_tokens": 0,        "output_tokens": 0,        "total_tokens": 0,        "cost": null,        "audio_input_tokens": 0,        "audio_output_tokens": 0,        "audio_total_tokens": 0,        "cache_read_tokens": 0,        "cache_write_tokens": 0,        "reasoning_tokens": 0,        "timer": null,        "time_to_first_token": null,        "duration": null,        "provider_metrics": null,        "additional_metrics": null      },      "references": null,      "created_at": 1769093539,      "temporary": false,      "input": "what is in this image ?"    },    {      "id": "f72fb630-d3e8-4dc9-b3f2-7f2f8f977351",      "role": "assistant",      "content": "The image displays the grand interior of a large, historic train station hall. The space is defined by its impressive scale and architectural details:\n\n*   **Architecture:** The dominant feature is a series of massive, symmetrical arches that stretch across the length of the hall. These arches frame large, arched windows at the top, allowing natural light to illuminate the space from above. Below these are smaller, matching arches that contain dark, glass-paneled doors.\n*   **Lighting and Atmosphere:** The lighting creates a dramatic contrast. Bright sunlight streams through the high windows, casting strong diagonal shadows across the polished stone floor. This leaves much of the hall in deep shadow, creating a moody and atmospheric scene.\n*   **People:** Several people can be seen moving through the hall. They appear as silhouettes or figures with motion blur, suggesting they are walking past the camera during a long-exposure photograph.\n*   **Details:** Ornate clocks are visible on the pillars between the main arches, and decorative elements like small lanterns hang along the walls.\n\nOverall, the image captures the majestic and spacious feeling of a 19th-century railway station.",      "compressed_content": null,      "name": null,      "tool_call_id": null,      "tool_calls": null,      "audio": null,      "images": null,      "videos": null,      "files": null,      "audio_output": null,      "image_output": null,      "video_output": null,      "file_output": null,      "redacted_reasoning_content": null,      "provider_data": {        "id": "chatcmpl-6989d6405f03ecfd95d8bed617b9fcf4",        "model_extra": {          "prompt_logprobs": null,          "kv_transfer_params": null        }      },      "citations": null,      "reasoning_content": null,      "tool_name": null,      "tool_args": null,      "tool_call_error": null,      "stop_after_tool_call": false,      "add_to_agent_memory": true,      "from_history": false,      "metrics": {        "input_tokens": 14114,        "output_tokens": 239,        "total_tokens": 14353,        "cost": null,        "audio_input_tokens": 0,        "audio_output_tokens": 0,        "audio_total_tokens": 0,        "cache_read_tokens": 0,        "cache_write_tokens": 0,        "reasoning_tokens": 0,        "timer": null,        "time_to_first_token": null,        "duration": null,        "provider_metrics": null,        "additional_metrics": null      },      "references": null,      "created_at": 1769093539,      "temporary": false    }  ],  "metrics": {    "input_tokens": 14114,    "output_tokens": 239,    "total_tokens": 14353,    "cost": null,    "audio_input_tokens": 0,    "audio_output_tokens": 0,    "audio_total_tokens": 0,    "cache_read_tokens": 0,    "cache_write_tokens": 0,    "reasoning_tokens": 0,    "timer": {      "start_time": 348993.139829958,      "end_time": 348998.399561208,      "elapsed_time": 5.259731250000186    },    "time_to_first_token": 0.11074754199944437,    "duration": 5.259731250000186,    "provider_metrics": null,    "additional_metrics": null  },  "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",  "model_provider": "VLLM",  "member_responses": [],  "tools": [],  "images": null,  "videos": null,  "audio": null,  "files": null,  "response_audio": null,  "reasoning_content": null,  "citations": null,  "model_provider_data": {    "id": "chatcmpl-6989d6405f03ecfd95d8bed617b9fcf4",    "model_extra": {      "prompt_logprobs": null,      "kv_transfer_params": null    }  },  "metadata": {    "role": "orchestrator",    "version": "1.1"  },  "session_state": null,  "references": null,  "additional_input": null,  "reasoning_steps": null,  "reasoning_messages": null,  "created_at": 1769093539,  "events": null,  "status": "COMPLETED",  "requirements": null,  "workflow_step_id": null}