Orchestrazione multiagente

L'orchestrazione multiagente consente a un agente di coordinarsi con altri per completare lavori complessi. Gli agenti possono agire in parallelo con il proprio contesto isolato, il che aiuta a migliorare la qualità dell'output e può anche ridurre il tempo di completamento.

Non sei sicuro che una configurazione multiagente sia adatta al tuo problema? Consulta quando usare i sistemi multiagente (e quando no).



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 session thread (thread di sessione), un flusso di eventi isolato a livello di contesto con la propria cronologia di conversazione. Il coordinatore riporta l'attività nel primary thread (thread primario), che coincide con il flusso di eventi a livello di sessione; thread aggiuntivi vengono generati a runtime quando il coordinatore delega il lavoro.

I thread sono persistenti: il coordinatore può inviare un follow-up a un agente che ha chiamato in precedenza, e quell'agente conserva tutto ciò che proviene dai suoi turni precedenti.

Ogni agente usa la propria configurazione: modello, prompt di sistema, strumenti, server MCP e skill. Gli override della configurazione dell'agente a livello di sessione sono l'eccezione; si applicano al coordinatore e alle sue copie self. Strumenti, server MCP e contesto non sono condivisi.



Cosa delegare

La coordinazione multiagente è più adatta per compiti complessi che richiedono lavoro su una varietà di superfici, oppure in cui più compiti ben delimitati contribuiscono a un obiettivo complessivo.

Pattern che funzionano bene:

• Parallelizzazione: Distribuisci simultaneamente sottocompiti indipendenti (ricerca su più fonti, analisi di file separati) e fai sintetizzare i risultati al coordinatore.
• Specializzazione: Indirizza verso agenti con prompt di sistema e strumenti focalizzati su un dominio, come un agente di sicurezza o un agente di documentazione, invece di caricare un singolo agente con ogni capacità.
• Escalation: Consulta un agente o un modello più capace per un sottoinsieme di sottocompiti complessi.



Configura il coordinatore

Quando definisci il tuo agente, imposta multiagent per dichiarare l'elenco degli agenti a cui il coordinatore può delegare:

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-8
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: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

multiagent.agents può accettare uno qualsiasi dei seguenti:

• {"type": "agent", "id": agent.id} fa riferimento a un agent creato in precedenza tramite ID. Se non viene specificata alcuna version, il riferimento viene fissato all'ultima versione di quell'agente al momento della creazione del coordinatore.
• {"type": "agent", "id": agent.id, "version": agent.version} fissa una versione specifica dell'agente.
• {"type": "self"} consente al coordinatore di generare copie di se stesso. Se la sessione è stata creata con override della configurazione dell'agente, tali override si applicano anche a queste copie; le voci dell'elenco referenziate tramite ID non sono interessate.

La configurazione del coordinatore, incluso il suo elenco multiagent.agents, viene acquisita come snapshot quando il coordinatore viene creato o aggiornato. Gli agenti referenziati rimangono fissati alle versioni risolte in quel momento e non recepiscono automaticamente gli aggiornamenti successivi alle loro definizioni. Per delegare a una versione più recente di un agente referenziato, aggiorna il coordinatore in modo che il suo elenco faccia riferimento a quella versione.

Il coordinatore può delegare solo a un livello di agenti; fare riferimento a un agente che ha il proprio elenco multiagent.agents fa fallire la richiesta di creazione o aggiornamento con un errore di validazione. È possibile elencare un massimo di 20 agenti univoci in multiagent.agents, ma il coordinatore può chiamare più copie di ciascun agente.



Crea la sessione

Crea una sessione che fa riferimento al coordinatore. Il coordinatore delega agli agenti nel suo elenco secondo necessità.

session = client.beta.sessions.create(
    agent=coordinator.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), mentre 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 tutti gli agenti.
• Per limitare l'accesso di un agente, dichiara solo i server di cui ha bisogno nella sua definizione di agente.

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

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.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 il coordinatore non vi ha accesso. I vault_ids della sessione forniscono la credenziale GitHub al thread del ricercatore.



Thread

Il flusso di eventi a livello di sessione (/v1/sessions/{session_id}/events/stream) è considerato il primary thread (thread primario) e contiene una vista condensata di tutta l'attività su tutti i thread. Non vedi l'attività completa dei subagenti, ma vedi l'inizio e la fine del loro lavoro, e gli eventi bloccanti come le richieste di autorizzazione degli strumenti.

I session thread (thread di sessione) sono il punto in cui approfondisci l'attività di un agente specifico.

Lo status della sessione è un'aggregazione di tutta l'attività degli agenti; se almeno un thread è running, allora anche lo stato complessivo della sessione è running.

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")



Eventi del thread primario

Questi eventi mostrano l'attività multiagente sul thread primario in /v1/sessions/{session_id}/events/stream. Gli eventi di direzione dei messaggi sono denominati rispetto al thread sul cui flusso appaiono: agent.thread_message_received significa che un messaggio è arrivato su questo thread da un altro thread, e agent.thread_message_sent significa che questo thread ne ha inviato uno. Il compito che il coordinatore delega, ad esempio, arriva sul flusso del thread figlio come evento agent.thread_message_received.



Eventi del thread di sessione

Gli eventi critici vengono inoltrati al thread primario. Tuttavia, potresti comunque voler esaminare il ragionamento e le chiamate di strumenti di un agente specifico. Per farlo, esegui lo streaming o elenca gli eventi dal thread di sessione associato.

Ogni thread di sessione ha il proprio flusso di eventi in /v1/sessions/{session_id}/threads/{thread_id}/stream, e accetta lo stesso parametro event_deltas[] del flusso a livello di sessione, quindi puoi visualizzare in anteprima il testo di un subagente mentre il modello lo genera. Una connessione mostra in anteprima solo il thread che sta leggendo: le anteprime di un thread figlio non appaiono mai sul flusso a livello di sessione, quindi per osservare un subagente in tempo reale, apri il flusso del suo thread. Consulta Anteprima degli eventi del thread di sessione per l'attivazione, l'accumulo e la riconciliazione delle anteprime.

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_status_idle":
                break



Autorizzazioni degli strumenti e strumenti personalizzati

Se un subagente ha bisogno di qualcosa dal tuo client, come l'autorizzazione per eseguire uno strumento always_ask, o il risultato di uno strumento personalizzato, l'evento viene pubblicato anche sul thread primario con session_thread_id che identifica il thread di sessione di origine.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

Invia user.tool_confirmation (con tool_use_id) o user.custom_tool_result (con custom_tool_use_id); il server instrada automaticamente la risposta al thread corretto.

L'esempio seguente estende il gestore di conferma degli strumenti per instradare le risposte. Lo stesso pattern si applica a user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )