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 e le impostazioni web per singolo strumento come i filtri di dominio, a sessione in corso senza creare una nuova versione dell'agente. Gli aggiornamenti sono locali alla sessione e non si propagano all'agente sottostante. I valori aggiornati di allowed_domains e blocked_domains si applicano al resto della sessione.

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 vincolo inference_geo, non può cambiare a sessione in corso: imposta il vincolo quando salvi l'agente, oppure impostalo o rimuovilo per una singola sessione con un override di model quando la crei. Il campo system configurato per l'agente è fisso per tutta la durata della sessione. Sui modelli che lo supportano, puoi comunque aggiungere indicazioni a livello di sistema a sessione in corso inviando un evento system.message.

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

La sessione deve essere idle per aggiornare l'agente. Per aggiornare l'agente mentre la sessione è in esecuzione, invia un evento user.interrupt da solo e attendi che la sessione diventi idle. Se un'esecuzione di workflow è aperta, che sia in corso o in pausa, l'aggiornamento restituisce un errore 400, anche quando la sessione è idle. Un'interruzione non termina un'esecuzione, quindi l'aggiornamento fallisce comunque dopo che hai interrotto la sessione. Invia un user.message che chieda all'agente di fermare le sue esecuzioni, oppure attendi che ogni esecuzione sia terminata.

client.beta.sessions.update(
    session.id,
    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"}
        ],
    },
)

Aggiornare il budget della sessione

Una sessione creata con un budget accetta due tipi di aggiornamento del budget: la sostituzione del limite con un nuovo max_list_cost e la sua rimozione passando budget=None. Entrambi riprendono automaticamente il lavoro che si era messo in pausa quando la sessione ha raggiunto il suo limite. Un limite sostitutivo può essere più alto o più basso di quello attuale, ma deve essere strettamente maggiore del costo di listino già consumato dalla sessione, e la rimozione è irreversibile: un budget non nullo viene accettato solo su una sessione che ne ha attualmente uno, quindi non puoi aggiungere di nuovo un budget rimosso né aggiungerne uno a una sessione creata senza. Consulta Budget delle sessioni per esempi di richieste, i comportamenti in caso di errore e cosa viene conteggiato nel costo di listino.

Recuperare una sessione

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

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 (i più recenti per primi). 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 una richiesta paginata e l'altra. Per i campi di paginazione condivisi tra gli endpoint di elenco, consulta Paginazione.

# Imposta `limit` basso così i risultati occupano più di una pagina.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` è None sulla prima pagina; `next_page` è None sull'ultima.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Ripassa `next_page` come `page` per recuperare la pagina successiva.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Ripassa `prev_page` come `page` per tornare alla pagina precedente.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Per l'iterazione solo in avanti, l'oggetto pagina è anche direttamente iterabile.

Archiviare una sessione

Archivia una sessione per impedire l'invio di nuovi eventi preservandone la cronologia. Una sessione running non può essere archiviata; per archiviarla, invia un evento user.interrupt da solo e attendi che la sessione diventi idle. Se un'esecuzione di workflow è aperta, l'archiviazione potrebbe restituire un errore 400, anche quando la sessione è idle, oppure potrebbe riuscire e terminare l'esecuzione. Prima di archiviare, invia un user.message che chieda all'agente di fermare le sue esecuzioni, oppure attendi che ogni esecuzione sia terminata. Quindi archivia la sessione una volta che è idle.

client.beta.sessions.archive(session.id)

Eliminare una sessione

Elimina una sessione per rimuoverne definitivamente il record, gli eventi e la sandbox associata. Una sessione running non può essere eliminata; per eliminarla, invia un evento user.interrupt da solo e attendi che la sessione diventi idle. Se un'esecuzione di workflow è aperta, l'eliminazione potrebbe restituire un errore 400, anche quando la sessione è idle, oppure potrebbe riuscire. Dopo un'eliminazione riuscita, nessun evento workflow_run segnala la fine delle esecuzioni della sessione. Prima di eliminare, invia un user.message che chieda all'agente di fermare le sue esecuzioni, oppure attendi che ogni esecuzione sia terminata. Quindi elimina la sessione una volta che è idle.

Memory store, vault, skill, ambienti e agenti sono risorse indipendenti e non sono interessati dall'eliminazione della sessione. Anche i file che hai caricato tramite la Files API non sono interessati, 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. Un file di output scritto alla fine dell'ultimo turno può richiedere alcuni secondi dopo che la sessione è diventata idle per comparire nell'elenco dei file della sessione, quindi verifica prima che i file che ti aspetti siano elencati.

client.beta.sessions.delete(session.id)