Skip to content

Getting Started

adham90 edited this page Feb 16, 2026 · 6 revisions

Getting Started with RubyLLM::Agents

This guide walks you through installing RubyLLM::Agents and creating your first AI-powered agent in a Rails application.

Prerequisites

Before you begin, ensure you have:

Quick Installation

Step 1: Add the Gem

Add to your Gemfile:

gem "ruby_llm-agents"

Step 2: Install Dependencies

bundle install

Step 3: Run the Generator

rails generate ruby_llm_agents:install rails db:migrate

This 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 /agents for the dashboard

Step 4: Configure API Keys

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" end

Option 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:edit
openai: api_key: sk-... anthropic: api_key: sk-ant-... google: api_key: ...

Your First Agent

Generate an Agent

rails generate ruby_llm_agents:agent Summarizer text:required max_length:500

This 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

Call the Agent

# 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"

Conversational Usage with .ask

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.content

Force JSON Output with assistant

Use 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 end

View in Dashboard

Visit http://localhost:3000/agents to see:

  • Execution history
  • Token usage
  • Costs
  • Performance metrics

Next Steps

Now that you have your first agent running:

  1. Agent DSL - Learn all configuration options
  2. Prompts and Schemas - Structure your outputs
  3. Reliability - Add retries and fallbacks
  4. Dashboard - Set up authentication
  5. Examples - See real-world use cases

Detailed Guides

Clone this wiki locally