Avviare una sessione

Una sessione è un'istanza di agente 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. Le sessioni seguono un ciclo di vita in due fasi: prima crea la sessione, poi invia un evento utente per avviare il lavoro. Puoi anche unire entrambi i passaggi in un'unica chiamata con initial_events.

Creare una sessione

Una sessione richiede un ID agent e un ID environment. Gli agenti sono risorse versionate; passando l'ID agent come stringa, la sessione viene creata con l'ultima versione dell'agente.

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

Per vincolare una sessione a una versione specifica dell'agente, passa un oggetto. Questo ti permette di controllare esattamente quale versione viene eseguita e di pianificare il rilascio graduale di nuove versioni in modo indipendente.

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

Inizializzare la sessione con eventi iniziali

Puoi creare una sessione e avviarne il lavoro in un'unica chiamata. initial_events è un array opzionale di eventi iniziali da inviare alla sessione al momento della creazione, elaborati in ordine. Supporta gli eventi user.message e user.define_outcome e accetta un massimo di 50 eventi. Una lista non vuota avvia il ciclo dell'agente nella stessa chiamata: la sessione viene creata direttamente nello stato running, senza ulteriori richieste.

L'esempio seguente crea una sessione con un singolo user.message in initial_events:

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# gli initial_events non vengono restituiti nella risposta di creazione; rileggili
# dall'elenco eventi della sessione.
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

Nessun altro tipo di evento è accettato. Gli eventi che rispondono a un turno dell'agente (user.tool_confirmation, user.tool_result e user.custom_tool_result) non sono accettati perché non esiste ancora alcun turno dell'agente, e user.interrupt non è accettato perché non c'è alcun turno da interrompere. A differenza di initial_events in un deployment pianificato, gli initial_events di una sessione non accettano system.message.

Ogni evento in initial_events viene validato e reso persistente prima che la risposta di creazione venga restituita, nell'ordine della lista, con un ID assegnato dal server, esattamente come se lo avessi inviato all'endpoint di invio eventi immediatamente dopo la creazione. Anche le regole sul contenuto per singolo evento sono le stesse di quell'endpoint. Una lista vuota equivale a omettere il campo. La validazione è tutto-o-niente: se un qualsiasi evento non supera la validazione, l'intera richiesta viene rifiutata e nessuna sessione viene creata.

La richiesta di creazione viene rifiutata nei seguenti casi:

Un evento user.define_outcome in initial_events è accettato alle stesse condizioni dell'invio a una sessione esistente; consulta Definire i risultati.

Sovrascrivere la configurazione dell'agente per una sessione

Puoi passare agent in tre forme: una stringa con l'ID dell'agente, un oggetto con versione vincolata (type: "agent") oppure un oggetto di override (sovrascritture). La forma con override modifica parti della configurazione dell'agente per una singola sessione. Usala per provare un modello diverso o concedere uno strumento aggiuntivo in una sessione senza creare una nuova versione dell'agente. Per la forma con override, imposta type su agent_with_overrides e passa l'id dell'agente e facoltativamente una version (ometti version per usare l'ultima versione dell'agente). Quindi includi uno qualsiasi tra model, system, tools, mcp_servers o skills con i valori che la sessione deve usare.

Ogni campo sovrascrivibile segue le stesse tre regole:

• Ometti il campo: la sessione eredita il valore dalla versione dell'agente a cui fa riferimento.
• Imposta il campo su null, o su un array vuoto per i campi di tipo lista: la sessione viene eseguita con quel campo azzerato. Questa regola si applica integralmente a system e skills. Ci sono tre eccezioni:
  • model non è mai azzerabile. Una sessione ha sempre bisogno di un modello, quindi model: null restituisce un errore 400 agent_model_required.
  • Azzerare tools restituisce un errore 400 quando gli skills effettivi della sessione non sono vuoti, perché le skill richiedono lo strumento read. Altrimenti, tools: null e tools: [] azzerano il campo.
  • Azzerare mcp_servers restituisce un errore 400 quando i tools effettivi della sessione contengono ancora un mcp_toolset che fa riferimento a uno dei server dell'agente. Sovrascrivi tools nella stessa richiesta per rimuovere quelle voci mcp_toolset, quindi azzera mcp_servers.
