Migration

Claude Managed Agents ersetzt Ihre handgeschriebene Agentenschleife durch verwaltete Infrastruktur. Diese Seite beschreibt, was sich ändert, wenn Sie von einer benutzerdefinierten Schleife migrieren, die auf der Messages API oder dem Claude Agent SDK aufgebaut ist.

Von einer Messages API-Agentenschleife

Wenn Sie einen Agenten erstellt haben, indem Sie messages.create in einer while-Schleife aufgerufen, Tool-Aufrufe selbst ausgeführt und Ergebnisse an den Gesprächsverlauf angehängt haben, entfällt der größte Teil dieses Codes.

Was Sie nicht mehr verwalten müssen

Code-Vergleich

Vorher (Messages API-Schleife, vereinfacht):

Nachher (Claude Managed Agents):

Was Sie weiterhin kontrollieren

• System-Prompt und Modell: Gleiche Felder, jetzt in der Agentendefinition.
• Benutzerdefinierte Tools: Werden weiterhin mit JSON Schema deklariert. Die Ausführung wechselt von der direkten Behandlung zur Reaktion auf agent.custom_tool_use-Events. Siehe Session-Event-Stream.
• Kontext: Sie können weiterhin Kontext über den System-Prompt, Dateiressourcen oder Skills einfügen.

Vom Claude Agent SDK

Wenn Sie mit dem Claude Agent SDK entwickelt haben, arbeiten Sie bereits mit Agenten, Tools und Sessions als Konzepten. 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 der Infrastruktur von Anthropic läuft. Der größte 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-sonnet-4-6",
    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-sonnet-4-6",
    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 einmalig erstellt und über Sessions hinweg wiederverwendet. Die Tool-Funktion läuft weiterhin in Ihrem Prozess; der Unterschied besteht darin, dass Sie das agent.custom_tool_use-Event lesen und das Ergebnis explizit senden, anstatt dass das SDK es für Sie ausführt.

Funktionen, die zu Ihrem Client wechseln

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

Migrations-Checkliste

1. Erstellen Sie eine Umgebung mit dem Netzwerk und den Laufzeiten, die Ihr Agent benötigt.
2. Portieren Sie Ihren System-Prompt und Ihre Tool-Auswahl in eine Agentendefinition.
3. Ersetzen Sie Ihre Schleife durch sessions.create und sessions.stream.
4. Laden Sie für alle lokalen Dateien, die der Agent liest, diese über die Files API hoch und mounten Sie sie als resources.
5. Verschieben Sie für alle benutzerdefinierten Tool-Handler die Ausführung in Ihre Event-Schleife als Antworten auf agent.custom_tool_use-Events.
6. Überprüfen Sie mit einer Test-Session, bevor Sie den Produktionsverkehr auf den neuen Ablauf umleiten.

Migration zwischen Modellversionen

Wenn ein neues Claude-Modell veröffentlicht wird, ist die Migration einer Claude Managed Agents-Integration typischerweise eine Änderung an einem einzigen Feld: Aktualisieren Sie model in Ihrer Agentendefinition, und die Änderung tritt bei der nächsten Session, die Sie erstellen, in Kraft.

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

• Änderungen an Request-Parametern (max_tokens-Standardwerte, thinking-Konfiguration) werden von der Claude Managed Agents-Laufzeit behandelt. Diese Felder sind in der Agentendefinition nicht verfügbar.
• Prefilling von Assistentennachrichten existiert im event-basierten Session-Modell nicht, daher ist seine Entfernung bei neueren Modellen ein No-Op.
• JSON-Escaping von Tool-Argumenten wird von der Laufzeit geparst, bevor Sie agent.custom_tool_use-Events 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 Request-Code ändern) gelten nicht.