開始使用自行託管的 Claude Managed Agents

在本快速入門中，您會使用 Docker Compose 在單一機器上啟動自行託管的 Claude Managed Agents。Compose 堆疊包含伺服器、其 PostgreSQL 資料庫，以及一組 worker，這些 worker 會在各自獨立的沙箱容器中執行每個工作階段。接著，您會從終端機與代理對話，並確認其工具呼叫是在沙箱容器中執行的。之後，您可以在您伺服器上的主控台中開啟該工作階段。

在正式環境中，Anthropic 建議使用該版本的兩個 Helm chart。請參閱在 Kubernetes 上部署。

先決條件

• 版本封存檔：若要申請下載的存取權，請聯絡您的 Anthropic 帳戶團隊。
• Claude API 金鑰：伺服器會使用它來進行模型呼叫。請在 Claude Console 中建立一個。
• Docker： 最新版本的 Docker Engine，搭配 Compose 外掛程式（docker compose，而非較舊的 docker-compose）。
• 至少具備兩顆 CPU 的主機：x86-64 或 Arm。在較小的主機上，請在建立 .env 時將 CMA_SANDBOX_CPUS 設為其 CPU 數量。
• 首次啟動時的網路存取：首次建置會從 Docker Hub、Alpine 套件儲存庫以及 GitHub releases 拉取內容。
• 工具：在您執行 Docker 的機器上，您需要 openssl 與 ant CLI。

啟動堆疊

1. 1

   解壓縮封存檔

   解壓縮封存檔，並在其 compose 目錄中作業。在指令中，將 <archive> 替換為您封存檔的名稱，不含 .tar.gz。

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

   如果您的 umask 比 022 更嚴格，二進位檔會失去其他使用者的執行權限，伺服器容器便無法啟動它們。在這種情況下，請將其設為 022，然後重新解壓縮封存檔。

2. 2

   建立 .env 檔案

   Compose 會從 docker-compose.yml 旁的 .env 檔案讀取堆疊的密鑰。建立檔案：

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   請在編輯器中開啟 .env，並將 sk-ant-... 替換為您的 Claude API 金鑰。此區塊會產生其餘內容：資料庫密碼、您的應用程式所傳送的伺服器 API 金鑰，以及用於加密伺服器所儲存之密鑰的金鑰。

3. 3

   啟動容器

   建置並啟動堆疊，然後追蹤伺服器的記錄：

   docker compose up --build -d
   docker compose logs -f cma-server

   

   當記錄中出現含有 msg="cma-server listening" 的一行時，按 Ctrl+C 停止追蹤記錄。

4. 4

   確認伺服器已就緒

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   已就緒的伺服器會回應 "status":"ready"。剛啟動時，在首次檢查執行期間，它可能會有幾秒鐘回應 "status":"degraded"。如果持續為 degraded 或回應 "status":"not_ready"，請參閱疑難排解。

執行您的第一個工作階段

使用 ant CLI 建立一個代理，並從您的終端機與它對話。

1. 1

   將 CLI 指向您的伺服器

   在同一個目錄中開啟第二個終端機，並保留它供 ant 使用。以下指令會將 ANTHROPIC_API_KEY 設為您的伺服器 API 金鑰，而非您的 Claude API 金鑰，如在自行託管的伺服器上呼叫 API 所說明：

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

   

   請在第一個終端機中執行 docker compose 指令。如果您在這個終端機中執行 docker compose up，Compose 會將這些變數傳遞給伺服器，伺服器便會呼叫自己，而不是 Claude API。

2. 2

   建立代理

   將指令後方的檔案儲存為 quickstart-agent.md，然後執行該指令。此檔案為代理提供內建工具，並讓代理無需先詢問您即可執行這些工具。

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   此指令會先印出一則警告，指出它 could not determine the organization and workspace，並附帶 404 錯誤，然後才建立代理。在您自己的伺服器上，這是預期的行為。

3. 3

   啟動工作階段

   這些指令會找到代理與堆疊的環境、啟動工作階段，並將工作階段的 ID 保存在 SESSION_ID 中。堆疊將其環境命名為 compose-sandbox。

   AGENT_ID=$(ant beta:agents list --format raw \
     --transform 'data.#(name=="Quickstart agent").id' --raw-output)
   ENVIRONMENT_ID=$(ant beta:environments list --format raw \
     --transform 'data.#(name=="compose-sandbox").id' --raw-output)
   SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
     --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)

   
4. 4

   要求代理執行指令

   將您的終端機連線到工作階段：

   ant beta:sessions connect "$SESSION_ID"

   

   此指令會開啟工作階段的聊天檢視。傳送此訊息：

   Run `hostname` with the bash tool and tell me the output.

   

   代理會回覆一個以 cma-sandbox- 開頭的主機名稱。那是執行該指令的沙箱容器名稱，這確認了工具是在沙箱中執行，而非在您的機器上。

