- Notifications
You must be signed in to change notification settings - Fork 4
Getting Started
adham90 edited this page Feb 16, 2026 · 6 revisions
This guide walks you through installing RubyLLM::Agents and creating your first AI-powered agent in a Rails application.
Before you begin, ensure you have:
Add to your Gemfile:
gem "ruby_llm-agents"bundle installrails generate ruby_llm_agents:install rails db:migrateThis creates:
-
db/migrate/xxx_create_ruby_llm_agents_executions.rb- Database table for tracking -
config/initializers/ruby_llm_agents.rb- Configuration file -
app/agents/application_agent.rb- Base class for your agents - Route mount at
/agentsfor the dashboard
Option A: Unified configuration (recommended, v2.1+)
Configure everything in one place:
# config/initializers/ruby_llm_agents.rb RubyLLM::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["GOOGLE_API_KEY"] config.default_model = "gpt-4o" endOption B: Environment variables
API keys are auto-detected from environment variables:
# .env (using dotenv-rails) OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... GOOGLE_API_KEY=...Option C: Rails credentials
rails credentials:editopenai: api_key: sk-... anthropic: api_key: sk-ant-... google: api_key: ...rails generate ruby_llm_agents:agent Summarizer text:required max_length:500This creates app/agents/summarizer_agent.rb:
class SummarizerAgent < ApplicationAgent model "gemini-2.0-flash" temperature 0.0 param :max_length, default: 500 system "You are a summarization assistant. Create concise summaries that capture the key points while staying under the word limit." user "Summarize the following text in under {max_length} words:\n\n{text}" end# In your Rails console or controller result = SummarizerAgent.call( text: "Long article text here...", max_length: 200 ) # Access the response puts result.content # The summary text # Access metadata puts result.total_tokens # => 150 puts result.total_cost # => 0.00025 puts result.duration_ms # => 850 puts result.model_id # => "gemini-2.0-flash"For multi-turn conversations, use .ask instead of .call:
agent = SummarizerAgent.new(max_length: 200) result = agent.ask("Summarize this article about climate change...") puts result.content # Follow up naturally result = agent.ask("Now make it shorter, under 50 words.") puts result.contentUse assistant to prefill the assistant's response, which is especially useful for forcing structured output:
class SummarizerAgent < ApplicationAgent model "gemini-2.0-flash" temperature 0.0 param :max_length, default: 500 system "You are a summarization assistant. Return JSON with keys: summary, word_count." user "Summarize the following text in under {max_length} words:\n\n{text}" assistant "{" # Forces the model to start its reply with "{", ensuring JSON output endVisit http://localhost:3000/agents to see:
- Execution history
- Token usage
- Costs
- Performance metrics
Now that you have your first agent running:
- Agent DSL - Learn all configuration options
- Prompts and Schemas - Structure your outputs
- Reliability - Add retries and fallbacks
- Dashboard - Set up authentication
- Examples - See real-world use cases
- Installation - Platform-specific setup instructions
- Configuration - All configuration options
- First Agent - Detailed agent tutorial