技術指南
Claude Agent SDK：功能介紹及評估方法
Claude Agent SDK 是一個開發者介面，用於建立允許 Claude 運行有界、使用工具的工作流程的應用程式。該 SDK 可以管理會話、呼叫工具和協調工作，但它並不能取代應用程式權限、原始碼控制、評估或手動批准。請將其視為代理運行時組件，而非完整的生產系統。
對於需要在不擁有代理程式執行環境的情況下完成基於原始程式碼的工作的團隊，Ottermind 提供了一種託管工作區路徑：在人員審核結果的同時，保持文件、研究背景、決策和交付成果之間的關聯。 SDK 和託管工作區分別解決了不同的操作問題。
研究與揭露: 本指南是根據 2026 年 9 月 3 日修訂的 Claude Agent SDK 儲存庫、Anthropic 工具使用文檔 和 AWS AgentCore Claude Agent SDK 文檔。 API 和限制正在不斷變化；請在實作前驗證目前版本。
核心建構模組
| 建構模組 | 職責 | 應用程式控制 |
|---|---|---|
| 會話 | 維護運作及其會話狀態 | 過期、隔離和審計記錄 |
| 模型 | 解釋上下文並提出步驟 | 模型版本、預算和輸出合約 |
| 工具 | 執行有界操作 | 模式、超時、權限和冪等性 |
| 子代理 | 處理一個完全獨立的角色 | 範圍、預算和升級規則 |
| 權限模式 | 控制代理可以存取或變更的內容 | 允許清單和人工確認 |
| 結果 | 傳回文字、結構化資料或工件 | 驗證和審閱者交接 |
從可逆任務開始
建立一個讀取密集型工作流程原型，例如將已核准的儲存庫檔案轉換為變更簡報。記錄輸入集、提示、模型版本、工具呼叫、輸出、審閱者更正和最終決定。僅在追蹤資訊清晰可辨且故障可恢復後才新增寫入權限。
最小任務契約
目標：產生基於原始碼的實作簡報。
允許的原始程式碼：僅限附件中的儲存庫檔案。
允許使用的工具：列出檔案和讀取檔案；禁止寫入或網路呼叫。
產出：調查結果、建議的變更、證據、風險和未解決的問題。
停止條件：缺少必需的原始碼或權限不明確。會話和子代理
當工作流程需要在多個步驟之間保持連續性時，請使用會話。僅當角色、工具或評估標準確實不同時才使用子代理程式。代理越多，協調性越差，延遲越高，故障的可能性也越大。傳遞每個角色所需的最小上下文，並傳回包含狀態和證據的結構化結果。
實用架構
將 SDK 置於應用程式邊界之後，並承擔以下五項職責：
- 請求處理程序： 驗證使用者身份，選擇允許的項目，並設定預算。
- 上下文載入器： 僅檢索允許的文件，並記錄其識別碼和日期。
- 代理程式運行器： 啟動會話，提供工具，並持久化每個工具請求和結果。
- 策略層： 驗證參數，阻止不允許的操作，並要求確認。
- 結果適配器： 驗證傳回的形狀，並將草稿交給審核員或下一個系統。
這種分離至關重要，因為 SDK 可以幫助模型請求工具，但您的應用程式決定是否允許該請求。請勿將授權邏輯放在提示中，也不要假設模型會自行維護租用戶邊界。
會話、恢復和故障
為每次運行指定一個明確識別碼和一個終止狀態，例如 completed、needs_review、blocked 或 failed。持久化模型和 SDK 版本、提示修訂、輸入來源、工具呼叫和審核員的決定。如果在寫入後發生網路錯誤，請使用冪等鍵並在重試之前查詢記錄系統。如果會話在手動編輯後恢復，請包含已編輯的文件及其更改原因，而不是重播一段晦澀難懂的對話。
工具設計範例
建議使用類似 create_draft_task(title, owner, due_date) 的函數，而不是通用 shell 工具。功能更強大的函數可以強制執行日期格式、允許的所有者、專案範圍以及僅限草稿狀態。文件搜尋工具應傳回檔案識別碼和摘要，而不是靜默地暴露整個磁碟機。瀏覽器工具應使用允許列表，並在身份驗證或付款之前停止存取。
成本和延遲
運行開始前設定預算：最大模型迭代次數、工具呼叫次數、令牌數、運行時間和子代理數。在品質允許的情況下，將提取過程路由到較小的模型，並將複雜的推理留給模糊的步驟。記錄實際使用情況以及結果，以確保成功的簡報不會掩蓋低效率的工作流程。耗時較長的任務應該是非同步的、可取消的，並且對使用者可見。
SDK 與託管工作區
如果您的團隊需要特定於應用程式的工具、部署控製或自訂運行時，並且能夠負責安全性、可觀測性和維護，則可以使用 SDK 進行建置。如果主要需求是連接文件、研究、決策和交付成果以供人工審核，則託管工作區是更好的起點。選擇的關鍵在於營運責任，而不是哪個標籤聽起來比較自主。
例：研究到簡報代理
想像一下，一個團隊需要每週一份競爭對手簡報。請求處理程序會檢查分析師的身份，並選擇已核准的項目。上下文載入器會檢索來源清單並記錄檢索日期。代理會話只能呼叫 search_approved_sources 和 draft_brief。策略層會拒絕任意 URL、外部貼文或項目外部文件的請求。結果適配器要求在將草稿提交給審閱者之前，包含發現、引用、不確定性和未決問題等部分。
有用的工件不僅僅是最終的文字。它還包括追蹤記錄：哪些來源可用、呼叫了哪些工具、哪些操作被阻止、審查者做了哪些更改，以及簡報是否被接受。當模型或 SDK 發生變更時，此追蹤記錄支援調試、成本分析和可重複的評估集。
版本控制和升級
在每個環境中鎖定 SDK 和模型版本。請閱讀發行說明，以了解權限模式、工具架構、會話行為和支援的模型方面的變更。升級前執行回歸測試案例，包括確認已停用工具仍停用的測試。保留回滾版本，避免在沒有遷移計畫的情況下，在長時間運行的工作流程中途進行升級。
生產環境準備清單
- 身份驗證和租戶檢查在上下文檢索之前進行。
- 每個工具都具有嚴格的模式、超時時間和授權檢查。
- 會話具有預算、取消、過期和終止狀態。
- 輸出在到達記錄系統之前會進行驗證。
- 敏感操作需要明確的人工批准。
- 日誌包含足夠的溯源訊息，可以在不儲存密鑰的情況下重現故障。
- 評估案例涵蓋品質、安全性、成本和延遲。
權限和安全邊界。
驗證應用程式程式碼中的工具參數。將憑證資訊保留在提示框之外，限製檔案系統和網路存取權限，設定逾時時間，並要求對傳送、刪除、購買或變更存取權限進行確認。記錄每次重要的工具調用，包括操作者的身分和批准決定。
評估工作流程，而非簡報。
建立包含正常、不完整、矛盾、對抗性和權限敏感案例的測試集。衡量正確完成率、安全升級、工具錯誤、延遲、成本和審查者更正。每次評估運行都應固定模型和 SDK 版本。
常見問題解答
Claude Agent SDK 與 Claude API 工具的使用方式相同嗎？
否。工具的使用是一種模型互動模式。 SDK 為代理會話和工作流程提供了更多應用程式級建置模組，而您的應用程式仍然擁有策略、儲存、權限和評估的所有權。
我需要多個代理商嗎？
通常一開始不需要。一個配備功能精簡的工具和明確檢查點的代理程式更容易測試和操作。
SDK 可以安全地編輯檔案或執行命令嗎？
它可以連接到此類工具，但安全性取決於您的沙箱、允許清單、驗證、審查和回滾設計。切勿將產生的命令視為預先批准的命令。
