Avvia una sessione

Una sessione è un'istanza di agente all'interno di un ambiente. Ogni sessione fa riferimento a un agente e a un ambiente (entrambi creati separatamente) e mantiene la cronologia della conversazione attraverso più interazioni. Le sessioni seguono un ciclo di vita in due fasi: prima crea la sessione, poi invia un evento utente per avviare il lavoro. Puoi anche unire entrambi i passaggi in una sola chiamata con initial_events.



Creazione di una sessione

Una sessione richiede un ID agent e un ID environment. Gli agenti sono risorse versionate; passare l'ID agent come stringa avvia la sessione con l'ultima versione dell'agente.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

Per fissare una sessione a una versione specifica dell'agente, passa un oggetto. Questo ti consente di controllare esattamente quale versione viene eseguita e di gestire il rilascio graduale delle nuove versioni in modo indipendente.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



Inizializza la sessione con eventi iniziali

Puoi creare una sessione e avviarne il lavoro in una sola chiamata. initial_events è un array opzionale di eventi iniziali da inviare alla sessione al momento della creazione, elaborati in ordine. Supporta gli eventi user.message e user.define_outcome e accetta un massimo di 50 eventi. Una lista non vuota avvia il ciclo dell'agente nella stessa chiamata: la sessione viene creata direttamente nello stato running, senza ulteriori richieste.

L'esempio seguente crea una sessione con un singolo user.message in initial_events:

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML
)

# initial_events non compaiono nella risposta di creazione; elenca gli eventi
# della sessione per vedere il messaggio iniziale.
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

Nessun altro tipo di evento è accettato. Gli eventi che rispondono a un turno dell'agente (user.tool_confirmation, user.tool_result e user.custom_tool_result) non sono accettati perché non esiste ancora alcun turno dell'agente, e user.interrupt non è accettato perché non c'è alcun turno da interrompere. A differenza di initial_events in un deployment pianificato, gli initial_events di una sessione non accettano system.message.

Ogni evento in initial_events viene validato e persistito prima che la risposta di creazione venga restituita, nell'ordine della lista, con un ID assegnato dal server, esattamente come se lo avessi inviato all'endpoint di invio eventi subito dopo la creazione. Anche le regole sul contenuto per singolo evento sono le stesse di quell'endpoint. Una lista vuota equivale a omettere il campo. La validazione è tutto-o-niente: se un evento non supera la validazione, l'intera richiesta viene rifiutata e nessuna sessione viene creata.

La richiesta di creazione viene rifiutata nei seguenti casi:

Un evento user.define_outcome in initial_events è accettato alle stesse condizioni dell'invio a una sessione esistente; consulta Definire gli esiti.



Sovrascrivi la configurazione dell'agente per una sessione

Puoi passare agent in tre forme: una stringa con l'ID dell'agente, un oggetto con versione fissata (type: "agent") o un oggetto di override. La forma con override modifica parti della configurazione dell'agente per una singola sessione. Usala per provare un modello diverso o concedere uno strumento aggiuntivo in una sessione senza creare una nuova versione dell'agente. Per la forma con override, imposta type su agent_with_overrides e passa l'id dell'agente e, facoltativamente, una version (ometti version per usare l'ultima versione dell'agente). Poi includi uno qualsiasi tra model, system, tools, mcp_servers o skills con i valori che la sessione deve usare.

Ogni campo sovrascrivibile segue le stesse tre regole:

• Ometti il campo: La sessione eredita il valore dalla versione dell'agente a cui fa riferimento.
• Imposta il campo su null, o su un array vuoto per i campi di tipo lista: La sessione viene eseguita con quel campo azzerato. Questa regola si applica integralmente a system e skills. Ci sono tre eccezioni:
  • model non è mai azzerabile. Una sessione ha sempre bisogno di un modello, quindi model: null restituisce un errore 400 agent_model_required.
  • Azzerare tools restituisce un errore 400 quando gli skills effettivi della sessione non sono vuoti, perché le skill richiedono lo strumento read. Altrimenti, tools: null e tools: [] azzerano il campo.
  • Azzerare mcp_servers restituisce un errore 400 quando i tools effettivi della sessione contengono ancora un mcp_toolset che fa riferimento a uno dei server dell'agente. Sovrascrivi tools nella stessa richiesta per rimuovere quelle voci mcp_toolset, poi azzera mcp_servers.
• Imposta il campo su un valore: Il valore sostituisce integralmente il valore dell'agente. Gli override non vengono mai uniti alla configurazione dell'agente, quindi un override di tools deve elencare ogni strumento che la sessione deve avere. C'è un'eccezione:
  • Un livello di effort all'interno di un override di model per sessione non viene applicato. Imposta invece effort sull'agente.

Gli override si applicano solo alla sessione che crei. Non modificano la risorsa agente né creano una nuova versione dell'agente, quindi le altre sessioni che fanno riferimento allo stesso agente non sono interessate.

Nella risposta, l'oggetto agent riflette la configurazione con cui la sessione viene eseguita dopo l'applicazione degli override. I suoi id e version identificano comunque l'agente e la versione a cui gli override sono applicati. Questo ti consente di risalire dalla sessione al suo agente di base.

L'esempio seguente avvia una sessione che sovrascrive il modello e azzera il prompt di sistema:

# L'`agent` nella risposta è lo snapshot risolto: ogni override sostituisce quel
# campo solo per questa sessione, e la risorsa agente conserva id e versione.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



Autenticazione MCP tramite vault

Se il tuo agente usa strumenti MCP che richiedono autenticazione, passa vault_ids alla creazione della sessione per fare riferimento a un vault contenente credenziali OAuth memorizzate. Anthropic gestisce il refresh dei token per tuo conto. Consulta Autenticazione con i vault per sapere come creare vault e registrare le credenziali.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



Avvio della sessione

Creare una sessione senza initial_events registra la sessione ma non avvia alcun lavoro; la sandbox dell'ambiente viene predisposta quando la sessione ne ha bisogno per la prima volta. Per delegare un'attività, invia eventi alla sessione usando un evento utente. Per fornire invece il primo evento nella richiesta di creazione, consulta Inizializza la sessione con eventi iniziali. La sessione agisce come una macchina a stati che tiene traccia dei progressi mentre gli eventi guidano l'esecuzione effettiva.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

Consulta Flusso di eventi della sessione per sapere come ricevere in streaming le risposte dell'agente e gestire le conferme degli strumenti.

Consulta Stati della sessione per gli stati attraverso cui passa una sessione.



Prossimi passi