Module: ActiveAgent

Extended by:
ActiveSupport::Autoload
Defined in:
lib/active_agent.rb,
lib/active_agent/base.rb,
lib/active_agent/railtie.rb,
lib/active_agent/service.rb,
lib/active_agent/version.rb,
lib/active_agent/collector.rb,
lib/active_agent/deprecator.rb,
lib/active_agent/generation.rb,
lib/active_agent/concerns/view.rb,
lib/active_agent/configuration.rb,
lib/active_agent/generation_job.rb,
lib/active_agent/concerns/rescue.rb,
lib/active_agent/concerns/preview.rb,
lib/active_agent/concerns/tooling.rb,
lib/active_agent/schema_generator.rb,
lib/active_agent/concerns/provider.rb,
lib/active_agent/concerns/queueing.rb,
lib/active_agent/concerns/callbacks.rb,
lib/active_agent/concerns/observers.rb,
lib/active_agent/concerns/streaming.rb,
lib/active_agent/providers/mock/_types.rb,
lib/active_agent/concerns/parameterized.rb,
lib/active_agent/providers/common/model.rb,
lib/active_agent/providers/common/usage.rb,
lib/active_agent/providers/mock/options.rb,
lib/active_agent/providers/mock/request.rb,
lib/active_agent/providers/mock_provider.rb,
lib/active_agent/providers/open_ai/_base.rb,
lib/active_agent/providers/_base_provider.rb,
lib/active_agent/providers/log_subscriber.rb,
lib/active_agent/providers/ollama/options.rb,
lib/active_agent/providers/common/response.rb,
lib/active_agent/providers/ollama_provider.rb,
lib/active_agent/providers/open_ai/options.rb,
lib/active_agent/inline_preview_interceptor.rb,
lib/active_agent/providers/anthropic/_types.rb,
lib/active_agent/providers/open_ai_provider.rb,
lib/active_agent/providers/anthropic/options.rb,
lib/active_agent/providers/anthropic/request.rb,
lib/active_agent/providers/anthropic_provider.rb,
lib/active_agent/providers/mock/messages/base.rb,
lib/active_agent/providers/mock/messages/user.rb,
lib/active_agent/providers/ollama/chat/_types.rb,
lib/active_agent/providers/open_router/_types.rb,
lib/active_agent/providers/ollama/chat/request.rb,
lib/active_agent/providers/open_ai/chat/_types.rb,
lib/active_agent/providers/open_router/options.rb,
lib/active_agent/providers/open_router/request.rb,
lib/active_agent/providers/anthropic/transforms.rb,
lib/active_agent/providers/common/messages/base.rb,
lib/active_agent/providers/common/messages/tool.rb,
lib/active_agent/providers/common/messages/user.rb,
lib/active_agent/providers/concerns/previewable.rb,
lib/active_agent/providers/mock/messages/_types.rb,
lib/active_agent/providers/open_ai/chat/request.rb,
lib/active_agent/providers/open_router_provider.rb,
lib/active_agent/providers/common/responses/base.rb,
lib/active_agent/providers/open_ai/chat_provider.rb,
lib/active_agent/providers/common/messages/_types.rb,
lib/active_agent/providers/common/messages/system.rb,
lib/active_agent/providers/common/responses/embed.rb,
lib/active_agent/providers/mock/embedding_request.rb,
lib/active_agent/providers/ollama/chat/transforms.rb,
lib/active_agent/providers/open_router/transforms.rb,
lib/generators/active_agent/agent/agent_generator.rb,
lib/active_agent/providers/common/responses/_types.rb,
lib/active_agent/providers/common/responses/format.rb,
lib/active_agent/providers/common/responses/prompt.rb,
lib/active_agent/providers/mock/messages/assistant.rb,
lib/active_agent/providers/ollama/embedding/_types.rb,
lib/active_agent/providers/open_ai/chat/transforms.rb,
lib/active_agent/providers/concerns/instrumentation.rb,
lib/active_agent/providers/ollama/embedding/request.rb,
lib/active_agent/providers/open_ai/embedding/_types.rb,
lib/active_agent/providers/open_ai/responses/_types.rb,
lib/active_agent/railtie/schema_generator_extension.rb,
lib/active_agent/providers/common/messages/assistant.rb,
lib/active_agent/providers/open_ai/embedding/request.rb,
lib/active_agent/providers/open_ai/responses/request.rb,
lib/active_agent/providers/concerns/exception_handler.rb,
lib/active_agent/providers/open_ai/responses_provider.rb,
lib/generators/active_agent/install/install_generator.rb,
lib/active_agent/providers/ollama/embedding/transforms.rb,
lib/active_agent/providers/open_router/requests/_types.rb,
lib/active_agent/providers/open_router/requests/plugin.rb,
lib/active_agent/providers/open_ai/embedding/transforms.rb,
lib/active_agent/providers/open_ai/responses/transforms.rb,
lib/active_agent/providers/concerns/tool_choice_clearing.rb,
lib/active_agent/providers/open_router/requests/prediction.rb,
lib/active_agent/providers/open_router/requests/plugins/_types.rb,
lib/active_agent/providers/open_router/requests/messages/_types.rb,
lib/active_agent/providers/open_router/requests/response_format.rb,
lib/active_agent/providers/open_router/requests/plugins/pdf_config.rb,
lib/active_agent/providers/open_router/requests/provider_preferences.rb,
lib/active_agent/providers/open_router/requests/messages/content/file.rb,
lib/active_agent/providers/open_router/requests/messages/content/_types.rb,
lib/active_agent/providers/open_router/requests/provider_preferences/_types.rb,
lib/active_agent/providers/open_router/requests/messages/content/files/_types.rb,
lib/active_agent/providers/open_router/requests/messages/content/files/details.rb,
lib/active_agent/providers/open_router/requests/provider_preferences/max_price.rb

