Multi-Agent Teams: Coordinator and Router

Orchestrate specialist AI agents using Coordinator and Router strategies to answer complex, multi-domain queries that no single agent can handle alone.

Multi-agent teams let you combine specialist agents into a collaborative group that can tackle queries too complex or too broad for a single agent. A team has a designated Leader agent that controls how work is distributed among its Member agents, then synthesizes or routes the result back to the user.

How teams work

From the API’s perspective, a team is just an agent. It has the same AgentDefinition structure as any other agent and is executed using the same /api/agents/{agentId}/runs endpoints. The difference is internal: when you run a team, the Leader agent orchestrates one or more Member agents behind the scenes before producing a final response.

You can identify a team agent by its is_team field:

{
  "id": "finance_team",
  "name": "Finance Team",
  "description": "Routes queries to specialist finance agents",
  "is_team": true
}

Always check is_team before rendering agent metadata in your UI. Team agents may have different latency characteristics than single agents because they involve multiple LLM calls.

Orchestration strategies

Agent Manager supports the following orchestration strategies. The strategy is configured on the team at creation time.

Strategy	Description
Coordinator	The Leader delegates subtasks to Member agents using tool calls, collects their outputs, and synthesizes a unified answer.
Router	The Leader classifies the user’s intent and routes the entire conversation to the single best-fit Member agent.
ActorCritic	One agent generates a response; a second agent critiques and refines it.
Broadcast	The query is sent to all Member agents in parallel; the Leader aggregates the results.
Debate	Members argue opposing positions; the Leader adjudicates a final answer.
Planner	The Leader decomposes the query into a plan of subtasks and assigns each to a Member.
Sequential	Each Member agent processes the output of the previous one in a fixed pipeline.
Swarm	Agents self-select tasks from a shared pool and work concurrently.

Coordinator mode

In Coordinator mode, the Leader has access to a special set of delegation tools — one per Member agent. When the user asks a question, the Leader decides which Member agents to call, invokes them as tools, and uses their responses to compose a final answer.

Example flow:

User: "Compare today's AAPL earnings against analyst sentiment."

Leader (finance_team):
  → Calls finance_agent: "Get AAPL earnings data"
  → Calls web_agent: "Search analyst sentiment for AAPL"
  → Synthesizes both outputs into a single response

The user sees only the final synthesized answer. The intermediate tool calls appear in the tools field of the RunResponse for audit purposes.

Router mode

In Router mode, the Leader examines the user’s message and selects exactly one Member agent to handle the entire conversation. Control is transferred to that specialist, and the Leader takes no further action.

Example flow:

User: "What is the yield on 10-year US treasuries?"

Leader (finance_team):
  → Classifies intent: "fixed income / bond data"
  → Routes to: bonds_agent
  → bonds_agent responds directly

Router mode is efficient when your Member agents have clearly distinct, non-overlapping domains. It adds minimal overhead — only one extra classification call before routing.

Running a team

Running a team is identical to running any other agent. Use the standard run endpoints with the team’s agent ID:

1. Identify the team agent

   List agents and find the one where is_team is true:

   GET /api/agents
   

   [
     {
       "id": "finance_team",
       "name": "Finance Team",
       "description": "Multi-agent team for financial queries",
       "is_team": true
     }
   ]
   
2. Send a run request

   Use the same POST /api/agents/{agentId}/runs endpoint you would use for a single agent:

   {
     "message": "Give me a full briefing on NVDA: stock price, recent news, and analyst ratings.",
     "sessionId": "session-xyz-789",
     "userId": "user-99"
   }
   
3. Receive the synthesized response

   The RunResponse includes the final answer in content and the full tool-call audit trail in tools:

   {
     "runId": "run-8c2f11",
     "sessionId": "session-xyz-789",
     "content": "**NVDA** closed at $875.40. Recent news highlights...",
     "tools": [
       { "name": "finance_agent", "input": { "query": "NVDA stock price" }, "output": "875.40" },
       { "name": "web_agent", "input": { "query": "NVDA recent news" }, "output": "..." }
     ],
     "status": "COMPLETED"
   }
   

Checking whether an agent is a team

Before constructing any team-specific UI or logic, check the is_team flag in the AgentDefinition:

interface AgentDefinition {
  id: string;
  name: string;
  description: string;
  is_team: boolean;
}

async function getAgent(agentId: string): Promise<AgentDefinition> {
  const res = await fetch(`/api/agents/${agentId}`);
  return res.json();
}

const agent = await getAgent('finance_team');

if (agent.is_team) {
  console.log(`${agent.name} is a multi-agent team.`);
} else {
  console.log(`${agent.name} is a single agent.`);
}

Team management API

Teams have their own management endpoints under /api/v1/teams for creating, updating, and inspecting team configurations:

Method	Endpoint	Description
GET	/api/v1/teams	List all teams with optional text search and archived filter.
GET	/api/v1/teams/{id}	Get a single team by ID.
POST	/api/v1/teams	Create a new team.
PATCH	/api/v1/teams/{id}	Update team configuration.
DELETE	/api/v1/teams/{id}	Delete a team.
GET	/api/v1/teams/{id}/members	List Member agents in a team.
POST	/api/v1/teams/{id}/members	Add a Member agent.
DELETE	/api/v1/teams/{id}/members/{agentId}	Remove a Member agent.
GET	/api/v1/teams/{id}/health	Check if all Member agents are reachable.

The team management endpoints configure the team’s composition and strategy. To actually run a team and receive a response, always use POST /api/agents/{teamAgentId}/runs — the same endpoint used for single agents.