---
title: Migration
url: https://platform.claude.com/docs/de/managed-agents/migration
description: Migriere einen bestehenden Agenten, der auf der Messages API oder dem Claude Agent SDK basiert, zu Claude Managed Agents.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
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](https://platform.claude.com/docs/de/build-with-claude/working-with-messages) aufgebaut ist, oder vom [Claude Agent SDK](https://code.claude.com/docs/de/agent-sdk/overview) migrierst.
## Von einer Messages-API-Agentenschleife
Wenn du einen Agenten gebaut hast, indem du `client.messages.create()` (python, typescript, ruby; csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`; curl: `POST /v1/messages`) 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):
```python Python
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,
}
],
}
)
```
```typescript TypeScript
const messages: Anthropic.MessageParam[] = [{ role: "user", content: task }];
while (true) {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages,
tools
});
messages.push({ role: "assistant", content: response.content });
if (response.stop_reason === "end_turn") {
break;
}
for (const block of response.content) {
if (block.type === "tool_use") {
const result = executeTool(block.name, block.input);
messages.push({
role: "user",
content: [
{
type: "tool_result",
tool_use_id: block.id,
content: result
}
]
});
}
}
}
```
```csharp C#
List messages = [new() { Role = Role.User, Content = task }];
while (true)
{
var response = await client.Messages.Create(new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages,
Tools = tools,
});
messages.Add(new()
{
Role = Role.Assistant,
Content = new([.. response.Content.Select(block => new ContentBlockParam(block.Json))]),
});
if (response.StopReason == StopReason.EndTurn)
{
break;
}
foreach (var block in response.Content)
{
if (block.Value is ToolUseBlock toolUse)
{
var result = ExecuteTool(toolUse.Name, toolUse.Input);
messages.Add(new()
{
Role = Role.User,
Content = new([new ToolResultBlockParam { ToolUseID = toolUse.ID, Content = result }]),
});
}
}
}
```
```go Go
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(task)),
}
for {
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
if response.StopReason == anthropic.StopReasonEndTurn {
break
}
for _, block := range response.Content {
if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
result := executeTool(toolUse.Name, toolUse.Input)
messages = append(messages, anthropic.NewUserMessage(
anthropic.NewToolResultBlock(toolUse.ID, result, false),
))
}
}
}
```
```java Java
var messages = new ArrayList();
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content(task)
.build());
while (true) {
var response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.messages(messages)
.tools(tools)
.build());
messages.add(response.toParam());
if (StopReason.END_TURN.equals(response.stopReason().orElse(null))) {
break;
}
for (var block : response.content()) {
block.toolUse().ifPresent(toolUse -> {
var result = executeTool(toolUse.name(), toolUse._input());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.content(result)
.build())))
.build());
});
}
}
```
```php PHP
$messages = [['role' => 'user', 'content' => $task]];
while (true) {
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
messages: $messages,
tools: $tools,
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
if ($response->stopReason === 'end_turn') {
break;
}
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$result = executeTool($block->name, $block->input);
$messages[] = [
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => $result,
],
],
];
}
}
}
```
```ruby Ruby
messages = [{ role: "user", content: task }]
loop do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages,
tools: tools
)
messages << { role: "assistant", content: response.content }
break if response.stop_reason == :end_turn
response.content.each do |block|
next unless block.type == :tool_use
result = execute_tool(block.name, block.input)
messages << {
role: "user",
content: [
{
type: "tool_result",
tool_use_id: block.id,
content: result
}
]
}
end
end
```
**Nachher** (Claude Managed Agents):
```bash cURL
agent=$(
curl --fail-with-body -sS "https://api.anthropic.com/v1/agents?beta=true" \
-H "x-api-key: ${ANTHROPIC_API_KEY}" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
--json '{
"name": "Task Runner",
"model": "claude-opus-5-5",
"tools": [{"type": "agent_toolset_20260401"}]
}'
)
agent_id=$(jq -r '.id' <<< "${agent}")
session_id=$(
curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions?beta=true" \
-H "x-api-key: ${ANTHROPIC_API_KEY}" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
--json "$(jq -n --argjson a "${agent}" --arg env "${environment_id}" \
'{agent: {type: "agent", id: $a.id, version: $a.version}, environment_id: $env}')" \
| jq -r '.id'
)
# Öffne den SSE-Stream im Hintergrund und sende dann die Nutzernachricht.
stream_log=$(mktemp)
curl --fail-with-body -sS -N \
"https://api.anthropic.com/v1/sessions/${session_id}/events/stream?beta=true" \
-H "x-api-key: ${ANTHROPIC_API_KEY}" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
> "${stream_log}" &
stream_pid=$!
curl --fail-with-body -sS \
"https://api.anthropic.com/v1/sessions/${session_id}/events?beta=true" \
-H "x-api-key: ${ANTHROPIC_API_KEY}" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
--json "$(jq -n --arg text "${task}" \
'{events: [{type: "user.message", content: [{type: "text", text: $text}]}]}')" \
> /dev/null
# Warte, bis die Session inaktiv ist. grep beendet sich beim ersten Treffer, und
# das Lesen per Process Substitution bewirkt, dass die Shell nicht auf
# tail wartet (eine Vordergrund-Pipeline `tail -f | grep -m1` würde hängen: tail
# stirbt erst beim nächsten Schreibvorgang, der bei inaktivem Stream nie kommt).
grep -m1 '"session.status_idle"' <(tail -f -n +1 "${stream_log}") > /dev/null
kill "${stream_pid}" 2>/dev/null || true
```
```bash CLI
ant apply agent.md
session_id=$(ant beta:sessions create \
--agent "{type: agent, id: $agent_id, version: $agent_version}" \
--environment-id "$environment_id" \
--transform id --raw-output)
# Öffne zuerst den Stream und sende dann die Benutzernachricht
exec {stream}< <(ant beta:sessions:events stream \
--session-id "$session_id" \
--transform type --raw-output)
ant beta:sessions:events send \
--session-id "$session_id" \
--event "{type: user.message, content: [{type: text, text: \"$task\"}]}" \
> /dev/null
# Warte, bis die Session inaktiv wird (grep beendet sich beim ersten Treffer)
grep -m1 -x 'session.status_idle' <&"$stream" > /dev/null
exec {stream}<&-
```
```markdown
---
name: Task Runner
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
```
```python Python
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":
break
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Task Runner",
model: "claude-opus-5-5",
tools: [{ type: "agent_toolset_20260401" }]
});
const session = await client.beta.sessions.create({
agent: { type: "agent", id: agent.id, version: agent.version },
environment_id: environment.id
});
const stream = await client.beta.sessions.events.stream(session.id);
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.message",
content: [{ type: "text", text: task }]
}
]
});
for await (const event of stream) {
if (event.type === "session.status_idle") {
break;
}
}
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Task Runner",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = "agent_toolset_20260401",
},
],
});
var session = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentParams
{
Type = "agent",
ID = agent.ID,
Version = agent.Version,
},
EnvironmentID = environment.ID,
});
var stream = client.Beta.Sessions.Events.StreamStreaming(session.ID);
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserMessageEventParams
{
Type = "user.message",
Content = [new BetaManagedAgentsTextBlock { Type = "text", Text = task }],
},
],
});
await foreach (var streamEvent in stream)
{
if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
{
break;
}
}
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Task Runner",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
})
if err != nil {
log.Fatal(err)
}
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: agent.ID,
Version: anthropic.Int(agent.Version),
},
},
EnvironmentID: environment.ID,
})
if err != nil {
log.Fatal(err)
}
stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: task,
},
}},
},
}},
})
if err != nil {
log.Fatal(err)
}
for stream.Next() {
event := stream.Current()
if event.Type == "session.status_idle" {
break
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Task Runner")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.build()
);
var session = client.beta().sessions().create(
SessionCreateParams.builder()
.agent(
BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(agent.id())
.version(agent.version())
.build()
)
.environmentId(environment.id())
.build()
);
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
client.beta().sessions().events().send(
session.id(),
EventSendParams.builder()
.addEvent(
BetaManagedAgentsUserMessageEventParams.builder()
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
.addTextContent(task)
.build()
)
.build()
);
stream.stream()
.takeWhile(event -> !event.isSessionStatusIdle())
.forEach(_ -> {});
}
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Task Runner',
model: 'claude-opus-5-5',
tools: [
BetaManagedAgentsAgentToolset20260401Params::with(
type: 'agent_toolset_20260401',
),
],
);
$session = $client->beta->sessions->create(
agent: BetaManagedAgentsAgentParams::with(
type: 'agent',
id: $agent->id,
version: $agent->version,
),
environmentID: $environment->id,
);
$stream = $client->beta->sessions->events->streamStream($session->id);
$client->beta->sessions->events->send(
$session->id,
events: [
[
'type' => 'user.message',
'content' => [['type' => 'text', 'text' => $task]],
],
],
);
foreach ($stream as $event) {
if ($event->type === 'session.status_idle') {
break;
}
}
```
```ruby Ruby
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
)
stream = client.beta.sessions.events.stream_events(session.id)
client.beta.sessions.events.send_(
session.id,
events: [{type: "user.message", content: [{type: "text", text: task}]}]
)
stream.each do
break if it.type == :"session.status_idle"
end
```
### 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](https://platform.claude.com/docs/de/managed-agents/events-and-streaming).
* **Einstellungen für Websuche und Web-Fetch:** Dieselben Felder `allowed_domains`, `blocked_domains`, `max_content_tokens` und `user_location`, die jetzt einmalig in den Einträgen `web_search` und `web_fetch` des `configs`-Arrays des Agenten-Toolsets gesetzt werden statt bei jeder Anfrage. Die Felder `max_uses`, `citations` und `cache_control` sind nicht verfügbar. Siehe [Unterschiede zu den Tools der Messages API](https://platform.claude.com/docs/de/managed-agents/tools-web-restrictions#differences-from-the-messages-api-tools).
* **Kontext:** Du kannst weiterhin Kontext über den System-Prompt, [Dateiressourcen](https://platform.claude.com/docs/de/managed-agents/files) oder [Skills](https://platform.claude.com/docs/de/managed-agents/skills) einbringen.
## Vom Claude Agent SDK
Wenn du mit dem [Claude Agent SDK](https://code.claude.com/docs/de/agent-sdk/overview) 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(...)` (python; typescript: `options`) wird pro Ausführung erstellt | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`) einmalig; der Agent wird serverseitig gespeichert und versioniert. Siehe [Agenten-Einrichtung](https://platform.claude.com/docs/de/managed-agents/agent-setup). |
| `async with ClaudeSDKClient(...)` oder `query(...)` | `client.beta.sessions.create(...)` (csharp: `client.Beta.Sessions.Create(...)`; go: `client.Beta.Sessions.New(...)`; java: `client.beta().sessions().create(...)`; php: `$client->beta->sessions->create(...)`), dann [Events](https://platform.claude.com/docs/de/managed-agents/events-and-streaming) senden und empfangen. |
| Mit `@tool` (python; typescript: `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](https://platform.claude.com/docs/de/managed-agents/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` (python; typescript: `additionalDirectories`) verweisen auf lokale Pfade | Lade [Dateien](https://platform.claude.com/docs/de/managed-agents/files) als Session-Ressourcen hoch oder binde sie ein. |
| `system_prompt` (python; typescript: `systemPrompt`) 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](https://platform.claude.com/docs/de/managed-agents/agent-setup). |
| `mcp_servers` (python; typescript: `mcpServers`) an einer Stelle konfiguriert und authentifiziert | Deklariere Server am Agenten; stelle Anmeldedaten über einen [Vault](https://platform.claude.com/docs/de/managed-agents/vaults) in der Session bereit. |
| `permission_mode` (python; typescript: `permissionMode`), `can_use_tool` (python; typescript: `canUseTool`) | [`permission_policy`](https://platform.claude.com/docs/de/managed-agents/permission-policies) 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):
```python Python
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)
```
```typescript TypeScript
import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const getWeather = tool(
"get_weather",
"Get the current weather for a city.",
{ city: z.string() },
async (args) => ({
content: [{ type: "text", text: `${args.city}: 18°C, clear` }]
})
);
for await (const message of query({
prompt: "What's the weather in Tokyo?",
options: {
model: "claude-opus-5-5",
systemPrompt: "You are a concise weather assistant.",
mcpServers: {
weather: createSdkMcpServer({ name: "weather", version: "1.0", tools: [getWeather] })
}
}
})) {
console.log(message);
}
```
**Nachher** (Managed Agents):
```python Python
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":
break
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const agent = await 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"]
}
}
]
});
const environment = await client.beta.environments.create({
name: "weather-env",
config: {
type: "cloud",
networking: { type: "limited", allow_package_managers: true }
}
});
const session = await client.beta.sessions.create({
agent: { type: "agent", id: agent.id, version: agent.version },
environment_id: environment.id
});
function getWeather({ city }: Record): string {
return `${city}: 18°C, clear`;
}
const stream = await client.beta.sessions.events.stream(session.id);
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.message",
content: [{ type: "text", text: "What's the weather in Tokyo?" }]
}
]
});
loop: for await (const event of stream) {
switch (event.type) {
case "agent.message":
for (const block of event.content) {
if (block.type === "text") {
console.log(block.text);
}
}
break;
case "agent.custom_tool_use": {
const result = getWeather(event.input);
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.custom_tool_result",
custom_tool_use_id: event.id,
content: [{ type: "text", text: result }]
}
]
});
break;
}
case "session.status_idle":
if (event.stop_reason?.type === "end_turn") {
break loop;
}
break;
}
}
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Beta.Agents;
using Anthropic.Models.Beta.Environments;
using Anthropic.Models.Beta.Sessions;
using Anthropic.Models.Beta.Sessions.Events;
AnthropicClient client = new();
var agent = await client.Beta.Agents.Create(new()
{
Name = "weather-agent",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You are a concise weather assistant.",
Tools =
[
new BetaManagedAgentsCustomToolParams
{
Type = "custom",
Name = "get_weather",
Description = "Get the current weather for a city.",
InputSchema = new()
{
Properties = new Dictionary
{
["city"] = JsonSerializer.SerializeToElement(new { type = "string" }),
},
Required = ["city"],
},
},
],
});
var environment = await client.Beta.Environments.Create(new()
{
Name = "weather-env",
Config = new BetaCloudConfigParams
{
Networking = new BetaLimitedNetworkParams { AllowPackageManagers = true },
},
});
var session = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentParams
{
Type = "agent",
ID = agent.ID,
Version = agent.Version,
},
EnvironmentID = environment.ID,
});
static string GetWeather(string city) => $"{city}: 18°C, clear";
using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserMessageEventParams
{
Type = "user.message",
Content = [new BetaManagedAgentsTextBlock { Type = "text", Text = "What's the weather in Tokyo?" }],
},
],
});
await foreach (var streamEvent in stream.Enumerate())
{
if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
{
var text = string.Concat(message.Content.Select(block =>
block.Value is BetaManagedAgentsTextBlock textBlock ? textBlock.Text : ""));
Console.WriteLine(text);
}
else if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
{
var result = GetWeather(toolUse.Input["city"].GetString()!);
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserCustomToolResultEventParams
{
Type = "user.custom_tool_result",
CustomToolUseID = toolUse.ID,
Content =
[
new BetaManagedAgentsTextBlock
{
Type = "text",
Text = result,
},
],
},
],
});
}
else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
&& idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
{
break;
}
}
```
```go Go
client := anthropic.NewClient()
ctx := context.Background()
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "weather-agent",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
},
System: anthropic.String("You are a concise weather assistant."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
Type: anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
Name: "get_weather",
Description: "Get the current weather for a city.",
InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
Properties: map[string]any{
"city": map[string]any{"type": "string"},
},
Required: []string{"city"},
},
},
}},
})
if err != nil {
panic(err)
}
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
Name: "weather-env",
Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
OfCloud: &anthropic.BetaCloudConfigParams{
Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
OfLimited: &anthropic.BetaLimitedNetworkParams{
AllowPackageManagers: anthropic.Bool(true),
},
},
},
},
})
if err != nil {
panic(err)
}
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: agent.ID,
Version: anthropic.Int(agent.Version),
},
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
getWeather := func(city string) string {
return fmt.Sprintf("%s: 18°C, clear", city)
}
stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: "What's the weather in Tokyo?",
},
}},
},
}},
})
if err != nil {
panic(err)
}
loop:
for stream.Next() {
event := stream.Current()
switch event.Type {
case "agent.message":
for _, block := range event.AsAgentMessage().Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
case "agent.custom_tool_use":
toolUse := event.AsAgentCustomToolUse()
result := getWeather(toolUse.Input["city"].(string))
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
Type: anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
CustomToolUseID: toolUse.ID,
Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: result,
},
}},
},
}},
}); err != nil {
panic(err)
}
case "session.status_idle":
idle := event.AsSessionStatusIdle()
if _, ok := idle.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionEndTurn); ok {
break loop
}
}
}
if err := stream.Err(); err != nil {
panic(err)
}
```
```java Java
import java.util.Map;
import java.util.function.Function;
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolInputSchema;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
import com.anthropic.models.beta.environments.BetaCloudConfigParams;
import com.anthropic.models.beta.environments.BetaLimitedNetworkParams;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;
import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams;
import com.anthropic.models.beta.sessions.SessionCreateParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserCustomToolResultEventParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
import com.anthropic.models.beta.sessions.events.EventSendParams;
var client = AnthropicOkHttpClient.fromEnv();
var agent = client.beta().agents().create(AgentCreateParams.builder()
.name("weather-agent")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You are a concise weather assistant.")
.addTool(BetaManagedAgentsCustomToolParams.builder()
.type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
.name("get_weather")
.description("Get the current weather for a city.")
.inputSchema(BetaManagedAgentsCustomToolInputSchema.builder()
.properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder()
.putAdditionalProperty("city", JsonValue.from(Map.of("type", "string")))
.build())
.addRequired("city")
.build())
.build())
.build());
var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
.name("weather-env")
.config(BetaCloudConfigParams.builder()
.networking(BetaLimitedNetworkParams.builder()
.allowPackageManagers(true)
.build())
.build())
.build());
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(agent.id())
.version(agent.version())
.build())
.environmentId(environment.id())
.build());
Function getWeather = city -> city + ": 18°C, clear";
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
client.beta().sessions().events().send(
session.id(),
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserMessageEventParams.builder()
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
.addTextContent("What's the weather in Tokyo?")
.build())
.build());
loop:
for (var event : (Iterable) stream.stream()::iterator) {
switch (event.type().value()) {
case AGENT_MESSAGE -> {
for (var block : event.asAgentMessage().content()) {
block.text().ifPresent(textBlock -> IO.println(textBlock.text()));
}
}
case AGENT_CUSTOM_TOOL_USE -> {
var toolUse = event.asAgentCustomToolUse();
var city = toolUse.input()._additionalProperties().get("city").asStringOrThrow();
var result = getWeather.apply(city);
client.beta().sessions().events().send(
session.id(),
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
.type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
.customToolUseId(toolUse.id())
.addTextContent(result)
.build())
.build());
}
case SESSION_STATUS_IDLE -> {
if (event.asSessionStatusIdle().stopReason().isEndTurn()) {
break loop;
}
}
}
}
}
```
```php PHP
use Anthropic\Client;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;
use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams;
use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentCustomToolUseEvent;
use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent;
use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionEndTurn;
use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent;
use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock;
$client = new Client();
$agent = $client->beta->agents->create(
name: 'weather-agent',
model: 'claude-opus-5-5',
system: 'You are a concise weather assistant.',
tools: [
BetaManagedAgentsCustomToolParams::with(
type: 'custom',
name: 'get_weather',
description: 'Get the current weather for a city.',
inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
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: BetaManagedAgentsAgentParams::with(
type: 'agent',
id: $agent->id,
version: $agent->version,
),
environmentID: $environment->id,
);
function getWeather(string $city): string
{
return "{$city}: 18°C, clear";
}
$stream = $client->beta->sessions->events->streamStream($session->id);
$client->beta->sessions->events->send(
$session->id,
events: [
[
'type' => 'user.message',
'content' => [['type' => 'text', 'text' => "What's the weather in Tokyo?"]],
],
],
);
foreach ($stream as $event) {
switch (true) {
case $event instanceof ManagedAgentsAgentMessageEvent:
foreach ($event->content as $block) {
if ($block instanceof ManagedAgentsTextBlock) {
echo $block->text . "\n";
}
}
break;
case $event instanceof ManagedAgentsAgentCustomToolUseEvent:
$result = getWeather($event->input['city']);
$client->beta->sessions->events->send(
$session->id,
events: [
[
'type' => 'user.custom_tool_result',
'custom_tool_use_id' => $event->id,
'content' => [['type' => 'text', 'text' => $result]],
],
],
);
break;
case $event instanceof ManagedAgentsSessionStatusIdleEvent:
if ($event->stopReason instanceof ManagedAgentsSessionEndTurn) {
break 2;
}
break;
}
}
$stream->close();
```
```ruby Ruby
require "anthropic"
client = Anthropic::Client.new
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)
"#{city}: 18°C, clear"
end
stream = client.beta.sessions.events.stream_events(session.id)
client.beta.sessions.events.send_(
session.id,
events: [{type: "user.message", content: [{type: "text", text: "What's the weather in Tokyo?"}]}]
)
stream.each do |event|
case event
when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent
event.content.each do |block|
puts block.text if block.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsTextBlock)
end
when Anthropic::Beta::Sessions::BetaManagedAgentsAgentCustomToolUseEvent
result = get_weather(event.input[:city])
client.beta.sessions.events.send_(
session.id,
events: [
{
type: "user.custom_tool_result",
custom_tool_use_id: event.id,
content: [{type: "text", text: result}]
}
]
)
when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
break if event.stop_reason.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsSessionEndTurn)
end
end
```
Der 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`](https://platform.claude.com/docs/de/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-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` (python; typescript: `maxTurns`) | Zähle Turns clientseitig. |
## Migrations-Checkliste
1. [Erstelle ein Environment](https://platform.claude.com/docs/de/managed-agents/environments) mit dem Netzwerk und den Laufzeitumgebungen, die dein Agent benötigt.
2. Portiere deinen System-Prompt und deine Tool-Auswahl in eine [Agentendefinition](https://platform.claude.com/docs/de/managed-agents/agent-setup).
3. Ersetze deine Schleife: [Erstelle eine Session](https://platform.claude.com/docs/de/managed-agents/sessions) mit `client.beta.sessions.create()` (python, typescript, ruby; go: `client.Beta.Sessions.New()`; csharp: `client.Beta.Sessions.Create()`; java: `client.beta().sessions().create()`; php: `$client->beta->sessions->create()`; cli: `ant beta:sessions create`; curl: `POST /v1/sessions`) und [streame ihre Events](https://platform.claude.com/docs/de/managed-agents/events-and-streaming) mit `client.beta.sessions.events.stream()` (python, typescript; ruby: `client.beta.sessions.events.stream_events()`; go: `client.Beta.Sessions.Events.StreamEvents()`; csharp: `client.Beta.Sessions.Events.StreamStreaming()`; java: `client.beta().sessions().events().streamStreaming()`; php: `$client->beta->sessions->events->streamStream()`; cli: `ant beta:sessions:events stream`; curl: `GET /v1/sessions/{session_id}/events/stream`).
4. Lade alle lokalen Dateien, die der Agent liest, über die [Files API](https://platform.claude.com/docs/de/managed-agents/files) hoch und binde sie als `resources` ein.
5. Verschiebe für alle benutzerdefinierten Tool-Handler die Ausführung in deine Event-Schleife als Antworten auf `agent.custom_tool_use`-Events.
6. 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](https://platform.claude.com/docs/de/managed-agents/agent-setup), und die Änderung wird bei der nächsten Session wirksam, die du erstellst.
```bash cURL
curl -sS --fail-with-body "https://api.anthropic.com/v1/agents/$AGENT_ID?beta=true" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
--json "$(jq -n --argjson version "$AGENT_VERSION" '{version: $version, model: "claude-opus-5-5"}')"
```
```bash CLI
ant apply agent.md
```
```markdown
---
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.
```
```python Python
client.beta.agents.update(
agent.id,
version=agent.version,
model="claude-opus-5-5",
)
```
```typescript TypeScript
await client.beta.agents.update(agent.id, {
version: agent.version,
model: "claude-opus-5-5"
});
```
```csharp C#
await client.Beta.Agents.Update(agent.ID, new()
{
Version = agent.Version,
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
});
```
```go Go
_, err = client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Version: agent.Version,
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
},
})
if err != nil {
panic(err)
}
```
```java Java
client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.version(agent.version())
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.build()
);
```
```php PHP
$client->beta->agents->update(
$agent->id,
version: $agent->version,
model: 'claude-opus-5-5',
);
```
```ruby Ruby
client.beta.agents.update(
agent.id,
version: agent.version,
model: "claude-opus-5-5"
)
```
Die meisten Verhaltensänderungen auf Modellebene, die im [Messages-API-Migrationsleitfaden](https://platform.claude.com/docs/de/about-claude/models/migration-guide) 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.