Overview

ActiveAgent is a framework for building AI agents with Rails-like conventions.

It provides a structured approach to interacting with Large Language Models (LLMs) by offering a familiar interface inspired by ActionMailer. ActiveAgent handles prompt management, tool integration, streaming responses, and provider abstraction.

Core Concepts

  • Agents: Classes that inherit from Base and define prompts as methods

  • Prompts: Methods that return Generation objects for LLM interactions

  • Tools: Ruby methods that can be called by LLMs during generation

  • Providers: Abstraction layer for different LLM services (OpenAI, Anthropic, etc.)

  • Streaming: Real-time response handling via Server-Sent Events

Examples:

Creating a simple agent

class GreetingAgent < ActiveAgent::Base
  generate_with :openai

  def welcome(name:)
    @name = name
  end
end

# app/views/greeting_agent/welcome.md.erb
# Hello <%= @name %>! How can I help you today?

generation = GreetingAgent.welcome(name: "Alice")
response = generation.generate_now

Using tools

class WeatherAgent < ActiveAgent::Base
  generate_with :anthropic

  tool def get_weather(location:)
    # Call weather API
    { temperature: 72, condition: "sunny" }
  end

  def forecast(location:)
    @location = location
  end
end

Streaming responses

class ChatAgent < ActiveAgent::Base
  generate_with :openai

  def chat(message:)
    @message = message
  end
end

ChatAgent.chat(message: "Tell me a story").generate do |stream|
  stream.on_text_delta { |delta| print delta }
  stream.on_tool_call { |name, args| puts "Calling #{name}" }
end

See Also:

Defined Under Namespace

Modules: Callbacks, Generators, Observers, Parameterized, Previews, Provider, Providers, Queueing, Rescue, SchemaGenerator, Streaming, Tooling, View Classes: Base, Collector, Configuration, Generation, GenerationJob, InlinePreviewInterceptor, Preview, Railtie, SchemaGeneratorRailtie, Service

Constant Summary collapse

VERSION = 
"1.0.1"

Class Method Summary collapse

Class Method Details

.configuration ⇒ Configuration

Returns the global configuration instance.

Creates a new Configuration instance if one doesn’t exist.

Examples:

Access configuration

ActiveAgent.configuration.retries  # => true

Returns:



382
383
384
 
# File 'lib/active_agent/configuration.rb', line 382

def self.configuration
  @configuration ||= Configuration.new
end

.configuration_load(filename) ⇒ Configuration

Note:

This method is typically called once during application initialization. Store API keys in Rails credentials rather than directly in the YAML file.

Loads and sets the global configuration from a YAML file.

Reads configuration from the specified file and sets it as the global configuration instance. This is an alternative to using configure with a block and is the recommended approach for managing provider-specific settings.

The YAML file supports ERB templating, environment-specific sections, and YAML anchors for reusing common configuration blocks across providers.

Examples:

Basic usage in Rails initializer

# config/initializers/activeagent.rb
ActiveAgent.configuration_load(Rails.root.join("config/activeagent.yml"))

Complete workflow

# 1. Create config/activeagent.yml with provider settings
# 2. Load in initializer:
ActiveAgent.configuration_load("config/activeagent.yml")

# 3. Use in your agents:
class MyAgent < ActiveAgent::Base
  generate_with :openai  # Automatically uses config from YAML
end

Accessing loaded provider configuration

ActiveAgent.configuration[:openai]
# => { "service" => "OpenAI", "model" => "gpt-4o-mini", "temperature" => 0.7, ... }

Parameters:

  • filename (String) —

    Path to the YAML configuration file

Returns:

See Also:



455
456
457
 
# File 'lib/active_agent/configuration.rb', line 455

def self.configuration_load(filename)
  @configuration = Configuration.load(filename)
end

.configure {|config| ... } ⇒ Configuration

Configures ActiveAgent with a block.

Yields the global configuration instance to the provided block, allowing settings to be modified. This is the recommended way to configure ActiveAgent.

Examples:

Custom logger (non-Rails environments)

ActiveAgent.configure do |config|
  config.logger = Logger.new(STDOUT)
  config.logger.level = Logger::DEBUG
end

Yields:

  • (config) —

    Yields the configuration instance

Yield Parameters:

Returns:



401
402
403
404
 
# File 'lib/active_agent/configuration.rb', line 401

def self.configure
  yield configuration if block_given?
  configuration
end

.deprecator ⇒ Object

:nodoc:



4
5
6
 
# File 'lib/active_agent/deprecator.rb', line 4

def self.deprecator # :nodoc:
  @deprecator ||= ActiveSupport::Deprecation.new
end

.eager_load! ⇒ void

Note:

In Rails applications, this is automatically called when config.eager_load is true (default in production).

This method returns an undefined value.

Eagerly loads all ActiveAgent components and descendant agent classes.

This method is called during Rails initialization in production mode to load all code upfront, improving request performance and catching load-time errors early.

Examples:

Manual eager loading

ActiveAgent.eager_load!


124
125
126
127
128
129
130
 
# File 'lib/active_agent.rb', line 124

def eager_load!
  super

  Base.descendants.each do |agent|
    agent.eager_load! unless agent.abstract?
  end
end

.reset_configuration! ⇒ Configuration

Resets the global configuration to default values.

Creates a new Configuration instance with all defaults restored. Useful for testing or resetting state.

Examples:

ActiveAgent.reset_configuration!

Returns:



415
416
417
 
# File 'lib/active_agent/configuration.rb', line 415

def self.reset_configuration!
  @configuration = Configuration.new
end