Sessioni multiagente

L'orchestrazione multi-agente consente a un agente di coordinare con altri per completare lavori complessi. Gli agenti possono agire in parallelo con il loro contesto isolato, il che aiuta a migliorare la qualità dell'output e ridurre il tempo di completamento.

Come funziona

Tutti gli agenti condividono lo stesso contenitore e filesystem, ma ogni agente viene eseguito nella propria sessione thread, un flusso di eventi isolato dal contesto con la propria cronologia di conversazione. Il coordinatore segnala l'attività nel thread primario (che è lo stesso del flusso di eventi a livello di sessione); i thread aggiuntivi vengono generati in fase di esecuzione quando il coordinatore decide di delegare.

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

Ogni agente utilizza la propria configurazione (modello, prompt di sistema, strumenti, server MCP e competenze) come definito quando quell'agente è stato creato. Gli strumenti e il contesto non sono condivisi.

Cosa delegare

Le sessioni multiagente funzionano meglio quando ci sono più attività ben definite e specializzate in un obiettivo generale:

• Revisione del codice: Un agente revisore con un prompt di sistema focalizzato e strumenti di sola lettura.
• Generazione di test: Un agente di test che scrive ed esegue test senza toccare il codice di produzione.
• Ricerca: Un agente di ricerca con strumenti web che riassume i risultati al coordinatore.

Dichiara agenti chiamabili

Quando definisci il tuo agente, elenca gli ID aggiuntivi degli agenti che è autorizzato a chiamare:

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
callable_agents:
  - type: agent
    id: $REVIEWER_AGENT_ID
    version: $REVIEWER_AGENT_VERSION
  - type: agent
    id: $TEST_WRITER_AGENT_ID
    version: $TEST_WRITER_AGENT_VERSION
YAML

Ogni voce in callable_agents deve essere l'ID di un agente esistente. È supportato solo un livello di delega: il coordinatore può chiamare altri agenti, ma quegli agenti non possono chiamare agenti propri.

Quindi crea una sessione che fa riferimento all'orchestratore:

session = client.beta.sessions.create(
    agent=orchestrator.id,
    environment_id=environment.id,
)

Gli agenti chiamabili vengono risolti dalla configurazione dell'orchestratore. Non è necessario farvi riferimento al momento della creazione della sessione.

Thread di sessione

Il flusso di eventi a livello di sessione (/v1/sessions/:id/stream) è considerato il thread primario, contenente una vista condensata di tutta l'attività su tutti i thread. Non vedrai le tracce individuali degli agenti chiamati, ma vedrai l'inizio e la fine del loro lavoro. I thread di sessione sono dove approfondisci il ragionamento e le chiamate di strumenti di un agente specifico.

Lo stato della sessione è anche un'aggregazione di tutta l'attività dell'agente; se almeno un thread è running, lo stato complessivo della sessione sarà running anche.

Elenca tutti i thread in una sessione come segue:

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

Trasmetti gli eventi da un thread specifico:

with client.beta.sessions.threads.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_idle":
                break

Elenca gli eventi passati per un thread:

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

Tipi di evento multiagente

Questi eventi emergono dall'attività multiagente nel flusso di sessione di primo livello.

Permessi degli strumenti e strumenti personalizzati nei thread

Quando un thread callable_agent ha bisogno di qualcosa dal tuo client (permesso per eseguire uno strumento always_ask, o il risultato di uno strumento personalizzato) la richiesta emerge nel flusso di sessione con un campo session_thread_id. Includi lo stesso session_thread_id quando pubblichi la tua risposta in modo che la piattaforma la indirizzi al thread in attesa.

• session_thread_id è presente: l'evento ha avuto origine in un thread di subagente. Ripetilo nella tua risposta.
• session_thread_id è assente: l'evento proviene dal thread primario. Rispondi senza il campo.
• Abbina su tool_use_id per associare le richieste alle risposte.

L'esempio seguente estende il gestore di conferma dello strumento per instradare le risposte. Lo stesso modello si applica a user.custom_tool_result.

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])