Orchestration multi-agents

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

Vous n’êtes pas sûr qu’une configuration multi-agents convienne à votre problème ? Consultez quand utiliser des systèmes multi-agents (et quand ne pas le faire).

Confier du travail à d’autres agents

L’agent qu’exécute une session peut confier du travail à d’autres agents de deux manières. Avec les « subagents » (sous-agents), il délègue lui-même des tâches et lit ce que chaque sous-agent rapporte. Avec les « dynamic workflows » (workflows dynamiques), il écrit un workflow : un programme qui exécute de nombreux agents en arrière-plan et combine leurs résultats. Il peut également consulter un modèle « advisor » (conseiller) pour obtenir des conseils tout en effectuant le travail lui-même.

Vous décidez lesquels de ces mécanismes l’agent peut utiliser, et l’agent détermine quand les utiliser. Pour orienter ce choix, indiquez à l’agent dans son invite système quand utiliser une exécution de workflow. Consultez Indiquer à l’agent quand utiliser une exécution. Vous pouvez également limiter l’agent aux agents que vous listez.

Avec les sous-agents, l’agent détermine lui-même ce qui se passe ensuite. Le fil d’un sous-agent reste disponible jusqu’à ce que vous l’archiviez, de sorte que l’agent peut lui envoyer des messages de suivi. Avec les workflows dynamiques, Claude écrit un programme pour orchestrer des agents sans l’intervention directe de Claude. Le contexte et les résultats sont transmis de manière programmatique d’un agent à l’autre, ce qui libère le fil principal de la session pour communiquer avec l’utilisateur et faire le point sur un ou plusieurs workflows en cours afin de rendre compte de leur progression. L’agent ne peut pas envoyer de messages de suivi aux fils d’une exécution, et le serveur archive chacun d’eux au plus tard à la fin de son exécution.

Vous les configurez dans le bloc multiagent de la définition de l’agent, qui possède un type. Avec le type multiagent_20261001, un agent peut utiliser les trois ensemble, et vous pouvez activer ou désactiver chacun d’eux. Par défaut, subagents et workflows sont tous deux activés. subagents et workflows ont chacun inline_agents activé, le paramètre pour les agents que l’agent ou un workflow définit lui-même :

{
  "multiagent": { "type": "multiagent_20261001" }
}

Pour définir quels agents l’agent peut appeler, consultez Agents prédéfinis et agents inline. Pour désactiver un paramètre, consultez Activer les workflows dynamiques.

Agents prédéfinis et agents inline

Chaque sous-agent, et chaque agent d’une exécution de workflow, appartient à l’un de ces deux types :

• Agent prédéfini : un agent que vous avez déjà créé, et que vous listez dans le bloc multiagent. Il utilise sa propre configuration : modèle, invite système, outils, serveurs MCP et skills.
• Agent inline : un agent qui n’est pas enregistré. L’agent qu’exécute la session, ou un workflow, le définit lorsqu’il distribue le travail. Il utilise le modèle, les outils, les serveurs MCP et les skills de cet agent.

Les deux types fonctionnent sous subagents et sous workflows :

subagents.predefined_agents et workflows.predefined_agents sont deux listes distinctes. Un agent présent dans une liste n’est pas ajouté à l’autre. Les deux listes sont vides par défaut. Une entrée de l’une ou l’autre liste prend l’une de ces formes :

• {"type": "agent", "id": agent.id} référence un agent précédemment créé par son ID. Si aucune version n’est spécifiée, la référence est épinglée à la dernière version de l’agent au moment où l’agent qui le liste est créé, ou lorsqu’une mise à jour envoie la liste.
• {"type": "agent", "id": agent.id, "version": agent.version} épingle une version spécifique de l’agent.
• agent.id seul, sous forme de chaîne, est un raccourci pour {"type": "agent", "id": agent.id}.
• {"type": "self"} liste l’agent lui-même, afin que des copies de celui-ci puissent effectuer le travail. Si la session a été créée avec des remplacements de configuration d’agent, ces remplacements s’appliquent également à ces copies. Les entrées référencées par ID ne sont pas affectées.

