Orchestrazione multiagente

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).

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. 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 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.

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é:

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

Per impostare quali agenti l'agente può chiamare, consulta Agenti predefiniti e inline. Per disattivare un'impostazione, consulta Attiva i workflow dinamici.

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 e che elenchi nel blocco 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:

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, 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.

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:

{
  "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.

Come funziona

Tutti gli agenti condividono la stessa sandbox, lo stesso filesystem e le stesse credenziali del vault, 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 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. Gli override della configurazione dell'agente 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, imposta l'elenco predefined_agents di subagents nel blocco multiagent per elencare gli agenti a cui può delegare:

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

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

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

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

You are a code reviewer.

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

You write unit tests.

L'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 di subagents, consulta Agenti predefiniti e inline.

"advisor": {"type": "enabled", "model": "<model id>"} fornisce al thread principale della sessione un advisor che può consultare a metà turno. L'advisor è un'impostazione del blocco multiagent, non una voce di questo elenco. Consulta Fornisci un advisor alla sessione.

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.

Le seguenti regole si applicano agli agenti che inserisci nell'elenco predefined_agents di subagents, e anche agli agenti che inserisci nell'elenco predefined_agents di workflows:

• Versioni fissate: La configurazione dell'agente, incluso l'elenco predefined_agents di 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 in modo che l'elenco predefined_agents di 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 impostato fa fallire la richiesta di creazione o aggiornamento con un errore di validazione 400.
• Fino a 20 agenti: L'elenco predefined_agents di subagents può elencare fino a 20 agenti univoci. Il limite è per elenco: anche l'elenco predefined_agents di workflows può elencarne fino a 20. L'agente può chiamare più copie di ciascun subagente, entro il limite di thread della sessione.
• Area geografica di inferenza: L'agente e ogni agente che elenchi, nell'elenco predefined_agents di subagents o di workflows, devono fissare la stessa area geografica di inferenza (inference_geo nel model della definizione dell'agente), 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 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 di subagents secondo necessità. Può anche delegare ad agenti inline, a meno che tu non li disattivi.

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 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 sia in subagents sia in workflows, ed elenca almeno un agente in ciascuno. Consulta Agenti predefiniti e inline.

Gli override della configurazione dell'agente alla creazione della sessione possono sostituire i server MCP dell'agente eseguito dalla sessione e quelli delle sue copie self.

Con un ambiente limited, la creazione della sessione fallisce con un errore 400 quando l'agente, o un agente che inserisci nell'elenco predefined_agents di subagents o di workflows, dichiara un server MCP il cui host non è in allowed_hosts. Impostare allow_mcp_servers 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:

ant apply lead.md researcher.md

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

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

Quindi crea la sessione con il vault che contiene la credenziale di GitHub:

session = client.beta.sessions.create(
    agent=lead_agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(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 della sessione forniscono la credenziale di GitHub al thread del ricercatore.

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.

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 nel blocco 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 definiti dal workflow, agenti predefiniti che inserisci nell'elenco predefined_agents di 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 di 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 che puoi elencare, leggere e seguire in streaming. Consulta Esecuzioni di workflow per gli eventi, le interruzioni, i limiti e cosa mostrano i thread di un'esecuzione.

Attiva i workflow dinamici

Quando definisci il tuo agente, 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.

ant apply contract-reviewer.md

---
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.

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. Per impostare un advisor, consulta Fornisci un advisor alla sessione. Questo agente consente a un workflow di usare un agente che hai creato, elenca due subagenti e ha un advisor:

{
  "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:

Per sapere cosa va in ciascun elenco e come consentire solo gli agenti che elenchi, consulta Agenti predefiniti e inline.

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 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 impostato non può essere elencato come subagente di un altro agente, né nell'elenco predefined_agents di 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 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.
• Budget: Imposta un budget di sessione 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.

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 usa questo prompt di sistema:

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 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.

Fornisci un advisor alla sessione

Un'impostazione advisor abilitata nel blocco 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:

ant apply backend-engineer.md

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

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

Questo esempio imposta solo advisor. Le altre due impostazioni, subagents e 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 di subagents o di workflows. Un 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 dello strumento advisor.

L'advisor è disponibile anche come strumento server sulla Messages API. La superficie di Managed Agents differisce per configurazione e modalità di consegna: l'impostazione 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, e la consegna del consiglio lo riporta come from_agent_name), 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 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à 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 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 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, 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 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.

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 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:

{
  "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 e Agenti predefiniti e inline.

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.