Orchestration avancée

Sessions multiagents

Coordonner plusieurs agents au sein d'une même session.

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 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 le temps d'exécution.

Toutes les requêtes 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 ces en-têtes bêta automatiquement.

Fonctionnement

Tous les agents partagent le même conteneur et système de fichiers, mais chaque agent s'exécute dans son propre thread de session, un flux d'événements isolé par contexte avec son propre historique de conversation. Le coordinateur rapporte l'activité dans le thread principal (qui est identique au flux d'événements au niveau de la session) ; des threads supplémentaires sont créé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 ce qui s'est passé lors 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.

Que 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 réviseur 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 identifiants supplémentaires des agents qu'il est autorisé à appeler :

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

Créez ensuite 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 principal, 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 en détail 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 d'une session comme suit :

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

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

Types d'événements multiagents

Ces événements font apparaître l'activité multiagent sur le flux de session de niveau supérieur.

Type	Description
`session.thread_created`	Le coordinateur a créé un nouveau thread. Inclut le `session_thread_id` et le `model`.
`session.thread_idle`	Un thread d'agent a terminé son travail en cours.
`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

Lorsqu'un thread callable_agent a besoin de quelque chose de votre client (une 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épercutez-le dans votre réponse.
session_thread_id est absent : l'événement provient du thread principal. 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.

Was this page helpful?

orchestrator=$(curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "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}
  ]
}
EOF
)

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      -d @-
done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")