建立您的第一個受管代理
如果您曾經手動建立過代理迴圈,您一定熟悉這套流程:while 迴圈、停止原因的切換判斷、工具執行。這樣的做法確實可行,而且對於許多功能來說,這其實是正確的架構。但有時候,這個迴圈需要執行很長一段時間——可能是幾分鐘,甚至是幾個小時——橫跨許多工具,需要保留狀態、寫入檔案,並且在網路短暫中斷後還能恢復工作。到了這個程度,您就不會想在自己的伺服器上執行這個迴圈了。您會想要將它委派出去。這正是受管代理的用途。
什麼是受管代理?
受管代理是一種在 Anthropic 基礎架構上執行的代理迴圈,而不是在您自己的基礎架構上執行。您只需描述一次代理、提供一個執行環境,然後啟動一個工作階段。Anthropic 會執行該迴圈,而您只需要串流接收執行過程中回傳的事件即可。
每個 API 帳戶預設都已啟用受管代理——無需特別申請權限。
四個基本元素
共有四個基本元素,並且有固定的先後順序:
- 代理(Agent)——也就是角色本身:模型、系統提示,以及工具集。這個元素可以在多次執行中重複使用。
- 環境(Environment)——代理執行的場所:雲端或自行託管、網路設定等等。
- 工作階段(Session)——代理在特定環境中的單次執行。工作階段是工作的最小單位。
- 事件(Events)——在系統中進出流動的訊息:代理的動作、工具呼叫、結果,以及回覆。
以下是各個部分如何組合在一起:您的應用程式與工作階段溝通,工作階段在環境中驅動工作的進行,而所有發生的事情都會透過事件串流回傳出來:

請注意這裡的轉變:您不是在執行一個 while 迴圈,而是在發送事件和讀取事件。
最精簡的受管代理
讓我們來建立一個能完成有意義任務的最精簡受管代理:在暫存磁碟中建立一個檔案、計算其行數,並回報結果。
至於工具,我們會使用代理工具集(agent toolset)——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:消費串流
最後,我們要消費這個串流,仍然是在步驟 4 的 with 區塊中進行。對於這個示範而言,有三種重要的事件類型:
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說明原因)。 - 當迴圈執行時間過長、處理量過大,或需要承受中斷後仍能恢復時,請選用受管代理。若您想要完全掌控,則選用手動迴圈。