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.

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 — stream a team run

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

---

List teams

GET /api/v1/teams

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

search · string

Optional text search across team names and descriptions.

showArchived · boolean · default: "false"

When true, includes archived teams in the response.

page · number · default: "0"

Zero-based page index.

size · number · default: "20"

Number of teams per page.

cURL

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

id · string · required

The team identifier.

cURL

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

id · string · required

The team identifier.

agentId · string · required

The identifier of the agent to add as a member.

role · string

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

cURL

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}

id · string · required

The team identifier.

agentId · string · required

The agent to remove from the team.

cURL

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.