发布说明迁移指南

迁移

将基于 Messages API 或 Claude Agent SDK 构建的现有智能体迁移到 Claude Managed Agents。

Claude Managed Agents 使用托管基础设施取代您手写的智能体循环。本页介绍当您从基于 Messages API 构建的自定义循环或从 Claude Agent SDK 迁移时会发生哪些变化。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置该 beta 标头。

从 Messages API 智能体循环迁移

如果您通过在 while 循环中调用 messages.create、自行执行工具调用并将结果追加到对话历史来构建智能体，那么大部分代码都可以删除。

您不再需要管理的内容

之前	之后
您维护对话历史数组，并在每个回合将其传回。	会话在服务器端存储历史记录。发送事件，接收事件。
您遍历 `tool_use` 内容块，运行每个工具，然后使用 `tool_result` 消息循环返回。	预构建工具在沙箱内自动运行。您只需通过 `agent.custom_tool_use` 事件处理自定义工具。
您为运行智能体生成的代码配置自己的沙箱。	会话沙箱处理代码执行、文件操作和 bash。
您决定循环何时结束。	当智能体没有更多任务要执行时，会话会发出 `session.status_idle`。

代码对比

之前（Messages API 循环，简化版）：

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        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,
                        }
                    ],
                }
            )

之后（Claude Managed Agents）：

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-4-8",
    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

您仍然控制的内容

**系统提示和模型：**相同的字段，现在位于智能体定义中。
**自定义工具：**仍然使用 JSON Schema 声明。执行方式从内联处理改为响应 agent.custom_tool_use 事件。请参阅会话事件流。
**上下文：**您仍然可以通过系统提示、文件资源或技能注入上下文。

从 Claude Agent SDK 迁移

如果您使用 Claude Agent SDK 进行构建，那么您已经在使用智能体、工具和会话这些概念。区别在于它们的运行位置：SDK 在您运营的进程中执行，而 Managed Agents 在 Anthropic 的基础设施中运行。大部分迁移工作是将 SDK 配置对象映射到其 API 端的等效项。

变化内容

Agent SDK	Managed Agents
每次运行时构造 `ClaudeAgentOptions(...)`	调用一次 `client.beta.agents.create(...)`；智能体在服务器端持久化并进行版本管理。请参阅智能体设置。
`async with ClaudeSDKClient(...)` 或 `query(...)`	调用 `client.beta.sessions.create(...)`，然后发送和接收事件。
由 SDK 自动分派的 `@tool` 装饰函数	在智能体上声明为 `{"type": "custom", ...}`；您的客户端处理 `agent.custom_tool_use` 事件并以 `user.custom_tool_result` 回复。请参阅工具。
内置工具在您的进程中针对您的文件系统运行	`{"type": "agent_toolset_20260401"}` 在会话沙箱内针对 `/workspace` 运行相同的工具。
`cwd`、`add_dirs` 指向本地路径	将文件作为会话资源上传或挂载。
`system_prompt` 和 `CLAUDE.md` 层级结构	智能体上的单个 `system` 字符串。每次更新都会生成一个新的服务器端版本；将会话固定到特定版本，无需部署即可升级或回滚。请参阅智能体设置。
在一处配置和认证的 `mcp_servers`	在智能体上声明服务器；通过会话上的 Vault 提供凭据。
`permission_mode`、`can_use_tool`	每个工具的 `permission_policy`；为 `always_ask` 工具发送 `user.tool_confirmation` 事件。

代码对比

之前（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-4-8",
    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)

之后（Managed Agents）：

from anthropic import Anthropic

client = Anthropic()

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

智能体和环境只需创建一次，即可在多个会话中重复使用。工具函数仍然在您的进程中运行；区别在于您需要读取 agent.custom_tool_use 事件并显式发送结果，而不是由 SDK 为您分派。

转移到您的客户端的功能

由 Anthropic 运行智能体循环的代价是，SDK 自动处理的一些功能现在需要由您的客户端负责。

