Sessioni multi-agente

L'orchestrazione multi-agente 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.



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 con contesto isolato e una propria cronologia di conversazione. Il coordinatore riporta l'attività nel thread primario (che corrisponde al 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 utilizza 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

Il coordinamento multi-agente è più adatto per attività complesse che richiedono lavoro su una varietà di superfici, o in cui più attività ben delimitate contribuiscono a un obiettivo generale.

Pattern che funzionano bene:

• Parallelizzazione: Distribuisci simultaneamente sottoattività 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 sottoattività complesse.



Configura il coordinatore

Quando definisci il tuo agente, imposta multiagent per dichiarare l'elenco di 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 valori:

• {"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 salvata come snapshot quando il coordinatore viene creato o aggiornato. Gli agenti referenziati rimangono fissati alle versioni risolte in quel momento e non acquisiscono automaticamente 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; una profondità > 1 viene ignorata. È 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 di agente (ogni definizione di agente dichiara i propri server e strumenti), mentre le credenziali del vault hanno ambito 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 utilizzato 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/:id/events/stream) è considerato il 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 dove puoi approfondire 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.



Eventi del thread primario

Questi eventi mostrano l'attività multi-agente sul thread primario su /v1/sessions/:id/events/stream.



Eventi del thread di sessione

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



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",
            }
        ],
    )