Active Agent: agents as Rails controllers

Agents as controllers, and what that changes

Active Agent is described as providing the missing AI layer in the Rails framework, with a structured approach to building AI-powered applications through Agent Oriented Programming, and the line that sums it up is that agents are now controllers.

That is a real architectural position rather than a slogan. The claim is that designing an application with agents lets you create modular, reusable components that integrate easily into existing systems, promoting reusability, maintainability and scalability, and doing it with the object oriented Ruby code you already use today.

The resemblance to a Rails controller is concrete. An agent is a class, it has actions, and an action is a method you can call. The quick example is a class inheriting from ActiveAgent::Base with a generate_with line naming the provider and model:

class ApplicationAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4o-mini"
end

And using it is a chain, prompt with a message and then generate_now:

response = ApplicationAgent.prompt(message: "Hello, world!").generate_now
puts response.message
# => "Hello! How can I help you today?"

The gem is MIT licensed, requires Ruby 3.1 or newer and Rails 7.2, 8.0 or 8.1, and it is published on RubyGems as activeagent with a companion gem named actionagent. The last push to the main branch was on 2026-10-20 and v1.9.1 was published on 2026-10-17, so the project is moving quickly.

Installing the framework, the provider and the generator

The installation is three steps, and the third one is what makes this a Rails framework rather than a library.

First, the framework, through bundler:

bundle add activeagent

That is the framework itself, covering agents, providers, generation and telemetry reporting. The dashboard is deliberately not part of it, since actionagent is a separate gem added when you want it.

Second, the provider gem for the service you are going to use. The list is worth reading closely because five of the seven entries install the same gem:

# OpenAI
bundle add openai

# Anthropic
bundle add anthropic

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

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

# Requesty (uses OpenAI-compatible API)
bundle add openai

# DeepSeek (uses OpenAI-compatible API)
bundle add openai

# RubyLLM (unified API for 15+ providers)
bundle add ruby_llm

So Ollama, OpenRouter, Requesty and DeepSeek all go through the openai gem, because each of them speaks an OpenAI-compatible API, and only Anthropic and RubyLLM need their own client. RubyLLM is the exception worth noting, since it presents a unified API for more than fifteen providers behind one gem.

Third, the generator:

rails generate active_agent:install

which creates two files, config/active_agent.yml for the generation provider configuration and app/agents/application_agent.rb as the base agent class. The generator is doing the work that a Rails developer expects a generator to do, which is to leave you with a working convention rather than a set of instructions.

Actions, and how a generator creates them for you

The second generator creates your first agent, and the way it works shows how actions are defined.

rails generate active_agent:agent TravelAgent search book confirm

The agent name comes first and the action names follow, and the result is a class with one method per action:

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

Each action ends with prompt, which is the part that makes this different from an ordinary service object. The action is where you write the logic, and the prompt call is what hands the conversation to the model, so an action is simultaneously a business operation and a turn in a dialogue. The action-based design is listed as one of the framework's features, and the generator naming your actions for you is a small quality touch, because a new agent with three capabilities and no code is a good starting point.

The other features follow the same logic. View templates let you use ERB templates for prompts, in text, JSON or HTML form, so a prompt is a view rather than a string literal. Structured output lets you define JSON schemas for predictable responses. Tool and function calling lets agents interact with external services. Context management maintains conversation history across interactions. Streaming gives real-time responses over ActionCable. And agent-as-tool delegation hands work to sub-agents with declared schemas, cost and latency budgets, and swappable backends, which is the feature that matters when one agent is not enough and you need to cap what the others may spend.

Provider configuration, and where the credentials come from

The configuration lives in config/active_agent.yml, and the shape of it is the thing to copy.

development:
  openai:
    service: "OpenAI"
    access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>
    model: "gpt-4o-mini"

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

  ollama:
    service: "Ollama"
    model: "llama3.2"

  deepseek:
    service: "DeepSeek"
    api_key: <%= Rails.application.credentials.dig(:deepseek, :api_key) %>
    model: "deepseek-flash"

  ruby_llm:
    service: "RubyLLM"

Every entry names a service, and the interesting part is that the credentials are not in the file. Each access_token and api_key is an ERB expression reading from Rails.application.credentials, so the secrets live in the encrypted credentials store rather than in a YAML file that tends to end up in version control. The Ollama and RubyLLM entries have no credential line at all, which is correct for a local model and for the unified client respectively.

The file is keyed by environment, with development as the top level here, which means the same structure holds a production block and a test block.

The examples in the README show the shape of a call for the common patterns. Data extraction passes an image path:

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

And translation passes a message and a locale:

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

Both use with, which passes parameters to the agent, and then name the action as a method before generate_now, so the call site reads as a sentence about what the agent should do.

The dashboard gem, and why it is not part of the framework

The dashboard and dev console is its own gem, actionagent, and the README is explicit about why it ships separately.

It is a mountable Rails engine with traces and span waterfalls, token usage and per-agent metrics, plus the agent builder, runs, conversations, evaluations, scorecards and cost estimates, so you can watch and drive your agents while you build it.

The reason for the split is a dependency boundary, and it is a good one. The dashboard's models are Active Record models, and it runs agents through solid_agent, and neither of those is a dependency of activeagent, so an application that only runs agents installs neither.

Installing it is three commands:

bundle add actionagent
rails generate action_agent:install
rails db:migrate

and the telemetry is turned on in the same configuration file:

# config/active_agent.yml
telemetry:
  enabled: true
  local_storage: true

The generator mounts the engine at /activeagents, and opening it shows every generation as a trace. The documentation page for the dashboard covers authentication, remote ingestion and multi-tenant mode, and the hosted platform at activeagents.ai runs the same engine multi-tenant, adding what a hosted product has to have, accounts, plans, billing, quotas and managed sandboxes, with every workspace starting on a free low-volume trial.

The split between framework and console is worth noting for anyone deciding what to install. The framework gem is the thing your production code depends on, and it is deliberately light. The console is a development tool that needs a database and a browser, and pulling it into a runtime dependency list would be a mistake, which is why the README frames it as something you add when you want it rather than something you get.

Editorial conclusion

Adopt Active Agent if your team is a Rails shop and you want to add AI features inside the application rather than beside it, because agents are ordinary Ruby classes with actions and prompt templates, and the separate dashboard gem gives you traces and token metrics without pulling Active Record into the core. Do not adopt it if you want a framework agnostic agent runtime, since the design is explicitly Rails shaped and the generator writes config/active_agent.yml and an ApplicationAgent base class. Before you start, decide which provider gem you are adding, because the OpenAI-compatible services all install the openai gem and differ only in the configuration, and remember that the dashboard is optional and separate, so an app that only runs agents installs neither it nor the solid_agent dependency.

Frequently asked questions

Official sources

1. activeagents/activeagent on GitHub
2. License: MIT
3. Project website
4. README
5. Releases