使用Anthropic SDK在Ruby中構建AI代理

本文詳細介紹瞭如何在Ruby應用中使用Anthropic SDK構建AI代理。AI代理的核心是一個循環系統：語言模型接收目標，決定是否調用工具，執行工具並反饋結果，如此反覆直到任務完成。這與工作流不同，後者是通過預定義代碼路徑編排LLM和工具，而代理則是讓LLM動態控制自身過程和工具使用。Anthropic官方建議尋找最簡單的解決方案，僅在必要時增加複雜性。對於許多功能，一個帶有良好上下文的單一模型調用比自主代理更便宜、更快速且更易調試。

最小代理循環

首先安裝anthropic gem，並創建客户端實例。一個簡單的循環代碼如下：

message = ANTHROPIC.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "一句話總結第一季度。" }]
)

要使其成為代理，需要添加循環和工具。手動編寫循環僅需十幾行代碼：檢查模型是否請求使用工具，執行工具，將結果追加到對話中，重複直到模型不再請求工具。SDK提供了tool_runner方法，可以自動化這一過程。

工具設計

工具是代理的核心，每個工具應繼承Anthropic::Tool並定義name、description和input_schema。call方法接收輸入並返回結果字符串。工具的描述和參數設計至關重要，因為模型依賴這些信息來決定何時調用。最佳實踐包括：為所有參數提供示例值、使用枚舉限制可選值、提供清晰詳細的描述。

流式傳輸

流式傳輸允許逐塊返回模型輸出，提升用户體驗。使用stream參數並傳遞一個塊，每個塊會即時廣播。在Rails應用中，可以與Turbo Streams或ActionCable配合，實現實時內容更新，無需控制器往返。

後台運行與生產注意事項

代理循環可能耗時較長，應放入後台作業（如Sidekiq）中執行，並通過WebSocket或輪詢將結果流式返回給用户。安全方面，需限制工具權限（如只讀）、防範提示注入（通過結構化輸出）和越獄攻擊（在系統提示中明確禁止不當行為）。錯誤處理應區分HTTP錯誤（如速率限制、網絡故障）和代理邏輯錯誤（如工具調用失敗、循環未收斂），並設置最大迭代次數以防止無限循環。

可觀測性

記錄每次工具調用的名稱、參數、用户和耗時，以及每次模型調用的令牌使用情況。這些日誌可用於調試、審計和成本歸因。對於高流量場景，建議使用TimescaleDB存儲時間序列數據以便高效查詢。

測試

測試應分為兩層：單獨測試工具的邏輯和授權，使用WebMock或VCR模擬API響應測試代理循環。工具測試是最關鍵的，需驗證沒有工具能夠返回其他租户的數據。對於循環測試，可以存根HTTP請求，確保工具執行結果被正確反饋。

總之，在Ruby中構建AI代理是一個強大的能力，但需要謹慎設計。本文提供了從概念到生產的完整指南，幫助開發者創建可靠且可維護的代理系統。