管理

遷移

將基於 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、自行執行工具調用並將結果附加到對話歷史記錄來構建代理，那麼大部分代碼將不再需要。

您不再需要管理的內容

之前	之後
您維護對話歷史記錄陣列並在每次輪次中傳回。	會話在服務器端存儲歷史記錄。發送事件，接收事件。
您解析 `stop_reason: "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-sonnet-4-6",
        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=$(
  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-sonnet-4-6",
      "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'
)

# 在後台打開 SSE 流，然後發送用戶消息。
stream_log=$(mktemp)
curl --fail-with-body -sS -N \
  "https://api.anthropic.com/v1/sessions/${session_id}/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

# 讀取事件直到會話進入空閒狀態。
while IFS= read -r line; do
  [[ ${line} == data:* ]] || continue
  event_type=$(jq -r '.type // empty' 2>/dev/null <<< "${line#data: }" || true)
  [[ ${event_type} == "session.status_idle" ]] && break
done < <(tail -f -n +1 "${stream_log}")

kill "${stream_pid}" 2>/dev/null || true

您仍然可以控制的內容

系統提示和模型： 相同的字段，現在位於代理定義上。
自定義工具： 仍使用 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` 指向本地路徑	通過文件 API 上傳或掛載文件作為會話資源。
`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-sonnet-4-6",
    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-sonnet-4-6",
    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(b.text for b in ev.content))
        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.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.stream 替換您的循環。
對於代理讀取的任何本地文件，通過文件 API 上傳並將其掛載為 resources。
對於任何自定義工具處理程序，將執行移至您的事件循環中，作為對 agent.custom_tool_use 事件的響應。
在將生產流量指向新流程之前，使用測試會話進行驗證。

在模型版本之間遷移

當新的 Claude 模型發布時，遷移 Claude Managed Agents 集成通常只需更改一個字段：更新您的代理定義上的 model，更改將在您創建的下一個會話中生效。

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-sonnet-4-6"}')"

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、自行執行工具調用並將結果附加到對話歷史記錄來構建代理，那麼大部分代碼將不再需要。

您不再需要管理的內容

之前	之後
您維護對話歷史記錄陣列並在每次輪次中傳回。	會話在服務器端存儲歷史記錄。發送事件，接收事件。
您解析 `stop_reason: "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-sonnet-4-6",
        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=$(
  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-sonnet-4-6",
      "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'
)

# 在後台打開 SSE 流，然後發送用戶消息。
stream_log=$(mktemp)
curl --fail-with-body -sS -N \
  "https://api.anthropic.com/v1/sessions/${session_id}/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

# 讀取事件直到會話進入空閒狀態。
while IFS= read -r line; do
  [[ ${line} == data:* ]] || continue
  event_type=$(jq -r '.type // empty' 2>/dev/null <<< "${line#data: }" || true)
  [[ ${event_type} == "session.status_idle" ]] && break
done < <(tail -f -n +1 "${stream_log}")

kill "${stream_pid}" 2>/dev/null || true

您仍然可以控制的內容

系統提示和模型： 相同的字段，現在位於代理定義上。
自定義工具： 仍使用 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` 指向本地路徑	通過文件 API 上傳或掛載文件作為會話資源。
`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-sonnet-4-6",
    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-sonnet-4-6",
    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(b.text for b in ev.content))
        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.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.stream 替換您的循環。
對於代理讀取的任何本地文件，通過文件 API 上傳並將其掛載為 resources。
對於任何自定義工具處理程序，將執行移至您的事件循環中，作為對 agent.custom_tool_use 事件的響應。
在將生產流量指向新流程之前，使用測試會話進行驗證。

在模型版本之間遷移

當新的 Claude 模型發布時，遷移 Claude Managed Agents 集成通常只需更改一個字段：更新您的代理定義上的 model，更改將在您創建的下一個會話中生效。

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-sonnet-4-6"}')"

Messages API 遷移指南中記錄的大多數模型級行為變更不需要您採取任何行動：

請求參數變更（max_tokens 默認值、thinking 配置）由 Claude Managed Agents 運行時處理。這些字段不在代理定義上公開。
助手消息預填充在基於事件的會話模型中不存在，因此在較新模型上移除它是一個無操作。
工具參數 JSON 轉義在您收到 agent.custom_tool_use 事件之前由運行時解析。您看到的是結構化數據，而不是原始字符串。

Messages API 指南中的行為描述（模型的不同之處）仍然適用。遷移步驟（如何更改您的請求代碼）則不適用。

Was this page helpful?