面向 Ruby on Rails 的生产级 LLM Agent 引擎，提供声明式 DSL、多模态编排、自动重试与熔断、多租户成本管控及实时监控 Dashboard。
RubyLLM::Agents 是一个 Rails Engine，旨在让开发者在 Rails 生态中以声明式 DSL 快速构建可投入生产的 LLM Agent。它基于上游 RubyLLM gem 抽象多 LLM 提供商（OpenAI、Anthropic、Google、ElevenLabs），覆盖文本对话、Embeddings、图像生成与分析、语音合成与转录等多模态场景。
Agent 定义支持两种范式：模板化 Agent（.call 结构化输入/输出，通过 returns 块声明 schema 自动解析 JSON）和对话式 Agent（.ask 自由文本，支持流式响应）。通过 RubyLLM::Agents::Routing mixin 可实现声明式消息路由与分类。Agent 还支持组合模式——一个 Agent 可作为另一个 Agent 的工具，自动维护层级追踪。
在生产可靠性方面，on_failure 块统一配置自动重试（指数退避）、模型回退、熔断器（阈值/时间窗口/冷却期）和超时控制。成本治理层面提供每日/月度支出限额（hard/soft）、7 源价格级联与缓存，支持按 agent、model、tenant、时间维度追踪。多租户场景下实现 per-tenant API keys、预算、熔断器与执行隔离。
可观测性通过 11 个 ActiveSupport::Notifications 仪器化事件实现，挂载 Engine 后获得 Turbo 驱动的实时 Dashboard UI。Queryable Agents 能力允许从 Agent 类直接查询历史执行记录，包含统计、重放和成本明细。内置 Eval Suite 支持 exact match、contains、LLM judge 和自定义 scorer，配合 RSpec 集成与 dry_run 模式进行测试。异步执行支持 Ruby Fiber 并发与 Active Job 后台任务，告警支持 Slack、Webhook 及自定义通知。全局或 per-agent 中间件支持位置控制，cache_for DSL 配置缓存策略。
安装仅需添加 gem、运行生成器与迁移，通过 rails ruby_llm_agents:doctor 诊断环境，rails generate ruby_llm_agents:agent 脚手架快速生成自定义 Agent，挂载路由即可启用 Dashboard。
待确认事项：
- RubyLLM 上游版本要求：README 标注
>= 1.12.0，Gemspec 实际要求>= 1.14.1，可能存在文档未同步 - Dashboard 认证方式未在 README 中详述，生产环境安全方案待确认
- 完整 LLM 提供商列表需参考 RubyLLM 上游文档
- 数据库支持范围（MySQL/PostgreSQL/SQLite 等）未明确标注
- Ruby 3.3/3.4 及 Rails 8 兼容性待确认