Class: ActiveAgent::Base Abstract

Inherits:
AbstractController::Base
  • Object
show all
Includes:
AbstractController::AssetPaths, AbstractController::Caching, AbstractController::Callbacks, AbstractController::Helpers, AbstractController::Logger, AbstractController::Rendering, AbstractController::Translation, Callbacks, Observers, Parameterized, Previews, Provider, Queueing, Rescue, Streaming, Tooling, View
Defined in:
lib/active_agent/base.rb

Overview

This class is abstract.

Provides AI-powered agents with prompt generation, tool calling, and conversation management.

Examples:

Basic agent

class MyAgent < ActiveAgent::Base
  generate_with :openai, model: "gpt-4"

  def greet
    prompt instructions: "Greet the user warmly"
  end
end

Constant Summary collapse

PROTECTED_OPTIONS = 
%i[exception_handler stream_broadcaster tools_function]
PROTECTED_IVARS = 
AbstractController::Rendering::DEFAULT_PROTECTED_INSTANCE_VARIABLES + [ :@_action_has_layout ]

Constants included from Provider

Provider::PROVIDER_SERVICE_NAMES_REMAPS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from View

#_prefixes, #embed_view_input, #prompt_view_instructions, #prompt_view_message, #prompt_view_schema

Methods included from Tooling

#tools_function

Methods included from Rescue

#handle_exceptions

Constructor Details

#initialize ⇒ Base

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Base.



170
171
172
173
174
 
# File 'lib/active_agent/base.rb', line 170

def initialize # :nodoc:
  super
  self.prompt_options = (self.class.prompt_options&.deep_dup || {}).except(:trace_id)
  self.embed_options  = (self.class.embed_options&.deep_dup  || {}).except(:trace_id)
end

Instance Attribute Details

#agent_name ⇒ String

Agent name used as a path for view lookup.

Returns:

  • (String) —

    agent name or “anonymous” for anonymous agents



179
180
181
 
# File 'lib/active_agent/base.rb', line 179

def agent_name
  @agent_name ||= self.class.anonymous? ? "anonymous" : self.class.name.underscore
end

#embed_options ⇒ Hash

Action-level embed options merged with agent embed options.

Returns:

  • (Hash) 


167
 
# File 'lib/active_agent/base.rb', line 167

attr_internal :embed_options

#prompt_options ⇒ Hash

Action-level prompt options merged with agent prompt options.

Returns:

  • (Hash) 


162
 
# File 'lib/active_agent/base.rb', line 162

attr_internal :prompt_options

Class Method Details

.default(value = nil) ⇒ Hash Also known as: default_params=

Sets default parameters applied to all actions unless overridden.

Examples:

default temperature: 0.7, max_tokens: 1000

Parameters:

  • value (Hash, nil) (defaults to: nil) —

    parameters to merge, or nil to return current defaults

Returns:

  • (Hash) 


85
86
87
88
 
# File 'lib/active_agent/base.rb', line 85

def default(value = nil)
  self.default_params = default_params.merge(value).freeze if value
  default_params
end

.embed_with(provider_reference, **agent_options) ⇒ void

This method returns an undefined value.

Configures embedding provider and options for embedding generation.

Examples:

embed_with :openai, model: "text-embedding-3-large"

Parameters:

  • provider_reference (Symbol, String) —

    embedding provider (:openai, :anthropic, etc.)

  • agent_options (Hash) —

    configuration options for embedding generation



126
127
128
129
130
131
132
133
 
# File 'lib/active_agent/base.rb', line 126

def self.embed_with(provider_reference, **agent_options)
  self.embed_provider = provider_reference

  global_options    = provider_config_load(provider_reference)
  inherited_options = self.embed_options || {}

  self.embed_options = global_options.merge(inherited_options).merge(agent_options)
end

.generate_with(provider_reference, **agent_options) ⇒ void

This method returns an undefined value.

Configures generation provider and options for prompt generation.

Options are merged with global provider config and inherited parent class options. Instructions are never inherited from parent classes.

Examples:

generate_with :openai, model: "gpt-4", temperature: 0.7

Parameters:

  • provider_reference (Symbol, String) —

    generation provider (:openai, :anthropic, etc.)

  • agent_options (Hash) —

    configuration options shared across actions



103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/active_agent/base.rb', line 103

def self.generate_with(provider_reference, **agent_options)
  self.prompt_provider = provider_reference

  global_options    = provider_config_load(provider_reference)
  inherited_options = (self.prompt_options || {}).except(:instructions) # Don't inherit instructions from parent

  # Different Service, different APIs — discard all inherited options
  # to prevent parent provider config (host, api_key, etc.) leaking through
  if global_options[:service] != inherited_options[:service]
    inherited_options = {}
  end

  self.prompt_options = global_options.merge(inherited_options).merge(agent_options)