Les règles relatives à ces entrées, et aux agents qu’elles désignent, s’appliquent aux deux listes. Consultez Lister les sous-agents.

Les agents inline sont activés par défaut sous les deux paramètres. Pour n’autoriser que les agents que vous listez, définissez inline_agents sur {"type": "disabled"} sous subagents, sous workflows, ou sous les deux. Un paramètre dont les agents inline sont désactivés nécessite au moins un agent dans sa liste predefined_agents. Avec une liste vide, la requête échoue avec une erreur 400. Lors d’une mise à jour, le serveur vérifie les paramètres tels qu’ils sont après la mise à jour.

L’agent suivant n’autorise que les agents qu’il liste. Il peut déléguer à un agent et à des copies de lui-même, et un workflow peut utiliser la version 2 d’un autre agent :

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

Déléguer à des sous-agents

Quoi déléguer

La coordination multi-agents convient particulièrement aux tâches complexes qui nécessitent soit un travail sur des surfaces variées, soit plusieurs tâches bien délimitées contribuant à un objectif global.

Les schémas 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 l’agent synthétiser les résultats.
• Spécialisation : orientez 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 de toutes les capacités.
• Escalade : consultez un agent ou un modèle plus performant pour un sous-ensemble de sous-tâches complexes. Pour consulter un modèle, donnez un conseiller à la session.

Fonctionnement

Tous les agents partagent le même sandbox, le même système de fichiers et les mêmes identifiants de coffre, mais chaque agent s’exécute dans son propre « session thread » (fil de session), un flux d’événements au contexte isolé doté de son propre historique de conversation. L’agent qu’exécute la session signale son activité dans le « primary thread » (fil principal), qui est le flux d’événements au niveau de la session. Des fils supplémentaires sont créés à l’exécution lorsqu’il délègue du travail. Une exécution de workflow crée également des fils.

Le fil d’un sous-agent est persistant. L’agent peut envoyer un suivi à un sous-agent qu’il a appelé précédemment, et ce sous-agent conserve tout ce qui provient de ses tours précédents.

La configuration qu’utilise un sous-agent dépend du fait qu’il s’agit d’un agent prédéfini ou d’un agent inline. Les remplacements de configuration d’agent au niveau de la session s’appliquent à l’agent qu’exécute la session et à ses copies self. Chaque agent conserve son propre historique de conversation.

Lister les sous-agents

Lors de la définition de votre agent, définissez la liste predefined_agents de subagents dans le bloc multiagent pour lister les agents auxquels il peut déléguer :

ant apply engineering-lead.md reviewer.md test-writer.md

---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./reviewer.md
      - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

L’agent peut également déléguer à des agents inline, sauf si vous les désactivez. Pour ce paramètre, et pour les formes que prend une entrée de la liste predefined_agents de subagents, consultez Agents prédéfinis et agents inline.

"advisor": {"type": "enabled", "model": "<model id>"} donne au fil principal de la session un conseiller qu’il peut consulter en cours de tour. Le conseiller est un paramètre du bloc multiagent, et non une entrée de cette liste. Consultez Donner un conseiller à la session.

Les workflows dynamiques sont également activés par défaut avec ce type, de sorte que cet agent peut planifier un travail de grande ampleur qui exécute de nombreux agents en arrière-plan. Pour les désactiver, ou pour lister les agents qu’un workflow peut utiliser, consultez Activer les workflows dynamiques.

Les règles suivantes s’appliquent aux agents que vous listez dans la liste predefined_agents de subagents, ainsi qu’aux agents que vous listez dans la liste predefined_agents de workflows :

