Comenzar con Claude Managed Agents

Esta guía te lleva a través de la creación de un agente, la configuración de un entorno, el inicio de una sesión y la transmisión de respuestas del agente.

Conceptos principales

Concept	Description
Agent	The model, system prompt, tools, MCP servers, and skills
Environment	A configured container template (packages, network access)
Session	A running agent instance within an environment, performing a specific task and generating outputs
Events	Messages exchanged between your application and the agent (user turns, tool results, status updates)

Requisitos previos

Una cuenta de Console de Anthropic
Una clave de API

Instalar la CLI

Verifica la instalación:

ant --version

Instalar el SDK

Establece tu clave de API como variable de entorno:

export ANTHROPIC_API_KEY="your-api-key-here"

Crea tu primera sesión

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.

Qué está ocurriendo

Cuando envías un evento de usuario, Claude Managed Agents:

Aprovisiona un contenedor: Tu configuración de entorno determina cómo se construye.
Ejecuta el bucle del agente: Claude decide qué herramientas usar según tu mensaje
Ejecuta herramientas: Las escrituras de archivos, los comandos bash y otras llamadas a herramientas se ejecutan dentro del contenedor
Transmite eventos: Recibes actualizaciones en tiempo real mientras el agente trabaja
Entra en reposo: El agente emite un evento session.status_idle cuando no tiene nada más que hacer

Próximos pasos

Define tu agente

Crea configuraciones de agente reutilizables y versionadas

Crear un agente

Crea un agente que defina el modelo, el prompt del sistema y las herramientas disponibles.

set -euo pipefail

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -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'
{
  "name": "Coding Assistant",
  "model": "claude-sonnet-4-6",
  "system": "You are a helpful coding assistant. Write clean, well-documented code.",
  "tools": [
    {"type": "agent_toolset_20260401"}
  ]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")

echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

El tipo de herramienta agent_toolset_20260401 habilita el conjunto completo de herramientas de agente predefinidas (bash, operaciones de archivos, búsqueda web y más). Consulta Herramientas para ver la lista completa y las opciones de configuración por herramienta.

Guarda el agent.id devuelto. Lo referenciarás en cada sesión que crees.

Crear un entorno

Un entorno define el contenedor donde se ejecuta tu agente.

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -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'
{
  "name": "quickstart-env",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

echo "Environment ID: $ENVIRONMENT_ID"

Guarda el environment.id devuelto. Lo referenciarás en cada sesión que crees.

Iniciar una sesión

Crea una sesión que haga referencia a tu agente y entorno.

session=$(
  curl -sS --fail-with-body 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",
  "title": "Quickstart session"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

Enviar un mensaje y transmitir la respuesta

Abre un stream, envía un evento de usuario y luego procesa los eventos a medida que llegan:

# Send the user message first; the API buffers events until the stream attaches
curl -sS --fail-with-body \
  "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 @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
        }
      ]
    }
  ]
}
EOF

# Open the SSE stream and process events as they arrive
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<<"$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<<"$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

El agente escribirá un script de Python, lo ejecutará en el contenedor y verificará que el archivo de salida fue creado. Tu salida se verá similar a esto:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.