Operazioni sulle sessioni

Una volta che una sessione esiste, usa queste operazioni per leggerla, aggiornarla, archiviarla o eliminarla. Consulta Avviare una sessione per creare una sessione e inviarle del lavoro.



Stati della sessione

Le sessioni attraversano questi stati. Consulta Avviare una sessione per il ciclo di vita della sessione.



Aggiornare la configurazione dell'agente

Puoi aggiornare agent.tools e agent.mcp_servers di una sessione, incluse le policy di autorizzazione, durante la sessione senza creare una nuova versione dell'agente. Gli aggiornamenti sono locali alla sessione e non si propagano all'agente sottostante.

Solo tools e mcp_servers dell'agente possono cambiare dopo la creazione di una sessione. Per eseguire una sessione con valori di model, system o skills diversi da quelli dell'agente, usa gli override della configurazione dell'agente quando crei la sessione. Anche la configurazione del modello dell'agente, incluso il suo pin inference_geo, non può cambiare durante la sessione: imposta il pin quando salvi l'agente, oppure impostalo o rimuovilo per una singola sessione con un override di model quando la crei. Il campo system configurato dell'agente è fisso per l'intera durata della sessione. Sui modelli che lo supportano, puoi comunque aggiungere indicazioni a livello di sistema durante la sessione inviando un evento system.message.

La semantica di un aggiornamento di tools o mcp_servers è una sostituzione completa: l'array fornito è il nuovo valore. Per preservare le voci esistenti, esegui una GET sulla sessione, modifica l'array e invialo di nuovo con POST.

La sessione deve essere idle per aggiornare l'agente. Interrompi la sessione se devi aggiornare l'agente mentre è in esecuzione.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
  tools:
    - type: agent_toolset_20260401
    - type: mcp_toolset
      mcp_server_name: linear
  mcp_servers:
    - type: url
      name: linear
      url: https://mcp.linear.app/sse
YAML



Aggiornare il budget della sessione

Una sessione creata con un budget accetta due tipi di aggiornamento del budget: sostituire il limite con un nuovo max_list_cost e rimuoverlo impostando budget su null. Entrambi riprendono automaticamente il lavoro che si era interrotto quando la sessione aveva raggiunto il suo limite. Un limite sostitutivo può essere superiore o inferiore a quello attuale, ma deve essere strettamente maggiore del costo di listino consumato dalla sessione, e la rimozione è unidirezionale: un budget non null è accettato solo su una sessione che attualmente ne ha uno, quindi non puoi riaggiungere un budget rimosso né aggiungerne uno a una sessione creata senza. Consulta Budget delle sessioni per esempi di richieste, i comportamenti di errore e cosa viene conteggiato nel costo di listino.



Recuperare una sessione

ant beta:sessions retrieve --session-id "$SESSION_ID"



Elencare le sessioni

I risultati di GET /v1/sessions sono paginati. Usa il parametro di query limit per controllare la dimensione della pagina. Ogni risposta include un cursore next_page; passalo come parametro page nella richiesta successiva per recuperare la pagina seguente. next_page è null quando non ci sono altri risultati.

Per tornare indietro di una pagina, passa prev_page come parametro page. prev_page è null quando sei sulla prima pagina.

Un cursore page è opaco e codifica l'order della richiesta che lo ha prodotto. Il parametro di query order imposta la direzione di ordinamento dei risultati, asc o desc per data di creazione; il valore predefinito è desc (più recenti prima). Riutilizzare un cursore con un order diverso restituisce un errore 400, così come modificare un filtro created_at in modo che escluda la posizione del cursore. Gli altri parametri di query, inclusi i filtri rimanenti e limit, possono cambiare tra richieste paginate. Per i campi di paginazione condivisi tra gli endpoint di elenco, consulta Paginazione.

# --format raw restituisce un singolo envelope di pagina con i cursori prev_page e
# next_page; l'output predefinito pagina automaticamente ed emette solo le sessioni.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Passa il cursore next_page come --page per recuperare la pagina successiva.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Passa il prev_page di quella risposta come --page per tornare indietro allo stesso modo.



Archiviare una sessione

Archivia una sessione per impedire l'invio di nuovi eventi preservandone la cronologia. Una sessione running non può essere archiviata; invia un evento di interruzione se devi archiviarla immediatamente.

ant beta:sessions archive \
  --session-id "$SESSION_ID"



Eliminare una sessione

Elimina una sessione per rimuovere definitivamente il suo record, gli eventi e la sandbox associata. Una sessione running non può essere eliminata; invia un evento di interruzione se devi eliminarla immediatamente.

Memory store, vault, skill, environment e agent sono risorse indipendenti e non sono influenzate dall'eliminazione della sessione. Anche i file che hai caricato tramite la Files API non sono influenzati, ma i file prodotti dalla sessione stessa sono limitati ad essa e vengono eliminati definitivamente insieme al suo filesystem. Scarica tutto ciò che devi conservare prima di eliminare la sessione.

ant beta:sessions delete \
  --session-id "$SESSION_ID"