• Épinglage : la configuration de l’agent, y compris la liste predefined_agents de subagents, est capturée sous forme d’instantané lors de la création ou de la mise à jour de l’agent. Les agents référencés restent épinglés aux versions résolues à ce moment-là et ne prennent pas en compte les mises à jour ultérieures de leurs définitions. Une mise à jour qui n’envoie pas la liste conserve les versions déjà épinglées. Pour déléguer à une version plus récente d’un agent référencé, mettez à jour l’agent afin que la liste predefined_agents de subagents référence cette version.
• Un seul niveau : l’agent ne peut déléguer qu’à un seul niveau d’agents. Référencer un autre agent pour lequel multiagent est défini fait échouer la requête de création ou de mise à jour avec une erreur de validation 400.
• Jusqu’à 20 agents : la liste predefined_agents de subagents peut lister jusqu’à 20 agents uniques. La limite s’applique à chaque liste : la liste predefined_agents de workflows peut également en lister jusqu’à 20. L’agent peut appeler plusieurs copies de chaque sous-agent, dans la limite de la limite de fils de la session.
• Géographie d’inférence : l’agent et chaque agent que vous listez, dans la liste predefined_agents de subagents ou de workflows, doivent épingler la même géographie d’inférence (inference_geo dans le model de la définition de l’agent), ou aucun d’entre eux ne doit en épingler une. Une incohérence dans l’une ou l’autre liste est rejetée avec une erreur de validation 400. Cette vérification s’exécute à la fois lors de l’enregistrement de l’agent et lorsqu’un remplacement à la création de session modifie l’un des épinglages.

Créer la session

Créez une session référençant l’agent. L’agent délègue selon les besoins aux agents que vous listez dans la liste predefined_agents de subagents. Il peut également déléguer à des agents inline, sauf si vous les désactivez.

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

Connecter des agents à des serveurs MCP

Les serveurs MCP sont propres à chaque agent : chaque définition d’agent déclare ses propres serveurs et outils. Un agent inline n’a pas de définition d’agent, il utilise donc les serveurs MCP et les outils de l’agent qu’exécute la session. Les identifiants de coffre sont propres à 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 pour chaque serveur MCP utilisé par n’importe lequel de vos agents.
• Pour limiter l’accès d’un agent, déclarez uniquement les serveurs dont il a besoin dans sa définition d’agent. Vous ne pouvez pas limiter un agent inline de cette manière. Pour n’autoriser que les agents que vous listez, désactivez inline_agents à la fois dans subagents et dans workflows, et listez au moins un agent dans chacun. Consultez Agents prédéfinis et agents inline.

Les remplacements de configuration d’agent lors de la création de session peuvent remplacer les serveurs MCP de l’agent qu’exécute la session ainsi que ceux de ses copies self.

Avec un environnement limited, la création de session échoue avec une erreur 400 lorsque l’agent, ou un agent que vous listez dans la liste predefined_agents de subagents ou de workflows, déclare un serveur MCP dont l’hôte ne figure pas dans allowed_hosts. Définir allow_mcp_servers sur true dans la configuration réseau de l’environnement désactive cette vérification.

Créez le chercheur, qui déclare le serveur MCP GitHub, ainsi que l’agent qui délègue au chercheur :

ant apply lead.md researcher.md

---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./researcher.md
---

---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

Créez ensuite la session avec le coffre qui contient l’identifiant GitHub :

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

Dans cet exemple, seul le chercheur déclare le serveur MCP GitHub, de sorte que l’agent qu’exécute la session n’y a pas accès. Les vault_ids de la session fournissent l’identifiant GitHub au fil du chercheur.

Fils

Le fil de session de chaque agent possède son propre flux d’événements. Pour lister, interrompre ou archiver des fils, lire leurs événements et gérer les autorisations d’outils entre eux, consultez Fils de session.

Workflows dynamiques

Avec les workflows dynamiques, un agent peut prendre en charge un travail comportant de nombreuses parties, comme la relecture de centaines de documents ou la vérification croisée de nombreuses sources. L’agent écrit un « workflow » : un programme qui exécute de nombreux agents par phases et combine ce qu’ils renvoient. Le serveur l’exécute en arrière-plan sous la forme d’un « workflow run » (exécution de workflow), pendant que l’agent continue de travailler ou termine son tour. Vous activez ou désactivez les workflows dynamiques avec le paramètre workflows du bloc multiagent de l’agent. Les agents d’une exécution peuvent travailler en même temps, de sorte qu’une tâche longue peut se terminer plus tôt que si un seul agent traitait chaque partie à tour de rôle.

