Active Agent

Appearance

Generation ​

Execute AI generations synchronously or asynchronously using ActiveAgent's generation methods.

Synchronous ​

Execute immediately and return the response:

ruby
ApplicationAgent.prompt(message: "Hello").generate_now

Use prompt_now (alias: generate_now) for generations or embed_now for embeddings.

Asynchronous ​

Queue for background execution using Active Job:

ruby
ApplicationAgent.prompt(message: "Analyze this data").generate_later
ruby
ApplicationAgent.prompt(message: "Generate report").generate_later(
  queue: :reports,
  priority: 10,
  wait: 5.minutes
)

Use prompt_later (alias: generate_later) for generations or embed_later for embeddings. Background jobs run through ActiveAgent::GenerationJob and respect your Active Job configuration.

Configure queue name and adapter:

ruby
class MyAgent < ApplicationAgent
  self.generate_later_queue_name = :ai_tasks
end

Jobs use your Active Job adapter (Sidekiq, Resque, etc.).

Interfaces ​

Direct Generation ​

Generate without defining action methods:

ruby
response = ApplicationAgent.prompt(
  "What is 2+2?",
  temperature: 0.7
).generate_now

Parameterized Generation ​

Pass parameters to action methods:

ruby
class WelcomeAgent < ApplicationAgent
  def greet
    prompt(message: "Hello #{params[:name]}!")
  end
end
ruby
response = WelcomeAgent.with(name: "Alice").greet.generate_now

Action-Based Generation ​

Define reusable actions:

ruby
class SupportAgent < ApplicationAgent
  def help(topic)
    prompt(message: "Help with #{topic}")
  end
end
ruby
response = SupportAgent.help("authentication").generate_now

Inspecting Before Execution ​

Access prompt properties before generating:

ruby
generation = ApplicationAgent.prompt(message: "test")

This is useful for debugging, testing, or conditional execution.

Prompt Previews ​

Preview the final prompt without executing generation, including rendered templates and merged parameters:

ruby
preview = ApplicationAgent.prompt(
  instructions: "You are a helpful assistant",
  message: "What is 2+2?",
  temperature: 0.7
).prompt_preview

The preview returns markdown-formatted output with YAML frontmatter:

Markdown Preview

activeagent/test/docs/agents/generation_examples_test.rb:200

ruby
---
:temperature: 0.7
---
## Instructions
You are a helpful assistant
## Messages

### Message 1 (User)
What is 2+2?

TIP

Since previews include all parameters, messages, instructions, and tool definitions, hashing the preview can be used to build cache keys.

Response Objects ​

All generations return response objects:

ruby
response = ApplicationAgent.prompt(message: "Hello").generate_now
ruby
response.message           # Most Recent Message
response.messages          # Full Message Stack
response.parsed_json       # Extracted JSON, if Parsable

response.raw_request       # The most recent request in provider format
response.raw_response      # The most recent response in provider format
response.context           # The original context that was sent

# Usage statistics (see /actions/usage for details)
response.usage             # Normalized usage object across all providers
response.usage.input_tokens
response.usage.output_tokens
response.usage.total_tokens

For embeddings:

ruby
response = ApplicationAgent.embed(input: "text").embed_now
ruby
response.data         # Collection of Embedding Datum

response.raw_request  # The most recent request in provider format
response.raw_response # The most recent response in provider format
response.context      # The original context that was sent

# Usage statistics
response.usage             # Normalized usage object
response.usage.input_tokens

Next Steps ​