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 essere modificati 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. Il campo system configurato dell'agente è fisso per tutta la durata della sessione. Sui modelli che lo supportano, puoi comunque sostituire il prompt di sistema effettivo tra un turno e l'altro inviando un evento system.message.

La semantica di un aggiornamento di tools o mcp_servers è la sostituzione completa: l'array fornito è il nuovo valore. Per preservare le voci esistenti, esegui una GET sulla sessione, modifica l'array e invialo nuovamente 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



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 più 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 in base alla data di creazione; il valore predefinito è desc (più recenti per primi). Riutilizzare un cursore con un order diverso restituisce un errore 400; altri parametri di query, inclusi i filtri e limit, possono cambiare tra richieste paginate. Per i campi di paginazione condivisi tra gli endpoint di elenco, consulta Paginazione.

# --format raw restituisce un envelope di pagina con i suoi cursori prev_page e
# next_page; l'output predefinito auto-pagina 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.

File, memory store, vault, skill, environment e agent sono risorse indipendenti e non sono influenzati dall'eliminazione della sessione.

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