Managed AgentsErste Schritte

Migration

Verschiebe einen bestehenden Agenten, der auf der Messages API oder dem Claude Agent SDK aufgebaut ist, zu Claude Managed Agents.

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

Von einer Messages-API-Agentenschleife

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

Vorher	Nachher
Du pflegst das Array mit dem Gesprächsverlauf und übergibst es bei jedem Zug erneut.	Die Session speichert den Verlauf serverseitig. Sende Events, empfange Events.
Du iterierst über `tool_use`-Inhaltsblöcke, führst jedes Tool aus und kehrst mit `tool_result`-Nachrichten in die Schleife zurück.	Vorgefertigte Tools laufen automatisch innerhalb der Sandbox. Du behandelst nur benutzerdefinierte Tools über `agent.custom_tool_use`-Events.
Du stellst deine eigene Sandbox zum Ausführen von agentengeneriertem Code bereit.	Die Session-Sandbox übernimmt Codeausfü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 Agentendefinition.
Benutzerdefinierte Tools: Werden weiterhin mit JSON Schema deklariert. Die Ausführung wechselt von der Inline-Behandlung zum Beantworten von 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 auf den Einträgen web_search und web_fetch im configs-Array 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, 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 läuft in einem Prozess, den du betreibst, während Managed Agents in der Infrastruktur von Anthropic läuft. Der Großteil der Migration besteht darin, SDK-Konfigurationsobjekte ihren API-seitigen Entsprechungen zuzuordnen.

Was sich ändert

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` wird pro Lauf konstruiert	`client.beta.agents.create(...)` einmalig; der Agent wird serverseitig persistiert und versioniert. Siehe Agenten-Setup.
`async with ClaudeSDKClient(...)` oder `query(...)`	`client.beta.sessions.create(...)`, dann Events senden und empfangen.
Mit `@tool` dekorierte Funktionen, die vom SDK automatisch aufgerufen werden	Als `{"type": "custom", ...}` auf dem Agenten deklarieren; dein Client behandelt `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 innerhalb der Session-Sandbox gegen `/workspace` aus.
`cwd`, `add_dirs` zeigen auf lokale Pfade	Dateien als Session-Ressourcen hochladen oder einbinden.
`system_prompt` und die `CLAUDE.md`-Hierarchie	Ein einzelner `system`-String auf dem Agenten. Jede Aktualisierung, die den Agenten ändert, erzeugt eine neue serverseitige Version; pinne Sessions an eine bestimmte Version, um ohne Deployment hochzustufen oder zurückzurollen. Siehe Agenten-Setup.
`mcp_servers` an einer Stelle konfiguriert und authentifiziert	Server auf dem Agenten deklarieren; Zugangsdaten über einen Vault auf der Session bereitstellen.
`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, anstatt dass das SDK es für dich aufruft.

Funktionen, die in deinen Client wandern

Der Kompromiss dafür, dass Anthropic die Agentenschleife ausführt, ist, dass einige Dinge, die das SDK automatisch erledigt hat, in die Verantwortung deines Clients übergehen.

SDK-Funktion	Ansatz bei Managed Agents
Plan-Modus	Führe zuerst eine reine Planungs-Session aus, dann eine zweite Session, um den Plan auszuführen.
Ausgabestile, 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 bereits 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 Züge clientseitig.

Migrations-Checkliste

Erstelle ein Environment mit dem Netzwerk und den Laufzeitumgebungen, die dein Agent benötigt.
Portiere deinen System-Prompt und deine Tool-Auswahl in eine Agentendefinition.
Ersetze deine Schleife durch sessions.create und sessions.events.stream.
Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und binde sie als resources ein.
Verschiebe bei allen benutzerdefinierten Tool-Handlern die Ausführung in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
Überprüfe mit einer Test-Session, bevor du Produktionsverkehr auf den neuen Ablauf 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 Agentendefinition, 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 Messages-API-Migrationsleitfaden dokumentiert sind, erfordern keine Maßnahmen deinerseits:

Änderungen an Anfrageparametern (max_tokens-Standardwerte, thinking-Konfiguration) werden von der Claude-Managed-Agents-Laufzeit übernommen. Diese Felder sind in der Agentendefinition nicht verfügbar.
Prefilling von Assistant-Nachrichten existiert im eventbasierten Session-Modell nicht, daher ist dessen Entfernung bei neueren Modellen ohne Auswirkung.
JSON-Escaping von Tool-Argumenten wird von der Laufzeit 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 Anfragecode änderst) gelten nicht.

Was this page helpful?

Managed AgentsErste Schritte

Migration

Verschiebe einen bestehenden Agenten, der auf der Messages API oder dem Claude Agent SDK aufgebaut ist, zu Claude Managed Agents.

Von einer Messages-API-Agentenschleife

Was du nicht mehr verwalten musst

Vorher	Nachher
Du pflegst das Array mit dem Gesprächsverlauf und übergibst es bei jedem Zug erneut.	Die Session speichert den Verlauf serverseitig. Sende Events, empfange Events.
Du iterierst über `tool_use`-Inhaltsblöcke, führst jedes Tool aus und kehrst mit `tool_result`-Nachrichten in die Schleife zurück.	Vorgefertigte Tools laufen automatisch innerhalb der Sandbox. Du behandelst nur benutzerdefinierte Tools über `agent.custom_tool_use`-Events.
Du stellst deine eigene Sandbox zum Ausführen von agentengeneriertem Code bereit.	Die Session-Sandbox übernimmt Codeausfü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 Agentendefinition.
Benutzerdefinierte Tools: Werden weiterhin mit JSON Schema deklariert. Die Ausführung wechselt von der Inline-Behandlung zum Beantworten von 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 auf den Einträgen web_search und web_fetch im configs-Array 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, Dateiressourcen oder Skills einbringen.

Vom Claude Agent SDK

Was sich ändert

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)` wird pro Lauf konstruiert	`client.beta.agents.create(...)` einmalig; der Agent wird serverseitig persistiert und versioniert. Siehe Agenten-Setup.
`async with ClaudeSDKClient(...)` oder `query(...)`	`client.beta.sessions.create(...)`, dann Events senden und empfangen.
Mit `@tool` dekorierte Funktionen, die vom SDK automatisch aufgerufen werden	Als `{"type": "custom", ...}` auf dem Agenten deklarieren; dein Client behandelt `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 innerhalb der Session-Sandbox gegen `/workspace` aus.
`cwd`, `add_dirs` zeigen auf lokale Pfade	Dateien als Session-Ressourcen hochladen oder einbinden.
`system_prompt` und die `CLAUDE.md`-Hierarchie	Ein einzelner `system`-String auf dem Agenten. Jede Aktualisierung, die den Agenten ändert, erzeugt eine neue serverseitige Version; pinne Sessions an eine bestimmte Version, um ohne Deployment hochzustufen oder zurückzurollen. Siehe Agenten-Setup.
`mcp_servers` an einer Stelle konfiguriert und authentifiziert	Server auf dem Agenten deklarieren; Zugangsdaten über einen Vault auf der Session bereitstellen.
`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