end

Instance Method Details

#action_methods ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



294
295
296
 
# File 'lib/active_agent/base.rb', line 294

def action_methods
  super - ActiveAgent::Base.public_instance_methods(false).map(&:to_s) - [ action_name ]
end

#controller_path ⇒ Object 



157
 
# File 'lib/active_agent/base.rb', line 157

alias_method :controller_path, :agent_name

#embed(input = nil, **options) ⇒ void

This method returns an undefined value.

Merges action-level parameters into embedding context.

Examples:

With direct input

embed "Text to embed", model: "text-embedding-3-large"

With template

embed locals: { text: "Custom text" }

Parameters:

  • input (String, Array<String>, nil) (defaults to: nil) —

    text to embed

  • options (Hash) —

    parameters to merge into embedding context



234
235
236
237
 
# File 'lib/active_agent/base.rb', line 234

def embed(input = nil, **options)
  new_options = { input: }.compact_blank.merge!(options)
  embed_options.merge!(new_options)
end

#logger ⇒ Logger?

Logger instance for agent operations.

Defaults to Rails.logger when used in Rails applications. Must conform to Log4r or Ruby Logger interface.

Returns:

  • (Logger, nil) 


65
 
# File 'lib/active_agent/base.rb', line 65

cattr_accessor :logger

#preview_prompt ⇒ String, Hash

Generates a preview of the prompt without executing generation.

Useful for debugging and inspecting the final prompt that would be sent to the provider, including rendered templates and merged parameters.

Returns:

  • (String, Hash) —

    preview format depends on provider implementation

Raises:

  • (RuntimeError) —

    if no prompt provider is configured



267
268
269
270
271
272
273
 
# File 'lib/active_agent/base.rb', line 267

def preview_prompt
  fail "Prompt Provider not Configured" unless prompt_provider_klass

  parameters = prepare_prompt_parameters

  prompt_provider_klass.new(**parameters).preview
end

#process(method_name, *args, **kwargs) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Processes an agent action with ActiveSupport::Notifications instrumentation.

Actions are triggered externally via Agent.action_name.generate_now or internally through tool calls during AI generation workflows.

Parameters:

  • method_name (Symbol, String) —

    action method to process

  • args (Array)
  • kwargs (Hash) 


193
194
195
196
197
198
199
 
# File 'lib/active_agent/base.rb', line 193

def process(method_name, *args, **kwargs)
  payload = { agent: self.class.name, action: method_name, args:, kwargs: }

  ActiveSupport::Notifications.instrument("process.active_agent", payload) do
    super
  end
end

#process_embed ⇒ ActiveAgent::Providers::Response

Executes embedding generation using configured provider and options.

Templates are rendered as late as possible to allow local overrides.

Returns:

  • (ActiveAgent::Providers::Response)

Raises:

  • (RuntimeError) —

    if no embed provider is configured



281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/active_agent/base.rb', line 281

def process_embed
  fail "Embed Provider not Configured" unless embed_provider_klass

  run_callbacks(:generation) do
    run_callbacks(:embedding) do
      parameters = prepare_embed_parameters

      embed_provider_klass.new(**parameters).embed
    end
  end
end

#process_prompt ⇒ ActiveAgent::Providers::Response Also known as: process_prompt!

Executes prompt generation using configured provider and options.

Triggered by generate_now or generate_later workflows. Templates are rendered as late as possible to allow local overrides.

Returns:

  • (ActiveAgent::Providers::Response)

Raises:

  • (RuntimeError) —

    if no prompt provider is configured



246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/active_agent/base.rb', line 246

def process_prompt
  fail "Prompt Provider not Configured" unless prompt_provider_klass

  run_callbacks(:generation) do
    run_callbacks(:prompting) do
      parameters = prepare_prompt_parameters

      prompt_provider_klass.new(**parameters).prompt
    end
  end
end

#prompt(*messages, **options) ⇒ void

This method returns an undefined value.

Merges action-level parameters into prompt context.

Processing is deferred until execution to allow local overrides.

Examples:

def my_action
  prompt "User message", temperature: 0.8, instructions: "Be creative"
end

Parameters:

  • messages (Array<String, Hash>) —

    message strings or hashes to add to conversation

  • options (Hash) —

    parameters to merge into prompt context



213
214
215
216
217
218
219
220
221
 
# File 'lib/active_agent/base.rb', line 213

def prompt(*messages, **options)
  # Extract message/messages from options and add to messages array
  messages += options.extract!(:message, :messages).values.flatten.compact

  # Extract image and document attachments
  messages += options.extract!(:image, :document).map { |k, v| { k => v } }

  prompt_options.merge!({ messages: }.compact_blank.merge!(options))
end