Guía de inicio rápido de Claude Managed Agents 2026

La primera vez que intenté ejecutar una sesión de Managed Agents, obtuve un error 400 en el primer curl. No en la creación del agente. No en el entorno. En el endpoint de streaming. Copié mi encabezado de la solicitud de creación — anthropic-beta: managed-agents-2026-04-01 — y la API de streaming lo rechazó. Resulta que el endpoint de streaming, en ese momento en la documentación, hacía referencia a un encabezado beta diferente. Perdí cuarenta minutos en eso.

Si estás intentando que tu primera sesión de Managed Agents funcione de extremo a extremo hoy, este es el camino que yo recorrí. ¡Hola, soy Dora! El encabezado beta primero, porque ahí es donde vive la mitad de los fallos. Luego el agente, el entorno, la sesión, el stream. Y un punto de control de costos al final, porque el tiempo de ejecución de la sesión sigue contando mientras depuras.

Antes de Empezar

Necesitas una clave API de Anthropic con acceso a Managed Agents. No hay lista de espera ahora mismo — cualquier clave existente funciona en la beta pública.

El encabezado beta no es negociable. Cada endpoint de Managed Agents requiere anthropic-beta: managed-agents-2026-04-01. Según el resumen de Managed Agents de Anthropic, el SDK lo configura automáticamente. Si usas curl directamente, lo añades tú mismo en cada solicitud. Esta es la causa más común de errores 400 que he visto en informes de la comunidad.

Si usas el SDK oficial (anthropic para Python, @anthropic-ai/sdk para TypeScript), verifica que estás en una versión que incluye soporte de agentes beta. Las versiones antiguas no tendrán client.beta.agents ni client.beta.sessions.

La elección del modelo importa aquí. Opus 4.7 es más inteligente para razonamiento de agentes a largo horizonte. Sonnet 4.6 es más económico y rápido por token. Para una ejecución de inicio rápido, Sonnet 4.6 es suficiente. Si tu carga de trabajo real implica depuración, planificación o cadenas largas de herramientas, Opus 4.7 justifica su precio.

Paso 1 — Define Tu Agente

Un agente, en Managed Agents, es un objeto de configuración, no un proceso. Defines nombre, modelo, prompt del sistema y acceso a herramientas una vez, y luego lo reutilizas en sesiones.

Definición mínima viable del inicio rápido oficial:

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

El tipo de herramienta agent_toolset_20260401 desbloquea el conjunto completo de herramientas integradas — bash, lectura/escritura de archivos, búsqueda web, fetch web, ejecución de código. Puedes restringirlo más adelante. Para una primera ejecución, déjalo amplio para que puedas ver qué elige usar el agente.

Guarda agent.id. Cada sesión lo referencia.

Paso 2 — Crea un Entorno

Un entorno define el contenedor aislado (sandbox). Para la mayoría de las primeras ejecuciones:

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

Guarda env.id. Si tu agente solo accede a su propio sistema de archivos, "networking": {"type": "limited"} es más seguro y está bien documentado en el cookbook del respondedor de incidentes SRE.

Paso 3 — Inicia una Sesión

Una sesión vincula un agente con un entorno. Crear una sesión no inicia el trabajo. Solo provisiona. El trabajo comienza cuando envías un evento de usuario.

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

Este patrón — crear, luego dirigir con eventos — es donde el modelo de máquina de estados de la referencia de sesiones tiene sentido. La sesión persiste. Puedes enviar más eventos después. El sistema de archivos sobrevive entre turnos.

Paso 4 — Transmitir Eventos

Abre el stream, envía el mensaje del usuario, lee eventos hasta session.status_idle:

python

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text",
                         "text": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

Los nombres de eventos siguen el patrón {dominio}.{acción}. El esquema completo está en la documentación de eventos y streaming. El campo processed_at importa: si es null, el evento está en cola, aún no ejecutado. Pasé esto por alto en mi primera ejecución y pensé que las herramientas fallaban silenciosamente.

