---
title: Orchestration multi-agents
url: https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration
description: Coordonnez plusieurs agents au sein d'une même session.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
La « multiagent orchestration » (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, chacun avec son propre contexte isolé, ce qui contribue à améliorer la qualité des résultats et peut également réduire le délai d'exécution.
Vous n'êtes pas sûr qu'une configuration multi-agents convienne à votre problème ? Consultez [quand utiliser les systèmes multi-agents (et quand ne pas le faire)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them).
## 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 lui-même le travail.
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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run). 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](https://platform.claude.com/docs/fr/managed-agents/session-threads) 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 de session principal 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.
| Approche | Ce qui se passe | Quand l'utiliser | À prendre en compte |
| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sous-agents](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#delegate-to-subagents) | L'agent délègue des tâches à ses sous-agents. Chaque sous-agent travaille dans son propre [fil de session](https://platform.claude.com/docs/fr/managed-agents/session-threads), que vous pouvez lister et diffuser en streaming. | L'agent doit envoyer un message de suivi à un sous-agent après que celui-ci a rendu compte, ou il a besoin de spécialistes que vous listez, avec leurs propres invites système et outils. | La délégation ne s'étend que sur un niveau, et une session peut avoir au maximum 25 fils enfants à la fois, y compris les fils inactifs. Les fils du conseiller et les fils d'une exécution de workflow ne sont pas comptés. |
| [Workflows dynamiques](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#dynamic-workflows) | L'agent écrit un workflow : un programme qui exécute de nombreux agents par phases et combine leurs résultats. Le serveur l'exécute en arrière-plan sous la forme d'une exécution de workflow, que vous pouvez suivre. Le workflow définit les agents ou les choisit dans une liste que vous fournissez. | La plupart des travaux qui nécessitent plus d'un agent : un travail comportant de nombreuses parties, un travail parallèle, ou une tâche longue qui devrait se terminer plus tôt. Les audits, les migrations, la recherche approfondie et la vérification croisée en sont des exemples. | Chaque agent d'une exécution consomme des tokens ; définissez donc un [budget de session](https://platform.claude.com/docs/fr/managed-agents/budgets) pour plafonner les dépenses de la session, exécutions comprises. Indiquez à l'agent dans son invite système quand utiliser une exécution. Vous suivez l'exécution par ses phases et pouvez lire chacun de ses fils. |
| [Donner un conseiller à la session](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | Le [fil principal](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#how-it-works) de la session consulte un modèle conseiller en cours de tour pour obtenir des conseils, par exemple pour planifier une approche ou relire un travail, et continue d'effectuer lui-même le travail. | Un seul agent doit effectuer le travail, avec le jugement d'un modèle conseiller aux moments clés, comme la planification ou une relecture finale. | Seul le fil principal peut consulter le conseiller, et les consultations sont facturées aux tarifs du modèle conseiller. |
Vous configurez ces mécanismes 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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents) :
```json
{
"multiagent": { "type": "multiagent_20261001" }
}
```
Pour définir quels agents l'agent peut appeler, consultez [Agents prédéfinis et agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Pour désactiver un paramètre, consultez [Activer les workflows dynamiques](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
## 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éé](https://platform.claude.com/docs/fr/managed-agents/agent-setup), et que vous listez dans le bloc `multiagent` (csharp, go: `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 au moment où 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` :
| Type d'agent | Sous `subagents` | Sous `workflows` |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prédéfini | L'agent peut déléguer aux agents que vous listez dans `subagents.predefined_agents`. | Un workflow peut utiliser les agents que vous listez dans `workflows.predefined_agents`. |
| Inline | L'agent peut définir un agent inline lorsqu'il délègue. `subagents.inline_agents` active ou désactive cette possibilité. | Un workflow peut définir des agents inline, et il écrit une invite système pour chacun. `workflows.inline_agents` active ou désactive cette possibilité. |
`subagents.predefined_agents` et `workflows.predefined_agents` sont deux listes distinctes. Un agent figurant 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 des formes suivantes :
* `{"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 l'agent au moment où l'agent qui la 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](https://platform.claude.com/docs/fr/managed-agents/sessions#override-agent-configuration-for-a-session), 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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#list-the-subagents).
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 se présentent 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 :
```json
{
"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 diverses surfaces, soit plusieurs tâches bien délimitées contribuant à un objectif global.
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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
### Fonctionnement
Tous les agents partagent le même sandbox, le même système de fichiers et les mêmes [identifiants de coffre](https://platform.claude.com/docs/fr/managed-agents/vaults), 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 rapporte son activité dans le « primary thread » (fil principal), qui est le [flux d'événements](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming) 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 message de 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 de s'il s'agit d'un [agent prédéfini ou d'un agent inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Les [remplacements de configuration d'agent](https://platform.claude.com/docs/fr/managed-agents/sessions#override-agent-configuration-for-a-session) 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](https://platform.claude.com/docs/fr/managed-agents/agent-setup), définissez la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) dans le bloc `multiagent` (csharp, go: `Multiagent`) pour lister les agents auxquels il peut déléguer :
```bash cURL
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 '{
"name": "Engineering Lead",
"model": "claude-opus-5-5",
"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": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [
{"type": "agent", "id": "'"$REVIEWER_AGENT_ID"'"},
{"type": "agent", "id": "'"$TEST_WRITER_AGENT_ID"'"}
]
}
}
}'
```
```bash CLI
ant apply engineering-lead.md reviewer.md test-writer.md
```
```markdown
---
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.
```
```markdown
---
name: reviewer
model: claude-haiku-5-5
---
You are a code reviewer.
```
```markdown
---
name: test-writer
model: claude-haiku-5-5
---
You write unit tests.
```
```python Python
lead_agent = client.beta.agents.create(
name="Engineering Lead",
model="claude-opus-5-5",
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": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [
{"type": "agent", "id": reviewer_agent.id},
{"type": "agent", "id": test_writer_agent.id},
],
},
},
)
```
```typescript TypeScript
const leadAgent = await client.beta.agents.create({
name: "Engineering Lead",
model: "claude-opus-5-5",
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: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{ type: "agent", id: reviewerAgent.id },
{ type: "agent", id: testWriterAgent.id }
]
}
}
});
```
```csharp C#
var leadAgent = await client.Beta.Agents.Create(new()
{
Name = "Engineering Lead",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
{
PredefinedAgents = [reviewerAgent.ID, testWriterAgent.ID],
},
},
});
```
```go Go
leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Engineering Lead",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
System: anthropic.String("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{
{OfString: anthropic.String(reviewerAgent.ID)},
{OfString: anthropic.String(testWriterAgent.ID)},
},
},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var leadAgent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Engineering Lead")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(reviewerAgent.id())
.build())
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(testWriterAgent.id())
.build())
.build())
.build())
.build()
);
```
```php PHP
$leadAgent = $client->beta->agents->create(
name: 'Engineering Lead',
model: 'claude-opus-5-5',
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' => 'multiagent_20261001',
'subagents' => [
'type' => 'enabled',
'predefined_agents' => [
['type' => 'agent', 'id' => $reviewerAgent->id],
['type' => 'agent', 'id' => $testWriterAgent->id],
],
],
],
);
```
```ruby Ruby
lead_agent = client.beta.agents.create(
name: "Engineering Lead",
model: "claude-opus-5-5",
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: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{type: "agent", id: reviewer_agent.id},
{type: "agent", id: test_writer_agent.id}
]
}
}
)
```
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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), consultez [Agents prédéfinis et agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
`"advisor": {"type": "enabled", "model": ""}` 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` (csharp, go: `Multiagent`), et non une entrée de cette liste. Consultez [Donner un conseiller à la session](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
Les règles suivantes s'appliquent aux agents que vous listez dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), ainsi qu'aux agents que vous listez dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) :
* **Épinglage :** la configuration de l'agent, y compris la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), est figée au moment où l'agent est créé ou mis à jour. 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](https://platform.claude.com/docs/fr/managed-agents/agent-setup#update-an-agent) afin que la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `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` (csharp, go: `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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) peut lister jusqu'à 20 agents uniques. La limite s'applique par liste : la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) peut également en lister jusqu'à 20. L'agent peut appeler plusieurs copies de chaque sous-agent, dans la limite de [fils](https://platform.claude.com/docs/fr/managed-agents/session-threads) de la session.
* **Géographie d'inférence :** l'agent et chaque agent que vous listez, dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`), doivent épingler la même [géographie d'inférence](https://platform.claude.com/docs/fr/manage-claude/data-residency) (`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) dans le `model` (csharp, go: `Model`) de la [définition de l'agent](https://platform.claude.com/docs/fr/managed-agents/agent-setup)), 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 lorsque l'agent est enregistré et lorsqu'un [remplacement à la création de session](https://platform.claude.com/docs/fr/managed-agents/sessions#override-agent-configuration-for-a-session) modifie l'un des épinglages.
### Créer la session
Créez une session qui référence l'agent. L'agent délègue selon les besoins aux agents que vous listez dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`). Il peut également déléguer à des [agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents), sauf si vous les désactivez.
```bash cURL
curl -fsSL 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": "'"$LEAD_AGENT_ID"'",
"environment_id": "'"$ENVIRONMENT_ID"'"
}'
```
```bash CLI
ant beta:sessions create \
--agent "$LEAD_AGENT_ID" \
--environment-id "$ENVIRONMENT_ID"
```
```python Python
session = client.beta.sessions.create(
agent=lead_agent.id,
environment_id=environment.id,
)
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: leadAgent.id,
environment_id: environment.id
});
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = leadAgent.ID,
EnvironmentID = environment.ID,
});
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(leadAgent.ID),
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(leadAgent.id())
.environmentId(environment.id())
.build());
```
```php PHP
$session = $client->beta->sessions->create(
agent: $leadAgent->id,
environmentID: $environment->id,
);
```
```ruby Ruby
session = client.beta.sessions.create(
agent: lead_agent.id,
environment_id: environment.id
)
```
### Connecter les agents aux 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` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) 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 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. 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` (java, php: `inlineAgents`; csharp, go: `InlineAgents`) à la fois dans `subagents` (csharp, go: `Subagents`) et dans `workflows` (csharp, go: `Workflows`), et listez au moins un agent dans chacun. Consultez [Agents prédéfinis et agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Les [remplacements de configuration d'agent](https://platform.claude.com/docs/fr/managed-agents/sessions#override-agent-configuration-for-a-session) lors de la création de la session peuvent remplacer les serveurs MCP de l'agent qu'exécute la session ainsi que ceux de ses copies `self`.
Avec un [environnement](https://platform.claude.com/docs/fr/managed-agents/environments#networking) `limited`, la création de la session échoue avec une erreur 400 lorsque l'agent, ou un agent que vous listez dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`), déclare un serveur MCP dont l'hôte ne figure pas dans `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Définir `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 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 :
```bash cURL
# Create the researcher
curl --fail-with-body -sS 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 '{
"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"}]
}'
# Create the agent that delegates to it: research_agent_id is the id from the first response
curl --fail-with-body -sS 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 '{
"name": "lead",
"model": "claude-opus-5-5",
"tools": [{"type": "agent_toolset_20260401"}],
"multiagent": {
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}]
}
}
}'
```
```bash CLI
ant apply lead.md researcher.md
```
```markdown
---
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
---
```
```markdown
---
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
---
```
```python Python
research_agent = client.beta.agents.create(
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"}],
)
lead_agent = client.beta.agents.create(
name="lead",
model="claude-opus-5-5",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [{"type": "agent", "id": research_agent.id}],
},
},
)
```
```typescript TypeScript
const researchAgent = await client.beta.agents.create({
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" }]
});
const leadAgent = await client.beta.agents.create({
name: "lead",
model: "claude-opus-5-5",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [{ type: "agent", id: researchAgent.id }]
}
}
});
```
```csharp C#
var researchAgent = await client.Beta.Agents.Create(new()
{
Name = "researcher",
Model = BetaManagedAgentsModel.ClaudeHaiku5_5,
McpServers =
[
new()
{
Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
Name = "github",
Url = "https://api.githubcopilot.com/mcp/",
},
],
Tools =
[
new BetaManagedAgentsMcpToolsetParams
{
Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
McpServerName = "github",
},
],
});
var leadAgent = await client.Beta.Agents.Create(new()
{
Name = "lead",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
{
PredefinedAgents =
[
new BetaManagedAgentsAgentParams
{
Type = BetaManagedAgentsAgentParamsType.Agent,
ID = researchAgent.ID,
},
],
},
},
});
```
```go Go
researcher, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "researcher",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku5_5},
MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
Name: "github",
URL: "https://api.githubcopilot.com/mcp/",
}},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
MCPServerName: "github",
},
}},
})
if err != nil {
panic(err)
}
leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "lead",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: researcher.ID,
},
}},
},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var researcher = client.beta().agents().create(
AgentCreateParams.builder()
.name("researcher")
.model(BetaManagedAgentsModel.CLAUDE_HAIKU_5_5)
.addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
.name("github")
.type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
.url("https://api.githubcopilot.com/mcp/")
.build())
.addTool(BetaManagedAgentsMcpToolsetParams.builder()
.type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
.mcpServerName("github")
.build())
.build()
);
var leadAgent = client.beta().agents().create(
AgentCreateParams.builder()
.name("lead")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build())
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(researcher.id())
.build())
.build())
.build())
.build()
);
```
```php PHP
$researchAgent = $client->beta->agents->create(
name: 'researcher',
model: 'claude-haiku-5-5',
mcpServers: [
['type' => 'url', 'name' => 'github', 'url' => 'https://api.githubcopilot.com/mcp/'],
],
tools: [
['type' => 'mcp_toolset', 'mcp_server_name' => 'github'],
],
);
$leadAgent = $client->beta->agents->create(
name: 'lead',
model: 'claude-opus-5-5',
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: [
'type' => 'multiagent_20261001',
'subagents' => [
'type' => 'enabled',
'predefined_agents' => [
['type' => 'agent', 'id' => $researchAgent->id],
],
],
],
);
```
```ruby Ruby
research_agent = client.beta.agents.create(
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"}
]
)
lead_agent = client.beta.agents.create(
name: "lead",
model: "claude-opus-5-5",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{type: "agent", id: research_agent.id}
]
}
}
)
```
Créez ensuite la session avec le coffre qui contient l'identifiant GitHub :
```bash cURL
curl --fail-with-body -sS 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": "'"$lead_agent_id"'",
"environment_id": "'"$environment_id"'",
"vault_ids": ["'"$vault_id"'"]
}'
```
```bash CLI
ant beta:sessions create \
--agent "$lead_agent_id" \
--environment-id "$environment_id" \
--vault-id "$vault_id"
```
```python Python
session = client.beta.sessions.create(
agent=lead_agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
)
print(session.id)
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: leadAgent.id,
environment_id: environment.id,
vault_ids: [vault.id]
});
console.log(session.id);
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = leadAgent.ID,
EnvironmentID = environment.ID,
VaultIds = [vault.ID],
});
Console.WriteLine(session.ID);
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(leadAgent.ID),
},
EnvironmentID: environment.ID,
VaultIDs: []string{vault.ID},
})
if err != nil {
panic(err)
}
fmt.Println(session.ID)
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(leadAgent.id())
.environmentId(environment.id())
.vaultIds(List.of(vault.id()))
.build());
IO.println(session.id());
```
```php PHP
$session = $client->beta->sessions->create(
agent: $leadAgent->id,
environmentID: $environment->id,
vaultIDs: [$vault->id],
);
echo "{$session->id}\n";
```
```ruby Ruby
session = client.beta.sessions.create(
agent: lead_agent.id,
environment_id: environment.id,
vault_ids: [vault.id]
)
puts session.id
```
Dans cet exemple, seul le chercheur déclare le serveur MCP GitHub ; l'agent qu'exécute la session n'y a donc pas accès. Les `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) de la session fournissent l'identifiant GitHub au fil du chercheur.
Si l'authentification des appels MCP d'un agent échoue après que vous avez déclaré le serveur, vérifiez que le `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) de l'identifiant désigne le même serveur que le `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`) de l'agent. Les deux URL sont normalisées avant la comparaison (schéma et hôte mis en minuscules, ports par défaut et barres obliques finales supprimés) ; ainsi, des différences de casse de l'hôte, un port par défaut ou une barre oblique finale n'empêchent pas la correspondance, contrairement à un chemin, un sous-domaine ou un port non par défaut différent.
### 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](https://platform.claude.com/docs/fr/managed-agents/session-threads).
## 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'une **« 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` (csharp, go: `Workflows`) du bloc `multiagent` (csharp, go: `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 là, l'agent détermine s'il faut démarrer une exécution et à quel moment ; aucun appel d'API supplémentaire n'est donc nécessaire. 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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents) que le workflow définit, des agents prédéfinis que vous listez dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `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](https://platform.claude.com/docs/fr/managed-agents/session-threads) que vous pouvez lister, lire et suivre en streaming. Consultez [Exécutions de workflow](https://platform.claude.com/docs/fr/managed-agents/workflow-runs) pour les événements, les interruptions, les [limites](https://platform.claude.com/docs/fr/managed-agents/workflow-runs#limits) et [ce que montrent les fils d'une exécution](https://platform.claude.com/docs/fr/managed-agents/workflow-runs#a-runs-threads).
### Activer les workflows dynamiques
Lors de la [définition de votre agent](https://platform.claude.com/docs/fr/managed-agents/agent-setup), 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 n'utiliser que les workflows dynamiques, ajoutez `"subagents": {"type": "disabled"}`.
Avant de modifier le `multiagent.type` d'un agent existant, consultez [comment faire passer un agent à ce type](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).
```bash cURL
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 '{
"name": "Contract Reviewer",
"model": "claude-opus-5-5",
"system": "You review contracts. When you are 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.",
"tools": [{"type": "agent_toolset_20260401"}],
"multiagent": {"type": "multiagent_20261001", "workflows": {"type": "enabled"}}
}'
```
```bash CLI
ant apply contract-reviewer.md
```
```markdown
---
name: Contract Reviewer
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
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.
```
```python Python
agent = client.beta.agents.create(
name="Contract Reviewer",
model="claude-opus-5-5",
system="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.",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={"type": "multiagent_20261001", "workflows": {"type": "enabled"}},
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Contract Reviewer",
model: "claude-opus-5-5",
system:
"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.",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: { type: "multiagent_20261001", workflows: { type: "enabled" } }
});
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Contract Reviewer",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "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.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
// La classe de configuration définit le type pour vous.
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Workflows = new BetaManagedAgentsMultiagentWorkflowsEnabledParams(),
},
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Contract Reviewer",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
System: anthropic.String("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."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Workflows: anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentWorkflowsEnabledParams{},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Contract Reviewer")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("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.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
// La classe de configuration définit le type pour vous.
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.workflows(BetaManagedAgentsMultiagentWorkflowsEnabledParams.builder().build())
.build())
.build()
);
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Contract Reviewer',
model: 'claude-opus-5-5',
system: "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.",
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: ['type' => 'multiagent_20261001', 'workflows' => ['type' => 'enabled']],
);
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Contract Reviewer",
model: "claude-opus-5-5",
system_: "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.",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {type: "multiagent_20261001", workflows: {type: "enabled"}}
)
```
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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#delegate-to-subagents). Pour définir un conseiller, consultez [Donner un conseiller à la session](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Cet agent permet à un workflow d'utiliser un agent que vous avez créé, liste deux sous-agents et dispose d'un conseiller :
```json
{
"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 :
| Paramètre | Ce qu'il active | Emplacement des agents | Valeur par défaut |
| ----------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------- |
| `workflows` | Workflows dynamiques | `workflows.predefined_agents`, jusqu'à 20 | Activé |
| `subagents` | Délégation à des sous-agents : les agents que vous listez et les agents que l'agent définit lui-même | `subagents.predefined_agents`, jusqu'à 20 | Activé |
| `advisor` | Un modèle conseiller | Aucun. Définissez `model`. | Désactivé |
Pour savoir ce qui figure dans chaque liste, et comment n'autoriser que les agents que vous listez, consultez [Agents prédéfinis et agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
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` prend 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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 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 en omettez prennent 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é ». Il en va de même pour `subagents`.
* **Sessions existantes :** Une session copie le paramètre lors de sa création ; modifier l'agent ultérieurement ne modifie donc pas une session qui existe déjà.
* **Agents que vous pouvez lister :** Un agent pour lequel `multiagent` (csharp, go: `Multiagent`) est défini ne peut pas être listé comme sous-agent d'un autre agent, ni dans la liste `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `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` (csharp, go: `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 que celle qui active les workflows dynamiques. Consultez [Outils personnalisés](https://platform.claude.com/docs/fr/managed-agents/tools#custom-tools).
* **Budget :** Définissez un [budget de session](https://platform.claude.com/docs/fr/managed-agents/budgets) lors de la création de la session pour plafonner les dépenses de la session, exécutions comprises ; vous ne pouvez pas en ajouter un à une session existante. Les exécutions se mettent 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](https://platform.claude.com/docs/fr/managed-agents/workflow-runs#cost-and-budgets).
### Indiquer à l'agent quand utiliser une exécution
L'activation des workflows dynamiques donne à l'agent la capacité de démarrer des exécutions de workflow. L'agent détermine quand en démarrer une. Pour orienter ce choix, ajoutez une instruction comme la suivante à l'invite système de l'agent. L'agent de révision de contrats de [Activer les workflows dynamiques](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) utilise cette invite système :
```text wrap
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 manière dont une exécution réalise 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, indiquez 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. Puis attendez mon feu vert. » Il n'existe aucune é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](https://platform.claude.com/docs/fr/managed-agents/sessions) 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 avec des exécutions ouvertes, ce qui change pendant qu'une exécution est ouverte, ainsi que les budgets et limites, consultez [Exécutions de workflow](https://platform.claude.com/docs/fr/managed-agents/workflow-runs).
## Donner un conseiller à la session
Un paramètre `advisor` activé dans le bloc `multiagent` (csharp, go: `Multiagent`) de l'agent donne au fil principal de la session un **« advisor » (conseiller)** : un modèle qu'il peut consulter en cours de tour pour obtenir des conseils stratégiques, par exemple pour planifier une approche, se débloquer ou relire le travail avant de terminer. Le 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` :
```bash cURL
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 '{
"name": "Backend engineer",
"model": "claude-sonnet-5",
"system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
"multiagent": {
"type": "multiagent_20261001",
"advisor": {"type": "enabled", "model": "claude-opus-5-5"}
}
}'
```
```bash CLI
ant apply backend-engineer.md
```
```markdown
---
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.
```
```python Python
agent = client.beta.agents.create(
name="Backend engineer",
model="claude-sonnet-5",
system="You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent={
"type": "multiagent_20261001",
"advisor": {"type": "enabled", "model": "claude-opus-5-5"},
},
)
print(agent.id)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Backend engineer",
model: "claude-sonnet-5",
system:
"You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent: {
type: "multiagent_20261001",
advisor: { type: "enabled", model: "claude-opus-5-5" }
}
});
console.log(agent.id);
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Backend engineer",
Model = BetaManagedAgentsModel.ClaudeSonnet5,
System = "You implement backend features end to end. Consult the advisor before major backend design decisions.",
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Advisor = new BetaManagedAgentsMultiagentAdvisorEnabledParams { Model = "claude-opus-5-5" },
},
});
Console.WriteLine(agent.ID);
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Backend engineer",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeSonnet5},
System: anthropic.String("You implement backend features end to end. Consult the advisor before major backend design decisions."),
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Advisor: anthropic.BetaManagedAgentsMultiagentAdvisorParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentAdvisorEnabledParams{
Model: "claude-opus-5-5",
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(agent.ID)
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Backend engineer")
.model(BetaManagedAgentsModel.CLAUDE_SONNET_5)
.system("You implement backend features end to end. Consult the advisor before major backend design decisions.")
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.advisor(BetaManagedAgentsMultiagentAdvisorEnabledParams.builder()
.model("claude-opus-5-5")
.build())
.build())
.build()
);
IO.println(agent.id());
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Backend engineer',
model: 'claude-sonnet-5',
system: 'You implement backend features end to end. Consult the advisor before major backend design decisions.',
multiagent: [
'type' => 'multiagent_20261001',
'advisor' => ['type' => 'enabled', 'model' => 'claude-opus-5-5'],
],
);
echo $agent->id, PHP_EOL;
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Backend engineer",
model: "claude-sonnet-5",
system_: "You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent: {
type: "multiagent_20261001",
advisor: {type: "enabled", model: "claude-opus-5-5"}
}
)
puts agent.id
```
Cet exemple définit uniquement `advisor` (csharp, go: `Advisor`). Les deux autres paramètres, `subagents` (csharp, go: `Subagents`) et `workflows` (csharp, go: `Workflows`), conservent leurs valeurs par défaut, donc tous deux sont 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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`). Un `advisor` (csharp, go: `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 propre modèle de l'agent 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/advisor-tool#model-compatibility) de l'outil conseiller.
Le conseiller est également disponible en tant qu'[outil serveur sur l'API Messages](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/advisor-tool). L'interface Managed Agents diffère en matière de configuration et de livraison : le paramètre `advisor` (csharp, go: `Advisor`) ne comporte pas de champs `max_uses`, `max_tokens` ou `caching`, et les conseils arrivent via des événements de fil plutôt que via des 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 de cycle de vie du fil le portent en tant que `agent_name` (java, php: `agentName`; csharp, go: `AgentName`), et la livraison du conseil le porte en tant que `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`)), 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 événements du fil du conseiller lui-même, 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 d'inactivité et de terminaison du fil du 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/advisor-tool#result-variants) de l'outil conseiller de l'API Messages. Un modèle conseiller qui y renvoie des résultats en texte brut livre ici du 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. Claude Opus 5.5 renvoie des résultats masqués, donc votre client ne voit que l'espace réservé. Pour lire le conseil dans le flux d'événements, utilisez un conseiller qui renvoie du texte brut, comme 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 peuvent être associés qu'à des conseillers à résultats masqués ; consultez le [tableau de compatibilité](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/advisor-tool#model-compatibility) de l'outil conseiller. 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 du conseiller sans qu'aucun conseil ne soit livré ; un `user.interrupt` avec le `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) du fil du conseiller abandonne uniquement cette consultation.
### Fils du conseiller
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 du conseiller sont exemptés de la limite de 25 fils enfants. Ils apparaissent dans la [liste des fils](https://platform.claude.com/docs/fr/managed-agents/session-threads) de la session. Leur `agent` prend 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 du conseiller ainsi que dans les totaux d'utilisation de la session. Elles sont également décomptées d'un [budget de session](https://platform.claude.com/docs/fr/managed-agents/budgets), au tarif public 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](https://platform.claude.com/docs/fr/managed-agents/agent-setup#update-an-agent) avec `advisor` défini 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](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#move-from-the-coordinator-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](https://platform.claude.com/docs/fr/managed-agents/agent-setup#update-an-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 leur forme actuelle.
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 :
```json
{
"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 prennent 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 désactiver l'un ou l'autre, définissez-le sur `{"type": "disabled"}` dans la même mise à jour. Consultez [Activer les workflows dynamiques](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) et [Agents prédéfinis et agents inline](https://platform.claude.com/docs/fr/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
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 prend 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.