Funktionen, die in deinen Client wandern

Der Kompromiss dafür, dass Anthropic die Agentenschleife ausführt, ist, dass einige Dinge, die das SDK automatisch erledigt hat, in die Verantwortung deines Clients übergehen.

SDK-Funktion	Ansatz bei Managed Agents
Plan-Modus	Führe zuerst eine reine Planungs-Session aus, dann eine zweite Session, um den Plan auszuführen.
Ausgabestile, 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 bereits 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 Züge clientseitig.

Migrations-Checkliste

Erstelle ein Environment mit dem Netzwerk und den Laufzeitumgebungen, die dein Agent benötigt.
Portiere deinen System-Prompt und deine Tool-Auswahl in eine Agentendefinition.
Ersetze deine Schleife durch sessions.create und sessions.events.stream.
Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und binde sie als resources ein.
Verschiebe bei allen benutzerdefinierten Tool-Handlern die Ausführung in deine Event-Schleife als Antworten auf agent.custom_tool_use-Events.
Überprüfe mit einer Test-Session, bevor du Produktionsverkehr auf den neuen Ablauf leitest.

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 Messages-API-Migrationsleitfaden dokumentiert sind, erfordern keine Maßnahmen deinerseits:

Änderungen an Anfrageparametern (max_tokens-Standardwerte, thinking-Konfiguration) werden von der Claude-Managed-Agents-Laufzeit übernommen. Diese Felder sind in der Agentendefinition nicht verfügbar.
Prefilling von Assistant-Nachrichten existiert im eventbasierten Session-Modell nicht, daher ist dessen Entfernung bei neueren Modellen ohne Auswirkung.
JSON-Escaping von Tool-Argumenten wird von der Laufzeit 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 Anfragecode änderst) gelten nicht.

Was this page helpful?

Von einer Messages-API-Agentenschleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Funktionen, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agentenschleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Funktionen, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agentenschleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Funktionen, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen

Von einer Messages-API-Agentenschleife

Was du nicht mehr verwalten musst

Code-Vergleich

Was du weiterhin kontrollierst

Vom Claude Agent SDK

Was sich ändert

Code-Vergleich

Funktionen, die in deinen Client wandern

Migrations-Checkliste

Migration zwischen Modellversionen