Migration

Claude Managed Agents ersetzt Ihre handgeschriebene Agent-Schleife durch verwaltete Infrastruktur. Diese Seite behandelt die Änderungen bei der Migration von einer benutzerdefinierten Schleife, die auf der Messages API basiert, oder vom Claude Agent SDK.

Von einer Messages API Agent-Schleife

Wenn Sie einen Agent erstellt haben, indem Sie messages.create in einer while-Schleife aufgerufen, Tool-Aufrufe selbst ausgeführt und Ergebnisse zum Gesprächsverlauf hinzugefügt haben, verschwindet der größte Teil dieses Codes.

Was Sie nicht mehr verwalten

Code-Vergleich

Vorher (Messages API-Schleife, vereinfacht):

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,
                        }
                    ],
                }
            )

Nachher (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

Was Sie noch kontrollieren

• System-Prompt und Modell: Gleiche Felder, jetzt in der Agent-Definition.
• Benutzerdefinierte Tools: Werden weiterhin mit JSON Schema deklariert. Die Ausführung wechselt von der Inline-Verarbeitung zur Reaktion auf agent.custom_tool_use-Ereignisse. Siehe Session-Ereignisstrom.
• Kontext: Sie können weiterhin Kontext über den System-Prompt, Datei-Ressourcen oder Skills injizieren.

Vom Claude Agent SDK

Wenn Sie mit dem Claude Agent SDK gebaut haben, arbeiten Sie bereits mit Agents, Tools und Sessions als Konzepte. Der Unterschied liegt darin, wo sie ausgeführt werden: Das SDK wird in einem Prozess ausgeführt, den Sie betreiben, während Managed Agents in Anthropics Infrastruktur ausgeführt wird. Der Großteil der Migration besteht darin, SDK-Konfigurationsobjekte ihren API-seitigen Entsprechungen zuzuordnen.

Was sich ändert

Code-Vergleich

Vorher (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-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)

Nachher (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

Der Agent und die Umgebung werden einmal erstellt und über Sitzungen hinweg wiederverwendet. Die Tool-Funktion wird weiterhin in Ihrem Prozess ausgeführt; der Unterschied besteht darin, dass Sie das agent.custom_tool_use-Ereignis lesen und das Ergebnis explizit senden, anstatt dass das SDK es für Sie verteilt.

Funktionen, die zu Ihrem Client wechseln

Der Kompromiss dafür, dass Anthropic die Agent-Schleife ausführt, besteht darin, dass einige Dinge, die das SDK automatisch verarbeitet hat, zur Verantwortung Ihres Clients werden.

Migrations-Checkliste

1. Erstellen Sie eine Umgebung mit den Netzwerk- und Laufzeit-Anforderungen, die Ihr Agent benötigt.
2. Portieren Sie Ihren System-Prompt und die Tool-Auswahl zu einer Agent-Definition.
3. Ersetzen Sie Ihre Schleife durch sessions.create und sessions.stream.
4. Für alle lokalen Dateien, die der Agent liest, laden Sie sie über die Files API hoch und mounten Sie sie als resources.
5. Für alle benutzerdefinierten Tool-Handler verschieben Sie die Ausführung in Ihre Ereignisschleife als Antworten auf agent.custom_tool_use-Ereignisse.
6. Überprüfen Sie mit einer Test-Sitzung, bevor Sie Produktionsverkehr auf den neuen Flow leiten.

Migration zwischen Modellversionen

Wenn ein neues Claude-Modell veröffentlicht wird, ist die Migration einer Claude Managed Agents-Integration typischerweise eine Änderung in einem Feld: Aktualisieren Sie model in Ihrer Agent-Definition und die Änderung wird bei der nächsten Sitzung, die Sie erstellen, wirksam.

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

Die meisten Verhaltensänderungen auf Modellebene, die im Messages API-Migrationsleitfaden dokumentiert sind, erfordern keine Maßnahmen Ihrerseits:

• Anfrageparameter-Änderungen (max_tokens-Standards, thinking-Konfiguration) werden von der Claude Managed Agents-Laufzeit verarbeitet. Diese Felder werden nicht in der Agent-Definition verfügbar gemacht.
• Assistent-Nachricht-Vorausfüllung existiert nicht im ereignisgesteuerten Sitzungsmodell, daher ist ihre Entfernung bei neueren Modellen ein No-Op.
• Tool-Argument JSON-Escaping wird von der Laufzeit analysiert, bevor Sie agent.custom_tool_use-Ereignisse empfangen. Sie sehen strukturierte Daten, keine rohen Strings.

Die Verhaltensbeschreibungen im Messages API-Leitfaden (was das Modell anders macht) gelten weiterhin. Die Migrationsschritte (wie Sie Ihren Anfragecode ändern) nicht.