LLMS.txt

# ruby_llm-agents

> A production-ready Rails engine for building, managing, and monitoring LLM-powered AI agents. Provides a declarative DSL for creating intelligent agents with built-in execution tracking, cost analytics, budget controls, multi-tenancy, reliability patterns, and a real-time dashboard. Built on RubyLLM for provider abstraction. Requires Ruby >= 3.1.0, Rails >= 7.0, and RubyLLM >= 1.12.0. MIT License. Current version: 3.0.0.

ruby_llm-agents brings structure, observability, and control to LLM-based Rails applications. Define agents using a class-based DSL with model selection, temperature, parameters, prompts, and response schemas. The three-role prompt DSL (v2.2+) supports `system`, `user`, and `assistant` class-level methods mirroring LLM API terminology. Use `.ask(message)` for conversational agents without a fixed user template. Supports two DSL styles: a simplified prompt-centric syntax (recommended) and a traditional method-override approach. Compose agents by passing agent classes in the `tools` list — they are automatically wrapped as LLM-callable tools with execution hierarchy tracking (`parent_execution_id`/`root_execution_id`). Every execution is automatically tracked with token usage, costs, and duration in a split schema (executions + execution_details tables). Set daily and monthly budget limits per tenant with alerts. Handle failures gracefully with automatic retries, model fallbacks, and circuit breakers. Subscribe to 11 ActiveSupport::Notifications events for real-time observability across execution, cache, budget, and reliability domains. Inject custom middleware into the pipeline globally or per-agent for audit logging, rate limiting, tracing, and content moderation. Configure all LLM provider API keys in a single unified configuration block (v2.1+). Process images with generation, analysis, editing, upscaling, and background removal. Handle audio with transcription and text-to-speech. Handle agent renames with the `aliases` DSL (for alias-aware queries), `RubyLLM::Agents.rename_agent` (programmatic batch update), or the `ruby_llm_agents:rename_agent` generator (reversible migration).

## Documentation

- [Home](wiki/Home.md): Wiki home page and documentation index
- [Getting Started](wiki/Getting-Started.md): Quick start guide and overview
- [Installation](wiki/Installation.md): Detailed installation and setup instructions
- [First Agent](wiki/First-Agent.md): Tutorial for creating your first agent
- [Configuration](wiki/Configuration.md): Global configuration options reference
- [Generators](wiki/Generators.md): Rails generators for agents, embedders, transcribers, and image operations
- [Agent DSL](wiki/Agent-DSL.md): Complete DSL reference for defining agents
- [Parameters](wiki/Parameters.md): Defining and validating agent parameters
- [Prompts and Schemas](wiki/Prompts-and-Schemas.md): System prompts, user prompts, and response schemas
- [Result Object](wiki/Result-Object.md): Understanding the unified result object with metadata
- [Examples](wiki/Examples.md): Code examples and common patterns
- [Best Practices](wiki/Best-Practices.md): Recommended patterns and guidelines
- [API Reference](wiki/API-Reference.md): Complete API documentation
- [FAQ](wiki/FAQ.md): Frequently asked questions
- [Troubleshooting](wiki/Troubleshooting.md): Common issues and solutions
- [Contributing](wiki/Contributing.md): How to contribute to the project

## Core Components

- [Base Agent](lib/ruby_llm/agents/base_agent.rb): Base class for all agents with DSL and pipeline execution
- [DSL Base](lib/ruby_llm/agents/dsl/base.rb): Core DSL - model, system, user, assistant, prompt (alias), returns, description
- [DSL Reliability](lib/ruby_llm/agents/dsl/reliability.rb): Reliability DSL - retries, fallbacks, circuit breakers, on_failure
- [DSL Caching](lib/ruby_llm/agents/dsl/caching.rb): Caching DSL - cache_for, cache(for:, key:)
- [DSL Queryable](lib/ruby_llm/agents/dsl/queryable.rb): Execution query DSL - .executions, .last_run, .stats, .total_spent, .failures, .cost_by_model, .with_params
- [Result](lib/ruby_llm/agents/result.rb): Unified result object with content, cost, tokens, duration
- [Configuration](lib/ruby_llm/agents/core/configuration.rb): Global configuration with 50+ options plus forwarded RubyLLM attributes (v2.1+)
- [Execution Detail](app/models/ruby_llm/agents/execution_detail.rb): Large payload storage (prompts, responses, tool_calls)
- [Engine](lib/ruby_llm/agents/engine.rb): Rails engine setup and initialization
- [Errors](lib/ruby_llm/agents/errors.rb): Custom error classes for agents

