Agentes gestionadosPrimeros pasos

Comienza con Claude Managed Agents

Crea tu primer agente autónomo.

Esta guía te muestra cómo crear un agente, configurar un entorno, iniciar una sesión y transmitir las respuestas del agente mediante streaming.

¿Prefieres un tutorial interactivo? Ejecuta /claude-api managed-agents-onboard en la versión más reciente de Claude Code para obtener una configuración guiada y respuestas interactivas a tus preguntas.

Conceptos fundamentales

Concepto	Descripción
Agente	El modelo, la indicación del sistema, las herramientas, los servidores MCP y las habilidades
Entorno	Configuración de dónde se ejecutan las sesiones: un sandbox en la nube gestionado por Anthropic, o un sandbox autoalojado en tu propia infraestructura
Sesión	Una instancia de agente en ejecución dentro de un entorno, que realiza una tarea específica y genera salidas
Eventos	Mensajes intercambiados entre tu aplicación y el agente (turnos del usuario, resultados de herramientas, actualizaciones de estado)

Requisitos previos

Una cuenta de Console de Anthropic
Una clave de API

Instala la CLI

Verifica la instalación:

ant --version

Instala el SDK

Configura tu clave de API como una variable de entorno:

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

Crea tu primera sesión

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

Crea un agente
Crea un agente que defina el modelo, la indicación del sistema y las herramientas disponibles.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
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 de cada herramienta.
Guarda el agent.id devuelto. Lo referenciarás en cada sesión que crees.
Crea un entorno
Un entorno define el sandbox donde se ejecuta tu agente.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Guarda el environment.id devuelto. Lo referenciarás en cada sesión que crees.
Para ejecutar el sandbox en tu propia infraestructura en lugar de un sandbox en la nube, consulta Sandboxes autoalojados.

Inicia una sesión

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

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

print(f"Session ID: {session.id}")

Envía un mensaje y transmite la respuesta mediante streaming

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

with client.beta.sessions.events.stream(session.id) as stream:
    # Envía el mensaje del usuario después de que se abra el stream
    client.beta.sessions.events.send(
        session.id,
        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",
                    },
                ],
            },
        ],
    )

    # Procesa los eventos de streaming
    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[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

El agente escribe un script de Python, lo ejecuta en el sandbox y verifica que se haya creado el archivo de salida. 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.

Qué está sucediendo

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

Aprovisiona un sandbox: La configuración de tu entorno determina cómo se construye.
Ejecuta el bucle del agente: Claude determina qué herramientas usar según tu mensaje.
Ejecuta herramientas: Las escrituras de archivos, los comandos de bash y otras llamadas a herramientas se ejecutan dentro del sandbox.
Transmite eventos mediante streaming: Recibes actualizaciones en tiempo real mientras el agente trabaja.
Pasa a estado inactivo: 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

Configura entornos

Personaliza la configuración de red y del sandbox

Herramientas del agente

Habilita herramientas específicas para tu agente

Stream de eventos de sesión

Maneja eventos y dirige al agente durante la ejecución

Despliegues programados

Ejecuta tu agente en un horario cron recurrente

Was this page helpful?

Conceptos fundamentales

Concepto	Descripción
Agente	El modelo, la indicación del sistema, las herramientas, los servidores MCP y las habilidades
Entorno	Configuración de dónde se ejecutan las sesiones: un sandbox en la nube gestionado por Anthropic, o un sandbox autoalojado en tu propia infraestructura
Sesión	Una instancia de agente en ejecución dentro de un entorno, que realiza una tarea específica y genera salidas
Eventos	Mensajes intercambiados entre tu aplicación y el agente (turnos del usuario, resultados de herramientas, actualizaciones de estado)

Crea tu primera sesión

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

Crea un agente
Crea un agente que defina el modelo, la indicación del sistema y las herramientas disponibles.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
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 de cada herramienta.
Guarda el agent.id devuelto. Lo referenciarás en cada sesión que crees.
Crea un entorno
Un entorno define el sandbox donde se ejecuta tu agente.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Guarda el environment.id devuelto. Lo referenciarás en cada sesión que crees.
Para ejecutar el sandbox en tu propia infraestructura en lugar de un sandbox en la nube, consulta Sandboxes autoalojados.

Inicia una sesión

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

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

print(f"Session ID: {session.id}")

Envía un mensaje y transmite la respuesta mediante streaming

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

with client.beta.sessions.events.stream(session.id) as stream:
    # Envía el mensaje del usuario después de que se abra el stream
    client.beta.sessions.events.send(
        session.id,
        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",
                    },
                ],
            },
        ],
    )

    # Procesa los eventos de streaming
    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[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

El agente escribe un script de Python, lo ejecuta en el sandbox y verifica que se haya creado el archivo de salida. 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.

Qué está sucediendo

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

Aprovisiona un sandbox: La configuración de tu entorno determina cómo se construye.

Ejecuta el bucle del agente: Claude determina qué herramientas usar según tu mensaje.

Ejecuta herramientas: Las escrituras de archivos, los comandos de bash y otras llamadas a herramientas se ejecutan dentro del sandbox.

Transmite eventos mediante streaming: Recibes actualizaciones en tiempo real mientras el agente trabaja.

Pasa a estado inactivo: El agente emite un evento session.status_idle cuando no tiene nada más que hacer.

Conceptos fundamentales

Requisitos previos

Instala la CLI

Instala el SDK

Crea tu primera sesión

Qué está sucediendo

Próximos pasos

Conceptos fundamentales

Requisitos previos

Instala la CLI

Instala el SDK

Crea tu primera sesión

Qué está sucediendo

Próximos pasos

Conceptos fundamentales

Requisitos previos

Instala la CLI

Instala el SDK

Crea tu primera sesión

Qué está sucediendo

Próximos pasos

Conceptos fundamentales

Requisitos previos

Instala la CLI

Instala el SDK

Crea tu primera sesión

Qué está sucediendo

Próximos pasos