Claude Managed Agents 快速入門指南 2026
Claude Managed Agents 分步快速入門：Beta 標頭設置、首個會話、工具呼叫和串流事件——附關鍵程式碼範例與費用確認要點。
第一次嘗試執行 Managed Agents 工作階段時，我在第一個 curl 指令就收到了 400 錯誤。不是在建立 agent 時出錯，也不是在環境設定時出錯，而是在串流端點。我從建立請求複製貼上了標頭——anthropic-beta: managed-agents-2026-04-01——但串流 API 拒絕了它。原來文件中的串流端點當時引用的是另一個 beta 標頭。我就這樣白白浪費了四十分鐘。
如果你今天想要完整跑通第一個 Managed Agents 工作階段，這是我實際走過的路。嗨，我是 Dora！先從 beta 標頭開始，因為那是半數失敗的根源。然後依序是 agent、環境、工作階段、串流。最後還有一個費用檢查點，因為工作階段的執行時間在你除錯時仍在計費。
開始之前
你需要一個具備 Managed Agents 存取權限的 Anthropic API 金鑰。目前沒有候補名單——所有現有金鑰在公開測試版中均可使用。
beta 標頭是不可或缺的。 每個 Managed Agents 端點都需要 anthropic-beta: managed-agents-2026-04-01。根據 Anthropic 的 Managed Agents 概覽，SDK 會自動設定此標頭。如果你使用原始 curl，則需要自行在每個請求中加入。這是我在社群回報中見過最常見的 400 錯誤原因。
如果你使用官方 SDK（Python 用 anthropic，TypeScript 用 @anthropic-ai/sdk），請確認你使用的版本已包含 beta agent 支援。舊版本不會有 client.beta.agents 或 client.beta.sessions。
模型選擇在這裡很重要。 Opus 4.7 在長期 agent 推理上更為智慧。Sonnet 4.6 每個 token 更便宜也更快。對於快速入門執行，Sonnet 4.6 已經足夠。如果你的實際工作負載是除錯、規劃或長工具鏈，Opus 4.7 的價格就物有所值。
步驟一——定義你的 Agent
在 Managed Agents 中，agent 是一個設定物件，而不是一個程序。你定義名稱、模型、系統提示和工具存取權限一次，然後在多個工作階段中重複使用。
來自官方快速入門的最小可用定義：
python
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-4-7",
system="You are a helpful coding agent.",
tools=[{"type": "agent_toolset_20260401"}],
)agent_toolset_20260401 工具類型可解鎖完整的內建工具集——bash、檔案讀寫、網路搜尋、網路擷取、程式碼執行。你之後可以縮小範圍。第一次執行時，保持寬鬆設定，這樣你才能看到 agent 實際選擇使用什麼工具。
儲存 agent.id。每個工作階段都需要引用它。
步驟二——建立環境
環境定義了沙箱容器。對於大多數首次執行：
python
env = client.beta.environments.create(
name="quickstart-env",
config={"type": "cloud", "networking": {"type": "unrestricted"}},
)儲存 env.id。如果你的 agent 只存取自身的檔案系統，"networking": {"type": "limited"} 更為安全，並且在 SRE 事件應對者指南中有詳細說明。
步驟三——啟動工作階段
工作階段將 agent 與環境綁定在一起。建立工作階段並不會開始工作。 它只是進行佈建。當你發送使用者事件時，工作才會開始。
python
session = client.beta.sessions.create(
agent=agent.id,
environment_id=env.id,
title="Quickstart session",
)這個模式——建立，然後以事件驅動——正是來自工作階段參考文件的狀態機模型有其意義的地方。工作階段會持續存在。你之後可以發送更多事件。檔案系統在每次對話輪次之間都會保留。
步驟四——串流事件
開啟串流、發送使用者訊息、讀取事件直到 session.status_idle：
python
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": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
}],
)
for event in stream:
match event.type:
case "agent.message":
for block in event.content:
print(block.text, end="")
case "agent.tool_use":
print(f"\n[tool: {event.name}]")
case "session.status_idle":
break事件名稱遵循 {domain}.{action} 格式。完整的結構說明請見事件與串流文件。processed_at 欄位很重要：如果它是 null，表示事件已排隊但尚未執行。我在第一次執行時忽略了這一點，以為工具是在靜默失敗。
費用檢查點
Managed Agents 計費兩項：標準 token 費率加上每工作階段小時$0.08 的活躍執行時間費用。根據官方定價頁面，執行時間以毫秒計費——但僅在狀態為 running 時計算。閒置時間和已終止的工作階段不收費。
實際意義如下：
- 除錯時忘記關閉的工作階段：仍在計費（如果它正在執行）。
- 網路搜尋：每 1,000 次呼叫 $10，單獨計費。研究型 agent 很快就會達到此上限。
- 下班前在 Console 追蹤中檢查活躍工作階段。請自行確認目前的 UI 路徑——Console 的版面配置一直在更新中。
常見錯誤
缺少或錯誤的 beta 標頭。 400 錯誤，通常附有關於不支援端點的訊息。修正方式：確認每個直接 HTTP 呼叫都包含 managed-agents-2026-04-01。如果你使用 SDK 仍然遇到此問題，請升級 SDK。
速率限制。 建立端點上限為每分鐘 60 次請求；讀取端點為每分鐘 600 次請求。組織層級限制仍會在此之上額外適用。收到 429 錯誤表示要使用抖動退避，而不是立即重試。
靜默工具迴圈。 Agent 持續呼叫工具但不產生最終訊息。檢查工作階段追蹤——通常是未處理的 requires_action 從未收到回應所致。
常見問題
Q1：如何在 Managed Agents 中啟用多 agent 協調？
多 agent（以及記憶體和成果）仍是研究預覽功能。你需要透過 Claude Console 單獨申請存取權限。協調模式——協調者委派給可呼叫的 agent——已記錄在多 agent 工作階段下，但在你的組織啟用預覽標誌之前無法使用。
Q2：我可以查看 agent 在工作階段中呼叫了哪些工具嗎？
可以。使用 client.beta.sessions.events.list(session.id) 進行程式化存取，或使用 Console 的追蹤視圖查看每個事件的時間順序時間軸，包含 token 數量和時間戳記。
Q3：官方 Managed Agents 食譜在哪裡？
教學文件位於 Claude Cookbook 網站——iterate-fix-failing-tests 筆記本是最佳的第一篇閱讀材料。operate-in-production 筆記本涵蓋了 vault、MCP 和 webhook，適合在完成 hello-world 階段後閱讀。
Q4：有辦法在不產生工作階段執行時間費用的情況下進行測試嗎？
沒有專屬的 Managed Agents 免費方案。標準 API 免費額度適用於此。開發期間保持工作階段簡短，並在停止工作時關閉它們。閒置工作階段不計費，但執行中的工作階段會計費——而「執行中」包括靜默迴圈的 agent。
Q5：長時間執行的 Managed Agents 任務最適合使用哪個模型？
這取決於「長時間執行」的含義。對於需要大量工具使用的多小時推理，使用 Opus 4.7。對於高量、較簡單的迴圈，搭配提示快取的 Sonnet 4.6 能大幅降低成本。我仍在測試 Opus 4.7 在兩小時以上工作階段的表現。那是我資料的終點。後續還有更多分享。
仍在驗證壓縮在超過兩小時後的行為。自己執行看看——那會比我能告訴你的更多。
先前的文章：
