Sessions multiagents

Sessions multi-agents

Multiagent est une fonctionnalité en aperçu de recherche. Demandez l'accès pour l'essayer.

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

Toutes les demandes de l'API Managed Agents nécessitent l'en-tête bêta managed-agents-2026-04-01. Un en-tête bêta supplémentaire est nécessaire pour les fonctionnalités en aperçu de recherche. Le SDK définit automatiquement ces en-têtes bêta.

Fonctionnement

Tous les agents partagent le même conteneur et système de fichiers, mais chaque agent s'exécute dans sa propre session thread, un flux d'événements isolé en contexte avec son propre historique de conversation. Le coordinateur rapporte l'activité dans le thread primaire (qui est le même que le flux d'événements au niveau de la session) ; les threads supplémentaires sont générés à l'exécution lorsque le coordinateur décide de déléguer.

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

Chaque agent utilise sa propre configuration (modèle, invite système, outils, serveurs MCP et compétences) telle que définie lors de la création de cet agent. Les outils et le contexte ne sont pas partagés.

Quoi déléguer

Les sessions multiagents fonctionnent mieux lorsqu'il y a plusieurs tâches bien délimitées et spécialisées dans un objectif global :

Révision de code : Un agent examinateur avec une invite système ciblée et des outils en lecture seule.
Génération de tests : Un agent de test qui écrit et exécute des tests sans toucher au code de production.
Recherche : Un agent de recherche avec des outils web qui résume les résultats au coordinateur.

Déclarer les agents appelables

Lors de la définition de votre agent, listez les ID supplémentaires des agents qu'il est autorisé à appeler :

Chaque entrée dans callable_agents doit être l'ID d'un agent existant. Un seul niveau de délégation est supporté : le coordinateur peut appeler d'autres agents, mais ces agents ne peuvent pas appeler d'autres agents.

Ensuite, créez une session référençant l'orchestrateur :

Les agents appelables sont résolus à partir de la configuration de l'orchestrateur. Vous n'avez pas besoin de les référencer lors de la création de la session.

Threads de session

Le flux d'événements au niveau de la session (/v1/sessions/:id/stream) est considéré comme le thread primaire, contenant une vue condensée de toute l'activité sur tous les threads. Vous ne verrez pas les traces individuelles des agents appelés, mais vous verrez le début et la fin de leur travail. Les threads de session sont l'endroit où vous explorez le raisonnement et les appels d'outils d'un agent spécifique.

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

Listez tous les threads dans une session comme suit :

Diffusez les événements d'un thread spécifique :

Listez les événements passés d'un thread :

Types d'événements multiagents

Ces événements font surface l'activité multiagent sur le flux de session de haut niveau.

Type	Description
`session.thread_created`	Le coordinateur a généré un nouveau thread. Inclut `session_thread_id` et `model`.
`session.thread_idle`	Un thread d'agent a terminé son travail actuel.
`agent.thread_message_sent`	Un agent a envoyé un message à un autre thread. Inclut `to_thread_id` et `content`.
`agent.thread_message_received`	Un agent a reçu un message d'un autre thread. Inclut `from_thread_id` et `content`.

Permissions d'outils et outils personnalisés dans les threads

Quand un thread callable_agent a besoin de quelque chose de votre client (permission pour exécuter un outil always_ask, ou le résultat d'un outil personnalisé) la demande apparaît sur le flux de session avec un champ session_thread_id. Incluez le même session_thread_id lorsque vous publiez votre réponse afin que la plateforme la route vers le thread en attente.

session_thread_id est présent : l'événement provient d'un thread de sous-agent. Répétez-le sur votre réponse.
session_thread_id est absent : l'événement provient du thread primaire. Répondez sans le champ.
Faites correspondre tool_use_id pour associer les demandes aux réponses.

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

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

with client.beta.sessions.threads.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_idle":
                break

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])