Rails AI Agents

A modular and extendable Rails engine that provides an Agent model and LLM client integration for building AI-powered applications.

Features

• 🚀 Mountable Rails Engine - Easily integrate into existing Rails applications
• 🤖 Agent Model - Manage AI agents with configurable settings
• 🔌 LLM Integration - Built-in support for OpenAI and other LLM providers
• ⚙️ Configurable - Flexible configuration through Rails initializers
• 🛠️ Generator Support - Easy installation with Rails generators
• 📋 Rake Tasks - Built-in commands for managing agents
• 🔄 Extensible - Modular design for easy customization

Requirements

• Ruby >= 3.2.0
• Rails >= 8.0.0
• A supported LLM provider (OpenAI, etc.)

Installation

Add this line to your application's Gemfile:

gem 'rails_ai_agents'

And then execute:

bundle install

Or install it yourself as:

gem install rails_ai_agents

Setup

1. Run the installer

rails generate ai_agents:install

This will:

• Create a migration for the ai_agents table
• Generate a configuration initializer at config/initializers/ai_agents.rb

2. Run the migration

rails db:migrate

3. Configure your LLM provider

Edit config/initializers/ai_agents.rb:

RailsAiAgents.configure do |config|
  # LLM Provider Configuration
  config.llm_provider = :openai

  # API Key (store securely!)
  config.api_key = Rails.application.credentials.openai_api_key || ENV['OPENAI_API_KEY']

  # Default model
  config.default_model = "gpt-3.5-turbo"

  # API base URL (for OpenAI-compatible APIs)
  config.api_base_url = "https://api.openai.com/v1"
end

4. Test your configuration

rails ai_agents:test_connection

Usage

Creating Agents

# Create a basic agent
agent = AiAgents::Agent.create!(
  name: "Assistant",
  description: "A helpful AI assistant",
  model: "gpt-3.5-turbo"
)

# Create an agent with custom configuration
agent = AiAgents::Agent.create!(
  name: "Creative Writer",
  description: "An AI specialized in creative writing",
  model: "gpt-4",
  config: {
    "temperature" => 0.9,
    "max_tokens" => 2000,
    "top_p" => 0.95
  }
)

Using Agents

# Simple usage
agent = AiAgents::Agent.find_by(name: "Assistant")
response = agent.run("Hello, how are you today?")
puts response

# Handle errors
begin
  response = agent.run("Write a story about robots")
  puts response
rescue AiAgents::LLMClient::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue AiAgents::LLMClient::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
rescue AiAgents::LLMClient::APIError => e
  puts "API error: #{e.message}"
end

Finding Agents

# Find by name
agent = AiAgents::Agent.by_name("Assistant")

# Find active agents
active_agents = AiAgents::Agent.active

# Find agents by model
gpt4_agents = AiAgents::Agent.where(model: "gpt-4")

Managing Agents

# List all agents (via rake task)
rails ai_agents:list

# Deactivate an agent
agent.update!(active: false)

# Update agent configuration
agent.update!(
  config: {
    "temperature" => 0.5,
    "max_tokens" => 1500
  }
)

Configuration

The gem supports the following configuration options:

RailsAiAgents.configure do |config|
  # LLM Provider (:openai is currently the only supported provider)
  config.llm_provider = :openai

  # Your API key
  config.api_key = "your-api-key-here"

  # Default model to use for new agents
  config.default_model = "gpt-3.5-turbo"

  # API base URL (useful for OpenAI-compatible APIs)
  config.api_base_url = "https://api.openai.com/v1"
end

Agent Configuration Options

Each agent can be configured with the following options in their config field:

• temperature: Controls randomness (0.0 to 2.0, default: 0.7)
• max_tokens: Maximum tokens in response (default: 1000)
• top_p: Nucleus sampling parameter (0.0 to 1.0, default: 1.0)
• frequency_penalty: Reduces repetition (-2.0 to 2.0, default: 0.0)
• presence_penalty: Encourages new topics (-2.0 to 2.0, default: 0.0)

Rake Tasks

List all agents

rails ai_agents:list

Shows all registered agents with their configurations and status.

Test LLM connection

rails ai_agents:test_connection

Tests the connection to your configured LLM provider.

Routes

This gem is designed as a mountable engine but does not auto-mount any routes. You have full control over the routing in your host application.

If you want to add web interfaces for managing agents, you can create controllers in your host app or mount specific routes as needed.

Error Handling

The gem provides several custom exception classes:

• AiAgents::LLMClient::LLMError - Base error class
• AiAgents::LLMClient::AuthenticationError - API key issues
• AiAgents::LLMClient::RateLimitError - Rate limiting
• AiAgents::LLMClient::APIError - General API errors

Extending the Gem

Adding Custom LLM Providers

To add support for additional LLM providers, extend the LLMClient class:

# In your application
module AiAgents
  class LLMClient
    private

    def complete_with_custom_provider(prompt)
      # Your custom implementation
    end
  end
end

Custom Agent Behaviors

You can extend the Agent model in your application:

# app/models/ai_agents/agent.rb (in your app)
module AiAgents
  class Agent
    # Add custom methods or behaviors
    def run_with_context(prompt, context = {})
      enhanced_prompt = "Context: #{context.to_json}\n\nPrompt: #{prompt}"
      run(enhanced_prompt)
    end
  end
end

Database Schema

The ai_agents table includes:

• name - Unique identifier for the agent
• description - Human-readable description
• model - LLM model to use (e.g., "gpt-3.5-turbo")
• config - JSON configuration for model parameters
• active - Boolean flag for enabling/disabling agents
• created_at / updated_at - Standard Rails timestamps

Security Considerations

1. API Keys: Store API keys securely using Rails credentials or environment variables
2. Input Validation: Always validate and sanitize user inputs before sending to LLM APIs
3. Rate Limiting: Implement rate limiting in your application to avoid API limits
4. Cost Control: Monitor your LLM provider usage to control costs

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This gem is available as open source under the terms of the MIT License.

Changelog

See CHANGELOG.md for version history and changes.