建立您的第一個託管代理

什麼是託管代理？

託管代理是一種在 Anthropic 的基礎設施上執行，而非在您自己的基礎設施上執行的代理迴圈。您只需描述一次代理，為它提供一個工作環境，然後啟動一個工作階段。Anthropic 會執行這個迴圈，而您只需在它運作時以串流方式接收事件即可。

每個 API 帳戶預設都已啟用託管代理——不需要任何特殊權限。

四個基本元素

共有四個基本元素，依序如下：

1. 代理（Agent）——角色設定：模型、系統提示和工具集。這可以在多次執行中重複使用。
2. 環境（Environment）——代理執行的位置：雲端或自行託管、網路設定等等。
3. 工作階段（Session）——代理在特定環境中的單次執行。工作階段是工作的基本單位。
4. 事件（Events）——進出的訊息：代理的動作、工具呼叫、結果、回覆。

以下是這些元件如何組合在一起：您的應用程式與工作階段溝通，工作階段在環境中驅動工作，而發生的一切都會透過事件串流回傳出來：



請注意這裡的轉變：您不是在執行 while 迴圈，而是在傳送事件和讀取事件。

最小可行的託管代理

讓我們建立一個能做有用事情的最小託管代理：在暫存磁碟機中建立一個檔案、計算其行數，並回報結果。

在工具方面，我們將使用代理工具集——Anthropic 內建的檔案、bash 和網頁工具。這些工具足以應付這項任務，因此我們不需要自行定義任何工具。

步驟 1：建立代理

首先，我們建立代理。請注意代理工具集就直接定義在 tools 陣列中——那就是內建的工具集：

import anthropic

client = anthropic.Anthropic()

agent = client.beta.agents.create(
    name="Line Counter",
    model="claude-opus-5",
    system="You are a helpful agent that completes small file tasks.",
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
    ],
)

請記住：代理是可重複使用的。只需建立一次，即可在多個工作階段中執行。

步驟 2：建立環境

接下來是環境。它定義了您的代理執行所在的沙箱：雲端，並使用 limited 網路設定。使用 limited 時，沙箱和網頁工具只能連接到您在 allowed_hosts 中列出的主機。這項任務不需要網路，因此我們不列出任何主機。只有當代理必須連接到您無法事先列出的網站時，才使用 unrestricted。每個工作階段都有自己的沙箱，檔案就是寫入到那裡：

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

步驟 3：建立工作階段

接著，我們使用代理和環境建立一個工作階段，並加上一個選用的標題。工作階段是工作的基本單位：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Count lines demo",
)

步驟 4：開啟串流，然後傳送啟動訊息

現在我們開啟事件串流——請注意我們先做這件事。串流只會傳遞在它開啟之後發生的事件，因此請務必在傳送啟動訊息之前先開啟串流。接著，我們將使用者訊息傳送到即時串流中：

with client.beta.sessions.events.stream(session_id=session.id) as stream:
    # 串流已開啟 — 現在傳送啟動訊息
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a file in the temp directory, "
                                "count its lines, and report back.",
                    }
                ],
            }
        ],
    )

請注意這是 events——複數形式。事件是這個 API 中一切流動的方式。

步驟 5：消費串流

最後，我們消費這個串流。對這個示範來說，有三種重要的事件類型：

• agent.message——Claude 的文字
• agent.tool_use——Claude 選擇了哪個工具
• session.status_idle——代理已停止並正在等待輸入

這個示範在第一個閒置事件時停止。在您自己的應用程式中，請在將工作視為完成之前檢查 event.stop_reason.type：end_turn 表示代理已完成其回合，或是您中斷了它；requires_action 則表示有工具呼叫需要您的回應。

    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.tool_use":
            print(f"\n[tool] {event.name}")
        elif event.type == "session.status_idle":
            print("\n--- Agent done ---")
            break

執行它，輸出的內容就是代理大聲推理的過程——實際的文字、它選擇的工具，以及最終的答案。這一切都在 Anthropic 的容器中執行，而不是在您自己的容器中：



取捨

通常使用代理時，我們需要有自己的迴圈，並且必須控制一切。使用託管代理時，您將該迴圈、沙箱和可恢復性都委派出去——只需在事件串流進來時消費它即可。工作階段的事件歷史記錄儲存在伺服器上。因此，如果您的連線中斷，請開啟一個新的串流，列出過去的事件以查看您錯過了什麼，並跳過清單中已經回傳過的任何即時事件。相關程式碼請參閱重新連線而不遺漏事件。

在正式環境的應用程式中，這就是長時間執行、涉及檔案操作、「幫我整理這個」類型任務的典型樣貌。想像一下檔案共享清理的情境：託管代理讀取目標目錄結構規格，走訪雜亂的傳入資料夾，將檔案移動到正確的專案資料夾中，封存重複檔案和零位元組的垃圾檔案，並標記任何它無法確信該如何放置的項目——這一切都在一個工作階段中完成，可以針對數千個檔案執行數分鐘之久。以下是這在實際應用程式中的樣貌——一個檔案共享清理儀表板，即時串流顯示代理在排序、封存和標記檔案時的活動：



回顧

• 託管代理就是代理迴圈，由系統為您執行——在 Anthropic 的基礎設施上執行，而非您自己的伺服器。
• 流程如下：建立代理、建立環境、建立工作階段、傳送事件進去，並以串流方式接收事件。
• 代理（模型、系統提示、工具集）可在多次執行中重複使用；工作階段是單次執行；事件是一切流動的方式。
• 在傳送啟動訊息之前先開啟事件串流——它只會傳遞在開啟之後發生的事件。
• 請留意三種事件：agent.message（文字）、agent.tool_use（工具選擇），以及 session.status_idle（已停止並等待輸入，並透過 stop_reason.type 說明原因）。
• 當迴圈需要執行過長時間、做太多事情，或需要在中斷後存活時，請選擇託管代理。當您想要完全掌控時，請選擇手動迴圈。