Migración

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 en la API de Mensajes o desde el SDK del Agente Claude.

Desde un bucle de agente de la API de Mensajes

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

Lo que dejas de administrar

Comparación de código

Antes (bucle de API de Mensajes, simplificado):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-7",
        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-7",
    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 todavía controlas

• Indicación del sistema y modelo: Los mismos campos, ahora en la definición del agente.
• Herramientas personalizadas: Todavía se declaran con JSON Schema. La ejecución se mueve 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 archivo, o habilidades.

Desde el SDK del Agente Claude

Si construiste con el SDK del Agente Claude, 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 operas, mientras que Managed Agents se ejecuta en la infraestructura de Anthropic. La mayoría de la migración es mapear objetos de configuración del SDK a sus equivalentes del lado de la API.

Qué cambia

Comparación de código

Antes (SDK del Agente):

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-7",
    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-7",
    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(b.text for b in ev.content))
        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.type == "end_turn":
            break

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

Características que se trasladan a tu cliente

El tradeoff para 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 tiempos de ejecución que tu agente necesita.
2. Porta 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.stream.
4. Para cualquier archivo local que el agente lea, cárgalo a través de la API de Archivos y móntalo como resources.
5. Para cualquier manejador de herramienta personalizada, 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 Claude, migrar una integración de Claude Managed Agents es típicamente un cambio de un campo: actualiza model en tu definición de agente y el cambio entra en vigor en la próxima sesión que crees.

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

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

• Cambios de parámetros de solicitud (valores predeterminados de max_tokens, configuración de thinking) son manejados por el tiempo de ejecución de Claude Managed Agents. Estos campos no se exponen en la definición del agente.
• Rellenado 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 nuevos es una no-operación.
• Escape JSON de argumentos de herramienta es analizado por el tiempo de ejecución 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 API de Mensajes (qué hace el modelo diferente) todavía se aplican. Los pasos de migración (cómo cambiar tu código de solicitud) no.