Claude Platform Docs
Managed AgentsPrimeros pasos

Migración

Traslada un agente existente construido sobre la Messages API o el Claude Agent SDK a Claude Managed Agents.

Claude Managed Agents reemplaza tu bucle de agente escrito a mano con infraestructura administrada. Esta página cubre qué cambia cuando migras desde un bucle personalizado construido sobre la Messages API o desde el Claude Agent SDK.

Desde un bucle de agente con la Messages API

Si construiste un agente llamando a messages.create en un bucle while, ejecutando tú mismo las llamadas a herramientas y agregando los resultados al historial de la conversación, la mayor parte de ese código desaparece.

Lo que dejas de administrar

AntesDespués
Mantienes el arreglo del historial de la conversación y lo vuelves a pasar en cada turno.La sesión almacena el historial del lado del servidor. Envía eventos, recibe eventos.
Iteras sobre los bloques de contenido tool_use, ejecutas cada herramienta y vuelves al bucle con mensajes tool_result.Las herramientas predefinidas se ejecutan automáticamente dentro del sandbox. Solo manejas las herramientas personalizadas a través de eventos agent.custom_tool_use.
Aprovisionas tu propio sandbox para ejecutar el código generado por el agente.El sandbox de la sesión maneja la ejecución de código, las operaciones de archivos y bash.
Tú decides cuándo termina el bucle.La sesión emite session.status_idle cuando el agente no tiene nada más que hacer.

Comparación de código

Antes (bucle con la Messages API, simplificado):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason == "end_turn":
        break
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            messages.append(
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": result,
                        }
                    ],
                }
            )

Después (Claude Managed Agents):

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-5",
    tools=[{"type": "agent_toolset_20260401"}],
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)

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": task}]}],
    )
    for event in stream:
        if event.type == "session.status_idle":
            break

Lo que sigues controlando

  • Indicación del sistema y modelo: Los mismos campos, ahora en la definición del agente.
  • Herramientas personalizadas: Se siguen declarando con JSON Schema. La ejecución pasa del manejo en línea a responder a eventos agent.custom_tool_use. Consulta Flujo de eventos de la sesión.
  • Configuración de búsqueda web y obtención web: Los mismos campos allowed_domains, blocked_domains, max_content_tokens y user_location, ahora establecidos una sola vez en las entradas web_search y web_fetch del arreglo configs del conjunto de herramientas del agente, en lugar de en cada solicitud. Los campos max_uses, citations y cache_control no están disponibles. Consulta Restringir los dominios de búsqueda web y obtención web.
  • Contexto: Aún puedes inyectar contexto a través de la indicación del sistema, recursos de archivos o skills.

Desde el Claude Agent SDK

Si construiste con el Claude Agent SDK, ya estás trabajando con agentes, herramientas y sesiones como conceptos. La diferencia es dónde se ejecutan: el SDK se ejecuta en un proceso que tú operas, mientras que Managed Agents se ejecuta en la infraestructura de Anthropic. La mayor parte de la migración consiste en mapear los objetos de configuración del SDK a sus equivalentes del lado de la API.

Qué cambia

Agent SDKManaged Agents
ClaudeAgentOptions(...) construido en cada ejecuciónclient.beta.agents.create(...) una sola vez; el Agent se persiste y se versiona del lado del servidor. Consulta Configuración del agente.
async with ClaudeSDKClient(...) o query(...)client.beta.sessions.create(...) y luego envía y recibe eventos.
Funciones decoradas con @tool despachadas automáticamente por el SDKDecláralas como {"type": "custom", ...} en el Agent; tu cliente maneja los eventos agent.custom_tool_use y responde con user.custom_tool_result. Consulta Herramientas.
Las herramientas integradas se ejecutan en tu proceso contra tu sistema de archivos{"type": "agent_toolset_20260401"} ejecuta las mismas herramientas dentro del sandbox de la sesión contra /workspace.
cwd, add_dirs apuntan a rutas localesSube o monta archivos como recursos de la sesión.
system_prompt y la jerarquía de CLAUDE.mdUna única cadena system en el Agent. Cada actualización que cambia el agente produce una nueva versión del lado del servidor; fija las sesiones a una versión específica para promover o revertir sin un despliegue. Consulta Configuración del agente.
mcp_servers configurados y autenticados en un solo lugarDeclara los servidores en el Agent; proporciona las credenciales a través de un Vault en la Session.
permission_mode, can_use_toolpermission_policy por herramienta; envía eventos user.tool_confirmation para las herramientas always_ask.

