Agent Teams & A2A

Coordinate multiple AI agents as a team. Use the visual team builder, war room chat, capability discovery, and A2A webhooks for agent-to-agent communication.

What is an Agent Team?

An Agent Team is a group of agents configured to work together toward a shared objective. Teams support internal agents (managed in the platform) and external agents (connected via A2A webhooks). Each team has a topology, a set of capabilities, and a secure A2A secret for external communication.

Team Concepts

Creating a Team

Teams are created via the Agent Teams page or the API. Each team receives a unique A2A secret that external agents must present when connecting.

{
  "name": "Research Squad",
  "description": "Research, analysis, and reporting team",
  "agents": ["agent_001", "agent_002"],
  "externalAgents": [
    { "name": "external-summarizer", "capabilities": ["summarize"] }
  ],
  "topology": "mesh"
}

War Room Chat

The war room is a real-time chat interface for a team session. When a team run is triggered, a session is created and the runner broadcasts status updates through Socket.IO. Users and agents can exchange messages in the shared session. All messages are persisted in the MessageLog collection.

Capability Discovery

The discovery endpoint returns the combined capabilities of all internal and external agents in a team. This allows the system (or a supervising agent) to understand what skills are available before delegating tasks.

{
  "ok": true,
  "discovery": [
    { "id": "agent_001", "name": "Researcher", "type": "internal", "capabilities": ["web_search", "summarize"] },
    { "id": "external-summarizer", "name": "External Summarizer", "type": "external", "capabilities": ["summarize"] }
  ]
}

A2A Webhook Security

External agents authenticate using the team's A2A secret, passed via the x-a2a-secret header. The webhook validates the secret against the team metadata and checks that the external agent identity is authorized for that team.

Headers:
  x-a2a-secret: <team_a2a_secret>

Body:
{
  "sessionId": "session_abc",
  "from": { "id": "external-summarizer", "type": "external" },
  "to": { "id": "broadcast", "type": "internal" },
  "type": "user_prompt",
  "content": { "result": "Summarize this report" }
}

Team Run Flow

1. User triggers a team run via the UI or POST /api/agent-teams/:id/run.
2. Backend creates an AgentSession with the provided objective.
3. If a war room is active, the runner immediately broadcasts aNEW_SWARM_MESSAGE event. Otherwise, it waits up to 10 seconds for a client to join before triggering.
4. Agents exchange messages through the Socket.IO war room.
5. Session logs are queryable via GET /api/agent-teams/sessions/:sessionId/logs.