Teams API — Multi-Agent Orchestration

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.

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.

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 and streaming 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}

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"
  }'

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.");

List teams

GET /api/v1/teams

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

string

Optional text search across team names and descriptions.

boolean

default:"false"

When true, includes archived teams in the response.

number

default:"0"

Zero-based page index.

number

default:"20"

Number of teams per page.

curl --request GET \
  --url "http://localhost:8080/api/v1/teams?search=research&page=0&size=20" \
  --header "Authorization: Bearer {token}"

Example response

{
  "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
}

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.

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

string

required

The team identifier.

curl --request GET \
  --url "http://localhost:8080/api/v1/teams/research_team/members" \
  --header "Authorization: Bearer {token}"

Add a member

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

string

required

The team identifier.

string

required

The identifier of the agent to add as a member.

string

Optional role label for this member within the team (e.g., "specialist", "validator").

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" }'

Remove a member

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

string

required

The team identifier.

string

required

The agent to remove from the team.

curl --request DELETE \
  --url "http://localhost:8080/api/v1/teams/research_team/members/web_agent" \
  --header "Authorization: Bearer {token}"

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.

Agents

Knowledge & Sessions

Workflows & Teams

Teams API — Multi-Agent Orchestration

Orchestration modes

Running a team

Streaming delegation events

List teams

Manage team members

List members

Add a member

Remove a member

Additional team operations

​Orchestration modes

​Running a team

​Streaming delegation events

​List teams

​Manage team members

​List members

​Add a member

​Remove a member

​Additional team operations

Orchestration modes

Running a team

Streaming delegation events

List teams

Manage team members

List members

Add a member

Remove a member

Additional team operations