開始使用 Claude Managed Agents
建立您的第一個自主代理。
本指南將逐步引導您建立代理、設定環境、啟動工作階段,以及串流代理回應。
Claude Code
讓 Claude Code 為您設定代理
/claude-api managed-agents-onboard核心概念
| 概念 | 說明 |
|---|---|
| Agent(代理) | 模型、系統提示、工具、MCP 伺服器與技能 |
| Environment(環境) | 工作階段執行位置的設定:由 Anthropic 管理的雲端沙箱,或在您自己的基礎設施上自行託管的沙箱 |
| Session(工作階段) | 在環境中執行的代理實例,負責執行特定任務並產生輸出 |
| Events(事件) | 您的應用程式與代理之間交換的訊息(使用者輪次、工具結果、狀態更新) |
開始之前
建立 Claude Console 帳戶
註冊 Claude Console 帳戶,或登入您既有的帳戶。
選擇驗證方式
對於本機開發,建議使用 CLI 登入。
CLIAPI 金鑰
安裝 CLI
brew install anthropics/tap/ant對於 Linux 環境,請直接下載發行版本的二進位檔。
VERSION=2.12.1 OS=$(uname -s | tr '[:upper:]' '[:lower:]') case $(uname -m) in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac 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您可以在 GitHub 發行版本頁面上找到所有發行版本。
您也可以使用
go install從原始碼安裝 CLI,這需要 Go 1.26.10 或更新版本。go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestgo install會將二進位檔放置在$(go env GOPATH)/bin中。如果該目錄尚未加入您的PATH,請將其加入:export PATH="$PATH:$(go env GOPATH)/bin"登入
ant auth login登入完成後,SDK 和 CLI 將會自動取得您的憑證。
建立 API 金鑰
在 Claude Console 中建立 API 金鑰。
設定環境變數
SDK 和 CLI 會從
ANTHROPIC_API_KEY讀取您的金鑰:export ANTHROPIC_API_KEY="your-api-key-here"
若要執行 CLI 範例,請安裝 CLI:
brew install anthropics/tap/ant對於 Linux 環境,請直接下載發行版本的二進位檔。
VERSION=2.12.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
x86_64) ARCH=amd64 ;;
aarch64) ARCH=arm64 ;;
esac
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您可以在 GitHub 發行版本頁面上找到所有發行版本。
您也可以使用 go install 從原始碼安裝 CLI,這需要 Go 1.26.10 或更新版本。
go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestgo install 會將二進位檔放置在 $(go env GOPATH)/bin 中。如果該目錄尚未加入您的 PATH,請將其加入:
export PATH="$PATH:$(go env GOPATH)/bin"安裝 SDK
pip install anthropic建立您的第一個工作階段
建立代理
建立一個定義模型、系統提示和可用工具的代理。
CLIant apply coding-assistant.mdcoding-assistant.md--- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 configs: - name: web_search enabled: false - name: web_fetch enabled: false --- You are a helpful coding assistant. Write clean, well-documented code.ant apply會印出代理的 ID,並將其記錄在claude-lock.json中。您建立的每個工作階段都會參照它。agent_toolset_20260401工具類型會啟用預建的代理工具(bash、檔案操作、網頁搜尋等)。此範例停用了網頁搜尋和網頁擷取,因為本指南中的任務(撰寫一個簡短的 Python 指令碼)不會用到網頁。請只為代理提供它所需的工具。如需完整清單及各工具的設定選項,請參閱工具。建立環境
環境定義了代理執行所在的「sandbox」(沙箱)。此環境使用
limited網路並允許套件管理器,因此在沙箱中執行的程式碼可以連線到公開的套件登錄庫和程式碼託管服務。使用limited網路時,allowed_hosts清單也同樣適用於網頁搜尋和網頁擷取,儘管它們在沙箱外執行。如果未列出任何主機(此環境正是如此),這些工具不會傳回任何頁面或搜尋結果。如果您自己的代理使用這些工具,請將它所需的主機新增至該清單。CLIant apply environment.yamlenvironment.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: quickstart-env config: type: cloud networking: type: limited allow_package_managers: trueant apply也會將環境的 ID 記錄在claude-lock.json中。若要用一個指令同時建立代理和環境,請傳入兩個檔案:ant apply coding-assistant.md environment.yaml。啟動工作階段
建立一個參照您的代理和環境的工作階段。
Pythonsession = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, title="Quickstart session", ) print(f"Session ID: {session.id}")傳送訊息並串流回應
開啟串流、傳送使用者事件,然後在事件抵達時進行處理:
Pythonwith client.beta.sessions.events.stream(session.id) as stream: # 在串流開啟後傳送使用者訊息 client.beta.sessions.events.send( session.id, events=[ { "type": "user.message", "content": [ { "type": "text", "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt", }, ], }, ], ) # 處理串流事件 for event in stream: match event.type: case "agent.message": for block in event.content: if block.type == "text": print(block.text, end="") case "agent.tool_use": print(f"\n[Using tool: {event.name}]") case "session.status_idle": print("\n\nAgent finished.") break代理會撰寫一個 Python 指令碼、在沙箱中執行它,並驗證輸出檔案已建立。您的輸出看起來會類似這樣:
I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file. [Using tool: write] [Using tool: bash] The script ran successfully. Let me verify the output file. [Using tool: bash] fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181). Agent finished.
運作原理
當您傳送使用者事件時,Claude Managed Agents 會:
- 佈建沙箱: 您的環境設定決定沙箱的建置方式。
- 執行「agent loop」(代理迴圈): Claude 根據您的訊息決定要使用哪些工具。
- 執行工具: 檔案寫入、bash 指令及其他工具呼叫都在沙箱內執行。
- 串流事件: 代理運作時,您會收到即時更新。
- 進入閒置: 當代理沒有其他工作要做時,會發出
session.status_idle事件。
建置完整的應用程式
以下每個快速入門都將 Claude Managed Agents 與熱門的聊天框架搭配,打造出完整、可執行的應用程式。在每個範例中,框架負責呈現聊天介面,而受管工作階段則在伺服器端執行代理迴圈:工作階段保存對話紀錄、在沙箱中執行工具,並串流前端所呈現的事件。
使用 Vercel 的 Chat SDK 建置的瀏覽器聊天研究分析師。每段對話都是一個持久的工作階段,在串流回覆的同時,即時動態會顯示工具呼叫。只要更換 Chat SDK 轉接器,即可將同一個處理常式移至 Slack、Teams、Discord 或 WhatsApp。
以 assistant-ui 基本元件建置的聊天式試算表分析師。工作階段即為討論串清單,一個 reducer 會將工作階段事件記錄轉換為訊息和工具卡片,且每個 bash 指令在執行前都會呈現內嵌的允許/拒絕關卡。
CopilotKit 聊天中的個人理財助理。適用於 Claude Managed Agents 的 AG-UI 轉接器會將每個聊天討論串對應至一個受管工作階段,並逐個 token 串流回覆,而自訂工具則會在對話中內嵌呈現互動式圖表。
後續步驟
這個頁面有幫助嗎?