> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "id": "finance_team",
  "name": "Finance Team",
  "description": "Routes queries to specialist finance agents",
  "is_team": true
}
```

<Tip>
  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.
</Tip>

## 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:

<Steps>
  <Step title="Identify the team agent">
    List agents and find the one where `is_team` is `true`:

    ```bash theme={null}
    GET /api/agents
    ```

    ```json theme={null}
    [
      {
        "id": "finance_team",
        "name": "Finance Team",
        "description": "Multi-agent team for financial queries",
        "is_team": true
      }
    ]
    ```
  </Step>

  <Step title="Send a run request">
    Use the same `POST /api/agents/{agentId}/runs` endpoint you would use for a single agent:

    ```json theme={null}
    {
      "message": "Give me a full briefing on NVDA: stock price, recent news, and analyst ratings.",
      "sessionId": "session-xyz-789",
      "userId": "user-99"
    }
    ```
  </Step>

  <Step title="Receive the synthesized response">
    The `RunResponse` includes the final answer in `content` and the full tool-call audit trail in `tools`:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>
</Steps>

## Checking whether an agent is a team

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

```typescript theme={null}
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.                     |

<Note>
  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.
</Note>