migration changedmanaged-agents/migration
Recorded here
Lines+38added
Lines−22removed
From line
45
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits31to this page, all time
The whole hunk
from line 45, old and new numbered
/
from line 45
4545
4646### What you stop managing
4747
48| Before | After |
49| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
50| You maintain the conversation history array and pass it back on every turn. | The session stores history server-side. You send events and receive events. |
51| You iterate `tool_use` content blocks, run each tool, and loop back with `tool_result` messages. | Pre-built tools run inside the sandbox automatically. You only handle custom tools through `agent.custom_tool_use` events. |
52| You provision your own sandbox for running agent-generated code. | The session sandbox handles code execution, file operations, and bash. |
53| You decide when the loop is done. | The session emits `session.status_idle` when the agent has nothing more to do. |
48| Before | After |
49| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
50| You maintain the conversation history array and pass it back on every turn. | The session stores history server-side. You send events and receive events. |
51| You iterate `tool_use` content blocks, run each tool, and loop back with `tool_result` messages. | Built-in tools run inside the sandbox automatically. You only handle custom tools through `agent.custom_tool_use` events. |
52| You provision your own sandbox for running agent-generated code. | The session sandbox handles code execution, file operations, and bash. |
53| You decide when the loop is done. | The session emits `session.status_idle` when the agent has nothing more to do. |
5454
5555### Code comparison
5656
from line 57
5757**Before** (Messages API loop, simplified):
5858
5959<CodeGroup exclude="shell:cURL, shell:CLI">
60 <CodeGroupItem language="cURL">
61 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
62 </CodeGroupItem>
63
64 <CodeGroupItem language="CLI">
65 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
66 </CodeGroupItem>
67
6068 ```python Python
6169 messages = [{"role": "user", "content": task}]
6270 while True:
from line 543
535543
536544### What changes
537545
538| Agent SDK | Managed Agents |
539| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
540| `ClaudeAgentOptions(...)` (typescript: `options`) constructed per run | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`) once; the Agent is persisted and versioned server-side. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
541| `async with ClaudeSDKClient(...)` or `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(...)`) then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |
542| Functions defined with `@tool` (typescript: `tool()`), dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the Agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |
543| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |
544| `cwd`, `add_dirs` (typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |
545| `system_prompt` (typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` (csharp, go: `System`; ruby: `system_`) string on the Agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
546| `mcp_servers` (typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the Agent; provide credentials through a [Vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the Session. |
547| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |
546| Agent SDK | Managed Agents |
547| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
548| `ClaudeAgentOptions(...)` (typescript: `options`) constructed for each run | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`; cli: `ant beta:agents create`; curl: `POST /v1/agents`) once. The server persists and versions the agent. See [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
549| `async with ClaudeSDKClient(...)` or `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(...)`; cli: `ant beta:sessions create`; curl: `POST /v1/sessions`) then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |
550| Functions defined with `@tool` (typescript: `tool()`), dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |
551| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |
552| `cwd`, `add_dirs` (typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |
553| `system_prompt` (typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` (csharp, go: `System`; ruby: `system_`) string on the agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
554| `mcp_servers` (typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the agent; provide credentials through a [vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the session. |
555| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |
548556
549557### Code comparison
550558
from line 617
609617
610618**After** (Managed Agents):
611619
612<CodeGroup exclude="shell">
620<CodeGroup exclude="shell:cURL, shell:CLI">
621 <CodeGroupItem language="cURL">
622 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
623 </CodeGroupItem>
624
625 <CodeGroupItem language="CLI">
626 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
627 </CodeGroupItem>
628
613629 ```python Python
614630 from anthropic import Anthropic
615631
from line 1173
11571173 break;
11581174 case $event instanceof ManagedAgentsSessionStatusIdleEvent:
11591175 if ($event->stopReason instanceof ManagedAgentsSessionEndTurn) {
1160 break 2;
1176 break 2; // Leave the foreach loop
11611177 }
11621178 break;
11631179 }
from line 1248
12321248 ```
12331249</CodeGroup>
12341250
1235The Agent and Environment are created once and reused across sessions. The tool function still runs in your process; the difference is that you read the `agent.custom_tool_use` event and send the result explicitly instead of the SDK dispatching it for you.
1251You create the agent and environment once and reuse them across sessions. The tool function still runs in your process. The difference is that you read the `agent.custom_tool_use` event and send the result explicitly instead of the Agent SDK dispatching it for you.
12361252
12371253### Features that move to your client
12381254
from line 1368
13521368 ```
13531369</CodeGroup>
13541370
1355Most model-level behavior changes documented in the [Messages API migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide) do not require action on your side:
1371Most model-level behavior changes documented in the [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide) do not require action on your side:
13561372
13571373* **Request parameter changes** (`max_tokens` (java, php: `maxTokens`; csharp, go: `MaxTokens`) defaults, `thinking` (csharp, go: `Thinking`) configuration) are handled by the Claude Managed Agents runtime. These fields are not exposed on the agent definition.
1358* **Assistant message prefilling** does not exist in the event-based session model, so its removal on newer models is a no-op.
1374* **Assistant message prefilling** does not exist in the event-based session model, so moving to a model that rejects prefill needs no change from you.
13591375* **Tool argument JSON escaping** is parsed by the runtime before you receive `agent.custom_tool_use` events. You see structured data, not raw strings.
13601376
1361The behavior descriptions in the Messages API guide (what the model does differently) still apply. The migration steps (how to change your request code) do not.
1377The behavior descriptions in those guides (what the model does differently) still apply. The migration steps (how to change your request code) do not.
13621378
No line in this hunk matches that.