Managed AgentsErste Schritte

Migration

Migriere einen bestehenden Agenten, der auf der Messages API oder dem Claude Agent SDK basiert, zu Claude Managed Agents.

Claude Managed Agents ersetzt deine selbst geschriebene Agenten-Schleife durch verwaltete Infrastruktur. Diese Seite beschreibt, was sich ändert, wenn du von einer eigenen Schleife auf Basis der Messages API 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 Ergebnisse an den Gesprächsverlauf anhängst, fällt der größte Teil dieses Codes weg.

Was du nicht mehr verwalten musst

Vorher	Nachher
Du pflegst das Array mit dem Gesprächsverlauf und übergibst es bei jedem Turn erneut.	Die Session speichert den Verlauf serverseitig. Sende Events, empfange Events.
Du iterierst über `tool_use`-Content-Blöcke, führst jedes Tool aus und springst mit `tool_result`-Nachrichten zurück in die Schleife.	Vorgefertigte Tools laufen automatisch in der Sandbox. Du kümmerst dich nur über `agent.custom_tool_use`-Events um eigene Tools.
Du stellst deine eigene Sandbox bereit, um vom Agenten generierten Code auszuführen.	Die Session-Sandbox übernimmt Code-Ausführung, Dateioperationen und Bash.
Du entscheidest, wann die Schleife fertig ist.	Die Session sendet `session.status_idle`, wenn der Agent nichts mehr zu tun hat.

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 in der Agenten-Definition.
Eigene 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.
Einstellungen für Websuche und Web-Fetch: Dieselben Felder allowed_domains, blocked_domains, max_content_tokens und user_location, jetzt einmalig in den Einträgen web_search und web_fetch des configs-Arrays des Agenten-Toolsets gesetzt statt bei jeder Anfrage. Die Felder max_uses, citations und cache_control sind nicht verfügbar. Siehe Domains für Websuche und Web-Fetch einschränken.
Kontext: Du kannst weiterhin Kontext über den System-Prompt, Datei-Ressourcen 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 läuft in einem Prozess, den du betreibst, während Managed Agents in der Infrastruktur von Anthropic läuft. Der größte Teil der Migration besteht darin, SDK-Konfigurationsobjekte auf ihre API-seitigen Entsprechungen abzubilden.

