*Build AI in Rails*

Now Agents are Controllers

Makes code TonsOfFun!

Active Agent

Active Agent provides that missing AI layer in the Rails framework, offering a structured approach to building AI-powered applications through Agent Oriented Programming. Now Agents are Controllers! Designing applications using agents allows developers to create modular, reusable components that can be easily integrated into existing systems. This approach promotes code reusability, maintainability, and scalability, making it easier to build complex AI-driven applications with the Object Oriented Ruby code you already use today.

Documentation

docs.activeagents.ai - The official documentation site for Active Agent.

Getting Started

Installation

Use bundler to add activeagent to your Gemfile and install:

bundle add activeagent

Add the generation provider gem you want to use:

# OpenAI
bundle add ruby-openai

# Anthropic
bundle add ruby-anthropic

# Ollama (uses OpenAI-compatible API)
bundle add ruby-openai

# OpenRouter (uses OpenAI-compatible API)
bundle add ruby-openai

Setup

Run the install generator to create the necessary configuration files:

rails generate active_agent:install

This creates:

• config/active_agent.yml: Configuration file for generation providers
• app/agents: Directory for your agent classes
• app/views/agent_*: Directory for agent prompt/view templates

Quick Example

Define an application agent:

class ApplicationAgent < ActiveAgent::Base
  generate_with :openai, 
    instructions: "You are a helpful assistant.",
    model: "gpt-4o-mini",
    temperature: 0.7
end

Use your agent:

message = "Test Application Agent"
prompt = ApplicationAgent.with(message: message).prompt_context
response = prompt.generate_now

Your First Agent

Generate a new agent:

rails generate active_agent:agent TravelAgent search book confirm

This creates an agent with actions that can be called:

class TravelAgent < ApplicationAgent
  def search
    # Your search logic here
    prompt
  end

  def book
    # Your booking logic here
    prompt
  end

  def confirm
    # Your confirmation logic here
    prompt
  end
end

Configuration

Configure generation providers in config/active_agent.yml:

development:
  openai:
    service: "OpenAI"
    api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>
    model: "gpt-4o-mini"
    embeddings_model: "text-embedding-3-small"

  anthropic:
    service: "Anthropic"
    api_key: <%= Rails.application.credentials.dig(:anthropic, :api_key) %>
    model: "claude-3-5-sonnet"

  ollama:
    service: "Ollama"
    model: "llama3.2"
    embeddings_model: "nomic-embed-text"
    host: "http://localhost:11434"

Features

• Agent-Oriented Programming: Build AI applications using familiar Rails patterns
• Multiple Provider Support: Works with OpenAI, Anthropic, Ollama, and more
• Action-Based Design: Define agent capabilities through actions
• View Templates: Use ERB templates for prompts (text, JSON, HTML)
• Streaming Support: Real-time response streaming with ActionCable
• Tool/Function Calling: Agents can use tools to interact with external services
• Context Management: Maintain conversation history across interactions
• Structured Output: Define JSON schemas for predictable responses

Examples

Data Extraction

Extract structured data from images, PDFs, and text:

prompt = DataExtractionAgent.with(
  output_schema: :chart_schema,
  image_path: Rails.root.join("sales_chart.png")
).parse_content

Translation

Translate text between languages:

response = TranslationAgent.with(
  message: "Hi, I'm Justin", 
  locale: "japanese"
).translate.generate_now

Tool Usage

Agents can use tools to perform actions:

# Agent with tool support
message = "Show me a cat"
prompt = SupportAgent.with(message: message).prompt_context
response = prompt.generate_now
# Response includes tool call results

Learn More

• Documentation
• Getting Started Guide
• API Reference
• Examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

Active Agent is released under the MIT License.