SDK 功能	Managed Agents 方式
计划模式	先运行一个仅用于规划的会话，然后运行第二个会话来执行计划。
输出样式、斜杠命令	在发送 `user.message` 之前或接收 `agent.message` 之后在您的客户端中应用。
`PreToolUse` / `PostToolUse` 钩子	您的客户端在响应之前已经能看到每个 `agent.custom_tool_use` 事件；将逻辑放在那里。对于内置工具，使用 `permission_policy: always_ask`。
`max_turns`	在客户端计算回合数。

迁移检查清单

创建一个环境，配置您的智能体所需的网络和运行时。
将您的系统提示和工具选择移植到智能体定义中。
用 sessions.create 和 sessions.events.stream 替换您的循环。
对于智能体读取的任何本地文件，通过 Files API 上传它们并将其挂载为 resources。
对于任何自定义工具处理程序，将执行逻辑移到您的事件循环中，作为对 agent.custom_tool_use 事件的响应。
在将生产流量指向新流程之前，先通过测试会话进行验证。

在模型版本之间迁移

当新的 Claude 模型发布时，迁移 Claude Managed Agents 集成通常只需更改一个字段：更新智能体定义上的 model，更改将在您创建的下一个会话中生效。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

Messages API 迁移指南中记录的大多数模型级行为变化不需要您采取任何操作：

请求参数变化（max_tokens 默认值、thinking 配置）由 Claude Managed Agents 运行时处理。这些字段不会在智能体定义中暴露。
助手消息预填充在基于事件的会话模型中不存在，因此在较新模型上移除该功能对您没有影响。
工具参数 JSON 转义在您收到 agent.custom_tool_use 事件之前已由运行时解析。您看到的是结构化数据，而不是原始字符串。

Messages API 指南中的行为描述（模型的不同行为）仍然适用。迁移步骤（如何更改您的请求代码）则不适用。

Was this page helpful?

发布说明迁移指南

迁移

将基于 Messages API 或 Claude Agent SDK 构建的现有智能体迁移到 Claude Managed Agents。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置该 beta 标头。

从 Messages API 智能体循环迁移

如果您通过在 while 循环中调用 messages.create、自行执行工具调用并将结果追加到对话历史来构建智能体，那么大部分代码都可以删除。

您不再需要管理的内容

之前	之后
您维护对话历史数组，并在每个回合将其传回。	会话在服务器端存储历史记录。发送事件，接收事件。
您遍历 `tool_use` 内容块，运行每个工具，然后使用 `tool_result` 消息循环返回。	预构建工具在沙箱内自动运行。您只需通过 `agent.custom_tool_use` 事件处理自定义工具。
您为运行智能体生成的代码配置自己的沙箱。	会话沙箱处理代码执行、文件操作和 bash。
您决定循环何时结束。	当智能体没有更多任务要执行时，会话会发出 `session.status_idle`。

代码对比

之前（Messages API 循环，简化版）：

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        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,
                        }
                    ],
                }
            )

之后（Claude Managed Agents）：

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-4-8",
    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

您仍然控制的内容

**系统提示和模型：**相同的字段，现在位于智能体定义中。
**自定义工具：**仍然使用 JSON Schema 声明。执行方式从内联处理改为响应 agent.custom_tool_use 事件。请参阅会话事件流。
**上下文：**您仍然可以通过系统提示、文件资源或技能注入上下文。

从 Claude Agent SDK 迁移

变化内容

