AI Agents

一个由 Chatwoot 维护的不绑定特定厂商的 Ruby SDK，用于构建具备无缝转接、工具调用和共享上下文的多 Agent AI 工作流。

项目概述#

AI Agents 旨在填补 Ruby 生态在多智能体编排领域的空白，解决在复杂业务流程中多个 AI 角色协同工作的难题。其能力边界专注于 Agent 的生命周期管理、互相转接与状态共享，不涉及底层大模型的训练或微调。通过依赖 ruby_llm，实现了对 OpenAI、Anthropic、Gemini 等主流 LLM 厂商的透明适配。

核心能力#

多 Agent 编排：创建并管理多个具有不同角色的专业化 AI Agent
无缝转接：Agent 之间透明转接，用户无感知，支持 Hub-and-spoke 等拓扑模式
工具集成：Agent 可调用自定义工具/函数与外部系统交互
结构化输出：JSON Schema 验证的响应，确保数据提取可靠性
共享上下文：跨 Agent 交互的共享会话状态，支持序列化持久化（可存入关系型数据库）
多模型适配：一套代码适配 OpenAI、Anthropic、Gemini 等多家提供商
线程安全架构：AgentRunner 线程安全，可在多线程 Web 环境中复用
回调机制：实时监听 Agent 思考、工具执行和转接事件
可观测性：内置 OpenTelemetry Instrumentation，兼容 Langfuse 等后端

架构要点#

组件	说明
Agent	不可变、线程安全的 AI 助手，封装指令、工具和转接关系
AgentRunner	线程安全的执行管理器，协调多 Agent 对话流转，支持跨线程复用
Runner	内部编排器，处理单轮对话执行循环
Tool	自定义函数基类（`Agents::Tool`），提供 DSL 声明参数，实现 `perform` 方法执行
Handoffs	基于对话上下文驱动的自动转接机制，支持单向分发与双向回传
Context & State	跨 Agent 共享的会话状态管理器，转接时自动携带，支持完整序列化
底层调用	统一依赖 `ruby_llm ~> 1.14` gem 作为 LLM 抽象层

环境要求与安装#

Ruby >= 3.2.0
核心依赖：ruby_llm ~> 1.14

# Gemfile
gem 'ai-agents'
# bundle install
# 或 gem install ai-agents

快速上手#

require 'agents'

Agents.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end

agent = Agents::Agent.new(
  name: "Weather Assistant",
  instructions: "Help users get weather information",
  tools: [WeatherTool.new]
)

runner = Agents::Runner.with_agents(agent)
result = runner.run("What's the weather like today?")
puts result.output

全局配置#

Agents.configure do |config|
  config.openai_api_key    = ENV['OPENAI_API_KEY']
  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
  config.gemini_api_key    = ENV['GEMINI_API_KEY']
  config.default_provider  = :openai
  config.default_model     = 'gpt-4o'
  config.request_timeout   = 120
  config.max_turns         = 10
  config.debug             = true
end

自定义工具定义#

class EmailTool < Agents::Tool
  description "Send emails to customers"
  param :to, type: "string", desc: "Email address"
  param :subject, type: "string", desc: "Email subject"
  param :body, type: "string", desc: "Email body"

  def perform(tool_context, to:, subject:, body:)
    "Email sent to #{to}"
  end
end

转接模式#

triage.register_handoffs(sales, support)  # Hub-and-spoke
sales.register_handoffs(triage)           # 可回传

可观测性集成#

require 'agents/instrumentation'
tracer = OpenTelemetry.tracer_provider.tracer('my-app')
runner = Agents::Runner.with_agents(triage, billing, support)
Agents::Instrumentation.install(runner, tracer: tracer)

典型应用场景#

客户服务智能路由：前台 Agent 自动将用户问题路由到销售、技术支持等专业化 Agent
ISP 故障排查：仓库示例 examples/isp-support/interactive.rb 展示完整多 Agent 工作流
CRM 集成：通过自定义 Tool 调用外部 API、数据库进行客户信息查询与线索创建
Rails / Web 应用集成：Context 可序列化为 JSON 存入数据库，实现会话管理

工程规范#

代码库包含 sig/ruby（RBS 类型签名）与 spec（RSpec 测试），保障类型安全与代码质量。采用 MIT 开源协议，由 Chatwoot 组织直接维护。

待确认信息#

具体版本号需查看 lib/agents/version.rb
未确认是否已发布到 rubygems.org
仓库包含 .claude/commands 和 CLAUDE.md，Claude Code 集成详情未在 README 中说明
ruby_llm 具体来源仓库待确认（可能与 cruise-automation/ruby_llm 相关或为 Chatwoot fork）