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, durante la sessione 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 i tools e gli 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 a metà 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 tutta la durata della sessione. Sui modelli che lo supportano, puoi comunque aggiungere indicazioni a livello di sistema a metà 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 e reinvialo 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.

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 impostando budget a null. Entrambi riprendono automaticamente il lavoro che si era interrotto quando la sessione aveva raggiunto il proprio limite. Un limite sostitutivo può essere più alto o più basso di quello attuale, ma deve essere strettamente maggiore del costo di listino consumato dalla sessione, e la rimozione è irreversibile: un budget non nullo è accettato solo su una sessione che attualmente ne ha uno, quindi non puoi aggiungere nuovamente 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.

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.

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)