• Comment une exécution démarre : vous décrivez le travail dans un user.message. À partir de celui-ci, l’agent détermine s’il faut démarrer une exécution et quand, il n’y a donc aucun appel d’API supplémentaire. Vous influencez plutôt la décision de l’agent en décrivant quand utiliser une exécution dans user.message ou dans l’invite système de l’agent. (Les politiques d’autorisation s’appliquent aux outils qu’appellent les agents d’une exécution, et non au démarrage de l’exécution.)
• Quels agents elle utilise : des agents inline que le workflow définit, des agents prédéfinis que vous listez dans la liste predefined_agents de workflows, ou les deux. Si vous n’en listez aucun, le workflow les définit tous. Un agent inline utilise le modèle de l’agent qu’exécute la session. Pour permettre à une exécution d’utiliser un autre modèle pour certains de ses agents, créez-les en tant qu’agents et listez-les dans la liste predefined_agents de workflows.
• Comment la suivre : les événements de l’exécution arrivent sur le flux d’événements de la session, et chaque agent de l’exécution travaille dans un fil de session que vous pouvez lister, lire et diffuser en streaming. Consultez Exécutions de workflow pour les événements, les interruptions, les limites, et ce que montrent les fils d’une exécution.

Activer les workflows dynamiques

Lorsque vous définissez votre agent, définissez multiagent.type sur "multiagent_20261001" et activez workflows. Les workflows dynamiques et la délégation (subagents) sont tous deux activés par défaut avec ce type. Pour les workflows dynamiques uniquement, définissez également subagents sur {"type": "disabled"}.

Avant de modifier le multiagent.type d’un agent existant, consultez comment faire passer un agent à ce type.

Cet exemple désactive également la recherche web et la récupération web, car la révision de contrats n’utilise pas le web :

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Pour permettre à un workflow d’utiliser des agents que vous avez déjà créés, listez-les dans workflows.predefined_agents. Les paramètres subagents et advisor se placent dans le même bloc multiagent. Pour lister des sous-agents, consultez Déléguer à des sous-agents. Pour définir un conseiller, consultez Donner un conseiller à la session. Cet agent permet à un workflow d’utiliser un agent que vous avez créé, liste deux sous-agents et dispose d’un conseiller :

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Chaque paramètre est activé ou désactivé indépendamment :

Pour savoir ce qui va dans chaque liste, et comment n’autoriser que les agents que vous listez, consultez Agents prédéfinis et inline.

Gardez les points suivants à l’esprit :

• Mise à jour : Une mise à jour qui conserve le type multiagent_20261001 ne modifie que ce qu’elle envoie :
  • Un paramètre ou un champ que vous omettez conserve sa valeur enregistrée.
  • Un paramètre ou un champ que vous envoyez avec la valeur null reprend sa valeur par défaut, de même que tout ce qu’il contient, quelle que soit la valeur que vous aviez enregistrée.
  • Une liste predefined_agents que vous envoyez remplace la liste enregistrée.
  • Un paramètre que vous envoyez avec un type différent remplace le paramètre enregistré, et les champs que vous y omettez reprennent leurs valeurs par défaut.
  • Chaque objet que vous envoyez nécessite son type, et un advisor activé nécessite son model.
