Avviare 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 per effettuare il provisioning della sua sandbox, poi invia un evento utente per avviare il lavoro.



Creazione di una sessione

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

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

Per vincolare una sessione a una versione specifica dell'agente, passa un oggetto. Questo ti consente di controllare esattamente quale versione viene eseguita e di gestire i rollout di nuove versioni in modo indipendente.

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



Sovrascrivere la configurazione dell'agente per una sessione

Puoi passare agent in tre forme: una stringa con l'ID dell'agente, un oggetto con versione vincolata (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 opzionalmente una version (ometti version per usare la versione più recente dell'agente). Quindi includi uno qualsiasi tra model, system, tools, mcp_servers o skills con i valori che la sessione dovrebbe 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 lista: la sessione viene eseguita con quel campo azzerato. Questa regola si applica integralmente a system, mcp_servers e skills. Ci sono due 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 il valore effettivo di skills della sessione non è vuoto, perché le skill richiedono lo strumento read. Altrimenti, tools: null e tools: [] azzerano il campo.
• 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 dovrebbe avere.

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

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 da una sessione al suo agente di base.

# L'`agent` nella risposta è lo snapshot risolto: ogni override sostituisce quel
# campo solo per questa sessione, e la risorsa agent mantiene 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 utilizza 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 credenziali.

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



Avvio della sessione

La creazione di una sessione effettua il provisioning della sandbox dell'ambiente ma non avvia alcun lavoro. Per delegare un'attività, invia eventi alla sessione utilizzando un evento utente. La sessione agisce come una macchina a stati che tiene traccia dell'avanzamento 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 Stream di eventi della sessione per sapere come eseguire lo streaming delle risposte dell'agente e gestire le conferme degli strumenti.

Consulta Stati della sessione per gli stati attraverso cui passa una sessione, e Operazioni sulla sessione per recuperare, elencare, aggiornare, archiviare ed eliminare sessioni.

Per creare sessioni automaticamente secondo una pianificazione ricorrente, consulta Deployment pianificati.