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 delle conversazioni attraverso più interazioni.

Tutte le richieste API di 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=$(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"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

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 il rilascio graduale di nuove versioni in modo indipendente.

L'agente definisce il comportamento di Claude all'interno della sessione, inclusi il modello, il prompt di sistema, gli strumenti e i server MCP. Consulta Configurazione dell'agente per i dettagli.

Autenticazione MCP tramite vault

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

Avvio della sessione

La creazione di una sessione predispone l'ambiente e l'agente, ma non avvia alcuna attività. Per delegare un'attività, invia eventi alla sessione utilizzando un evento utente. La sessione agisce come una macchina a stati che tiene traccia dei progressi mentre gli eventi guidano l'esecuzione effettiva.

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

Stati della sessione

Le sessioni avanzano attraverso questi stati:

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

Altre operazioni sulle sessioni

Recupero di una sessione

Elenco delle sessioni

Archiviazione di una sessione

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

Eliminazione di una sessione

Elimina una sessione per rimuovere definitivamente il suo record, gli eventi e il container associato. Una sessione in stato 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 vengono influenzati dall'eliminazione della sessione.

pinned_session=$(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": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")

vault_session=$(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",
  "vault_ids": ["$VAULT_ID"]
}
EOF
)
VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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'
{
  "events": [
    {
      "type": "user.message",
      "content": [{"type": "text", "text": "List the files in the working directory."}]
    }
  ]
}
EOF

retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
echo "Status: $(jq -r '.status' <<< "$retrieved")"

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" \
  | jq -r '.data[] | "\(.id): \(.status)"'

curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"