版本資訊遷移指南

遷移

將基於 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(...)`；Agent 會在伺服器端持久化並進行版本控制。請參閱代理設定。
`async with ClaudeSDKClient(...)` 或 `query(...)`	呼叫 `client.beta.sessions.create(...)`，然後傳送和接收事件。
由 SDK 自動分派的 `@tool` 裝飾函式	在 Agent 上宣告為 `{"type": "custom", ...}`；您的用戶端處理 `agent.custom_tool_use` 事件並以 `user.custom_tool_result` 回覆。請參閱工具。
內建工具在您的程序中針對您的檔案系統執行	`{"type": "agent_toolset_20260401"}` 在工作階段沙箱內針對 `/workspace` 執行相同的工具。
`cwd`、`add_dirs` 指向本機路徑	上傳或掛載檔案作為工作階段資源。
`system_prompt` 和 `CLAUDE.md` 階層	Agent 上的單一 `system` 字串。每次更新都會產生新的伺服器端版本；將工作階段固定到特定版本，即可在不部署的情況下升級或回滾。請參閱代理設定。
在單一位置設定和驗證 `mcp_servers`	在 Agent 上宣告伺服器；透過 Session 上的 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 和 Environment 只需建立一次，即可在多個工作階段中重複使用。工具函式仍然在您的程序中執行；差異在於您讀取 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。

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 遷移

變更內容

Agent SDK	Managed Agents
每次執行時建構 `ClaudeAgentOptions(...)`	呼叫一次 `client.beta.agents.create(...)`；Agent 會在伺服器端持久化並進行版本控制。請參閱代理設定。
`async with ClaudeSDKClient(...)` 或 `query(...)`	呼叫 `client.beta.sessions.create(...)`，然後傳送和接收事件。
由 SDK 自動分派的 `@tool` 裝飾函式	在 Agent 上宣告為 `{"type": "custom", ...}`；您的用戶端處理 `agent.custom_tool_use` 事件並以 `user.custom_tool_result` 回覆。請參閱工具。
內建工具在您的程序中針對您的檔案系統執行	`{"type": "agent_toolset_20260401"}` 在工作階段沙箱內針對 `/workspace` 執行相同的工具。
`cwd`、`add_dirs` 指向本機路徑	上傳或掛載檔案作為工作階段資源。
`system_prompt` 和 `CLAUDE.md` 階層	Agent 上的單一 `system` 字串。每次更新都會產生新的伺服器端版本；將工作階段固定到特定版本，即可在不部署的情況下升級或回滾。請參閱代理設定。
在單一位置設定和驗證 `mcp_servers`	在 Agent 上宣告伺服器；透過 Session 上的 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 遷移

變更內容

程式碼比較

移至您的用戶端的功能

遷移檢查清單

在模型版本之間遷移