Skip to content

Getting Started

Jump to bottom
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