Active Agent

Appearance

Getting Started ​

This guide will help you set up and create your first ActiveAgent application.

Installation ​

Use bundler to add activeagent to your Gemfile and install:

bash
bundle add activeagent

Add the generation provider gem you want to use:

bash
bundle add ruby-openai
bash
bundle add ruby-anthropic
bash
# Ollama follows the same API spec as OpenAI, so you can use the same gem.
bundle add ruby-openai
bash
bundle add ruby-openai
# OpenRouter follows the same API spec as OpenAI, so you can use the same gem.

Then install the gems by running:

bash
bundle install

Active Agent install generator ​

To set up Active Agent in your Rails application, you can use the install generator. This will create the necessary configuration files and directories for Active Agent.

bash
rails generate active_agent:install

This command will create the following files and directories:

  • config/active_agent.yml: The configuration file for Active Agent, where you can specify your generation providers and their settings.
  • app/agents: The directory where your agent classes will be stored.
  • app/views/layouts/agent.text.erb: The layout file for your agent prompt/view templates.
  • app/views/agent_*: The directory where your agent prompt/view templates will be stored.

Usage ​

Active Agent is designed to work seamlessly with Rails applications. It can be easily integrated into your existing Rails app without any additional configuration. The framework automatically detects the Rails environment and configures itself accordingly.

You can start by defining an ApplicationAgent class that inherits from ActiveAgent::Base. This class will define the actions and behaviors of your application's base agent. You can then use the generate_with method to specify the generation provider for your agent.

ruby
class ApplicationAgent < ActiveAgent::Base
  layout "agent"

  generate_with :openai, model: "gpt-4o-mini"
end

This sets up the ApplicationAgent to use OpenAI as the generation provider. You can replace :openai with any other supported provider, such as :anthropic, :google, or :ollama. Learn more about generation providers and their configuration →

Now, you can interact with your application agent using the default prompt_context method. This method allows you to provide a context for the agent to generate a response based on the defined actions and behaviors:

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

activeagent/test/agents/application_agent_test.rb:23

ruby
# Response object
#<ActiveAgent::GenerationProvider::Response:0x2ad0
  @message=#<ActiveAgent::ActionPrompt::Message:0x2ae4
    @action_id=nil,
    @action_name=nil,
    @action_requested=false,
    @charset="UTF-8",
    @content="It seems like you're referring to a \"Test Application Agent.\" Could you please provide more details about what you need? Are you looking for information on how to create one, its functions, or specific technologies related to application testing? Let me kn...",
    @role=:assistant>
  @prompt=#<ActiveAgent::ActionPrompt::Prompt:0x2af8 ...>
  @content_type="text/plain"
  @raw_response={...}>

# Message content
response.message.content # => "It seems like you're referring to a \"Test Application Agent.\" Could you please provide more details about what you need? Are you looking for information on how to create one, its functions, or specific technologies related to application testing? Let me know how I can assist you!"

This code parameterizes the ApplicationAgent with a set of params.

Configuration ​

Generation Provider Configuration ​

Active Agent supports multiple generation providers, including OpenAI, Anthropic, and Ollama. You can configure these providers in your Rails application using the config/active_agent.yml file. This file allows you to specify the API keys, models, and other settings for each provider. This is similar to Active Storage service configurations.

yaml
# This file is used to configure the Active Agent Generation Providers for different environments.
# Each provider can have its own settings, such as API keys and model configurations.
# Make sure to set the API keys in your Rails credentials for each generation provider before using them
# in your agent's `generate_with` config.

# region config_anchors
# region anthropic_anchor
anthropic: &anthropic
  service: "Anthropic"
  access_token: <%= Rails.application.credentials.dig(:anthropic, :access_token) %>
# endregion anthropic_anchor
# region openai_anchor
openai: &openai
  service: "OpenAI"
  access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>
# endregion openai_anchor
# region open_router_anchor
open_router: &open_router
  service: "OpenRouter"
  access_token: <%= Rails.application.credentials.dig(:open_router, :access_token) || Rails.application.credentials.dig(:open_router, :api_key) %>
# endregion open_router_anchor
# region ollama_anchor
ollama: &ollama
  service: "Ollama"
  access_token: ""
  host: "http://localhost:11434"
  model: "gemma3:latest"
  temperature: 0.7
# endregion ollama_anchor
# endregion config_anchors

# region config_development
development:
  # region openai_dev_config
  openai:
    <<: *openai
    model: "gpt-4o-mini"
    temperature: 0.7
  # endregion openai_dev_config
  # region open_router_dev_config
  open_router:
    <<: *open_router
    model: "qwen/qwen3-30b-a3b:free"
    temperature: 0.7
  # endregion open_router_dev_config
  # region ollama_dev_config
  ollama:
    <<: *ollama
  # endregion ollama_dev_config
  # region anthropic_dev_config
  anthropic:
    <<: *anthropic
  # endregion anthropic_dev_config
# endregion config_development

# region config_test
test:
  openai:
    <<: *openai
    model: "gpt-4o-mini"
    temperature: 0.7
  open_router:
    <<: *open_router
    model: "qwen/qwen3-30b-a3b:free"
    temperature: 0.7
  ollama:
    <<: *ollama
  anthropic:
    <<: *anthropic
# endregion config_test

Configuring custom hosts ​

You can also set the host and port for the generation provider if needed. For example, if you are using a local instance of Ollama or a cloud provider's hosted instance of OpenAI, you can set the host in your configuration file as shown in the example above.

Your First Agent ​

You can generate your first agent using the Rails generator. This will create a new agent class in the app/agents directory. It will also create a corresponding view template for the agent's actions as well as an Application Agent if you don't already have one.

bash
$ rails generate active_agent:agent TravelAgent search book confirm

The ApplicationAgent is the base class for all agents in your application, similar to how ApplicationController is the base class for all controllers.

The generator will create:

  • An agent class with the specified actions (search, book, and confirm)
  • View templates for each action in app/views/travel_agent/
  • An ApplicationAgent base class if one doesn't exist
ruby
class TravelAgent < ApplicationAgent
  MockUser = Data.define(:name) unless defined?(MockUser)
  before_action :set_user

  def search
    @departure = params[:departure]
    @destination = params[:destination]
    @results = params[:results] || []
    prompt(content_type: :html)
  end

  def book
    @flight_id = params[:flight_id]
    @passenger_name = params[:passenger_name]
    @confirmation_number = params[:confirmation_number]
    prompt(content_type: :text)
  end

  def confirm
    @confirmation_number = params[:confirmation_number]
    @passenger_name = params[:passenger_name]
    @flight_details = params[:flight_details]
    prompt(content_type: :text)
  end

  private

  def set_user
    @user = params[:user] || MockUser.new(name: "Guest")
  end
end

Agent action methods are used for building Prompt context objects with Message content from rendered Action Views.

Action Prompts ​

Each action is defined as a public instance method that can call prompt to build context objects that are used to generate responses. Learn more about Action Prompts and how they work →

Instruction messages ​

Prompt messages The views define: ​