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 politiche 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 i campi 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. Il campo system configurato dell'agente è fisso per tutta la 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 è la sostituzione completa: l'array fornito è il nuovo valore. Per preservare le voci esistenti, esegui una GET della sessione, modifica l'array ed esegui una POST per reinviarlo.

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 altri risultati.

Per tornare indietro di una pagina, passa prev_page come parametro page. prev_page è null quando ti trovi 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 (prima i più recenti). Riutilizzare un cursore con un order diverso restituisce un errore 400; gli altri parametri di query, inclusi i filtri e limit, possono cambiare tra le 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 rimuoverne in modo permanente il 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, ambienti e agenti sono risorse indipendenti e non sono influenzati dall'eliminazione della sessione.

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