Was sich ändert

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` pro Durchlauf erstellt	`client.beta.agents.create(...)` einmalig; der Agent wird serverseitig persistiert und versioniert. Siehe Agenten-Einrichtung.
`async with ClaudeSDKClient(...)` oder `query(...)`	`client.beta.sessions.create(...)`, dann Events senden und empfangen.
Mit `@tool` dekorierte Funktionen, die automatisch vom SDK dispatcht werden	Als `{"type": "custom", ...}` am Agenten deklarieren; dein Client verarbeitet `agent.custom_tool_use`-Events und antwortet mit `user.custom_tool_result`. Siehe Tools.
Eingebaute Tools laufen in deinem Prozess gegen dein Dateisystem	`{"type": "agent_toolset_20260401"}` führt dieselben Tools in der Session-Sandbox gegen `/workspace` aus.
`cwd`, `add_dirs` zeigen auf lokale Pfade	Lade Dateien hoch oder mounte sie als Session-Ressourcen.
`system_prompt` und die `CLAUDE.md`-Hierarchie	Ein einzelner `system`-String am Agenten. Jedes Update, das den Agenten ändert, erzeugt eine neue serverseitige Version; pinne Sessions an eine bestimmte Version, um ohne Deployment zu promoten oder zurückzurollen. Siehe Agenten-Einrichtung.
`mcp_servers` an einer Stelle konfiguriert und authentifiziert	Deklariere Server am Agenten; stelle Zugangsdaten über einen Vault an der Session bereit.
`permission_mode`, `can_use_tool`	`permission_policy` pro Tool; sende `user.tool_confirmation`-Events für `always_ask`-Tools.

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 event in stream:
        if event.type == "agent.message":
            print(
                "".join(block.text for block in event.content if block.type == "text")
            )
        elif event.type == "agent.custom_tool_use":
            result = get_weather(**event.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": event.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif (
            event.type == "session.status_idle"
            and event.stop_reason
            and event.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, statt dass das SDK es für dich dispatcht.

Features, 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.

SDK-Feature	Ansatz bei Managed Agents
Plan-Modus	Führe zuerst eine reine Planungs-Session aus, dann eine zweite Session, um den Plan auszuführen.
Output-Styles, Slash-Befehle	Wende sie in deinem Client an, bevor du `user.message` sendest oder nachdem du `agent.message` empfangen hast.
`PreToolUse`- / `PostToolUse`-Hooks	Dein Client sieht ohnehin jedes `agent.custom_tool_use`-Event, bevor er antwortet; platziere die Logik dort. Für eingebaute Tools verwende `permission_policy: always_ask`.
`max_turns`	Zähle Turns clientseitig.

Migrations-Checkliste

Erstelle ein Environment mit dem Netzwerkzugriff und den Laufzeitumgebungen, die dein Agent benötigt.
Übertrage deinen System-Prompt und deine Tool-Auswahl in eine Agenten-Definition.
Ersetze deine Schleife durch sessions.create und sessions.events.stream.
Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und mounte sie als resources.
Verlagere für alle eigenen Tool-Handler die Ausführung in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
Verifiziere mit einer Test-Session, bevor du Produktions-Traffic auf den neuen Ablauf lenkst.

Migration zwischen Modellversionen

Wenn ein neues Claude-Modell veröffentlicht wird, ist die Migration einer Claude-Managed-Agents-Integration in der Regel eine Änderung an einem einzigen Feld: Aktualisiere model in deiner Agenten-Definition, und die Änderung wird bei der nächsten Session wirksam, die du erstellst.

ant beta:agents update --agent-id "$AGENT_ID" < agent.yaml

agent.yaml

name: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
  - type: agent_toolset_20260401

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

Änderungen an Request-Parametern (max_tokens-Defaults, thinking-Konfiguration) werden von der Claude-Managed-Agents-Laufzeitumgebung gehandhabt. Diese Felder sind in der Agenten-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 Laufzeitumgebung 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.

Was this page helpful?

Managed AgentsErste Schritte

Migration

Migriere einen bestehenden Agenten, der auf der Messages API oder dem Claude Agent SDK basiert, zu Claude Managed Agents.

Von einer Messages-API-Agenten-Schleife

Was du nicht mehr verwalten musst

Vorher	Nachher
Du pflegst das Array mit dem Gesprächsverlauf und übergibst es bei jedem Turn erneut.	Die Session speichert den Verlauf serverseitig. Sende Events, empfange Events.
Du iterierst über `tool_use`-Content-Blöcke, führst jedes Tool aus und springst mit `tool_result`-Nachrichten zurück in die Schleife.	Vorgefertigte Tools laufen automatisch in der Sandbox. Du kümmerst dich nur über `agent.custom_tool_use`-Events um eigene Tools.
Du stellst deine eigene Sandbox bereit, um vom Agenten generierten Code auszuführen.	Die Session-Sandbox übernimmt Code-Ausführung, Dateioperationen und Bash.
Du entscheidest, wann die Schleife fertig ist.	Die Session sendet `session.status_idle`, wenn der Agent nichts mehr zu tun hat.

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 in der Agenten-Definition.
Eigene 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.
Einstellungen für Websuche und Web-Fetch: Dieselben Felder allowed_domains, blocked_domains, max_content_tokens und user_location, jetzt einmalig in den Einträgen web_search und web_fetch des configs-Arrays des Agenten-Toolsets gesetzt statt bei jeder Anfrage. Die Felder max_uses, citations und cache_control sind nicht verfügbar. Siehe Domains für Websuche und Web-Fetch einschränken.
Kontext: Du kannst weiterhin Kontext über den System-Prompt, Datei-Ressourcen oder Skills einbringen.

Vom Claude Agent SDK

Was sich ändert

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` pro Durchlauf erstellt	`client.beta.agents.create(...)` einmalig; der Agent wird serverseitig persistiert und versioniert. Siehe Agenten-Einrichtung.
`async with ClaudeSDKClient(...)` oder `query(...)`	`client.beta.sessions.create(...)`, dann Events senden und empfangen.
Mit `@tool` dekorierte Funktionen, die automatisch vom SDK dispatcht werden	Als `{"type": "custom", ...}` am Agenten deklarieren; dein Client verarbeitet `agent.custom_tool_use`-Events und antwortet mit `user.custom_tool_result`. Siehe Tools.
Eingebaute Tools laufen in deinem Prozess gegen dein Dateisystem	`{"type": "agent_toolset_20260401"}` führt dieselben Tools in der Session-Sandbox gegen `/workspace` aus.
`cwd`, `add_dirs` zeigen auf lokale Pfade	Lade Dateien hoch oder mounte sie als Session-Ressourcen.
`system_prompt` und die `CLAUDE.md`-Hierarchie	Ein einzelner `system`-String am Agenten. Jedes Update, das den Agenten ändert, erzeugt eine neue serverseitige Version; pinne Sessions an eine bestimmte Version, um ohne Deployment zu promoten oder zurückzurollen. Siehe Agenten-Einrichtung.
`mcp_servers` an einer Stelle konfiguriert und authentifiziert	Deklariere Server am Agenten; stelle Zugangsdaten über einen Vault an der Session bereit.
`permission_mode`, `can_use_tool`	`permission_policy` pro Tool; sende `user.tool_confirmation`-Events für `always_ask`-Tools.

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 event in stream:
        if event.type == "agent.message":
            print(
                "".join(block.text for block in event.content if block.type == "text")
            )
        elif event.type == "agent.custom_tool_use":
            result = get_weather(**event.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": event.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif (
            event.type == "session.status_idle"
            and event.stop_reason
            and event.stop_reason.type == "end_turn"
        ):
            break

