Migración

Claude Managed Agents reemplaza tu bucle de agente escrito a mano con infraestructura gestionada. 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 las llamadas a herramientas tú mismo y añadiendo los resultados al historial de conversación, la mayor parte de ese código desaparece.



Lo que dejas de gestionar



Comparación de código

Antes (bucle de Messages API, simplificado):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        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-4-8",
    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: Siguen declarándose 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 sesión.
• 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 está en 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



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

El Agent y el Environment se crean una vez y se reutilizan en todas las sesiones. La función de 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.



Lista de verificación de migración

1. Crea un entorno con la configuración de red y los runtimes que tu agente necesita.
2. Traslada tu indicación del sistema y 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 el agente lea, súbelo a través de la Files API y móntalo como resources.
5. Para cualquier manejador de herramientas personalizadas, mueve la ejecución a tu bucle de eventos como respuestas a 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 modelo

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 surtirá efecto en la siguiente sesión que crees.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

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 acción de tu parte:

• Cambios en 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 están expuestos 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 modelos más recientes no tiene efecto.
• El escapado JSON de argumentos de herramientas es analizado por el runtime antes de que recibas eventos agent.custom_tool_use. Ves datos estructurados, no cadenas sin procesar.

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