Overview
Multi-agent workflows enable complex task orchestration by creating teams of specialized agents that work together hierarchically. This system allows you to build sophisticated AI applications where different agents handle specific domains or functions, coordinated by an orchestrator agent.
Agents can invoke sub-agents using a hierarchical agent system:
- Orchestrator: Main agent that delegates tasks.
- Sub-agents: Specialized agents for specific functions.
- Delegation: Automatic task routing based on agent capabilities.
- Context Sharing: Shared memory and knowledge between agents.
Prerequisites
Before using sub-agents, you must:
- Create Sub-agents First: Use the Agent CRUD endpoints (
POST /v2/agents) to create the specialized agents
- Reference by key: Add the created agent keys to the
team_of_agents array in your orchestrator agent configuration
- Include Required Tools: Add
retrieve_agents and call_sub_agent tools to your orchestrator’s configuration to enable sub-agent discovery and delegation
- Define Roles: Specify each sub-agent’s role to help the orchestrator decide when to delegate.
Example
Creating Agents
We are creating two sub-agents that we will be later orchestrating through an agent run.
Calling the Create Agent endpoint to create a Youth Agent
curl -X POST https://api.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "youth-agent",
"role": "Agent specialized in talking to the younger generation until 25 years old",
"description": "An agent which is tailored to a youthful tone",
"instructions": "You are an agent who is tasked with talking to people under 25 years old and tries to match the tone that the younger generation uses in an informal, but respectful way. You use hip lingo actually and a bunch of emojis that helps they relate to you.",
"settings": {
"max_iterations": 15,
"max_execution_time": 300,
"tools": [
{
"id": "01JKG6QJ5FGHCWA7RVMMZB82QY",
"action_type": "orq_current_date"
}
]
},
"model": "openai/gpt-4o",
"path": "Default/agents"
}'
Calling the Create Agent endpoint to create a Formal Agent
curl -X POST https://api.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "formal-agent",
"role": "Agent specialized in talking to a more mature audience",
"description": "An agent which is tailored to formal communication",
"instructions": "You are a professional agent responsible for engaging with individuals under 25 years of age. Your communication should maintain a formal and respectful tone while remaining accessible to younger audiences.",
"settings": {
"max_iterations": 15,
"max_execution_time": 300,
"tools": [
{
"id": "01JKG6QJ5FGHCWA7RVMMZB82QY",
"action_type": "orq_current_date"
}
]
},
"model": "openai/gpt-4o",
"path": "Default/agents"
}'
To update an existing agent, issue a similar call using the PATCH method to an existing agent_key. e.g. PATCH /v2/agents/youth-agent . To learn more, see Updating an Agent. Orchestrating Agents
- Orchestrator agents must use the
retrieve_agents tool to discover available sub-agents before delegating tasks.
- Include instructions like: “Use
retrieve_agents to see what specialized agents are available, then use call_sub_agent to delegate appropriate tasks based on their capabilities.”
- Both tools must be included in the orchestrator’s configuration.
Step 1: Create the Orchestrator Agent
Now that you have created the sub-agents, create the orchestrator agent using the CRUD endpoint. Reference the sub-agents through the team_of_agents field by their keys and roles. You can later update this orchestrator (and its sub-agents) using the PATCH endpoint.
Calling the Create Agent endpoint to create an Orchestrator Agent
curl -X POST https://api.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "tone-orchestrator",
"role": "Book Assistant",
"description": "A friendly orchestrator agent who strives to help people by coordinating specialized sub-agents",
"instructions": "Answer the question of the user using your sub agents. Delegate tasks to your sub agents who will write the message and you will provide it in the final response with NO CHANGES. You create the answer and then you need to call the sub-agents after retrieving them and they will need to rephrase it according to their instructions. Instruct the sub-agents what they need to do, make their task clear as the orchestrator. Provide clear instructions to the sub agents what they need to do.",
"settings": {
"max_iterations": 15,
"max_execution_time": 600,
"tool_approval_required": "none",
"tools": [
{
"requires_approval": false,
"display_name": "current_date",
"type": "current_date"
},
{
"requires_approval": false,
"display_name": "retrieve_agents",
"type": "retrieve_agents"
},
{
"requires_approval": false,
"display_name": "call_sub_agent",
"type": "call_sub_agent"
}
]
},
"model": "openai/gpt-4o",
"path": "Default/agents",
"team_of_agents": [
{
"key": "youth-agent",
"role": "The youth agent for ages under 25"
},
{
"key": "formal-agent",
"role": "The formal agent for ages above 25"
}
]
}'
You can update the orchestrator agent and its sub-agents at any time using the PATCH endpoint (e.g., PATCH /v2/agents/tone-orchestrator). This allows you to refine instructions, add or remove sub-agents from the team_of_agents array, or modify settings while keeping the same agent key.
Step 2: Run the Orchestrator Agent
Once the orchestrator agent is created, invoke it by referencing its key. The orchestrator will use the sub-agents defined in the team_of_agents array during the creation step.
Calling the Invoke Agent endpoint with the Orchestrator Agent key
curl -X POST https://api.orq.ai/v2/agents/tone-orchestrator/task \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "I am writing a book for young adults about financial literacy. Can you help me come up with an engaging introduction that would appeal to teenagers, and then also provide a more formal version for a business audience?"
}
]
}
}'