Features, 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.

SDK-Feature	Ansatz bei Managed Agents
Plan-Modus	Führe zuerst eine reine Planungs-Session aus, dann eine zweite Session, um den Plan auszuführen.
Output-Styles, Slash-Befehle	Wende sie in deinem Client an, bevor du `user.message` sendest oder nachdem du `agent.message` empfangen hast.
`PreToolUse`- / `PostToolUse`-Hooks	Dein Client sieht ohnehin jedes `agent.custom_tool_use`-Event, bevor er antwortet; platziere die Logik dort. Für eingebaute Tools verwende `permission_policy: always_ask`.
`max_turns`	Zähle Turns clientseitig.

Migrations-Checkliste

Erstelle ein Environment mit dem Netzwerkzugriff und den Laufzeitumgebungen, die dein Agent benötigt.
Übertrage deinen System-Prompt und deine Tool-Auswahl in eine Agenten-Definition.
Ersetze deine Schleife durch sessions.create und sessions.events.stream.
Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und mounte sie als resources.
Verlagere für alle eigenen Tool-Handler die Ausführung in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
Verifiziere mit einer Test-Session, bevor du Produktions-Traffic auf den neuen Ablauf lenkst.

Migration zwischen Modellversionen

ant beta:agents update --agent-id "$AGENT_ID" < agent.yaml

agent.yaml

name: Task Runner
model: claude-opus-5
system: You are a task automation agent. Complete the task you are given end to end.
tools:
  - type: agent_toolset_20260401

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

Änderungen an Request-Parametern (max_tokens-Defaults, thinking-Konfiguration) werden von der Claude-Managed-Agents-Laufzeitumgebung gehandhabt. Diese Felder sind in der Agenten-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 Laufzeitumgebung 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.

Was this page helpful?

Von einer Messages-API-Agenten-Schleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Features, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agenten-Schleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Features, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agenten-Schleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Features, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agenten-Schleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Features, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen