在自行託管的伺服器上呼叫 API

自行託管的 Claude Managed Agents 伺服器具有與 Anthropic 託管的 Managed Agents 服務相同的 API。您的程式碼可以使用官方 SDK、cURL 或 ant CLI 來呼叫它。有兩件事會改變：「base URL」（基礎 URL）是您伺服器的位址，而 API 金鑰是您的伺服器 API 金鑰，而不是 Claude API 金鑰。

若要在瀏覽器中建立代理並執行工作階段，請參閱使用您伺服器上的主控台。

先決條件

• 執行中的伺服器： 請依照開始使用自行託管的 Claude Managed Agents或在 Kubernetes 上部署啟動一個伺服器。
• 伺服器的存取權： 如果伺服器由其他人執行，請向他們詢問其位址及驗證方式。如果他們使用單一登入，請參閱讓開發人員從終端機登入。
• ant CLI： 請依照 CLI 快速入門所示，安裝最新版本。

將您的用戶端指向您的伺服器

SDK 與 ant CLI 會從 ANTHROPIC_BASE_URL 讀取伺服器位址，並從 ANTHROPIC_API_KEY 讀取 API 金鑰。請在您為此伺服器保留的終端機中設定這兩個變數。

對於快速入門堆疊，請從存放您 .env 檔案的目錄執行以下指令：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

在 Kubernetes 上，請依照執行工作階段所示設定這兩個變數，並讓其 port-forward 保持執行。

在該終端機中，每個 ant 指令（例如 ant beta:agents list）都會連線到您的伺服器。請勿在該終端機中執行 Claude Code 或 docker compose，因為它們會讀取相同的變數。

啟動工作階段

工作階段需要一個代理的 ID 和一個環境的 ID：

• 代理： 依照建立代理所示建立一個代理，並將您的用戶端指向您的伺服器。如果您傳送原始 HTTP 請求，請將 URL 中的 https://api.anthropic.com 替換為 $ANTHROPIC_BASE_URL。
• 環境： 快速入門堆疊會建立一個名為 compose-sandbox 的環境，而 Helm chart 會建立一個名為 default 的環境。ant beta:environments list 會印出每個環境的名稱和 ID。對於您自己的 worker，則是管理 CLI 在執行您自己的 worker中印出的 ID。

將您的兩個 ID 放入您的 shell，取代這些範例 ID：

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

以下範例會建立一個工作階段，並在同一個請求中傳送其第一則訊息：

import os

from anthropic import Anthropic

client = Anthropic()