## Execution Tracking

- [Execution Tracking Guide](wiki/Execution-Tracking.md): How execution tracking works
- [Execution Model](app/models/ruby_llm/agents/execution.rb): ActiveRecord model for tracking all executions
- [Execution Metrics](app/models/ruby_llm/agents/execution/metrics.rb): Token usage, cost, and duration metrics
- [Execution Analytics](app/models/ruby_llm/agents/execution/analytics.rb): Aggregation and reporting methods
- [Execution Scopes](app/models/ruby_llm/agents/execution/scopes.rb): Query scopes for filtering executions
- [Execution Workflow](app/models/ruby_llm/agents/execution/workflow.rb): Parent/child/root execution relationships
- [Execution Replayable](app/models/ruby_llm/agents/execution/replayable.rb): Replay previous executions with same or overridden inputs
- [DSL Queryable](lib/ruby_llm/agents/dsl/queryable.rb): Agent-centric execution queries (.executions, .stats, .last_run, .total_spent, .failures, .cost_by_model, .with_params)
- [Instrumentation](lib/ruby_llm/agents/instrumentation.rb): Execution logging and telemetry hooks
- [ActiveSupport Notifications](wiki/ActiveSupport-Notifications.md): 11 AS::Notifications events (execution.start/complete/error, cache.hit/miss/write, budget.check/exceeded/record, reliability.fallback_used/all_models_exhausted)
- [Execution Logger Job](lib/ruby_llm/agents/execution_logger_job.rb): Background job for async logging
- [Database Queries](wiki/Database-Queries.md): Common queries for execution data
- [Querying Executions](wiki/Querying-Executions.md): Agent-centric queries, convenience methods, and replay
- [ActiveSupport Notifications](wiki/ActiveSupport-Notifications.md): Real-time instrumentation events across execution, cache, budget, and reliability domains
- [Custom Middleware](wiki/Custom-Middleware.md): Inject custom middleware into the pipeline globally or per-agent with before:/after: positioning

## Reliability

- [Reliability Guide](wiki/Reliability.md): Overview of reliability features
- [Reliability Module](lib/ruby_llm/agents/reliability.rb): Main reliability configuration
- [Reliability DSL](lib/ruby_llm/agents/base/reliability_dsl.rb): DSL for retry, fallback, circuit breaker
- [Reliability Execution](lib/ruby_llm/agents/base/reliability_execution.rb): Execution with reliability patterns
- [Automatic Retries](wiki/Automatic-Retries.md): Retry configuration and strategies
- [Retry Strategy](lib/ruby_llm/agents/reliability/retry_strategy.rb): Exponential backoff implementation
- [Model Fallbacks](wiki/Model-Fallbacks.md): Fallback model configuration
- [Fallback Routing](lib/ruby_llm/agents/reliability/fallback_routing.rb): Automatic model switching on failure
- [Circuit Breakers](wiki/Circuit-Breakers.md): Circuit breaker configuration and usage
- [Circuit Breaker](lib/ruby_llm/agents/circuit_breaker.rb): Circuit breaker implementation
- [Breaker Manager](lib/ruby_llm/agents/reliability/breaker_manager.rb): Managing multiple circuit breakers
- [Execution Constraints](lib/ruby_llm/agents/reliability/execution_constraints.rb): Timeouts and rate limiting
- [Reliability Executor](lib/ruby_llm/agents/reliability/executor.rb): Orchestrates retry, fallback, breaker
- [Attempt Tracker](lib/ruby_llm/agents/attempt_tracker.rb): Tracks retry attempts and failures

## Budget and Cost

- [Budget Controls](wiki/Budget-Controls.md): Setting up budget limits and alerts
- [Budget Tracker](lib/ruby_llm/agents/budget_tracker.rb): Daily and monthly spending enforcement
- [Budget Query](lib/ruby_llm/agents/budget/budget_query.rb): Querying budget usage
- [Config Resolver](lib/ruby_llm/agents/budget/config_resolver.rb): Resolving budget configuration
- [Forecaster](lib/ruby_llm/agents/budget/forecaster.rb): Spending forecasting
- [Spend Recorder](lib/ruby_llm/agents/budget/spend_recorder.rb): Recording spending events
- [Cost Calculation](lib/ruby_llm/agents/base/cost_calculation.rb): Per-execution cost calculation
- [Tenant Budget Model](app/models/ruby_llm/agents/tenant_budget.rb): Per-tenant budget limits
- [Alerts](wiki/Alerts.md): Setting up budget breach notifications
- [Alert Manager](lib/ruby_llm/agents/alert_manager.rb): Slack and webhook alerts