Puntos de Control de Costos

Managed Agents factura dos cosas: tarifas de tokens estándar más $0.08 por hora de sesión de tiempo de ejecución activo. Según la página oficial de precios, el tiempo de ejecución se acumula por milisegundo — pero solo mientras el estado es running. El tiempo inactivo y las sesiones terminadas no cobran.

Lo que esto significa en la práctica:

• Una sesión que olvidas cerrar mientras depuras: sigue acumulando (si está en ejecución).
• Búsqueda web: $10 por 1,000 llamadas, facturado por separado. Los agentes de investigación alcanzan esto rápido.
• Verifica las sesiones activas en el rastreo de la Consola antes de terminar el día. Verifica tú mismo la ruta actual de la interfaz — el diseño de la Consola ha estado iterando.

Errores Comunes

Encabezado beta faltante o incorrecto. Error 400, a menudo con un mensaje sobre endpoints no soportados. Solución: confirma managed-agents-2026-04-01 en cada llamada HTTP directa. Si usas el SDK y aún tienes este error, actualiza el SDK.

Límites de velocidad. Los endpoints de creación tienen un límite de 60 rpm; los endpoints de lectura, 600 rpm. Los límites de nivel de organización siguen aplicándose encima. Los errores 429 significan que debes esperar con jitter, no reintentar de inmediato.

Bucle de herramientas silencioso. El agente sigue llamando herramientas pero no produce un mensaje final. Verifica los trazos de sesión — generalmente es un requires_action no gestionado que nunca recibió una respuesta enviada de vuelta.

Preguntas Frecuentes

P1: ¿Cómo habilito la coordinación multi-agente en Managed Agents?

Multi-agente (junto con memoria y resultados) sigue siendo una función de vista previa de investigación. Solicitas el acceso por separado a través de la Consola de Claude. El patrón de coordinación — orquestador delegando a agentes invocables — está documentado en sesiones multiagente, pero no puedes usarlo hasta que el indicador de vista previa esté activado para tu organización.

P2: ¿Puedo inspeccionar qué herramientas llamó el agente durante una sesión?

Sí. Usa client.beta.sessions.events.list(session.id) para acceso programático, o la vista de rastreo de la Consola para una línea de tiempo cronológica con tokens y marcas de tiempo por evento.

P3: ¿Dónde está el cookbook oficial de Managed Agents?

Los tutoriales están en el sitio de Claude Cookbook — el notebook iterate-fix-failing-tests es la mejor primera lectura. El notebook operate-in-production cubre vaults, MCP y webhooks una vez que superas la etapa de hello-world.

P4: ¿Hay alguna forma de probar sin incurrir en costos de tiempo de ejecución de sesión?

No existe un nivel gratuito dedicado para Managed Agents. Los créditos gratuitos estándar de la API lo cubren. Mantén las sesiones cortas durante el desarrollo y ciérralas cuando dejes de trabajar. Las sesiones inactivas no cobran, pero las que están en ejecución sí — y “en ejecución” incluye agentes en bucle silencioso.

P5: ¿Cuál es el mejor modelo para tareas de larga duración en Managed Agents?

Depende de lo que signifique “larga duración”. Para razonamiento de varias horas con uso intensivo de herramientas, Opus 4.7. Para bucles simples de alto volumen, Sonnet 4.6 con caché de prompts reduce significativamente el costo. Sigo probando Opus 4.7 en sesiones de más de 2 horas. Ahí es donde terminan mis datos. Más por venir.

Todavía verificando cómo se comporta la compactación después de las dos horas. Ejecútalo tú mismo — eso te dirá más de lo que yo puedo.

Publicaciones anteriores:

• Godmod3 AI Explained
• Claude Opus 4.7 Unified Model & API Layer
• Agentic Workflow Tool Wiring: Patterns & Pitfalls
• GLM-5V Turbo vs GPT-4o Vision UI & Coding
• How to Set Up G0DM0D3 OpenRouter 2026