session = client.beta.sessions.create(
    agent=os.environ["AGENT_ID"],
    environment_id=os.environ["ENVIRONMENT_ID"],
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
print(session.id)

回應中包含工作階段的 ID，其開頭為 sesn_。代理會立即開始工作。其內建工具（例如 bash）會在服務該環境的 worker 上執行。

若要觀看工作階段，請在瀏覽器中開啟您伺服器上的主控台，選取 Sessions，然後選取該工作階段。如本頁面所示使用伺服器 API 金鑰啟動的工作階段，只有管理員才能看到。

若要改為在終端機中追蹤工作階段，請將其 ID 傳遞給 ant beta:sessions connect：

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

關於工作階段還能做的其他事情（例如固定代理版本），請參閱啟動工作階段。

傳送訊息並讀取回覆

將您工作階段的 ID 放入您的 shell，取代此範例 ID：

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

請等到工作階段閒置後再執行下一個範例。此範例會在回合結束時停止讀取。如果較早的回合仍在執行中，其結束可能會使範例在您訊息的回覆抵達之前就停止。主控台和 ant beta:sessions connect 都會顯示工作階段的狀態。

以下範例會傳送訊息並印出代理的回覆。範例會先開啟工作階段的事件串流，因為串流只會傳遞其開啟之後發生的事件：

import os

from anthropic import Anthropic

client = Anthropic()
session_id = os.environ["SESSION_ID"]

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": "Summarize what you did in one sentence."}
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
            case "session.status_idle":
                if event.stop_reason.type != "requires_action":
                    break
            case "session.status_terminated":
                break

除了印出 agent.message 文字之外，迴圈還會處理三種事件：

• session.status_idle： 迴圈結束，除非該事件的 stop_reason.type 是 requires_action。
• session.status_terminated： 迴圈結束。
• session.error： 迴圈會印出該錯誤的訊息並繼續讀取，因為伺服器可以重試失敗的模型呼叫並完成該回合。

requires_action 表示工作階段已為了工具呼叫而暫停。結束暫停的方式取決於該呼叫：

• 自訂工具呼叫，或確認工具呼叫的請求： 只有您的程式碼能回應它。如果您的代理使用其中任一種，請參閱回應使工作階段暫停的工具呼叫。
• 對由 worker 執行的工具（例如 bash）的呼叫： 此呼叫通常不會暫停工作階段。如果約 3 分鐘內沒有任何 worker 接手該呼叫，工作階段就會暫停，直到 worker 傳回結果為止。此時您的程式碼無需回應任何內容。請保持串流開啟，當 worker 執行該呼叫時，回合就會繼續。

關於工作階段傳送的其他事件，以及如何在不遺漏任何事件的情況下重新連線，請參閱工作階段事件串流。

在工作階段中移入與移出資料

資料透過 worker 的工作目錄進入和離開工作階段。

在快速入門堆疊上，每個工作階段的容器都會以空的 /workspace 目錄啟動，但工作階段儲存庫的複製除外。預設情況下，在一個回合結束約一分鐘後，容器就會結束，而 Docker 會將它連同該目錄一起刪除。工作階段必須保留的任何內容，都必須在此之前透過工具呼叫（例如上傳或 git push）移出。

容器也會在啟動約一小時後結束，即使正處於回合中途也是如此。沒有任何設定可以改變這一點。回合會在新的容器中繼續，通常在一到兩分鐘之後，而您的用戶端不會收到任何關於此切換的事件。此切換有兩項代價：

• 指令： 在舊容器中執行的所有內容都會停止。新容器會從頭再次執行被中斷的工具呼叫，但代理留在背景執行的指令不會被任何機制重新啟動。
• 檔案： 新容器的 /workspace 會再次變為空的，但工作階段儲存庫的全新複製除外。

在較長的回合中，請讓代理隨著工作進行上傳或推送其成果，並避免使用執行兩次會造成損害的指令。

在 Kubernetes 上，一個工作階段最多保留同一個 pod 約一小時，而回合會以相同的方式繼續。有兩點不同：新的 pod 會在 /workspace 中找到工作階段的檔案，而且它會在舊 pod 停止約 6 分鐘後啟動。

對於您自行啟動的 worker，請在傳送需要輸入檔案的訊息之前將這些檔案放在工作目錄中。之後再從該目錄讀取輸出檔案。

當您自行為每個工作階段啟動容器時，請將存放該工作階段輸入檔案的目錄掛載為容器的工作目錄。在容器結束後，從該目錄收集輸出檔案。請參閱為工作階段準備檔案。

在託管服務指南中尋找更多範例

託管服務的指南說明了 API 的核心概念，並提供每項功能的範例。當您在已設定 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 的終端機中執行這些指南中的 SDK 和 CLI 範例時，這些範例會呼叫您的伺服器。這些指南中的 cURL 範例指定的是 https://api.anthropic.com，因此在執行之前，請將該位址替換為 $ANTHROPIC_BASE_URL。

對於某些功能，您的伺服器需要先進行設定，或範例需要修改：

與託管服務的差異列出了完整清單。在移轉現有應用程式之前，請先查看該清單。

執行您自己的 worker

快速入門堆疊會建立一個環境並執行其 worker。在 Kubernetes 上部署中的 Helm chart 也是如此。如果您只需要這些 worker，請略過本節。

您執行 worker 的方式與自行託管的沙箱相同：使用相同的 ant beta:worker 指令和 SDK worker，並採用部署自行託管的 worker 所示的方式。例外是由 webhook 觸發的 worker，因為您的伺服器不會傳送任何 webhook。

建立環境及其金鑰

請使用管理 CLI 建立一個環境和一個環境金鑰，而不是在 Claude Console 中建立。此 CLI cma-server-admin 位於版本封存檔的頂層，因此請從該處執行指令。對於 -base-url，請傳遞您的 worker 連線到伺服器的位址：

• 位於執行快速入門堆疊之機器上的 worker： http://127.0.0.1:8400
• 位於其他機器上的 worker： 您放在伺服器前方的 TLS 代理伺服器的 https 位址

管理 CLI 會在相同的位址呼叫伺服器，因此請在可連線到該位址的機器上執行它。

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin bootstrap \
  -base-url http://127.0.0.1:8400 -name my-env -key-file -

此指令會印出 worker 的設定、啟動 worker 的指令，以及金鑰的 ID 和到期時間：

export ANTHROPIC_BASE_URL='http://127.0.0.1:8400'
export ANTHROPIC_ENVIRONMENT_ID='env_...'
export ANTHROPIC_ENVIRONMENT_KEY='sk-ant-oat01-...'
# then: histchars= HISTFILE=/dev/null ant beta:worker poll --workdir /workspace
# key id: 'etok_...'  expires: '...'

此指令只會顯示金鑰一次，因此請將金鑰、其 ID 和到期時間儲存在您的密鑰管理器中。金鑰會在 365 天後失效。在此之前，請依照為您自己的 worker 更換環境金鑰進行操作。

請勿將伺服器 API 金鑰放在執行 worker 的機器上。請在不含任何需要保護之內容的容器或 VM 中執行 worker。關於您的其他安全職責，請參閱您的安全責任。

執行本機實驗

請在您啟動 worker 的 shell 中執行這三行 export。然後使用以下指令啟動 worker，而不是使用印出的那個指令。第一個指令會建立 worker 的工作目錄，因為 worker 不會建立它：

mkdir -p "$HOME/cma-workspace" "$HOME/.config/cma"
cat > "$HOME/.config/cma/worker.inputrc" <<'EOF'
$include /etc/inputrc
set disable-completion on
EOF
histchars= HISTFILE=/dev/null INPUTRC="$HOME/.config/cma/worker.inputrc" \
  ant beta:worker poll --workdir "$HOME/cma-workspace"

histchars、INPUTRC 和 HISTFILE 會設定 worker 的 bash 工具背後的 shell，使其依照代理撰寫的方式執行每個指令：

• histchars=： shell 不會將 ! 視為對其指令歷史記錄的參照。
• INPUTRC： 該檔案會關閉補全功能，否則補全會吃掉指令中的每個 tab 字元。請將該檔案放在工作目錄之外，因為代理的檔案工具可能會在工作目錄中改寫它。
• HISTFILE=/dev/null： shell 既不會讀取也不會寫入歷史記錄檔。

請勿將此 worker 用於其他任何用途。它持有環境金鑰，並在單一程序中執行每個工作階段的工具。它也不會複製工作階段的儲存庫。工作階段會在沒有儲存庫的情況下執行，而您的用戶端不會收到任何錯誤。

在正式環境中執行 worker

若是本機實驗以外的任何情況，請依照為每個工作階段執行一個沙箱所示，為每個工作階段啟動一個容器，並在其中執行 ant beta:worker run。請為其映像檔提供建置您自己的沙箱映像檔中列出的內容，並在該設定中變更三項內容：

• 環境金鑰： 請勿將 ANTHROPIC_ENVIRONMENT_KEY 傳入工作階段的容器。伺服器會針對該環境中的每個工作階段接受該金鑰，而容器只需要存取單一工作階段。
• 工作項目的密鑰： 請改為傳遞此密鑰以取代金鑰，因為伺服器只會針對該單一工作階段接受它。轉送工作項目的密鑰說明了您的程式碼接收它的位置。在該節設定 ANTHROPIC_WORK_SECRET 之處，請將密鑰放在只有容器使用者能讀取的檔案中。例如，將密鑰透過管線傳送至容器的標準輸入，並讓容器在啟動 worker 之前寫入該檔案。然後將 ANTHROPIC_WORK_SECRET_FILE 設定為該檔案的路徑。
• 伺服器位址： 將 ANTHROPIC_BASE_URL 設定為容器可連線的位址。http://127.0.0.1:8400 不是這樣的位址。

對於 SDK worker，還有兩點適用：

• 版本： 請依照 SDK、CLI 與函式庫中的說明，使用最新版本的 SDK 建置 worker。該版本的 worker 會在執行需要核准的工具呼叫之前等待核准，且絕不會執行遭政策拒絕的呼叫。以較舊版本建置的 worker 會在每個工具呼叫抵達時立即執行它。
• 範例： 在沙箱內執行 SDK worker 中的範例會讀取環境金鑰，因此無法直接在此使用。

建置您自己的沙箱映像檔

您自己的映像檔需要以下套件和設定：

• 套件： Git 2.38 或更新版本、curl、jq 和 ripgrep（worker 的 grep 工具會使用它進行搜尋）。

• Shell 設定： 如同本機實驗中的 histchars、HISTFILE 和 INPUTRC，以及 TERMINFO。請在 Dockerfile 中任何 USER 行之前加入以下幾行：

  ENV histchars=
  RUN printf '\nset disable-completion on\n' >> /etc/inputrc
  ENV INPUTRC=/etc/inputrc TERMINFO=/etc/terminfo HISTFILE=/dev/null
  RUN test -r /etc/terminfo/d/dumb

  

  TERMINFO 必須指定存放 d/dumb（worker 的 bash 所讀取的終端機描述）的目錄。在已安裝 bash 的 Alpine 上，該目錄是 /etc/terminfo，如上所示。在其他基礎映像檔（例如 Debian 或 Ubuntu）上，則是 /lib/terminfo 或 /usr/share/terminfo，以存放 d/dumb 者為準。請將該目錄寫入 TERMINFO 設定和 RUN test 行中；如果缺少該檔案，該行會使建置停止。

映像檔還需要封存檔中的兩個指令碼，它們會在 worker 啟動之前執行：

1. 將 image-build/with-repositories.sh 複製到 /usr/local/bin/cma-with-repositories。它會複製單一工作階段的儲存庫。
2. 將 image-build/with-egress.sh 複製到 /usr/local/bin/cma-with-egress。如果您的伺服器執行「egress gateway」（輸出閘道），它會將工作階段的工具指向該閘道。
3. 將這兩個檔案設為可執行。
4. 將兩者放在 worker 指令的前面，例如 cma-with-egress cma-with-repositories ant beta:worker run ...。如果您的映像檔執行封存檔中的 kubernetes/sandbox/worker.sh，請略過此步驟，因為該指令碼會以這種方式啟動 worker。

未透過 cma-with-repositories 啟動的 worker 會在沒有儲存庫的情況下執行工作階段。您的用戶端不會收到任何錯誤。

從託管服務移轉 worker

如果您已經為 Anthropic 的託管服務執行 worker，相同的 worker 也可以改為服務您的伺服器。請執行以下三件事：

• 將管理 CLI 印出的三個 export 值提供給輪詢工作的程序。
• 依照本機實驗中的方式設定 histchars、HISTFILE 和 INPUTRC 來啟動該程序。
• 進行在正式環境中執行 worker中所述的變更，並依照建置您自己的沙箱映像檔檢查每個工作階段的映像檔。

後續步驟

• 讓開發人員從終端機登入：設定單一登入，讓開發人員能在沒有 ANTHROPIC_API_KEY 的終端機中以自己的身分使用 ant CLI。
• 代理身分與憑證：讓外部系統信任您的代理，並將 vault 憑證保存在您的密鑰管理器中。
• 推論供應商：將模型呼叫傳送至雲端供應商或您自己的模型閘道。