Claude Agent SDK 與傳統的無狀態 LLM API 不同，它維護對話狀態並在持久環境中執行命令。本指南涵蓋架構、託管考慮因素以及在生產環境中部署基於 SDK 的代理的最佳實踐。

託管要求

基於容器的沙箱

為了安全和隔離，SDK 應在沙箱容器環境中運行。這提供：

• 進程隔離 - 每個會話的獨立執行環境
• 資源限制 - CPU、內存和存儲約束
• 網絡控制 - 限制出站連接
• 臨時文件系統 - 每個會話的清潔狀態

系統要求

每個 SDK 實例需要：

• 運行時依賴項

  • Python 3.10+（適用於 Python SDK）或 Node.js 18+（適用於 TypeScript SDK）
  • Node.js（Claude Code CLI 所需）
  • Claude Code CLI：npm install -g @anthropic-ai/claude-code

• 資源分配

  • 建議：1GiB RAM、5GiB 磁盤和 1 個 CPU（根據您的任務需要進行調整）

• 網絡訪問

  • 出站 HTTPS 到 api.anthropic.com
  • 可選：訪問 MCP 服務器或外部工具

理解 SDK 架構

與無狀態 API 調用不同，Claude Agent SDK 作為長時間運行的進程運行，該進程：

• 在持久 shell 環境中執行命令
• 在工作目錄內管理文件操作
• 處理工具執行，包含來自先前交互的上下文

沙箱提供商選項

多個提供商專門提供用於 AI 代碼執行的安全容器環境：

• Cloudflare Sandboxes
• Modal Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

生產部署模式

模式 1：臨時會話

為每個用戶任務創建一個新容器，完成後銷毀它。

最適合一次性任務，用戶可能在任務完成時仍與 AI 交互，但完成後容器會被銷毀。

示例：

• 錯誤調查和修復：使用相關上下文調試和解決特定問題
• 發票處理：從收據/發票中提取和結構化數據用於會計系統
• 翻譯任務：在語言之間翻譯文檔或內容批次
• 圖像/視頻處理：對媒體文件應用轉換、優化或提取元數據

模式 2：長時間運行的會話

為長時間運行的任務維護持久容器實例。通常在容器內根據需求運行多個 Claude Agent 進程。

最適合主動代理，它們在沒有用戶輸入的情況下採取行動、提供內容的代理或處理大量消息的代理。

示例：

• 電子郵件代理：監控傳入電子郵件並根據內容自主進行分類、回復或採取行動
• 網站構建器：為每個用戶託管自定義網站，具有通過容器端口提供的實時編輯功能
• 高頻聊天機器人：處理來自 Slack 等平台的連續消息流，其中需要快速響應時間

模式 3：混合會話

臨時容器，使用歷史和狀態進行補充，可能來自數據庫或 SDK 的會話恢復功能。

最適合與用戶進行間歇性交互的容器，啟動工作並在工作完成時關閉，但可以繼續。

示例：

• 個人項目經理：幫助管理進行中的項目，進行間歇性檢查，維護任務、決策和進度的上下文
• 深度研究：進行多小時的研究任務，保存發現並在用戶返回時恢復調查
• 客戶支持代理：處理跨越多次交互的支持票證，加載票證歷史和客戶上下文

模式 4：單一容器

在一個全局容器中運行多個 Claude Agent SDK 進程。

最適合必須密切協作的代理。這可能是最不受歡迎的模式，因為您必須防止代理相互覆蓋。

示例：

• 模擬：在模擬中相互交互的代理，例如視頻遊戲。

常見問題

我如何與我的沙箱通信？

在容器中託管時，公開端口以與您的 SDK 實例通信。您的應用程序可以公開 HTTP/WebSocket 端點供外部客戶端使用，而 SDK 在容器內部運行。

託管容器的成本是多少？

我們發現服務代理的主要成本是令牌，容器根據您配置的內容而異，但最低成本大約是每小時運行 5 美分。

何時應該關閉空閒容器與保持它們溫暖？

這可能取決於提供商，不同的沙箱提供商將允許您設置不同的空閒超時標準，之後沙箱可能會關閉。 您需要根據您認為用戶響應可能的頻率來調整此超時。

我應該多久更新一次 Claude Code CLI？

Claude Code CLI 使用 semver 進行版本控制，因此任何破壞性更改都將進行版本控制。

我如何監控容器健康和代理性能？

由於容器只是服務器，您用於後端的相同日誌記錄基礎設施將適用於容器。

代理會話在超時前可以運行多長時間？

代理會話不會超時，但我們建議設置 'maxTurns' 屬性以防止 Claude 陷入循環。

後續步驟

• 會話指南 - 了解會話管理
• 權限 - 配置工具權限
• 成本追蹤 - 監控 API 使用情況
• MCP 集成 - 使用自定義工具進行擴展