Avviare una sessione

Avvia una sessione

Una sessione è un'istanza di agente in esecuzione all'interno di un ambiente. Ogni sessione fa riferimento a un agente e a un ambiente (entrambi creati separatamente) e mantiene la cronologia della conversazione attraverso più interazioni.

Tutte le richieste dell'API Managed Agents richiedono l'intestazione beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'intestazione beta.

Creazione di una sessione

Una sessione richiede un ID agent e un ID environment. Gli agenti sono risorse con versione; passare l'ID agent come stringa avvia la sessione con la versione più recente dell'agente.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Per fissare una sessione a una versione specifica dell'agente, passa un oggetto. Questo ti consente di controllare esattamente quale versione viene eseguita e di gestire i rollout delle nuove versioni in modo indipendente.

L'agente definisce come Claude si comporta all'interno della sessione, incluso il modello, il prompt di sistema, gli strumenti e i server MCP. Vedi Configurazione dell'agente per i dettagli.

Autenticazione MCP tramite vault

Se il tuo agente utilizza strumenti MCP che richiedono autenticazione, passa vault_ids durante la creazione della sessione per fare riferimento a un vault contenente credenziali OAuth archiviate. Anthropic gestisce l'aggiornamento dei token per tuo conto. Vedi Autenticazione con vault per come creare vault e registrare credenziali.

Avvio della sessione

La creazione di una sessione provisioning l'ambiente e l'agente ma non avvia alcun lavoro. Per delegare un'attività, invia eventi alla sessione utilizzando un evento utente. La sessione agisce come una macchina a stati che traccia il progresso mentre gli eventi guidano l'esecuzione effettiva.

Vedi Eventi e streaming per come trasmettere le risposte dell'agente e gestire le conferme degli strumenti.

Stati della sessione

Le sessioni progrediscono attraverso questi stati:

Stato	Descrizione
`idle`	L'agente è in attesa di input, inclusi messaggi utente o conferme di strumenti. Le sessioni iniziano in `idle`.
`running`	L'agente è in esecuzione attiva
`rescheduling`	Si è verificato un errore transitorio, riprovando automaticamente
`terminated`	La sessione è terminata a causa di un errore irrecuperabile

Altre operazioni di sessione

Recupero di una sessione

Elenco delle sessioni

Archiviazione di una sessione

Archivia una sessione per impedire l'invio di nuovi eventi preservando la sua cronologia:

Eliminazione di una sessione

Elimina una sessione per rimuovere permanentemente il suo record, gli eventi e il contenitore associato. Una sessione running non può essere eliminata; invia un evento di interruzione se hai bisogno di eliminarla immediatamente.

File, archivi di memoria, ambienti e agenti sono risorse indipendenti e non sono interessati dall'eliminazione della sessione.

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)