• Imposta il campo su un valore: il valore sostituisce integralmente quello dell'agente. Gli override non vengono mai uniti alla configurazione dell'agente, quindi un override di tools deve elencare ogni strumento che la sessione deve avere. Allo stesso modo, un override di model sostituisce integralmente l'oggetto model dell'agente, quindi l'effort proprio dell'agente non viene mantenuto. Per eseguire la sessione a un livello di effort specifico, imposta effort all'interno dell'oggetto model dell'override. Un livello non supportato dal modello restituisce un errore 400, e un override di model senza effort viene eseguito al livello di effort predefinito di quel modello.

Gli override si applicano solo alla sessione che crei. Non modificano la risorsa agente né creano una nuova versione dell'agente, quindi le altre sessioni che fanno riferimento allo stesso agente non ne sono influenzate.

Nella risposta, l'oggetto agent riflette la configurazione con cui la sessione viene eseguita dopo l'applicazione degli override. I suoi id e version identificano comunque l'agente e la versione a cui gli override sono applicati. Questo ti permette di ricondurre una sessione al suo agente di base.

L'esempio seguente avvia una sessione che sovrascrive il modello e azzera il prompt di sistema:

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# L'agente nella risposta è lo snapshot risolto con gli override applicati.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

Vincolare l'area geografica di inferenza per una sessione

Poiché un override model sostituisce integralmente l'oggetto model dell'agente, imposta o azzera anche il vincolo inference_geo del modello per la sessione: un override che include inference_geo vincola l'area geografica che serve le richieste al modello della sessione, mentre uno che lo omette azzera il vincolo dell'agente, così che la sessione segua il default_inference_geo del workspace. Il valore sovrascritto viene validato rispetto agli allowed_inference_geos del workspace al momento della creazione della sessione.

L'esempio seguente avvia una sessione da un agente il cui modello non ha alcun vincolo geografico, vincola le richieste al modello della sessione all'inferenza negli Stati Uniti includendo inference_geo nell'override model, e stampa il valore restituito in agent.model nella risposta:

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

Impostare un budget per la sessione

Per limitare quanto una sessione può spendere, passa l'oggetto opzionale budget quando la crei. Un budget è un tetto rigido sul costo di listino della sessione: la piattaforma valuta tutto ciò che la sessione consuma alle tariffe di listino pubbliche, e la sessione smette di emettere nuove richieste al modello una volta che il totale progressivo raggiunge max_list_cost. Imposta type su limit e assegna a max_list_cost un amount e una currency. amount è un numero intero di centesimi di dollaro USA scritto come stringa, ad esempio "2500" per $25,00; l'API accetta una stringa anziché un numero in modo che non venga mai applicato alcun arrotondamento in virgola mobile. USD è l'unica valuta attualmente supportata. Quando la sessione raggiunge il tetto, si mette in pausa e diventa inattiva con lo stop reason budget_reached. Il tetto viene applicato tra una richiesta al modello e l'altra, quindi la richiesta che lo supera viene prima completata e il costo di listino finale della sessione può risultare leggermente oltre il tetto. Un budget può essere associato solo al momento della creazione: puoi modificarlo o rimuoverlo in seguito, ma non puoi aggiungerne uno a una sessione creata senza.

L'esempio seguente crea una sessione con un budget di $25,00; la risposta riporta il budget nella risorsa della sessione:

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

Consulta Budget delle sessioni per sapere come funziona l'applicazione del limite, cosa viene conteggiato nel costo di listino e come si comportano i budget nelle sessioni multiagente.

Autenticazione MCP tramite vault

Se il tuo agente usa strumenti MCP che richiedono autenticazione, passa vault_ids alla creazione della sessione per fare riferimento a un vault contenente credenziali OAuth archiviate. Anthropic gestisce il rinnovo dei token per tuo conto. Consulta Autenticarsi con i vault per sapere come creare vault e registrare credenziali.

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Avviare la sessione

Creare una sessione senza initial_events registra la sessione ma non avvia alcun lavoro; il provisioning della sandbox dell'ambiente inizia non appena la sessione viene creata, quindi la prima chiamata a uno strumento non deve attenderlo. Per delegare un'attività, invia eventi alla sessione usando un evento utente. Per fornire invece il primo evento nella richiesta di creazione, consulta Inizializzare la sessione con eventi iniziali. La sessione agisce come una macchina a stati che tiene traccia dei progressi, mentre gli eventi guidano l'esecuzione effettiva.

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

Consulta Stream di eventi della sessione per sapere come ricevere in streaming le risposte dell'agente e gestire le conferme degli strumenti.

Consulta Stati della sessione per gli stati attraverso cui passa una sessione.

Passaggi successivi