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

# Teams API — Multi-Agent Orchestration

> Configure, manage, and run multi-agent teams using Coordinator or Router orchestration modes, with member management and real-time SSE streaming.

Teams are multi-agent orchestration units that coordinate two or more individual agents to handle complex tasks. A team appears in the agent registry as an `AgentDefinition` with `is_team: true`, and you run it through the exact same endpoints as a single agent. The orchestration strategy — Coordinator or Router — determines how the team leader dispatches work to its member agents.

All requests require a valid bearer token in the `Authorization` header.

***

## Orchestration modes

Agent Manager supports two primary team modes:

**Coordinator** — A designated leader agent delegates subtasks to member agents as tool calls. The leader synthesizes member outputs into a final response. This is best for tasks that require parallel or sequential delegation across specialists.

**Router** — The leader classifies the user's intent and routes the entire conversation to the most appropriate specialist agent. The selected specialist handles the request directly. This is best for domain-specific queries where one specialist is clearly the right choice.

<Note>
  In both modes, `TOOL_START` and `TOOL_END` events in the SSE stream reflect agent-to-agent delegation. The `data` field in `TOOL_START` contains the target member agent's ID and the delegated instruction.
</Note>

***

## Running a team

Teams are executed using the same endpoints as individual agents. Pass the team's `id` as the `agentId` path parameter.

**Synchronous:** `POST /api/agents/{teamId}/runs`

**Streaming:** `POST /api/agents/{teamId}/runs/stream`

**Background:** `POST /api/agents/{teamId}/runs/background`

See the [synchronous run](/api/agents/run) and [streaming](/api/agents/stream) reference pages for full request/response documentation.

### Streaming delegation events

When you stream a team run, the SSE stream includes `TOOL_START` and `TOOL_END` events for each member agent delegation. Use these to show your users which specialist is handling their query.

```
data: {"event":"START","data":"{\"runId\":\"run_team_001\",\"sessionId\":\"sess_xyz\"}","timestamp":1746518400000}

data: {"event":"REASONING_DELTA","data":"This is a finance question. I should route to finance_agent.","timestamp":1746518400120}

data: {"event":"TOOL_START","data":"{\"name\":\"delegate_to_agent\",\"arguments\":{\"agentId\":\"finance_agent\",\"message\":\"What is the current NVDA stock price?\"}}","timestamp":1746518400250}

data: {"event":"TOOL_END","data":"{\"name\":\"delegate_to_agent\",\"result\":\"The current stock price of NVDA is $875.40.\"}","timestamp":1746518401800}

data: {"event":"CONTENT_DELTA","data":"The current stock price of NVIDIA (NVDA) is **$875.40**","timestamp":1746518401900}

data: {"event":"STOP","data":"","timestamp":1746518401950}
```

<CodeGroup>
  ```bash cURL — stream a team run theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/agents/research_team/runs/stream" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: text/event-stream" \
    --data '{
      "message": "What is the current NVDA stock price and how does it compare to AMD?",
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user_abc123"
    }'
  ```

  ```typescript TypeScript — handle delegation events theme={null}
  async function streamTeamRun(teamId: string, message: string) {
    const response = await fetch(
      `http://localhost:8080/api/agents/${teamId}/runs/stream`,
      {
        method: "POST",
        headers: {
          Authorization: "Bearer {token}",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ message }),
      }
    );

    const reader = response.body!
      .pipeThrough(new TextDecoderStream())
      .getReader();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      for (const line of value.split("\n")) {
        if (!line.startsWith("data:")) continue;
        const event = JSON.parse(line.slice(5).trim());

        if (event.event === "TOOL_START") {
          const tool = JSON.parse(event.data);
          if (tool.arguments?.agentId) {
            // Show which specialist the team is delegating to
            console.log(`Routing to specialist: ${tool.arguments.agentId}`);
          }
        }

        if (event.event === "CONTENT_DELTA") {
          process.stdout.write(event.data);
        }
      }
    }
  }

  streamTeamRun("research_team", "Compare NVDA and AMD stock performance this quarter.");
  ```
</CodeGroup>

***

## List teams

```
GET /api/v1/teams
```

Returns a paginated list of configured teams, with optional search filtering and an option to include archived teams.

<ParamField query="search" type="string">
  Optional text search across team names and descriptions.
</ParamField>

<ParamField query="showArchived" type="boolean" default="false">
  When `true`, includes archived teams in the response.
</ParamField>

<ParamField query="page" type="number" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of teams per page.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/teams?search=research&page=0&size=20" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "content": [
    {
      "id": "research_team",
      "name": "Research Team",
      "description": "Coordinator team that delegates to web and finance specialists.",
      "mode": "COORDINATOR",
      "members": ["web_agent", "finance_agent"]
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0
}
```

<Tip>
  You can also discover teams from the standard agents endpoint. `GET /api/agents` returns all agents including teams — filter on `is_team: true` to identify team entries.
</Tip>

***

## Manage team members

You can add and remove member agents from a team without re-creating it.

### List members

```
GET /api/v1/teams/{id}/members
```

<ParamField path="id" type="string" required>
  The team identifier.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/teams/research_team/members" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

### Add a member

```
POST /api/v1/teams/{id}/members
```

<ParamField path="id" type="string" required>
  The team identifier.
</ParamField>

<ParamField body="agentId" type="string" required>
  The identifier of the agent to add as a member.
</ParamField>

<ParamField body="role" type="string">
  Optional role label for this member within the team (e.g., `"specialist"`, `"validator"`).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/v1/teams/research_team/members" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --data '{ "agentId": "web_agent", "role": "specialist" }'
  ```
</CodeGroup>

### Remove a member

```
DELETE /api/v1/teams/{id}/members/{agentId}
```

<ParamField path="id" type="string" required>
  The team identifier.
</ParamField>

<ParamField path="agentId" type="string" required>
  The agent to remove from the team.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/v1/teams/research_team/members/web_agent" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

Returns `204 No Content`.

***

## Additional team operations

| Method   | Endpoint                     | Description                                                          |
| -------- | ---------------------------- | -------------------------------------------------------------------- |
| `POST`   | `/api/v1/teams`              | Create a new team. Body: `TeamDTO` with name, description, and mode. |
| `PATCH`  | `/api/v1/teams/{id}`         | Update team metadata.                                                |
| `DELETE` | `/api/v1/teams/{id}`         | Delete a team (204).                                                 |
| `PATCH`  | `/api/v1/teams/{id}/archive` | Archive a team without deleting it.                                  |
| `PATCH`  | `/api/v1/teams/{id}/restore` | Restore an archived team.                                            |
| `POST`   | `/api/v1/teams/{id}/clone`   | Clone a team with all members and edges.                             |
| `GET`    | `/api/v1/teams/{id}/health`  | Get operational health status for a team.                            |