• Désactivation : Définissez workflows sur {"type": "disabled"}. Il reste désactivé jusqu’à ce qu’une mise à jour le réactive. Envoyer null l’active, car sa valeur par défaut est activée. Il en va de même pour subagents.
• Sessions existantes : Une session copie le paramètre lors de sa création ; modifier l’agent par la suite ne modifie donc pas une session qui existe déjà.
• Agents que vous pouvez lister : Un agent pour lequel multiagent est défini ne peut pas être listé comme sous-agent d’un autre agent, ni dans la liste predefined_agents de workflows d’un autre agent. Un agent peut se lister lui-même dans l’une ou l’autre liste avec {"type": "self"}, qui est relu comme son propre id et sa propre version.
• Noms d’outils : Le préfixe ant__ est réservé. Si votre agent possède déjà un outil personnalisé dont le nom commence par ant__, une mise à jour échoue avec une erreur 400 jusqu’à ce que vous envoyiez tools sans ce nom. Une nouvelle session est également refusée avec une erreur 400 si son agent, ou un agent de l’une ou l’autre liste, possède un tel outil. Renommez ou supprimez l’outil dans la même mise à jour qui active les workflows dynamiques. Consultez Outils personnalisés.
• Budget : Définissez un budget de session lorsque vous créez la session afin de plafonner les dépenses de la session, exécutions comprises ; vous ne pouvez pas en ajouter un à une session existante. Les exécutions sont mises en pause lorsque la session atteint le budget, et les exécutions mises en pause par le budget reprennent lorsque vous l’augmentez ou le supprimez, sauf si une interruption les a également mises en pause. Consultez Coût et budgets.

Indiquer à l’agent quand utiliser une exécution

Activer les workflows dynamiques donne à l’agent la capacité de démarrer des exécutions de workflow (workflow runs). L’agent détermine quand en démarrer une. Pour orienter ce choix, ajoutez une instruction telle que la suivante à l’invite système de l’agent. L’agent de révision de contrats présenté dans Activer les workflows dynamiques utilise cette invite système :

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Pour l’adapter, nommez les tâches du domaine de votre agent qui nécessitent une exécution, ainsi que les petites tâches que l’agent doit effectuer lui-même. Vous pouvez également orienter la façon dont une exécution effectue le travail, comme dans ces exemples :

• Comment répartir le travail : « Dans une exécution, utilisez un agent par contrat. Ensuite, demandez à un second agent de réviser chaque contrat, pas seulement ceux où le premier agent a trouvé quelque chose, et de rechercher ce que le premier agent a manqué. Tout ce qui échoue à la révision est refait et révisé à nouveau. »
• Que faire lorsqu’un agent échoue : « L’échec d’un agent ne doit pas faire échouer l’exécution. Si un agent ne parvient pas à lire un contrat, listez ce contrat comme non couvert. À la fin de l’exécution, indiquez-moi quels contrats n’ont pas été couverts. »
• Une limite de temps : « Donnez à l’exécution une limite de temps d’une heure. »
• Planifier d’abord : « Avant de démarrer une exécution, décrivez ses phases et le nombre d’agents que chacune exécute. Attendez ensuite mon feu vert. » Il n’y a pas d’étape d’approbation avant le démarrage d’une exécution, donc rien n’impose cela.

Réservez les exécutions aux tâches qui en ont besoin, car chaque agent d’une exécution consomme des tokens.

Ensuite, créez une session avec l’agent, comme vous le feriez avec n’importe quel agent, et décrivez le travail dans un user.message. Vous pouvez également demander une exécution dans ce message.

Pour les événements d’une exécution, l’interruption d’une session comportant des exécutions ouvertes, ce qui change pendant qu’une exécution est ouverte, ainsi que les budgets et les limites, consultez Exécutions de workflow.

Donner un conseiller à la session

Un paramètre advisor activé dans le bloc multiagent de l’agent donne au fil principal de la session un conseiller (advisor) : un modèle qu’il peut consulter en cours de tour pour obtenir des conseils stratégiques, par exemple pour planifier une approche, surmonter un obstacle ou réviser le travail avant de terminer. Ce paramètre est désactivé par défaut. Pour l’activer, définissez advisor sur {"type": "enabled", "model": "..."}, qui comporte exactement deux champs, type et model :

ant apply backend-engineer.md

---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

