Iniciar uma sessão

Uma sessão é uma instância de agente em execução dentro de um ambiente. Cada sessão referencia um agente e um ambiente (ambos criados separadamente) e mantém o histórico de conversas em múltiplas interações.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Criando uma sessão

Uma sessão requer um ID de agent e um ID de environment. Agentes são recursos versionados; passar o ID do agent como uma string inicia a sessão com a versão mais recente do 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")

Para fixar uma sessão a uma versão específica do agente, passe um objeto. Isso permite que você controle exatamente qual versão é executada e prepare lançamentos de novas versões independentemente.

O agente define como Claude se comporta dentro da sessão, incluindo o modelo, prompt do sistema, ferramentas e servidores MCP. Veja Configuração do agente para detalhes.

Autenticação MCP através de cofres

Se seu agente usa ferramentas MCP que requerem autenticação, passe vault_ids na criação da sessão para referenciar um cofre contendo credenciais OAuth armazenadas. Anthropic gerencia a atualização de tokens em seu nome. Veja Autenticar com cofres para saber como criar cofres e registrar credenciais.

Iniciando a sessão

Criar uma sessão provisiona o ambiente e o agente, mas não inicia nenhum trabalho. Para delegar uma tarefa, envie eventos para a sessão usando um evento de usuário. A sessão atua como uma máquina de estados que rastreia o progresso enquanto os eventos impulsionam a execução real.

Veja Eventos e streaming para saber como fazer streaming das respostas do agente e lidar com confirmações de ferramentas.

Status das sessões

As sessões progridem através destes status:

Status	Descrição
`idle`	O agente está aguardando entrada, incluindo mensagens de usuário ou confirmações de ferramentas. As sessões começam em `idle`.
`running`	O agente está executando ativamente
`rescheduling`	Erro transitório ocorreu, tentando novamente automaticamente
`terminated`	A sessão terminou devido a um erro irrecuperável

Outras operações de sessão

Recuperando uma sessão

Listando sessões

Arquivando uma sessão

Arquive uma sessão para evitar que novos eventos sejam enviados enquanto preserva seu histórico:

Deletando uma sessão

Delete uma sessão para remover permanentemente seu registro, eventos e contêiner associado. Uma sessão running não pode ser deletada; envie um evento de interrupção se precisar deletá-la imediatamente.

Arquivos, armazenamentos de memória, ambientes e agentes são recursos independentes e não são afetados pela exclusão da sessão.

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"