Migration

Claude Managed Agents ersetzt deine selbst geschriebene Agent-Schleife durch verwaltete Infrastruktur. Diese Seite beschreibt, was sich ändert, wenn du von einer benutzerdefinierten Schleife auf Basis der Messages API oder vom Claude Agent SDK migrierst.



Von einer Messages-API-Agent-Schleife

Wenn du einen Agenten gebaut hast, indem du messages.create in einer while-Schleife aufrufst, Tool-Aufrufe selbst ausführst und Ergebnisse an den Gesprächsverlauf anhängst, fällt der Großteil dieses Codes weg.



Was du nicht mehr verwalten musst



Code-Vergleich

Vorher (Messages-API-Schleife, vereinfacht):

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

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



Was du weiterhin kontrollierst

• System-Prompt und Modell: Dieselben Felder, jetzt in der Agent-Definition.
• Benutzerdefinierte Tools: Weiterhin mit JSON Schema deklariert. Die Ausführung wechselt von Inline-Behandlung zum Reagieren auf agent.custom_tool_use-Events. Siehe Session-Event-Stream.
• Kontext: Du kannst weiterhin Kontext über den System-Prompt, Dateiressourcen oder Skills einbringen.



Vom Claude Agent SDK

Wenn du mit dem Claude Agent SDK gebaut hast, arbeitest du bereits mit Agenten, Tools und Sessions als Konzepten. Der Unterschied liegt darin, wo sie laufen: Das SDK wird in einem Prozess ausgeführt, den du betreibst, während Managed Agents in der Infrastruktur von Anthropic läuft. Der Großteil der Migration besteht darin, SDK-Konfigurationsobjekte auf ihre API-seitigen Entsprechungen abzubilden.



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

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

Der Agent und das Environment werden einmal erstellt und über Sessions hinweg wiederverwendet. Die Tool-Funktion läuft weiterhin in deinem Prozess; der Unterschied ist, dass du das agent.custom_tool_use-Event liest und das Ergebnis explizit sendest, anstatt dass das SDK es für dich dispatcht.



Features, die in deinen Client wandern

Der Kompromiss dafür, dass Anthropic die Agent-Schleife ausführt, besteht darin, dass einige Dinge, die das SDK automatisch erledigt hat, in die Verantwortung deines Clients übergehen.



Migrations-Checkliste

1. Erstelle ein Environment mit dem Networking und den Runtimes, die dein Agent benötigt.
2. Portiere deinen System-Prompt und deine Tool-Auswahl in eine Agent-Definition.
3. Ersetze deine Schleife durch sessions.create und sessions.events.stream.
4. Für alle lokalen Dateien, die der Agent liest, lade sie über die Files API hoch und mounte sie als resources.
5. Für alle benutzerdefinierten Tool-Handler verschiebe die Ausführung in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
6. Verifiziere mit einer Test-Session, bevor du Produktions-Traffic auf den neuen Flow leitest.



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: Aktualisiere model in deiner Agent-Definition, und die Änderung wird bei der nächsten Session wirksam, die du erstellst.

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

Die meisten Verhaltensänderungen auf Modellebene, die im Messages-API-Migrationsleitfaden dokumentiert sind, erfordern keine Aktion deinerseits:

• Änderungen an Request-Parametern (max_tokens-Defaults, thinking-Konfiguration) werden von der Claude-Managed-Agents-Runtime behandelt. Diese Felder sind in der Agent-Definition nicht verfügbar.
• Assistant-Message-Prefilling existiert im eventbasierten Session-Modell nicht, daher ist dessen Entfernung bei neueren Modellen ohne Auswirkung.
• JSON-Escaping von Tool-Argumenten wird von der Runtime geparst, bevor du agent.custom_tool_use-Events empfängst. Du siehst strukturierte Daten, keine rohen Strings.

Die Verhaltensbeschreibungen im Messages-API-Leitfaden (was das Modell anders macht) gelten weiterhin. Die Migrationsschritte (wie du deinen Request-Code änderst) nicht.