## Multi-Tenancy

- [Multi-Tenancy Guide](wiki/Multi-Tenancy.md): Setting up multi-tenant support
- [LLM Tenant](lib/ruby_llm/agents/llm_tenant.rb): Tenant concern for models
- [Tenant](app/models/ruby_llm/agents/tenant.rb): Per-tenant budgets and tracking

## Caching

- [Caching Guide](wiki/Caching.md): Response caching strategies
- [Caching Module](lib/ruby_llm/agents/base/caching.rb): Cache configuration DSL
- [Cache Helper](lib/ruby_llm/agents/cache_helper.rb): Cache key generation and storage

## Streaming

- [Streaming Guide](wiki/Streaming.md): Real-time response streaming
- [Conversation History](wiki/Conversation-History.md): Multi-turn conversation support

## Text Operations

- [Embeddings Guide](wiki/Embeddings.md): Vector embeddings with batching and caching
- [Embedder](lib/ruby_llm/agents/embedder.rb): Base embedder class
- [Embedder DSL](lib/ruby_llm/agents/embedder/dsl.rb): Embedder configuration DSL
- [Embedder Execution](lib/ruby_llm/agents/embedder/execution.rb): Embedding generation logic
- [Embedding Result](lib/ruby_llm/agents/embedding_result.rb): Embedding result with vectors

## Audio Operations

- [Audio Guide](wiki/Audio.md): Transcription and text-to-speech overview
- [Transcriber](lib/ruby_llm/agents/transcriber.rb): Audio transcription base class
- [Transcriber DSL](lib/ruby_llm/agents/transcriber/dsl.rb): Transcription configuration
- [Transcriber Execution](lib/ruby_llm/agents/transcriber/execution.rb): Transcription logic
- [Transcription Result](lib/ruby_llm/agents/transcription_result.rb): Result with text and segments
- [Speaker](lib/ruby_llm/agents/speaker.rb): Text-to-speech base class
- [Speaker DSL](lib/ruby_llm/agents/speaker/dsl.rb): Speech configuration with voice options
- [Speaker Execution](lib/ruby_llm/agents/speaker/execution.rb): Speech synthesis logic
- [Speech Result](lib/ruby_llm/agents/speech_result.rb): Result with audio data

## Image Operations