Cet exemple définit uniquement advisor. Les deux autres paramètres, subagents et workflows, conservent leurs valeurs par défaut ; ils sont donc tous deux activés, et l’agent peut également déléguer à des agents inline et démarrer des exécutions de workflow. Pour un agent qui consulte un conseiller et effectue tout le travail lui-même, définissez les deux sur {"type": "disabled"}.

Vous ne pouvez pas lister le conseiller dans la liste predefined_agents de subagents ou de workflows. Un advisor activé réserve le nom anthropic.advisor. Tant qu’il est activé, aucune des deux listes ne peut contenir un agent nommé littéralement anthropic.advisor : la requête est rejetée avec une erreur de validation 400.

Le modèle conseiller doit atteindre un niveau de capacité minimal, et le modèle de l’agent lui-même ne doit pas être plus performant que son conseiller ; des modèles de capacité égale peuvent être associés. Une association invalide est rejetée avec une erreur de validation 400 lors de l’enregistrement de l’agent, puis à nouveau lors de la création d’une session. L’association est également vérifiée au début de chaque consultation : si elle n’est plus valide, cette consultation échoue et la session continue. Les associations valides suivent le tableau de compatibilité des modèles de l’outil conseiller.

Le conseiller est également disponible en tant qu’outil serveur sur l’API Messages. L’interface Managed Agents diffère en matière de configuration et de livraison : le paramètre advisor ne comporte pas de champs max_uses, max_tokens ou caching, et les conseils arrivent par le biais d’événements de fil plutôt que de blocs advisor_tool_result.

Fonctionnement des consultations

Chaque consultation s’exécute sous la forme d’un fil créé par la plateforme, nommé anthropic.advisor, qui se termine de lui-même lorsque la consultation est achevée, et le conseil est livré au fil principal sous la forme d’un événement agent.thread_message_received. Une consultation émet les événements de fil standard, identifiés par le nom réservé anthropic.advisor (les événements du cycle de vie du fil le portent en tant que agent_name, et la livraison du conseil le porte en tant que from_agent_name), généralement dans cet ordre :

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received (le conseil)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

Aucun événement agent.tool_use n’est émis pour une consultation, et aucun événement agent.thread_message_sent n’apparaît dans le flux d’événements de la session, car l’entrée de la consultation est composée par la plateforme plutôt qu’envoyée par l’agent. Si vous listez les propres événements du fil conseiller, le conseil y apparaît également sous la forme d’un événement agent.thread_message_sent. Il n’est pas garanti que la livraison du conseil (événement 3) arrive avant les événements idle et terminated du fil conseiller ; ne les considérez donc pas comme un signal indiquant que le conseil a déjà été livré.

La possibilité pour votre client de lire le conseil dépend de la politique du modèle conseiller. Elle reflète la distinction des variantes de résultat de l’outil advisor de l’API Messages. Un modèle conseiller qui y renvoie des résultats en texte brut livre ici un texte lisible. Un modèle qui renvoie des résultats masqués livre un espace réservé [{"type": "redacted"}] sur chaque interface client, tandis que l’agent lit toujours le conseil complet côté serveur. L’exemple précédent utilise comme conseiller le modèle Opus le plus récent à votre disposition. Il renvoie des résultats masqués ; votre client ne voit donc que l’espace réservé. Pour lire le conseil dans le flux d’événements, utilisez un conseiller qui renvoie du texte brut, tel que Claude Opus 4.8. La politique d’un modèle peut changer sans modification de l’API ; gérez donc à la fois les blocs text et redacted. Certains modèles d’agent ne s’associent qu’à des conseillers à résultats masqués ; consultez la section Compatibilité des modèles de l’outil advisor. La réflexion du conseiller n’est jamais exposée. Les clients ne peuvent pas envoyer eux-mêmes de blocs redacted ; un événement en contenant un est rejeté avec une erreur de validation 400.

Une consultation échouée ou interrompue ne fait jamais échouer le tour de l’agent : l’agent continue après un avis générique indiquant que la consultation a échoué. Un user.interrupt au niveau de la session pendant une consultation termine le fil conseiller sans qu’aucun conseil ne soit livré ; un user.interrupt avec le session_thread_id du fil conseiller abandonne uniquement cette consultation.

