Iniciar una sesión

Una sesión es una instancia de agente en ejecución dentro de un entorno. Cada sesión hace referencia a un agente y un entorno (ambos creados por separado), y mantiene el historial de conversación a través de múltiples interacciones.

Todas las solicitudes a la API de Managed Agents requieren el encabezado beta managed-agents-2026-04-01. El SDK establece el encabezado beta automáticamente.

Crear una sesión

Una sesión requiere un ID de agent y un ID de environment. Los agentes son recursos versionados; pasar el ID de agent como cadena de texto inicia la sesión con la versión más reciente del 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 fijar una sesión a una versión específica del agente, pasa un objeto. Esto te permite controlar exactamente qué versión se ejecuta y gestionar los despliegues de nuevas versiones de forma independiente.

El agente define cómo se comporta Claude dentro de la sesión, incluyendo el modelo, el prompt del sistema, las herramientas y los servidores MCP. Consulta Configuración del agente para más detalles.

Autenticación MCP mediante vaults

Si tu agente utiliza herramientas MCP que requieren autenticación, pasa vault_ids al crear la sesión para hacer referencia a un vault que contenga credenciales OAuth almacenadas. Anthropic gestiona la renovación de tokens en tu nombre. Consulta Autenticar con vaults para saber cómo crear vaults y registrar credenciales.

Iniciar la sesión

Crear una sesión aprovisiona el entorno y el agente, pero no inicia ningún trabajo. Para delegar una tarea, envía eventos a la sesión usando un evento de usuario. La sesión actúa como una máquina de estados que rastrea el progreso mientras los eventos impulsan la ejecución real.

Consulta Eventos y streaming para saber cómo transmitir las respuestas del agente y gestionar las confirmaciones de herramientas.

Estados de la sesión

Las sesiones avanzan a través de estos estados:

Estado	Descripción
`idle`	El agente está esperando entrada, incluyendo mensajes de usuario o confirmaciones de herramientas. Las sesiones comienzan en `idle`.
`running`	El agente está ejecutando activamente
`rescheduling`	Ocurrió un error transitorio, reintentando automáticamente
`terminated`	La sesión ha finalizado debido a un error irrecuperable

Otras operaciones de sesión

Recuperar una sesión

Listar sesiones

Archivar una sesión

Archiva una sesión para evitar que se envíen nuevos eventos mientras se preserva su historial:

Eliminar una sesión

Elimina una sesión para borrar permanentemente su registro, eventos y el contenedor asociado. Una sesión en estado running no puede eliminarse; envía un evento de interrupción si necesitas eliminarla de inmediato.

Los archivos, almacenes de memoria, entornos y agentes son recursos independientes y no se ven afectados por la eliminación de la sesión.

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"