Migración

Claude Managed Agents reemplaza tu bucle de agente escrito a mano con infraestructura gestionada. Esta página cubre lo que 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 agregando los resultados al historial de la conversación, la mayor parte de ese código desaparece.



Lo que dejas de gestionar



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 sesión.
• Contexto: Todavía 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.



Lo que 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-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 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 entre sesiones. La función de la herramienta todavía se ejecuta 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 se convierten en responsabilidad de tu cliente.



Lista de verificación de migración

1. Crea un entorno con la red y los runtimes que tu agente necesita.
2. Porta 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 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 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" \
  --version "$AGENT_VERSION" \
  --model claude-opus-5

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 la 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 los modelos más nuevos no tiene efecto.
• El escapado 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 en la guía de la Messages API (lo que el modelo hace de manera diferente) siguen siendo aplicables. Los pasos de migración (cómo cambiar tu código de solicitud) no.