Claude Platform Docs
Managed Agents入門步驟

開始使用 Claude Managed Agents

建立您的第一個自主代理。

本指南將逐步引導您建立代理、設定環境、啟動工作階段,以及串流代理回應。

Claude Code

讓 Claude Code 為您設定代理

/claude-api managed-agents-onboard

核心概念

概念說明
Agent(代理)模型、系統提示、工具、MCP 伺服器與技能
Environment(環境)工作階段執行位置的設定:由 Anthropic 管理的雲端沙箱,或在您自己的基礎設施上自行託管的沙箱
Session(工作階段)在環境中執行的代理實例,負責執行特定任務並產生輸出
Events(事件)您的應用程式與代理之間交換的訊息(使用者輪次、工具結果、狀態更新)

開始之前

  1. 建立 Claude Console 帳戶

    註冊 Claude Console 帳戶,或登入您既有的帳戶。

  2. 選擇驗證方式

    對於本機開發,建議使用 CLI 登入。

    CLIAPI 金鑰
  1. 安裝 CLI

    brew install anthropics/tap/ant
  2. 登入

    ant auth login

    登入完成後,SDK 和 CLI 將會自動取得您的憑證。

安裝 SDK

pip install anthropic

建立您的第一個工作階段

  1. 建立代理

    建立一個定義模型、系統提示和可用工具的代理。

    ant apply coding-assistant.md
    coding-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 指令碼)不會用到網頁。請只為代理提供它所需的工具。如需完整清單及各工具的設定選項,請參閱工具。

  2. 建立環境

    環境定義了代理執行所在的「sandbox」(沙箱)。此環境使用 limited 網路並允許套件管理器,因此在沙箱中執行的程式碼可以連線到公開的套件登錄庫和程式碼託管服務。使用 limited 網路時,allowed_hosts 清單也同樣適用於網頁搜尋和網頁擷取,儘管它們在沙箱外執行。如果未列出任何主機(此環境正是如此),這些工具不會傳回任何頁面或搜尋結果。如果您自己的代理使用這些工具,請將它所需的主機新增至該清單。

    ant apply environment.yaml
    environment.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: true

    ant apply 也會將環境的 ID 記錄在 claude-lock.json 中。若要用一個指令同時建立代理和環境,請傳入兩個檔案:ant apply coding-assistant.md environment.yaml。

  3. 啟動工作階段

    建立一個參照您的代理和環境的工作階段。

    session = client.beta.sessions.create(
        agent=agent.id,
        environment_id=environment.id,
        title="Quickstart session",
    )
    
    print(f"Session ID: {session.id}")
  4. 傳送訊息並串流回應

    開啟串流、傳送使用者事件,然後在事件抵達時進行處理:

    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": "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 會:

  1. 佈建沙箱: 您的環境設定決定沙箱的建置方式。
  2. 執行「agent loop」(代理迴圈): Claude 根據您的訊息決定要使用哪些工具。
  3. 執行工具: 檔案寫入、bash 指令及其他工具呼叫都在沙箱內執行。
  4. 串流事件: 代理運作時,您會收到即時更新。
  5. 進入閒置: 當代理沒有其他工作要做時,會發出 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 串流回覆,而自訂工具則會在對話中內嵌呈現互動式圖表。

後續步驟

建立可重複使用、具版本控制的代理設定

自訂網路和沙箱設定

為您的代理啟用特定工具

處理事件並在代理執行時引導它

依週期性 cron 排程執行您的代理

將文件語料庫一次性提煉成知識 wiki,再以極低的成本從中回答重複的問題

這個頁面有幫助嗎?