Multi Agents Workflow

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:

  1. Create Sub-agents First: Use the Agent CRUD endpoints (POST /v2/agents) to create the specialized agents
  2. Reference by ID: Add the created agent IDs to the team_of_agents array in your orchestrator agent configuration
  3. Define Roles: Specify each sub-agent's role to help the orchestrator decide when to delegate
❗️

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.

Example

Creating an Agent

Calling POST /v2/agents 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"
}'

Orchestrating Agents

Calling the previously created Youth Agent via the call_sub_agent tool.

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "sub-agent-testing-tone",
  "role": "Book Assistant",
  "description": "A friendly orchestrator agent who strives to help people",
  "instructions": "Answer the question of the user using your sub agents",
  "system_prompt": "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. You need to provide clear instructions to the sub agents what they need to do. Provide the original message to the sub agents as well. Use retrieve_agents to see what specialized agents are available, then use call_sub_agent to delegate appropriate tasks based on their capabilities.",
  "settings": {
    "max_iterations": 15,
    "max_execution_time": 600,
    "tools": [
      {
        "type": "current_date"
      },
      {
        "type": "retrieve_agents"
      },
      {
        "type": "call_sub_agent"
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Good afternoon my 22nd birthday is today! What is the current date and what is a historical piece of trivia that happened today?"
      }
    ]
  },
  "model": "cerebras/gpt-oss-120b",
  "path": "Default/agents",
  "team_of_agents": [
    {
      "_id": "01K5YDH2Z6GR3ZVTCCBMW5YK8V",
      "role": "The youth agent for ages under 25"
    },
    {
      "_id": "01K5YDGT5AVJ5XRY1AVBGTJKAG",
      "role": "The formal agent for ages above 25"
    }
  ]
}'
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "sub-agent-testing-tone",
        "role": "Book Assistant",
        "description": "A friendly orchestrator agent who strives to help people",
        "instructions": "Answer the question of the user using your sub agents",
        "system_prompt": "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. You need to provide clear instructions to the sub agents what they need to do. Provide the original message to the sub agents as well. Use retrieve_agents to see what specialized agents are available, then use call_sub_agent to delegate appropriate tasks based on their capabilities.",
        "settings": {
            "max_iterations": 15,
            "max_execution_time": 600,
            "tools": [
                {
                    "type": "current_date"
                },
                {
                    "type": "retrieve_agents"
                },
                {
                    "type": "call_sub_agent"
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "Good afternoon my 22nd birthday is today! What is the current date and what is a historical piece of trivia that happened today?"
                }
            ]
        },
        "model": "cerebras/gpt-oss-120b",
        "path": "Default/agents",
        "team_of_agents": [
            {
                "_id": "01K5YDH2Z6GR3ZVTCCBMW5YK8V",
                "role": "The youth agent for ages under 25"
            },
            {
                "_id": "01K5YDGT5AVJ5XRY1AVBGTJKAG",
                "role": "The formal agent for ages above 25"
            }
        ]
    })

    assert res is not None
    print(res)
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.run({
    key: "sub-agent-testing-tone",
    role: "Book Assistant",
    description: "A friendly orchestrator agent who strives to help people",
    instructions: "Answer the question of the user using your sub agents",
    systemPrompt: "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. You need to provide clear instructions to the sub agents what they need to do. Provide the original message to the sub agents as well. Use retrieve_agents to see what specialized agents are available, then use call_sub_agent to delegate appropriate tasks based on their capabilities.",
    settings: {
      maxIterations: 15,
      maxExecutionTime: 600,
      tools: [
        {
          type: "current_date"
        },
        {
          type: "retrieve_agents"
        },
        {
          type: "call_sub_agent"
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "Good afternoon my 22nd birthday is today! What is the current date and what is a historical piece of trivia that happened today?"
        }
      ]
    },
    model: "cerebras/gpt-oss-120b",
    path: "Default/agents",
    teamOfAgents: [
      {
        _id: "01K5YDH2Z6GR3ZVTCCBMW5YK8V",
        role: "The youth agent for ages under 25"
      },
      {
        _id: "01K5YDGT5AVJ5XRY1AVBGTJKAG",
        role: "The formal agent for ages above 25"
      }
    ]
  });

  console.log(result);
}

run();