Comparación de código

Antes (Agent SDK):

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ClaudeSDKClient,
    create_sdk_mcp_server,
    tool,
)


@tool("get_weather", "Get the current weather for a city.", {"city": str})
async def get_weather(args: dict) -> dict:
    return {"content": [{"type": "text", "text": f"{args['city']}: 18°C, clear"}]}


options = ClaudeAgentOptions(
    model="claude-opus-5",
    system_prompt="You are a concise weather assistant.",
    mcp_servers={
        "weather": create_sdk_mcp_server("weather", "1.0", tools=[get_weather])
    },
)

async with ClaudeSDKClient(options=options) as agent:
    await agent.query("What's the weather in Tokyo?")
    async for msg in agent.receive_response():
        print(msg)

Después (Managed Agents):

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-opus-5",
    system="You are a concise weather assistant.",
    tools=[
        {
            "type": "custom",
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
)
environment = client.beta.environments.create(
    name="weather-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)


def get_weather(city: str) -> str:
    return f"{city}: 18°C, clear"


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": "What's the weather in Tokyo?"}],
            }
        ],
    )
    for event in stream:
        if event.type == "agent.message":
            print(
                "".join(block.text for block in event.content if block.type == "text")
            )
        elif event.type == "agent.custom_tool_use":
            result = get_weather(**event.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": event.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif (
            event.type == "session.status_idle"
            and event.stop_reason
            and event.stop_reason.type == "end_turn"
        ):
            break

El Agent y el Environment se crean una sola vez y se reutilizan entre sesiones. La función de la herramienta sigue ejecutándose en tu proceso; la diferencia es que lees el evento agent.custom_tool_use y envías el resultado explícitamente en lugar de que el SDK lo despache por ti.

Funcionalidades que pasan a tu cliente

La contrapartida de que Anthropic ejecute el bucle del agente es que algunas cosas que el SDK manejaba automáticamente pasan a ser responsabilidad de tu cliente.

Funcionalidad del SDKEnfoque en Managed Agents
Modo de planificaciónEjecuta primero una sesión solo de planificación y luego una segunda sesión para ejecutar el plan.
Estilos de salida, comandos slashAplícalos en tu cliente antes de enviar user.message o después de recibir agent.message.
Hooks PreToolUse / PostToolUseTu cliente ya ve cada evento agent.custom_tool_use antes de responder; coloca la lógica ahí. Para las herramientas integradas, usa permission_policy: always_ask.
max_turnsCuenta los turnos del lado del cliente.

Lista de verificación de la migración

  1. Crea un entorno con la red y los runtimes que tu agente necesita.
  2. Traslada tu indicación del sistema y tu selección de herramientas a una definición de agente.
  3. Reemplaza tu bucle con sessions.create y sessions.events.stream.
  4. Para cualquier archivo local que lea el agente, súbelo a través de la Files API y móntalo como resources.
  5. Para cualquier manejador de herramientas personalizadas, traslada la ejecución a tu bucle de eventos como respuestas a los eventos agent.custom_tool_use.
  6. Verifica con una sesión de prueba antes de dirigir el tráfico de producción al nuevo flujo.

Migración entre versiones de modelos

Cuando se lanza un nuevo modelo de Claude, migrar una integración de Claude Managed Agents suele ser un cambio de un solo campo: actualiza model en tu definición de agente y el cambio surte efecto en la siguiente sesión que crees.

ant beta:agents update --agent-id "$AGENT_ID" < agent.yaml
agent.yaml
name: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
  - type: agent_toolset_20260401

La mayoría de los cambios de comportamiento a nivel de modelo documentados en la guía de migración de la Messages API no requieren ninguna acción de tu parte:

  • Los cambios en los parámetros de solicitud (valores predeterminados de max_tokens, configuración de thinking) son manejados por el runtime de Claude Managed Agents. Estos campos no se exponen en la definición del agente.
  • El prellenado de mensajes del asistente no existe en el modelo de sesión basado en eventos, por lo que su eliminación en los modelos más nuevos no tiene ningún efecto.
  • El escape de JSON en los argumentos de herramientas es analizado por el runtime antes de que recibas los eventos agent.custom_tool_use. Ves datos estructurados, no cadenas sin procesar.

Las descripciones de comportamiento de la guía de la Messages API (lo que el modelo hace de forma diferente) siguen aplicando. Los pasos de migración (cómo cambiar tu código de solicitud) no.

Was this page helpful?