---
title: Orchestrazione multiagente
url: https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration
description: Coordina più agenti all'interno di una singola sessione.
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" (orchestrazione multiagente) consente a un agente di coordinarsi con altri per completare lavori complessi. Gli agenti possono agire in parallelo, ciascuno con il proprio contesto isolato. Questo aiuta a migliorare la qualità dell'output e può anche migliorare i tempi di completamento.
Non sei sicuro che una configurazione multiagente sia adatta al tuo problema? Consulta [quando usare i sistemi multiagente (e quando no)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them).
## Affidare il lavoro ad altri agenti
L'agente eseguito da una sessione può affidare il lavoro ad altri agenti in due modi. Con i "subagents" (**subagenti**), delega esso stesso le attività e legge ciò che ogni subagente riporta. Con i "dynamic workflows" (**workflow dinamici**), scrive un workflow: un programma che esegue molti agenti in background e combina i loro risultati. Può anche consultare un modello **advisor** (consulente) per ricevere indicazioni mentre svolge il lavoro da sé.
Sei tu a decidere quali di questi l'agente può usare, e l'agente determina quando usarli. Per guidare questa scelta, indica all'agente nel suo prompt di sistema quando usare un'esecuzione di workflow. Consulta [Indicare all'agente quando usare un'esecuzione](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run). Puoi anche limitare l'agente agli agenti che elenchi.
Con i subagenti, è l'agente stesso a determinare cosa succede dopo. Il [thread di un subagente](https://platform.claude.com/docs/it/managed-agents/session-threads) rimane disponibile finché non lo archivi, quindi l'agente può inviargli messaggi di follow-up. Con i workflow dinamici, Claude scrive un programma per orchestrare gli agenti senza il coinvolgimento diretto di Claude. Il contesto e i risultati vengono passati in modo programmatico da un agente all'altro, liberando il thread principale della sessione per comunicare con l'utente e controllare uno o più workflow in esecuzione per riferire sui progressi. L'agente non può inviare messaggi di follow-up ai thread di un'esecuzione, e il server archivia ciascuno di essi entro la fine della sua esecuzione.
| Approccio | Cosa succede | Usalo quando | Considera |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Subagenti](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#delegate-to-subagents) | L'agente delega le attività ai suoi subagenti. Ogni subagente lavora nel proprio "session thread" ([thread di sessione](https://platform.claude.com/docs/it/managed-agents/session-threads)), che puoi elencare e seguire in streaming. | L'agente deve fare un follow-up con un subagente dopo che questo ha riferito, oppure ha bisogno di specialisti che elenchi tu, con i propri prompt di sistema e strumenti. | La delega ha un solo livello di profondità, e una sessione può avere al massimo 25 thread figli alla volta, inclusi quelli inattivi. I thread advisor e i thread di un'esecuzione di workflow non contano. |
| [Workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#dynamic-workflows) | L'agente scrive un workflow: un programma che esegue molti agenti in fasi e combina i loro risultati. Il server lo esegue in background come un'unica esecuzione di workflow, che puoi seguire. Il workflow definisce gli agenti o li sceglie da un elenco che fornisci. | La maggior parte del lavoro che richiede più di un agente: lavoro composto da molte parti, lavoro parallelo o un'attività lunga che dovrebbe terminare prima. Esempi sono audit, migrazioni, ricerche approfondite e verifiche incrociate. | Ogni agente in un'esecuzione consuma token, quindi imposta un [budget di sessione](https://platform.claude.com/docs/it/managed-agents/budgets) per limitare la spesa della sessione, esecuzioni incluse. Indica all'agente nel suo prompt di sistema quando usare un'esecuzione. Segui l'esecuzione attraverso le sue fasi e puoi leggere ciascuno dei suoi thread. |
| [Fornisci un advisor alla sessione](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | Il [thread principale](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#how-it-works) della sessione consulta un modello advisor a metà turno per ricevere indicazioni, ad esempio per pianificare un approccio o rivedere il lavoro, e continua a svolgere il lavoro da sé. | Un solo agente deve svolgere il lavoro, con il giudizio di un modello advisor nei momenti chiave come la pianificazione o una revisione finale. | Solo il thread principale può consultare l'advisor, e le consultazioni vengono fatturate alle tariffe del modello advisor. |
Configuri questi elementi nel blocco `multiagent` della definizione dell'agente, che ha un `type`. Con il tipo `multiagent_20261001`, un agente può usarli tutti e tre insieme, e puoi attivare o disattivare ciascuno di essi. Per impostazione predefinita, `subagents` e `workflows` sono entrambi abilitati. `subagents` e `workflows` hanno ciascuno `inline_agents` abilitato, l'impostazione per gli [agenti che l'agente o un workflow definisce da sé](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents):
```json
{
"multiagent": { "type": "multiagent_20261001" }
}
```
Per impostare quali agenti l'agente può chiamare, consulta [Agenti predefiniti e inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Per disattivare un'impostazione, consulta [Attiva i workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
## Agenti predefiniti e inline
Ogni subagente, e ogni agente in un'esecuzione di workflow, è di uno di due tipi:
* **Agente predefinito:** Un agente che hai già [creato](https://platform.claude.com/docs/it/managed-agents/agent-setup) e che elenchi nel blocco `multiagent` (csharp, go: `Multiagent`). Usa la propria configurazione: modello, prompt di sistema, strumenti, server MCP e skill.
* **Agente inline:** Un agente che non è salvato. L'agente eseguito dalla sessione, o un workflow, lo definisce quando assegna il lavoro. Usa il modello, gli strumenti, i server MCP e le skill di quell'agente.
Entrambi i tipi funzionano sotto `subagents` e sotto `workflows`:
| Tipo di agente | Sotto `subagents` | Sotto `workflows` |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Predefinito | L'agente può delegare agli agenti che elenchi in `subagents.predefined_agents`. | Un workflow può usare gli agenti che elenchi in `workflows.predefined_agents`. |
| Inline | L'agente può definire un agente inline quando delega. `subagents.inline_agents` attiva o disattiva questa possibilità. | Un workflow può definire agenti inline, e scrive un prompt di sistema per ciascuno. `workflows.inline_agents` attiva o disattiva questa possibilità. |
`subagents.predefined_agents` e `workflows.predefined_agents` sono due elenchi separati. Un agente in un elenco non viene aggiunto all'altro. Entrambi gli elenchi sono vuoti per impostazione predefinita. Una voce di ciascun elenco assume una di queste forme:
* `{"type": "agent", "id": agent.id}` fa riferimento tramite ID a un `agent` creato in precedenza. Se non viene specificata alcuna `version`, il riferimento viene fissato all'ultima versione dell'agente quando viene creato l'agente che lo elenca, o quando un aggiornamento invia l'elenco.
* `{"type": "agent", "id": agent.id, "version": agent.version}` fissa una versione specifica dell'agente.
* `agent.id` da solo, come stringa, è l'abbreviazione di `{"type": "agent", "id": agent.id}`.
* `{"type": "self"}` elenca l'agente stesso, in modo che sue copie possano svolgere il lavoro. Se la sessione è stata creata con [override della configurazione dell'agente](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session), tali override si applicano anche a queste copie. Le voci referenziate tramite ID non sono interessate.
Le regole per queste voci, e per gli agenti che nominano, si applicano a entrambi gli elenchi. Consulta [Elenca i subagenti](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#list-the-subagents).
Gli agenti inline sono attivi per impostazione predefinita in entrambe le impostazioni. Per consentire solo gli agenti che elenchi, imposta `inline_agents` su `{"type": "disabled"}` sotto `subagents`, sotto `workflows` o sotto entrambi. Un'impostazione con gli agenti inline disattivati richiede almeno un agente nel suo elenco `predefined_agents`. Con un elenco vuoto, la richiesta fallisce con un errore 400. In un aggiornamento, il server verifica le impostazioni così come risultano dopo l'aggiornamento.
L'agente seguente consente solo gli agenti che elenca. Può delegare a un agente e a copie di sé stesso, e un workflow può usare la versione 2 di un altro agente:
```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 }
]
}
}
}
```
## Delegare ai subagenti
### Cosa delegare
Il coordinamento multiagente è più adatto alle attività complesse che richiedono lavoro su superfici diverse, oppure a quelle in cui più attività ben delimitate contribuiscono a un obiettivo complessivo.
Schemi che funzionano bene:
* **Parallelizzazione:** Distribuisci simultaneamente sottoattività indipendenti (ricerca in più fonti, analisi di file separati) e fai sintetizzare i risultati all'agente.
* **Specializzazione:** Indirizza il lavoro ad agenti con prompt di sistema e strumenti specifici per un dominio, come un agente per la sicurezza o un agente per la documentazione, invece di caricare un singolo agente con tutte le capacità.
* **Escalation:** Consulta un agente o un modello più capace per un sottoinsieme di sottoattività complesse. Per consultare un modello, [fornisci un advisor alla sessione](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
### Come funziona
Tutti gli agenti condividono la stessa sandbox, lo stesso filesystem e le stesse [credenziali del vault](https://platform.claude.com/docs/it/managed-agents/vaults), ma ogni agente viene eseguito nel proprio **thread di sessione**, uno stream di eventi con contesto isolato e con la propria cronologia di conversazione. L'agente eseguito dalla sessione riporta l'attività nel **thread principale**, che è lo [stream di eventi](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) a livello di sessione. Thread aggiuntivi vengono generati in fase di esecuzione quando delega il lavoro. Anche un'esecuzione di workflow crea thread.
Il thread di un subagente è persistente. L'agente può inviare un follow-up a un subagente chiamato in precedenza, e quel subagente conserva tutto il contenuto dei suoi turni precedenti.
La configurazione usata da un subagente dipende dal fatto che sia un [agente predefinito o inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Gli [override della configurazione dell'agente](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session) a livello di sessione si applicano all'agente eseguito dalla sessione e alle sue copie `self`. Ogni agente mantiene la propria cronologia di conversazione.
### Elenca i subagenti
Quando [definisci il tuo agente](https://platform.claude.com/docs/it/managed-agents/agent-setup), imposta l'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) nel blocco `multiagent` (csharp, go: `Multiagent`) per elencare gli agenti a cui può delegare:
```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'agente può anche delegare ad agenti inline, a meno che tu non li disattivi. Per questa impostazione, e per le forme che può assumere una voce dell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`), consulta [Agenti predefiniti e inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
`"advisor": {"type": "enabled", "model": ""}` fornisce al thread principale della sessione un advisor che può consultare a metà turno. L'advisor è un'impostazione del blocco `multiagent` (csharp, go: `Multiagent`), non una voce di questo elenco. Consulta [Fornisci un advisor alla sessione](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
Anche i workflow dinamici sono abilitati per impostazione predefinita con questo tipo, quindi questo agente può pianificare lavori di grandi dimensioni che eseguono molti agenti in background. Per disattivarli, o per elencare gli agenti che un workflow può usare, consulta [Attiva i workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
Le seguenti regole si applicano agli agenti che inserisci nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`), e anche agli agenti che inserisci nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`):
* **Versioni fissate:** La configurazione dell'agente, incluso l'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`), viene acquisita come snapshot quando l'agente viene creato o aggiornato. Gli agenti referenziati restano fissati alle versioni risolte in quel momento e non recepiscono gli aggiornamenti successivi alle loro definizioni. Un aggiornamento che non invia l'elenco mantiene le versioni già fissate. Per delegare a una versione più recente di un agente referenziato, [aggiorna l'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent) in modo che l'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) faccia riferimento a quella versione.
* **Un solo livello:** L'agente può delegare a un solo livello di agenti. Fare riferimento a un altro agente che ha `multiagent` (csharp, go: `Multiagent`) impostato fa fallire la richiesta di creazione o aggiornamento con un errore di validazione 400.
* **Fino a 20 agenti:** L'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) può elencare fino a 20 agenti univoci. Il limite è per elenco: anche l'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`) può elencarne fino a 20. L'agente può chiamare più copie di ciascun subagente, entro il [limite di thread](https://platform.claude.com/docs/it/managed-agents/session-threads) della sessione.
* **Area geografica di inferenza:** L'agente e ogni agente che elenchi, nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) o di `workflows` (csharp, go: `Workflows`), devono fissare la stessa [area geografica di inferenza](https://platform.claude.com/docs/it/manage-claude/data-residency) (`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) nel `model` (csharp, go: `Model`) della [definizione dell'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup)), oppure nessuno di essi può fissarne una. Una mancata corrispondenza in uno dei due elenchi viene rifiutata con un errore di validazione 400. Questo controllo viene eseguito sia quando l'agente viene salvato sia quando un [override alla creazione della sessione](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session) modifica uno qualsiasi dei valori fissati.
### Crea la sessione
Crea una sessione che fa riferimento all'agente. L'agente delega agli agenti che inserisci nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) secondo necessità. Può anche delegare ad [agenti inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents), a meno che tu non li disattivi.
```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
)
```
### Connetti gli agenti ai server MCP
I server MCP hanno ambito a livello di agente: ogni definizione di agente dichiara i propri server e strumenti. Un agente inline non ha una definizione di agente, quindi usa i server MCP e gli strumenti dell'agente eseguito dalla sessione. Le credenziali del vault hanno ambito a livello di sessione: i `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) passati alla creazione della sessione si applicano a ogni thread. Due implicazioni per la tua integrazione:
* Per autenticare i server MCP, includi una credenziale del vault per ogni server MCP usato da qualsiasi agente.
* Per limitare l'accesso di un agente, dichiara nella sua definizione solo i server di cui ha bisogno. Non puoi limitare un agente inline in questo modo. Per consentire solo gli agenti che elenchi, disabilita `inline_agents` (java, php: `inlineAgents`; csharp, go: `InlineAgents`) sia in `subagents` (csharp, go: `Subagents`) sia in `workflows` (csharp, go: `Workflows`), ed elenca almeno un agente in ciascuno. Consulta [Agenti predefiniti e inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Gli [override della configurazione dell'agente](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session) alla creazione della sessione possono sostituire i server MCP dell'agente eseguito dalla sessione e quelli delle sue copie `self`.
Con un [ambiente](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited`, la creazione della sessione fallisce con un errore 400 quando l'agente, o un agente che inserisci nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) o di `workflows` (csharp, go: `Workflows`), dichiara un server MCP il cui host non è in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Impostare `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) su `true` nella configurazione di rete dell'ambiente disattiva questo controllo.
Crea il ricercatore, che dichiara il server MCP di GitHub, e l'agente che delega al ricercatore:
```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}
]
}
}
)
```
Quindi crea la sessione con il vault che contiene la credenziale di 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
```
In questo esempio, solo il ricercatore dichiara il server MCP di GitHub, quindi l'agente eseguito dalla sessione non vi ha accesso. I `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) della sessione forniscono la credenziale di GitHub al thread del ricercatore.
Se le chiamate MCP di un agente non riescono ad autenticarsi dopo che hai dichiarato il server, verifica che il `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) della credenziale faccia riferimento allo stesso server del `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`) dell'agente. Entrambi gli URL vengono normalizzati prima del confronto (schema e host convertiti in minuscolo, porte predefinite e barre finali rimosse), quindi differenze nelle maiuscole/minuscole dell'host, una porta predefinita o una barra finale non impediscono la corrispondenza; un percorso, un sottodominio o una porta non predefinita diversi invece sì.
### Thread
Il thread di sessione di ogni agente ha il proprio stream di eventi. Per elencare, interrompere o archiviare i thread, leggerne gli eventi e gestire le autorizzazioni degli strumenti tra di essi, consulta [Thread di sessione](https://platform.claude.com/docs/it/managed-agents/session-threads).
## Workflow dinamici
Con i workflow dinamici, un agente può affrontare lavori composti da molte parti, come la revisione di centinaia di documenti o la verifica incrociata di molte fonti. L'agente scrive un **workflow** (flusso di lavoro): un programma che esegue molti agenti in fasi e combina ciò che restituiscono. Il server lo esegue in background come "workflow run" (**esecuzione di workflow**), mentre l'agente continua a lavorare o termina il suo turno. Attivi o disattivi i workflow dinamici con l'impostazione `workflows` (csharp, go: `Workflows`) nel blocco `multiagent` (csharp, go: `Multiagent`) dell'agente. Gli agenti di un'esecuzione possono lavorare contemporaneamente, quindi un'attività lunga può terminare prima di quanto accadrebbe se un solo agente svolgesse ogni parte una dopo l'altra.
* **Come inizia un'esecuzione:** Descrivi il lavoro in un `user.message`. Da questo, l'agente determina se e quando avviare un'esecuzione, quindi non è necessaria alcuna chiamata API aggiuntiva. Invece, influenzi la decisione dell'agente descrivendo quando usare un'esecuzione nel `user.message` o nel prompt di sistema dell'agente. (Le policy di autorizzazione si applicano agli strumenti chiamati dagli agenti di un'esecuzione, non all'avvio dell'esecuzione.)
* **Quali agenti usa:** [Agenti inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents) definiti dal workflow, agenti predefiniti che inserisci nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`), o entrambi. Se non ne elenchi nessuno, il workflow li definisce tutti. Un agente inline usa il modello dell'agente eseguito dalla sessione. Per consentire a un'esecuzione di usare un altro modello per alcuni dei suoi agenti, creali come agenti e inseriscili nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`).
* **Come seguirla:** Gli eventi dell'esecuzione arrivano sullo stream di eventi della sessione, e ogni agente dell'esecuzione lavora in un [thread di sessione](https://platform.claude.com/docs/it/managed-agents/session-threads) che puoi elencare, leggere e seguire in streaming. Consulta [Esecuzioni di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs) per gli eventi, le interruzioni, i [limiti](https://platform.claude.com/docs/it/managed-agents/workflow-runs#limits) e [cosa mostrano i thread di un'esecuzione](https://platform.claude.com/docs/it/managed-agents/workflow-runs#a-runs-threads).
### Attiva i workflow dinamici
Quando [definisci il tuo agente](https://platform.claude.com/docs/it/managed-agents/agent-setup), imposta `multiagent.type` su `"multiagent_20261001"` e abilita `workflows`. I workflow dinamici e la delega (`subagents`) sono entrambi attivi per impostazione predefinita con questo tipo. Per usare solo i workflow dinamici, aggiungi `"subagents": {"type": "disabled"}`.
Prima di modificare il `multiagent.type` di un agente esistente, consulta [come spostare un agente a questo tipo](https://platform.claude.com/docs/it/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 di configurazione imposta il tipo per te.
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 di configurazione imposta il tipo al posto tuo.
.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"}}
)
```
Per consentire a un workflow di usare agenti che hai già creato, elencali in `workflows.predefined_agents`. Le impostazioni `subagents` e `advisor` vanno nello stesso blocco `multiagent`. Per elencare i subagenti, consulta [Delegare ai subagenti](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#delegate-to-subagents). Per impostare un advisor, consulta [Fornisci un advisor alla sessione](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Questo agente consente a un workflow di usare un agente che hai creato, elenca due subagenti e ha un advisor:
```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" }
}
}
```
Ogni impostazione viene abilitata o disabilitata in modo indipendente:
| Impostazione | Cosa attiva | Dove vanno gli agenti | Predefinito |
| ------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------ |
| `workflows` | Workflow dinamici | `workflows.predefined_agents`, fino a 20 | Abilitato |
| `subagents` | Delega ai subagenti: gli agenti che elenchi e gli agenti che l'agente definisce autonomamente | `subagents.predefined_agents`, fino a 20 | Abilitato |
| `advisor` | Un modello advisor | Nessuno. Imposta `model`. | Disabilitato |
Per sapere cosa va in ciascun elenco e come consentire solo gli agenti che elenchi, consulta [Agenti predefiniti e inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Tieni presente quanto segue:
* **Aggiornamento:** Un aggiornamento che mantiene il tipo `multiagent_20261001` modifica solo ciò che invia:
* Un'impostazione o un campo che ometti mantiene il valore memorizzato.
* Un'impostazione o un campo che invii come `null` assume il valore predefinito, e lo stesso vale per tutto ciò che contiene, indipendentemente da ciò che avevi memorizzato.
* Un elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) che invii sostituisce l'elenco memorizzato.
* Un'impostazione che invii con un `type` diverso sostituisce l'impostazione memorizzata, e i campi che ometti assumono i valori predefiniti.
* Ogni oggetto che invii necessita del suo `type`, e un `advisor` abilitato necessita del suo `model`.
* **Disattivazione:** Imposta `workflows` su `{"type": "disabled"}`. Rimane disattivato finché un aggiornamento non lo riattiva. Inviare `null` lo attiva, perché il suo valore predefinito è abilitato. Lo stesso vale per `subagents`.
* **Sessioni esistenti:** Una sessione copia l'impostazione al momento della creazione, quindi modificare l'agente in seguito non cambia una sessione già esistente.
* **Agenti che puoi elencare:** Un agente che ha `multiagent` (csharp, go: `Multiagent`) impostato non può essere elencato come subagente di un altro agente, né nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`) in un altro agente. Un agente può elencare se stesso in entrambi gli elenchi con `{"type": "self"}`, che viene restituito come il suo `id` e la sua `version`.
* **Nomi degli strumenti:** Il prefisso `ant__` è riservato. Se il tuo agente ha già uno strumento personalizzato il cui nome inizia con `ant__`, un aggiornamento fallisce con un errore 400 finché non invii `tools` (csharp, go: `Tools`) senza quel nome. Anche una nuova sessione viene rifiutata con un errore 400 se il suo agente, o un agente in uno dei due elenchi, ha uno strumento di questo tipo. Rinomina o rimuovi lo strumento nello stesso aggiornamento che attiva i workflow dinamici. Consulta [Strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/tools#custom-tools).
* **Budget:** Imposta un [budget di sessione](https://platform.claude.com/docs/it/managed-agents/budgets) quando crei la sessione per limitare la spesa della sessione, esecuzioni incluse; non puoi aggiungerne uno a una sessione esistente. Le esecuzioni vengono messe in pausa quando la sessione raggiunge il budget, e le esecuzioni messe in pausa dal budget riprendono quando lo aumenti o lo rimuovi, a meno che non siano state messe in pausa anche da un'interruzione. Consulta [Costi e budget](https://platform.claude.com/docs/it/managed-agents/workflow-runs#cost-and-budgets).
### Indicare all'agente quando usare un'esecuzione
Attivare i workflow dinamici dà all'agente la possibilità di avviare esecuzioni di workflow. È l'agente a stabilire quando avviarne una. Per orientare questa scelta, aggiungi un'istruzione come la seguente al prompt di sistema dell'agente. L'agente di revisione dei contratti in [Attiva i workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) usa questo prompt di sistema:
```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.
```
Per adattarlo, indica le attività nel dominio del tuo agente che richiedono un'esecuzione e le piccole attività che l'agente dovrebbe svolgere da solo. Puoi anche orientare il modo in cui un'esecuzione svolge il lavoro, come in questi esempi:
* **Come suddividere il lavoro:** "In un'esecuzione, usa un agente per contratto. Poi fai rivedere ogni contratto a un secondo agente, non solo quelli in cui il primo agente ha trovato qualcosa, e cerca ciò che il primo agente ha tralasciato. Tutto ciò che non supera la revisione viene rifatto e rivisto di nuovo."
* **Cosa fare quando un agente fallisce:** "Il fallimento di un agente non deve far fallire l'esecuzione. Se un agente non riesce a leggere un contratto, elenca quel contratto come non coperto. Al termine dell'esecuzione, dimmi quali contratti non sono stati coperti."
* **Un limite di tempo:** "Dai all'esecuzione un limite di tempo di un'ora."
* **Pianifica prima:** "Prima di avviare un'esecuzione, descrivi le sue fasi e quanti agenti esegue ciascuna. Poi attendi il mio via libera." Non esiste una fase di approvazione prima dell'avvio di un'esecuzione, quindi nulla impone questo comportamento.
Limita le esecuzioni alle attività che ne hanno bisogno, perché ogni agente in un'esecuzione consuma token.
Poi [crea una sessione](https://platform.claude.com/docs/it/managed-agents/sessions) con l'agente, come faresti con qualsiasi agente, e descrivi il lavoro in un `user.message`. Puoi anche richiedere un'esecuzione in quel messaggio.
Per gli eventi di un'esecuzione, l'interruzione di una sessione con esecuzioni aperte, cosa cambia mentre un'esecuzione è aperta, e budget e limiti, consulta [Esecuzioni di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs).
## Fornisci un advisor alla sessione
Un'impostazione `advisor` abilitata nel blocco `multiagent` (csharp, go: `Multiagent`) dell'agente dà al thread principale della sessione un **advisor** (consulente): un modello che può consultare a metà turno per ottenere indicazioni strategiche, ad esempio per pianificare un approccio, sbloccarsi o rivedere il lavoro prima di terminare. L'impostazione è disabilitata per impostazione predefinita. Per abilitarla, imposta `advisor` su `{"type": "enabled", "model": "..."}`, che ha esattamente due campi, `type` e `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
```
Questo esempio imposta solo `advisor` (csharp, go: `Advisor`). Le altre due impostazioni, `subagents` (csharp, go: `Subagents`) e `workflows` (csharp, go: `Workflows`), mantengono i valori predefiniti, quindi sono entrambe abilitate, e l'agente può anche delegare ad agenti inline e avviare esecuzioni di workflow. Per un agente che consulta un advisor e svolge tutto il lavoro da sé, imposta entrambe su `{"type": "disabled"}`.
Non puoi inserire l'advisor nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) o di `workflows` (csharp, go: `Workflows`). Un `advisor` (csharp, go: `Advisor`) abilitato riserva il nome `anthropic.advisor`. Finché è abilitato, nessuno dei due elenchi può contenere un agente chiamato letteralmente `anthropic.advisor`: la richiesta viene rifiutata con un errore di validazione 400.
Il modello advisor deve soddisfare una soglia minima di capacità, e il modello dell'agente stesso non deve essere più capace del suo advisor; modelli di pari capacità possono essere abbinati. Un abbinamento non valido viene rifiutato con un errore di validazione 400 quando l'agente viene salvato, e di nuovo quando viene creata una sessione. L'abbinamento viene verificato anche all'avvio di ogni consultazione: se non è più valido, quella consultazione fallisce e la sessione continua. Gli abbinamenti validi seguono la tabella di [compatibilità dei modelli](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#model-compatibility) dello strumento advisor.
L'advisor è disponibile anche come [strumento server sulla Messages API](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool). La superficie di Managed Agents differisce per configurazione e modalità di consegna: l'impostazione `advisor` (csharp, go: `Advisor`) non ha i campi `max_uses`, `max_tokens` o `caching`, e i consigli arrivano tramite eventi di thread anziché tramite blocchi `advisor_tool_result`.
### Come funzionano le consultazioni
Ogni consultazione viene eseguita come un thread generato dalla piattaforma chiamato `anthropic.advisor` che termina da sé al completamento della consultazione, e il consiglio viene consegnato al thread principale come evento `agent.thread_message_received`. Una consultazione emette gli eventi di thread standard, identificati dal nome riservato `anthropic.advisor` (gli eventi del ciclo di vita del thread lo riportano come `agent_name` (java, php: `agentName`; csharp, go: `AgentName`), e la consegna del consiglio lo riporta come `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`)), tipicamente in questo ordine:
1. `session.thread_created`
2. `session.thread_status_running`
3. `agent.thread_message_received` (il consiglio)
4. `session.thread_status_idle` (`stop_reason: end_turn`)
5. `session.thread_status_terminated`
Per una consultazione non vengono emessi eventi `agent.tool_use`, e nessun evento `agent.thread_message_sent` compare nello stream di eventi della sessione, perché l'input della consultazione è composto dalla piattaforma anziché inviato dall'agente. Se elenchi gli eventi del thread advisor stesso, il consiglio compare lì anche come evento `agent.thread_message_sent`. Non è garantito che la consegna del consiglio (evento 3) arrivi prima degli eventi idle e terminated del thread advisor, quindi non considerarli un segnale che il consiglio sia già stato consegnato.
La possibilità per il tuo client di leggere il consiglio dipende dalla policy del modello advisor. Rispecchia la suddivisione delle [varianti di risultato](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#result-variants) dello strumento advisor della Messages API. Un modello advisor che lì restituisce risultati in chiaro consegna qui testo leggibile. Uno che restituisce risultati oscurati consegna un segnaposto `[{"type": "redacted"}]` su ogni superficie client, mentre l'agente legge comunque il consiglio completo lato server. L'esempio precedente usa come advisor il modello Opus più recente a tua disposizione. Claude Opus 5.5 restituisce risultati oscurati, quindi il tuo client vede solo il segnaposto. Per leggere il consiglio nello stream di eventi, usa un advisor che restituisce testo in chiaro, come Claude Opus 4.8. La policy di un modello può cambiare senza alcuna modifica all'API, quindi gestisci sia i blocchi `text` sia quelli `redacted`. Alcuni modelli di agente si abbinano solo ad advisor con risultati oscurati; consulta la [tabella di compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/advisor-tool#model-compatibility) dello strumento advisor. Il ragionamento dell'advisor non viene mai esposto. I client non possono inviare blocchi `redacted` da sé; un evento che ne contiene uno viene rifiutato con un errore di validazione 400.
Una consultazione fallita o interrotta non fa mai fallire il turno dell'agente: l'agente prosegue dopo un avviso generico che la consultazione è fallita. Un `user.interrupt` a livello di sessione durante una consultazione termina il thread advisor senza consegnare alcun consiglio; un `user.interrupt` con il `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) del thread advisor abbandona solo quella consultazione.
### Thread advisor
L'advisor non è un subagente. Lo strumento `list_agents` dell'agente non lo mostra, e `send_to_agent`, che invia a un subagente un messaggio di follow-up, non può raggiungerlo. Solo il thread principale della sessione può consultarlo; i subagenti no.
I thread advisor sono esenti dal limite di 25 thread figli. Compaiono nell'[elenco dei thread](https://platform.claude.com/docs/it/managed-agents/session-threads) della sessione. Il loro `agent` è nella forma advisor, `{"type": "advisor", "model": ...}`, con il modello che hai configurato, e il loro `parent_thread_id` è il thread principale.
Il "prompt caching" (cache dei prompt) lato advisor è automatico; non c'è nulla da configurare. Le consultazioni vengono fatturate alle tariffe del modello advisor, e i loro token compaiono nell'utilizzo del thread advisor e nei totali di utilizzo della sessione. Vengono inoltre conteggiate in un [budget di sessione](https://platform.claude.com/docs/it/managed-agents/budgets), al prezzo di listino del modello advisor. Ogni consultazione invia all'advisor la conversazione del thread principale fino a quel momento, quindi le consultazioni che avvengono tardi in una sessione lunga consumano più token di input.
### Rimuovere l'advisor
Per rimuovere l'advisor, [aggiorna l'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent) con `advisor` impostato su `{"type": "disabled"}`. Su un agente che ha già il tipo `multiagent_20261001`, un'impostazione omessa dall'aggiornamento mantiene il valore memorizzato, quindi non è necessario inviare di nuovo `subagents` o `workflows`. Per lo stesso motivo, un aggiornamento che omette `advisor` mantiene l'advisor. Prima di modificare il `multiagent.type` di un agente esistente, consulta [come spostare un agente a questo tipo](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).
## Passare dal tipo `coordinator`
Come `multiagent_20261001`, il tipo `coordinator` consente a un agente di delegare ai subagenti che elenchi e di consultare un modello advisor. Con il tipo `coordinator`, l'agente non può avviare esecuzioni di workflow né definire subagenti autonomamente. L'API accetta entrambi i tipi.
Per spostare un agente a `multiagent_20261001`, [aggiorna l'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent) con un blocco `multiagent` di quel tipo:
1. Imposta `type` su `"multiagent_20261001"`.
2. Elenca gli agenti che l'agente può chiamare in `subagents.predefined_agents`. Le voci mantengono la forma che hanno attualmente.
3. Se l'agente ha un advisor, imposta `advisor` su `{"type": "enabled", "model": "..."}` con il modello dell'advisor.
4. Invia l'intero blocco in un unico aggiornamento.
Ad esempio, questo blocco dà a un agente due subagenti e un advisor:
```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" }
}
}
```
Quel blocco omette `workflows` e `subagents.inline_agents`, quindi entrambi assumono il valore predefinito e sono abilitati. L'agente spostato può anche avviare esecuzioni di workflow e definire subagenti autonomamente. Per mantenere disattivato uno dei due, impostalo su `{"type": "disabled"}` nello stesso aggiornamento. Consulta [Attiva i workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) e [Agenti predefiniti e inline](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Se l'agente ha un advisor e nessun subagente, imposta `subagents` su `{"type": "disabled"}` per mantenere disattivata la delega. Una richiesta che disabilita `subagents.inline_agents` e non elenca alcun agente fallisce con un errore 400.
L'aggiornamento sostituisce l'intero blocco `multiagent`, quindi invia di nuovo l'elenco degli agenti e l'advisor, come fa l'esempio. Ciò che ometti assume il valore predefinito:
* **`subagents.predefined_agents`:** L'elenco è vuoto, quindi l'agente perde i subagenti che avevi elencato.
* **`advisor`:** L'advisor è disabilitato.
Una volta che l'agente ha il tipo `multiagent_20261001`, un'impostazione omessa da un aggiornamento successivo mantiene il valore memorizzato.
L'aggiornamento non modifica le sessioni già esistenti. Per usare il nuovo blocco, crea una sessione dopo l'aggiornamento.