Cómo construir un agente autónomo con Claude Managed Agents: guía paso a paso

Claude Managed Agents es la alternativa gestionada a la Messages API de Anthropic. Mientras la Messages API te da acceso directo al modelo con control total sobre el loop de razonamiento, Managed Agents entrega un harness preconfigurado que corre en infraestructura de Anthropic: sandbox seguro, herramientas integradas (bash, lectura/escritura de archivos, búsqueda web), compaction automática y caché de prompts.

Cuándo elegir Managed Agents sobre un loop propio

Elige Managed Agents cuando la tarea dura minutos u horas, necesitas un sandbox limpio por ejecución, tu equipo no quiere mantener su propio harness, o requieres sesiones con historial que persista entre interacciones.

Cuatro conceptos centrales

• Agent: define el modelo, el system prompt, las herramientas y los servidores MCP.
• Environment: configura dónde corre cada sesión (sandbox cloud de Anthropic o self-hosted en tu infraestructura).
• Session: instancia de ejecución que referencia un Agent y un Environment; mantiene historial y estado del filesystem.
• Events: mensajes que intercambias con el agente (turnos de usuario, resultados de herramientas, actualizaciones de estado) vía server-sent events (SSE).

Un agente es un recurso reutilizable y versionado. Lo creas una vez y lo referencias por ID en cada sesión. El tipo de herramienta agent_toolset_20260401 activa el conjunto completo: bash, operaciones de archivo, búsqueda web y más.

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Agente de análisis",
    model="claude-opus-4-8",
    system="Eres un asistente técnico. Analiza archivos, ejecuta scripts y reporta resultados con precisión.",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
)

print("Agent ID:", agent.id)
print("Version:", agent.version)

Guarda el valor de agent.id; lo necesitarás en cada sesión que inicies. Los agentes son versionados: cada modificación genera una nueva versión y puedes fijar sesiones a versiones específicas para rollouts controlados.

Una sesión es la instancia de ejecución real. Crearla provisiona el sandbox; el trabajo no comienza hasta que envías el primer evento de usuario. El patrón correcto es abrir el stream primero y luego enviar el evento; el SDK gestiona el orden internamente.

Crea la sesión

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Analisis de dependencias Python",
)

print("Session ID:", session.id)

Abre el stream y envía el mensaje

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": "Crea un script Python que lea requirements.txt, detecte dependencias desactualizadas con pip list --outdated y guarde un reporte en outdated.txt",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="", flush=True)
            case "agent.tool_use":
                print("[Herramienta: " + event.name + "]")
            case "session.status_idle":
                print("\n[Agente termino]")
                break

El agente ejecuta el loop de razonamiento automáticamente: escribe el script, lo ejecuta con bash, lee el resultado y entrega el reporte — sin que tú administres ninguno de esos pasos internos.

Para integrar herramientas externas (bases de datos, CRMs, APIs propias), puedes conectar servidores MCP al agente. MCP (Model Context Protocol) es el estándar de Anthropic para extensión de herramientas y funciona con cualquier servidor accesible vía URL.

agent_con_mcp = client.beta.agents.create(
    name="Agente con CRM",
    model="claude-opus-4-8",
    system="Eres un asistente de ventas. Usa las herramientas disponibles para consultar y actualizar el CRM.",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mi-mcp-server.ejemplo.com/sse",
            "name": "crm-interno",
        }
    ],
)

Si el servidor MCP requiere autenticación OAuth, usa vault_ids al crear la sesión para referenciar credenciales almacenadas; Anthropic gestiona el refresco de tokens automáticamente.