Migration

Claude Managed Agents ersetzt deine handgeschriebene Agenten-Schleife durch verwaltete Infrastruktur. Diese Seite behandelt, was sich ändert, wenn du von einer benutzerdefinierten Schleife, die auf der Messages API aufbaut, oder vom Claude Agent SDK migrierst.



Von einer Messages-API-Agenten-Schleife

Wenn du einen Agenten gebaut hast, indem du messages.create in einer while-Schleife aufrufst, Tool-Aufrufe selbst ausführst und die 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-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,
                        }
                    ],
                }
            )

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



Was du weiterhin kontrollierst

• System-Prompt und Modell: Dieselben Felder, jetzt auf der Agentendefinition.
• Benutzerdefinierte Tools: Werden weiterhin mit JSON Schema deklariert. Die Ausführung verlagert sich von der 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-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)

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

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.



Funktionen, die in deinen Client wandern

Der Kompromiss dafür, dass Anthropic die Agenten-Schleife betreibt, ist, 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 Agentendefinition.
3. Ersetze deine Schleife durch sessions.create und sessions.events.stream.
4. Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und mounte sie als resources.
5. Verlagere die Ausführung aller benutzerdefinierten Tool-Handler in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
6. Verifiziere mit einer Test-Session, bevor du den Produktionsverkehr auf den neuen Ablauf umstellst.



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 Agentendefinition, 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-5

Die meisten Verhaltensänderungen auf Modellebene, die im Migrationsleitfaden für die Messages API dokumentiert sind, erfordern auf deiner Seite keine Maßnahmen:

• Änderungen an Request-Parametern (max_tokens-Standardwerte, thinking-Konfiguration) werden von der Claude-Managed-Agents-Runtime gehandhabt. Diese Felder sind in der Agentendefinition nicht verfügbar.
• Assistant-Message-Prefilling existiert im eventbasierten Session-Modell nicht, daher ist seine Entfernung in neueren Modellen ohne Auswirkung.
• JSON-Escaping von Tool-Argumenten wird von der Runtime geparst, bevor du agent.custom_tool_use-Events erhältst. 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.