Fils conseillers

Le conseiller n’est pas un sous-agent. L’outil list_agents de l’agent ne l’affiche pas, et send_to_agent, qui envoie un message de suivi à un sous-agent, ne peut pas l’atteindre. Seul le fil principal de la session peut le consulter ; les sous-agents ne le peuvent pas.

Les fils conseillers sont exemptés de la limite de 25 fils enfants. Ils apparaissent dans la liste des fils de la session. Leur agent est la forme conseiller, {"type": "advisor", "model": ...}, avec le modèle que vous avez configuré, et leur parent_thread_id est le fil principal.

La « prompt caching » (mise en cache des prompts) côté conseiller est automatique ; il n’y a rien à configurer. Les consultations sont facturées aux tarifs du modèle conseiller, et leurs tokens apparaissent dans l’utilisation du fil conseiller ainsi que dans les totaux d’utilisation de la session. Elles sont également décomptées d’un budget de session, au prix catalogue du modèle conseiller. Chaque consultation envoie au conseiller la conversation du fil principal jusqu’à ce point ; les consultations tardives dans une longue session consomment donc davantage de tokens d’entrée.

Supprimer le conseiller

Pour supprimer le conseiller, mettez à jour l’agent en définissant advisor sur {"type": "disabled"}. Sur un agent qui possède déjà le type multiagent_20261001, un paramètre omis par la mise à jour conserve sa valeur enregistrée ; vous n’avez donc pas besoin de renvoyer subagents ou workflows. Pour la même raison, une mise à jour qui omet advisor conserve le conseiller. Avant de modifier le multiagent.type d’un agent existant, consultez comment faire passer un agent à ce type.

Migrer depuis le type coordinator

Comme multiagent_20261001, le type coordinator permet à un agent de déléguer à des sous-agents que vous listez et de consulter un modèle conseiller. Avec le type coordinator, l’agent ne peut pas démarrer d’exécutions de workflow ni définir lui-même des sous-agents. L’API accepte les deux types.

Pour faire passer un agent à multiagent_20261001, mettez à jour l’agent avec un bloc multiagent de ce type :

1. Définissez type sur "multiagent_20261001".
2. Listez les agents que l’agent peut appeler dans subagents.predefined_agents. Les entrées conservent la forme qu’elles ont actuellement.
3. Si l’agent dispose d’un conseiller, définissez advisor sur {"type": "enabled", "model": "..."} avec le modèle du conseiller.
4. Envoyez le bloc entier en une seule mise à jour.

Par exemple, ce bloc donne à un agent deux sous-agents et un conseiller :

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Ce bloc omet workflows et subagents.inline_agents ; tous deux reprennent donc leur valeur par défaut et sont activés. L’agent migré peut également démarrer des exécutions de workflow et définir lui-même des sous-agents. Pour maintenir l’un ou l’autre désactivé, définissez-le sur {"type": "disabled"} dans la même mise à jour. Consultez Activer les workflows dynamiques et Agents prédéfinis et inline.

Si l’agent dispose d’un conseiller et d’aucun sous-agent, définissez subagents sur {"type": "disabled"} pour maintenir la délégation désactivée. Une requête qui désactive subagents.inline_agents et ne liste aucun agent échoue avec une erreur 400.

La mise à jour remplace l’intégralité du bloc multiagent ; renvoyez donc la liste des agents et le conseiller, comme le fait l’exemple. Ce que vous omettez reprend sa valeur par défaut :

• subagents.predefined_agents : La liste est vide ; l’agent perd donc les sous-agents que vous aviez listés.
• advisor : Le conseiller est désactivé.

Une fois que l’agent possède le type multiagent_20261001, un paramètre omis par une mise à jour ultérieure conserve sa valeur enregistrée.

La mise à jour ne modifie pas les sessions qui existent déjà. Pour utiliser le nouveau bloc, créez une session après la mise à jour.

Disponibilité