Claude Managed Agents 完整教學 - 從零打造雲端 AI Agent

自己搭 AI agent 的基礎設施有多痛？沙箱要做、狀態要管、retry 要寫、工具執行要安全隔離、觀測性要加、容器要維護。光這些就能吃掉幾週的開發時間，而且你真正想解決的業務問題一行 code 都還沒寫。

4/8 Anthropic 推出 Claude Managed Agents，把上面這些全包了。你只要定義「agent 要做什麼」，基礎設施的部分 Anthropic 幫你扛。目前是公開測試版，所有 API 帳號都能用。

四個核心概念

在動手之前，先搞清楚四個東西的關係：

概念	是什麼	類比
Agent	模型 + system prompt + 工具 + MCP servers	職位說明書
Environment	容器設定（套件、網路規則、檔案掛載）	辦公室環境
Session	一個正在跑的 agent 實例	一次工作任務
Events	你跟 agent 之間的訊息交換	對話和指令

Agent 定義一次，可以跨多個 Session 重複使用。Environment 也是——配好一個環境，所有 Session 都能引用。Session 是實際跑任務的地方，每個 Session 有獨立的檔案系統和對話歷史。

跟 Messages API 有什麼不同

如果你已經在用 Claude API 的 Messages endpoint 搭配自己的 agent loop，可能會問：Managed Agents 跟我自己做的有什麼差？

	Messages API	Managed Agents
定位	直接存取模型	預建的 agent 執行環境
適合	需要細緻控制 agent loop	長時間執行、非同步任務
基礎設施	自己搭	Anthropic 代管
工具執行	自己實作	雲端沙箱自動執行
狀態管理	自己處理	內建 checkpointing

簡單說：Messages API 給你最大的自由度，Managed Agents 給你最快的上線速度。如果你的 agent 需要跑幾分鐘到幾小時、需要安全的容器環境、而且不想自己管基礎設施——Managed Agents 就是為你設計的。

前置準備

需要三樣東西：

Anthropic Console 帳號
API key
安裝 ant CLI 或 SDK

安裝 ant CLI

# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"

# Linux
VERSION=1.0.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

# 或用 Go 安裝
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

安裝 SDK

# Python
pip install anthropic

# TypeScript
npm install @anthropic-ai/sdk

設定 API key：

1	export ANTHROPIC_API_KEY="your-api-key-here"

Step 1：建立 Agent

Agent 就是一份「職位說明書」——定義用哪個模型、system prompt 寫什麼、可以用哪些工具。

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    system="你是一個專業的程式碼助手。寫乾淨、有文件註解的程式碼。",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
)

print(f"Agent ID: {agent.id}, version: {agent.version}")

agent_toolset_20260401 是全套內建工具——bash、檔案操作、網頁搜尋等等。建立完會拿到一個 agent.id，後面每個 Session 都要用到。

用 ant CLI 也能做同樣的事：

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-sonnet-4-6}' \
  --system "你是一個專業的程式碼助手。寫乾淨、有文件註解的程式碼。" \
  --tool '{type: agent_toolset_20260401}'

Step 2：建立 Environment

Environment 定義容器的設定——裝什麼套件、網路怎麼開、要不要掛載檔案。

environment = client.beta.environments.create(
    name="dev-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

print(f"Environment ID: {environment.id}")

unrestricted 代表容器可以存取外部網路。如果你的 agent 不需要上網，可以設定限制來提高安全性。

Step 3：啟動 Session

有了 Agent 和 Environment，就能啟動 Session 了：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="第一個 Managed Agent",
)

print(f"Session ID: {session.id}")

Session 建立後，Anthropic 會在背景 provision 一個容器。

Step 4：互動 - 送訊息、收串流

重頭戲來了。開啟 SSE 串流，送出使用者訊息，然後即時收到 agent 的回應：

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": "寫一個 Python 腳本計算前 20 個費波那契數，存到 fibonacci.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[使用工具: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent 完成。")
                break

跑起來大概長這樣：

我來寫一個 Python 腳本計算費波那契數列。
[使用工具: write]
[使用工具: bash]
腳本執行成功，讓我確認輸出檔案。
[使用工具: bash]
fibonacci.txt 已包含前 20 個費波那契數（0 到 4181）。

Agent 完成。

整個過程中，Claude 自己決定要用什麼工具、自己寫程式碼、自己執行、自己驗證結果。你只要送訊息和收串流。

背後發生了什麼

當你送出 user event，Managed Agents 依序做了這些事：

Provision 容器 — 根據 Environment 設定建置執行環境
跑 agent loop — Claude 根據你的訊息決定用哪些工具
執行工具 — 檔案寫入、bash 指令等全在容器內執行
串流事件 — 即時推送更新到你的應用
進入 idle — 沒事做了就發 session.status_idle

你也可以在 agent 執行途中送新的 user event 來引導方向，或者中斷它改做別的事。

內建工具清單

agent_toolset_20260401 包含的工具：

Bash — 在容器內執行 shell 指令
檔案操作 — 讀取、寫入、編輯、glob、grep
網頁搜尋與抓取 — 搜尋網路、讀取網頁內容
MCP servers — 連接外部工具提供者

如果不想給全套工具，也可以只啟用特定工具。

跟其他 AI Agent 平台比一下

市面上做類似事情的不只 Anthropic。OpenAI 的 Codex 有自己的 sandbox 環境，但走的是 ChatGPT 整合路線而不是獨立 API。Google 的 Gemini API 支援 function calling 但沒有代管的 agent 執行環境。Kiro 和 Cursor 則專注在 IDE 端的 agent 體驗。

Managed Agents 的差異化在於：它是純 API 服務，不綁任何 UI。你可以用它建 Slack bot、內部工具、CI/CD pipeline、自動化工作流——任何需要 AI agent 跑在雲端的場景都行。