使用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代理是一个强大的能力，但需要谨慎设计。本文提供了从概念到生产的完整指南，帮助开发者创建可靠且可维护的代理系统。