Agent SDK	Managed Agents
每次运行时构造 `ClaudeAgentOptions(...)`	调用一次 `client.beta.agents.create(...)`；智能体在服务器端持久化并进行版本管理。请参阅智能体设置。
`async with ClaudeSDKClient(...)` 或 `query(...)`	调用 `client.beta.sessions.create(...)`，然后发送和接收事件。
由 SDK 自动分派的 `@tool` 装饰函数	在智能体上声明为 `{"type": "custom", ...}`；您的客户端处理 `agent.custom_tool_use` 事件并以 `user.custom_tool_result` 回复。请参阅工具。
内置工具在您的进程中针对您的文件系统运行	`{"type": "agent_toolset_20260401"}` 在会话沙箱内针对 `/workspace` 运行相同的工具。
`cwd`、`add_dirs` 指向本地路径	将文件作为会话资源上传或挂载。
`system_prompt` 和 `CLAUDE.md` 层级结构	智能体上的单个 `system` 字符串。每次更新都会生成一个新的服务器端版本；将会话固定到特定版本，无需部署即可升级或回滚。请参阅智能体设置。
在一处配置和认证的 `mcp_servers`	在智能体上声明服务器；通过会话上的 Vault 提供凭据。
`permission_mode`、`can_use_tool`	每个工具的 `permission_policy`；为 `always_ask` 工具发送 `user.tool_confirmation` 事件。

代码对比

之前（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-4-8",
    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)

之后（Managed Agents）：

from anthropic import Anthropic

client = Anthropic()

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

转移到您的客户端的功能

由 Anthropic 运行智能体循环的代价是，SDK 自动处理的一些功能现在需要由您的客户端负责。

SDK 功能	Managed Agents 方式
计划模式	先运行一个仅用于规划的会话，然后运行第二个会话来执行计划。
输出样式、斜杠命令	在发送 `user.message` 之前或接收 `agent.message` 之后在您的客户端中应用。
`PreToolUse` / `PostToolUse` 钩子	您的客户端在响应之前已经能看到每个 `agent.custom_tool_use` 事件；将逻辑放在那里。对于内置工具，使用 `permission_policy: always_ask`。
`max_turns`	在客户端计算回合数。

迁移检查清单

创建一个环境，配置您的智能体所需的网络和运行时。
将您的系统提示和工具选择移植到智能体定义中。
用 sessions.create 和 sessions.events.stream 替换您的循环。
对于智能体读取的任何本地文件，通过 Files API 上传它们并将其挂载为 resources。
对于任何自定义工具处理程序，将执行逻辑移到您的事件循环中，作为对 agent.custom_tool_use 事件的响应。
在将生产流量指向新流程之前，先通过测试会话进行验证。

在模型版本之间迁移

当新的 Claude 模型发布时，迁移 Claude Managed Agents 集成通常只需更改一个字段：更新智能体定义上的 model，更改将在您创建的下一个会话中生效。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

Messages API 迁移指南中记录的大多数模型级行为变化不需要您采取任何操作：

请求参数变化（max_tokens 默认值、thinking 配置）由 Claude Managed Agents 运行时处理。这些字段不会在智能体定义中暴露。
助手消息预填充在基于事件的会话模型中不存在，因此在较新模型上移除该功能对您没有影响。
工具参数 JSON 转义在您收到 agent.custom_tool_use 事件之前已由运行时解析。您看到的是结构化数据，而不是原始字符串。

Messages API 指南中的行为描述（模型的不同行为）仍然适用。迁移步骤（如何更改您的请求代码）则不适用。

Was this page helpful?

从 Messages API 智能体循环迁移

您不再需要管理的内容

代码对比

您仍然控制的内容

从 Claude Agent SDK 迁移

变化内容

代码对比

转移到您的客户端的功能

迁移检查清单

在模型版本之间迁移

从 Messages API 智能体循环迁移

您不再需要管理的内容

代码对比

您仍然控制的内容

从 Claude Agent SDK 迁移

变化内容

代码对比

转移到您的客户端的功能

迁移检查清单

在模型版本之间迁移

从 Messages API 智能体循环迁移

您不再需要管理的内容

代码对比

您仍然控制的内容

从 Claude Agent SDK 迁移

变化内容

代码对比

转移到您的客户端的功能

迁移检查清单

在模型版本之间迁移

从 Messages API 智能体循环迁移

您不再需要管理的内容

代码对比

您仍然控制的内容

从 Claude Agent SDK 迁移

变化内容

代码对比

转移到您的客户端的功能

迁移检查清单

在模型版本之间迁移