使用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代理是一個強大的能力，但需要謹慎設計。本文提供了從概念到生產的完整指南，幫助開發者建立可靠且可維護的代理系統。