Active Agent

Install

Gemfile

gem 'activeagent', require: 'active_agent'

CLI

gem install activeagent

Rails Generator

After installing the gem, run the Rails installation generator:

$ rails generate active_agent:install

This will create:

create config/initializers/active_agent.rb
create config/active_agent.yml
create app/agents/application_agent.rb
create app/agents

• An initializer that uses default configurations

# config/initializers/active_agent.rbActiveAgent.load_configuration(Rails.root.join('config','active_agent.yml'))

• A YAML configuration file for provider settings, such as OpenAI and might include environment-specific configurations:

# config/active_agent.ymldevelopment:
openai:
service: "OpenAI"api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>model: "gpt-3.5-turbo"temperature: 0.7production:
openai:
service: "OpenAI"api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>model: "gpt-3.5-turbo"temperature: 0.7

• A base application agent class

# app/agents/application_agent.rbclassApplicationAgent < ActiveAgent::Baselayout'agent'defpromptsuper{ |format| format.text{renderplain: params[:message]}}end

• The agents directory structure

Agent

Create agents that take instructions, prompts, and perform actions

Rails Generator

To use the Rails Active Agent generator to create a new agent and the associated views for the requested action prompts:

$ rails generate active_agent:agent travel search book plans 

This will create:

create app/agents/travel_agent.rb
create app/views/agents/travel/search.text.erb
create app/views/agents/travel/book.text.erb
create app/views/agents/travel/plans.text.erb

The generator creates:

• An agent class inheriting from ApplicationAgent
• Text template views for each action
• Action methods in the agent class for processing prompts

Agent Actions

classTravelAgent < ApplicationAgentdefsearchprompt{ |format| format.text{renderplain: "Searching for travel options"}}enddefbookprompt{ |format| format.text{renderplain: "Booking travel plans"}}enddefplansprompt{ |format| format.text{renderplain: "Making travel plans"}}endend

Action Prompt

Action Prompt provides the structured interface for composing AI interactions through messages, actions/tools, and conversation context. Read more about Action Prompt

agent.prompt(message: "Find hotels in Paris",actions: [{name: "search",params: {query: "hotels paris"}}])

The prompt interface manages:

• Message content and roles (system/user/assistant)
• Action/tool definitions and requests
• Headers and context tracking
• Content types and multipart handling

Generation Provider

Generation Provider defines how prompts are sent to AI services for completion and embedding generation. Read more about Generation Providers

classVacationAgent < ActiveAgent::Base# Try not to get too model-rous with the parameters!generate_with:openai,model: "gpt-4",temperature: 0.7# Embed yourself in the joy of vector searchembed_with:openai,model: "text-embedding-ada-002"end

Providers handle:

• API client configuration
• Prompt/completion generation
• Stream processing
• Embedding generation
• Context management
• Error handling

Queue Generation

Active Agent also supports queued generation with Active Job using a common Generation Job interface.

Perform actions

Active Agents can define methods that are autoloaded as callable tools. These actions’ default schema will be provided to the agent’s context as part of the prompt request to the Generation Provider.

Actions

defget_cat_image_base64uri=URI("https://cataas.com/cat")response=Net::HTTP.get_response(uri)ifresponse.is_a?(Net::HTTPSuccess)image_data=response.bodyBase64.strict_encode64(image_data)elseraise"Failed to fetch cat image. Status code: #{response.code}"endendclassSupportAgent < ActiveAgentgenerate_with:openai,model: "gpt-4o",instructions: "Help people with their problems",temperature: 0.7defget_cat_imageprompt{ |format| format.text{renderplain: get_cat_image_base64}}endend

Prompts

Basic

Plain text prompt and response templates

HTML

Action Schema JSON

response = SupportAgent.prompt(‘show me a picture of a cat’).generate_now

response.message