5. 5

   找到沙箱容器

   保持聊天開啟。在第一個終端機中，列出沙箱容器：

   docker ps --filter label=cma-server.sandbox

   

   清單會顯示代理所回報的容器。容器會在一個回合結束後約一分鐘結束，而工作階段的下一則訊息會啟動一個新容器。如果清單是空的，請要求代理再次執行 hostname，並在它回覆期間再次列出容器。

   若要離開聊天，請在其終端機中按下 Ctrl+C。工作階段會持續執行。

在您的伺服器上試用主控台

本節為選用。主控台需要單一登入。若要試用，請搭配版本中的模擬登入提供者重新啟動堆疊。您機器上的連接埠 8080 必須未被占用。

1. 1

   搭配模擬登入提供者重新啟動堆疊

   在第一個終端機中執行這些指令：

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   export 這一行僅適用於第一個終端機，因此請在您為 docker compose 開啟的任何新終端機中再次執行它。若要變更此堆疊中伺服器的設定，請編輯 compose.config.oidc.yaml，而非 compose.config.yaml，然後執行 docker compose restart cma-server。

2. 2

   開啟工作階段

   在同一台機器上的瀏覽器中開啟 http://127.0.0.1:8400/，按一下 Continue with SSO，然後選取示範管理員 alice。在側邊欄中選取 Sessions，然後選取該工作階段。

   頁面會隨著代理的工作而更新，您也可以從該頁面傳送訊息給代理。

若也要在主控台中建立代理並啟動工作階段，請參閱從主控台執行代理。

停止堆疊

在第一個終端機中，執行此指令：

docker compose down --remove-orphans

此指令會刪除容器並保留資料庫。若也要刪除資料庫，以及其中所有代理、工作階段與工作階段歷程記錄，請執行 docker compose down --remove-orphans -v。

疑難排解

• 您的封存檔沒有 compose 目錄：該封存檔包含較早的版本，本頁的指令與其不符。請向您的 Anthropic 帳戶團隊索取目前的版本。若要將執行中的部署移至目前的版本，請參閱升級自行託管的 Claude Managed Agents。
• 伺服器始終無法啟動：執行 docker compose logs migrate。一次性的 migrate 容器會建立資料庫資料表。它必須以狀態 0 結束，伺服器才會啟動。
• 就緒檢查持續為 degraded，或每個回合都失敗：如果您在 ANTHROPIC_BASE_URL 為 http://127.0.0.1:8400 的終端機中執行了 docker compose up，伺服器會呼叫自己，而不是 Claude API。請在未設定該變數的第一個終端機中再次執行 docker compose up -d。否則，伺服器記錄會顯示失敗的項目。若要閱讀記錄，請再次執行 docker compose logs -f cma-server。
• 就緒檢查回應 not_ready：在回應中，找出狀態為 failed 的檢查：
  • upstream：Claude API 拒絕了您的 Claude API 金鑰。請更正 .env 中的 ANTHROPIC_API_KEY，然後在第一個終端機中再次執行 docker compose up -d。如果您的 shell 也設定了 ANTHROPIC_API_KEY，Compose 會使用 shell 的值，因此請先執行 unset ANTHROPIC_API_KEY。
  • database：資料庫拒絕了伺服器的登入（例如因為密碼錯誤），或是與資料庫的開啟連線中斷。若要查看是哪一種，請再次執行 docker compose logs -f cma-server。
• 代理有回覆，但其工具呼叫始終未完成：沒有 worker 在輪詢該環境。請使用 docker compose logs sandbox 檢查 worker 的記錄。無法連線至 Docker daemon 通訊端的 worker 會結束，並顯示提及 CMA_DOCKER_SOCKET 的訊息。請在 .env 中將該變數設為您 daemon 的通訊端路徑，然後在第一個終端機中再次執行 docker compose up -d。
• worker 正在執行，但工具呼叫仍始終未完成：堆疊會啟動 10 個 worker，每個 worker 一次執行一個工作階段的容器。工作階段在建立時就會占用一個空閒的 worker，而從未收到訊息的工作階段會保留其 worker 最多一小時。當 10 個都被占用時，任何其他工作階段的工具呼叫都會等待 worker。如果「找到沙箱容器」步驟中的 docker ps 指令列出 10 個容器，請封存您未使用的工作階段：
  1. 在第一個終端機中，執行 docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'。它會印出每個容器背後的工作階段 ID。等待中的工作階段還沒有容器，因此不在清單中。
  2. 在第二個終端機中，按 Ctrl+C 離開聊天，並針對每個列出且您未使用的工作階段執行 ant beta:sessions archive --session-id <session-id>。
  3. 再次執行 ant beta:sessions connect "$SESSION_ID"。當有 worker 接手其工作階段時，工具呼叫就會完成。

後續步驟