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 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 client.messages.create() in einer 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 gibt session.status_idle aus, wenn der Agent nichts mehr zu tun hat. |
Codevergleich
Vorher (Messages-API-Schleife, vereinfacht):
messages = [{"role": "user", "content": task}]
while True:
response = client.messages.create(
model="claude-opus-5-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-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":
breakWas 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_tokensunduser_location, die jetzt einmalig in den Einträgenweb_searchundweb_fetchdesconfigs-Arrays des Agenten-Toolsets gesetzt werden statt bei jeder Anfrage. Die Feldermax_uses,citationsundcache_controlsind nicht verfügbar. Siehe Unterschiede zu den Tools der Messages API. - 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 Ausführung erstellt | client.beta.agents.create(...) einmalig; der Agent wird serverseitig gespeichert und versioniert. Siehe Agenten-Einrichtung. |
async with ClaudeSDKClient(...) oder query(...) | client.beta.sessions.create(...), dann Events senden und empfangen. |
Mit @tool definierte Funktionen, die vom SDK automatisch aufgerufen werden | Als {"type": "custom", ...} am Agenten deklarieren; dein Client behandelt agent.custom_tool_use-Events und antwortet mit user.custom_tool_result. Siehe Tools. |
| Integrierte Tools laufen in deinem Prozess auf deinem Dateisystem | {"type": "agent_toolset_20260401"} führt dieselben Tools in der Session-Sandbox auf /workspace aus. |
cwd, add_dirs verweisen auf lokale Pfade | Lade Dateien als Session-Ressourcen hoch oder binde sie ein. |
system_prompt und die CLAUDE.md-Hierarchie | Ein einzelner system-String am Agenten. Jede Aktualisierung, die den Agenten ändert, erzeugt eine neue serverseitige Version; pinne Sessions auf eine bestimmte Version, um ohne Deployment hochzustufen oder zurückzurollen. Siehe Agenten-Einrichtung. |
mcp_servers an einer Stelle konfiguriert und authentifiziert | Deklariere Server am Agenten; stelle Anmeldedaten über einen Vault in der Session bereit. |
permission_mode, can_use_tool | permission_policy pro Tool (always_allow, always_ask oder auto); sende user.tool_confirmation-Events für Aufrufe, die auf deine Freigabe warten. |
Codevergleich
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-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-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": "limited", "allow_package_managers": True},
},
)
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:
match event.type:
case "agent.message":
print(
"".join(
block.text for block in event.content if block.type == "text"
)
)
case "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}],
}
],
)
case "session.status_idle":
if event.stop_reason and event.stop_reason.type == "end_turn":
breakDer Agent und das Environment werden einmalig 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 und dann eine zweite Session, um den Plan umzusetzen. |
| 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 integrierte Tools verwende permission_policy: always_ask, um jeden Aufruf zu prüfen. Mit auto bewertet stattdessen der Server jeden Aufruf, aber wenn der Server einen Aufruf als sicher einstuft, wird er ausgeführt, ohne deinen Client zu erreichen. |
max_turns | Zähle Turns 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: Erstelle eine Session mit
client.beta.sessions.create()und streame ihre Events mitclient.beta.sessions.events.stream(). - Lade alle lokalen Dateien, die der Agent liest, über die Files API hoch und binde sie als
resourcesein. - Verschiebe für alle benutzerdefinierten Tool-Handler die Ausführung in deine Event-Schleife als Antworten auf
agent.custom_tool_use-Events. - Verifiziere 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 apply agent.md---
name: Task Runner
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a task automation agent. Complete the task you are given end to end.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?