- [Image Generation Guide](wiki/Image-Generation.md): Image generation and manipulation overview
- [Image Generator](lib/ruby_llm/agents/image_generator.rb): Image generation base class
- [Image Generator DSL](lib/ruby_llm/agents/image_generator/dsl.rb): Generation configuration
- [Image Generator Execution](lib/ruby_llm/agents/image_generator/execution.rb): Generation logic
- [Image Generation Result](lib/ruby_llm/agents/image_generation_result.rb): Result with image URLs
- [Image Generator Pricing](lib/ruby_llm/agents/image_generator/pricing.rb): Cost calculation for images
- [Image Generator Templates](lib/ruby_llm/agents/image_generator/templates.rb): Prompt templates
- [Content Policy](lib/ruby_llm/agents/image_generator/content_policy.rb): Image content safety
- [ActiveStorage Support](lib/ruby_llm/agents/image_generator/active_storage_support.rb): Rails ActiveStorage integration
- [Image Analyzer](lib/ruby_llm/agents/image_analyzer.rb): Extract captions, tags, objects from images
- [Image Analyzer DSL](lib/ruby_llm/agents/image_analyzer/dsl.rb): Analysis configuration
- [Image Analyzer Execution](lib/ruby_llm/agents/image_analyzer/execution.rb): Analysis logic
- [Image Analysis Result](lib/ruby_llm/agents/image_analysis_result.rb): Result with extracted data
- [Image Editor](lib/ruby_llm/agents/image_editor.rb): Modify existing images
- [Image Editor DSL](lib/ruby_llm/agents/image_editor/dsl.rb): Editing configuration
- [Image Editor Execution](lib/ruby_llm/agents/image_editor/execution.rb): Editing logic
- [Image Edit Result](lib/ruby_llm/agents/image_edit_result.rb): Result with edited image
- [Image Transformer](lib/ruby_llm/agents/image_transformer.rb): Style transfer and effects
- [Image Transformer DSL](lib/ruby_llm/agents/image_transformer/dsl.rb): Transform configuration
- [Image Transformer Execution](lib/ruby_llm/agents/image_transformer/execution.rb): Transform logic
- [Image Transform Result](lib/ruby_llm/agents/image_transform_result.rb): Result with transformed image
- [Image Upscaler](lib/ruby_llm/agents/image_upscaler.rb): Improve image resolution
- [Image Upscaler DSL](lib/ruby_llm/agents/image_upscaler/dsl.rb): Upscaling configuration
- [Image Upscaler Execution](lib/ruby_llm/agents/image_upscaler/execution.rb): Upscaling logic
- [Image Upscale Result](lib/ruby_llm/agents/image_upscale_result.rb): Result with upscaled image
- [Image Variator](lib/ruby_llm/agents/image_variator.rb): Generate image variations
- [Image Variator DSL](lib/ruby_llm/agents/image_variator/dsl.rb): Variation configuration
- [Image Variator Execution](lib/ruby_llm/agents/image_variator/execution.rb): Variation logic
- [Image Variation Result](lib/ruby_llm/agents/image_variation_result.rb): Result with variations
- [Background Remover](lib/ruby_llm/agents/background_remover.rb): Extract subjects with transparency
- [Background Remover DSL](lib/ruby_llm/agents/background_remover/dsl.rb): Removal configuration
- [Background Remover Execution](lib/ruby_llm/agents/background_remover/execution.rb): Removal logic
- [Background Removal Result](lib/ruby_llm/agents/background_removal_result.rb): Result with transparent image
- [Image Pipeline](lib/ruby_llm/agents/image_pipeline.rb): Chain multiple image operations
- [Image Pipeline DSL](lib/ruby_llm/agents/image_pipeline/dsl.rb): Pipeline configuration
- [Image Pipeline Execution](lib/ruby_llm/agents/image_pipeline/execution.rb): Pipeline execution
- [Image Pipeline Result](lib/ruby_llm/agents/image_pipeline_result.rb): Combined pipeline result
- [Image Operation DSL](lib/ruby_llm/agents/concerns/image_operation_dsl.rb): Shared DSL for image operations
- [Image Operation Execution](lib/ruby_llm/agents/concerns/image_operation_execution.rb): Shared execution logic

## Tools and Agent Composition

- [Tools Guide](wiki/Tools.md): Adding tools/functions to agents, including agent-as-tool composition
- [AgentTool](lib/ruby_llm/agents/agent_tool.rb): Wraps agent classes as RubyLLM::Tool subclasses for use in other agents' tools lists
- [Tool Tracking](lib/ruby_llm/agents/base/tool_tracking.rb): Tracking tool calls in executions
- [Attachments](wiki/Attachments.md): Sending files and images to agents

## Evaluation

- [Evaluation Guide](wiki/Evaluation.md): Score agent quality with test datasets and built-in scorers
- [EvalSuite](lib/ruby_llm/agents/eval/eval_suite.rb): DSL for defining test cases, running them, and scoring results (exact match, contains, LLM judge, custom lambda)
- [EvalResult](lib/ruby_llm/agents/eval/eval_result.rb): Per-case result with score, actual/expected, error tracking
- [EvalRun](lib/ruby_llm/agents/eval/eval_run.rb): Aggregate results with score, pass/fail counts, summary, JSON export

## Testing and Development

- [Testing Agents](wiki/Testing-Agents.md): Testing strategies and mocking
- [Error Handling](wiki/Error-Handling.md): Handling errors and exceptions

## Dashboard

- [Dashboard Guide](wiki/Dashboard.md): Real-time monitoring dashboard setup
- [Production Deployment](wiki/Production-Deployment.md): Deploying to production
- [Background Jobs](wiki/Background-Jobs.md): Configuring async execution logging

## Optional

- [Async/Fiber Guide](wiki/Async-Fiber.md): High-throughput fiber-based concurrency
- [Async Module](lib/ruby_llm/agents/async.rb): Fiber-based async support
- [Thinking Guide](wiki/Thinking.md): Extended thinking for complex reasoning
- [Resolved Config](lib/ruby_llm/agents/resolved_config.rb): Runtime configuration resolution
- [Inflections](lib/ruby_llm/agents/inflections.rb): Custom Rails inflections
- [Deprecations](lib/ruby_llm/agents/deprecations.rb): Deprecated method handling
- [Version](lib/ruby_llm/agents/version.rb): Gem version constant