Sessions multi-agents

L'orchestration multi-agents permet à un agent de se coordonner avec d'autres pour accomplir des tâches complexes. Les agents peuvent agir en parallèle avec leur propre contexte isolé, ce qui contribue à améliorer la qualité des résultats et peut également réduire le temps d'exécution.



Fonctionnement

Tous les agents partagent le même bac à sable, le même système de fichiers et les mêmes identifiants de coffre-fort, mais chaque agent s'exécute dans son propre « session thread » (fil de session), un flux d'événements à contexte isolé disposant de son propre historique de conversation. Le coordinateur rapporte son activité dans le fil principal (qui correspond au flux d'événements au niveau de la session) ; des fils supplémentaires sont créés à l'exécution lorsque le coordinateur délègue du travail.

Les fils sont persistants : le coordinateur peut envoyer un message de suivi à un agent qu'il a appelé précédemment, et cet agent conserve tout ce qui provient de ses tours précédents.

Chaque agent utilise sa propre configuration : modèle, invite système, outils, serveurs MCP et compétences. Les substitutions de configuration d'agent au niveau de la session constituent l'exception ; elles s'appliquent au coordinateur et à ses copies self. Les outils, les serveurs MCP et le contexte ne sont pas partagés.



Quoi déléguer

La coordination multi-agents convient le mieux aux tâches complexes qui nécessitent soit un travail sur diverses surfaces, soit où plusieurs tâches bien délimitées contribuent à un objectif global.

Modèles qui fonctionnent bien :

• Parallélisation : Répartissez simultanément des sous-tâches indépendantes (recherche dans plusieurs sources, analyse de fichiers distincts) et laissez le coordinateur synthétiser les résultats.
• Spécialisation : Acheminez vers des agents dotés d'invites système et d'outils axés sur un domaine, comme un agent de sécurité ou un agent de documentation, plutôt que de charger un seul agent avec toutes les capacités.
• Escalade : Consultez un agent ou un modèle plus performant pour un sous-ensemble de sous-tâches complexes.



Configurer le coordinateur

Lors de la définition de votre agent, définissez multiagent pour déclarer la liste des agents auxquels le coordinateur peut déléguer :

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents peut accepter l'un des éléments suivants :

• {"type": "agent", "id": agent.id} référence un agent créé précédemment par son ID. Si aucune version n'est spécifiée, la référence est épinglée à la dernière version de cet agent au moment de la création du coordinateur.
• {"type": "agent", "id": agent.id, "version": agent.version} épingle une version spécifique de l'agent.
• {"type": "self"} permet au coordinateur de créer des copies de lui-même. Si la session a été créée avec des substitutions de configuration d'agent, ces substitutions s'appliquent également à ces copies ; les entrées de la liste référencées par ID ne sont pas affectées.

La configuration du coordinateur, y compris sa liste multiagent.agents, est capturée sous forme d'instantané lors de la création ou de la mise à jour du coordinateur. Les agents référencés restent épinglés aux versions résolues à ce moment-là et ne récupèrent pas automatiquement les mises à jour ultérieures de leurs définitions. Pour déléguer à une version plus récente d'un agent référencé, mettez à jour le coordinateur afin que sa liste référence cette version.

Le coordinateur ne peut déléguer qu'à un seul niveau d'agents ; une profondeur > 1 est ignorée. Un maximum de 20 agents uniques peut être listé dans multiagent.agents, mais le coordinateur peut appeler plusieurs copies de chaque agent.



Créer la session

Créez une session référençant le coordinateur. Le coordinateur délègue aux agents de sa liste selon les besoins.

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)



Connecter les agents aux serveurs MCP

Les serveurs MCP sont limités à l'agent (chaque définition d'agent déclare ses propres serveurs et outils), tandis que les identifiants de coffre-fort sont limités à la session (les vault_ids transmis lors de la création de la session s'appliquent à chaque fil). Deux implications pour votre intégration :

• Pour authentifier les serveurs MCP, incluez un identifiant de coffre-fort pour chaque serveur MCP utilisé par l'ensemble des agents.
• Pour limiter l'accès d'un agent, déclarez uniquement les serveurs dont il a besoin dans sa définition d'agent.

Les substitutions de configuration d'agent lors de la création de la session peuvent remplacer les serveurs MCP du coordinateur et ceux de ses copies self.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(session.id)

Dans cet exemple, seul le chercheur déclare le serveur MCP GitHub, donc le coordinateur n'y a pas accès. Les vault_ids de la session fournissent l'identifiant GitHub au fil du chercheur.



Fils

Le flux d'événements au niveau de la session (/v1/sessions/:id/events/stream) est considéré comme le fil principal, contenant une vue condensée de toute l'activité sur l'ensemble des fils. Vous ne voyez pas l'activité complète des sous-agents, mais vous voyez le début et la fin de leur travail, ainsi que les événements bloquants tels que les demandes d'autorisation d'outils.

Les fils de session sont l'endroit où vous explorez en détail l'activité d'un agent spécifique.

Le status de la session est une agrégation de toute l'activité des agents ; si au moins un fil est running, alors le statut global de la session est également running.



Événements du fil principal

Ces événements font remonter l'activité multi-agents sur le fil principal à /v1/sessions/:id/events/stream.



Événements des fils de session

Les événements critiques sont relayés vers le fil principal. Cependant, vous pourriez tout de même vouloir examiner le raisonnement et les appels d'outils d'un agent spécifique. Pour ce faire, diffusez en streaming ou listez les événements du fil de session associé.



Autorisations d'outils et outils personnalisés

Si un sous-agent a besoin de quelque chose de votre client, comme une autorisation pour exécuter un outil always_ask, ou le résultat d'un outil personnalisé, l'événement est publié en parallèle sur le fil principal avec session_thread_id identifiant le fil de session d'origine.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

Publiez user.tool_confirmation (avec tool_use_id) ou user.custom_tool_result (avec custom_tool_use_id) ; le serveur achemine automatiquement la réponse vers le fil approprié.

L'exemple suivant étend le gestionnaire de confirmation d'outil pour acheminer les réponses. Le même modèle s'applique à user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )