Active Agent Documentation

ActiveAgent provides built-in redaction for common sensitive keys like password, secret, token, key, and credential.

Custom Redactions

You can extend the list of redacted keys via configuration:

ActiveAgent::Telemetry.configure do |config|
  config.redact_attributes += ["ssn", "credit_card"]
end

Capturing Message Bodies

By default, message bodies are not captured. If you need to capture request/response bodies for debugging, you must explicitly enable it. Use this with caution in production environments:

ActiveAgent::Telemetry.configure do |config|
  config.capture_bodies = true
end

You can guide agent behavior using system instructions via three methods:

• Class-level configuration: Using generate_with in the agent class.
• Template-level: Using an instructions.text file (or similar template) to define the persona.
• Action-level: Passing instructions: directly to the prompt method within an action.

# Class-level
class ApplicationAgent < ActiveAgent::Base
  generate_with :openai, instructions: "You are a helpful assistant."
end

# Action-level
def help
  prompt(instructions: "Answer the user's question clearly and briefly")
end

ActiveAgent offers two ways to handle messages:

Common Format (Recommended)

Use the unified prompt() interface. This is the preferred method because it normalizes messages across different providers, allowing you to switch providers without changing your code.

Native Format

Use native provider message structures when you need to access provider-specific features that are not covered by the common format.

Both formats are supported by all providers.

# Common Format (Portable)
agent.chat(prompt: [{ role: :user, content: "Hello" }])

# Native Format (Provider-specific)
agent.chat(messages: [{ role: "user", parts: [{ text: "Hello" }] }])

Actions are public methods defined within an agent that represent specific AI behaviors. They act as the interface for what your agent can do. An action typically performs one of two primary tasks:

1. Text Generation: Using the prompt() method to generate responses.
2. Vector Embeddings: Using the embed() method to create vector embeddings for semantic search.

Conceptually, actions are similar to controller actions in Ruby on Rails: they define the entry points for requests and dictate how the agent responds to them.

Active Agent supports two distinct approaches for web search via OpenAI:

1. Chat Completions API: Uses a specialized model (e.g., gpt-4o-search-preview) where web search is built-in and automatic. This is best for simple, straightforward queries and location-based searches.

2. Responses API: Uses standard models (e.g., gpt-4o, gpt-5) by explicitly providing the web_search_preview tool. This approach offers more control, such as configuring the search_context_size, and is required if you want to combine web search with other tools like image_generation.

Active Agent supports structured output to guarantee that AI responses match a specific JSON schema. You can configure this in your agent class using the response_format option.

Static Schema Files

If you define your schema in a JSON file under app/views/agents/[agent_name]/, you can load it automatically:

response_format: :json_schema  # Loads parse.json automatically

Model-Generated Schemas

You can also generate schemas dynamically from existing ActiveRecord or ActiveModel classes. This ensures your extraction logic mirrors your database structure and provides a single source of truth for validations.

Translation agents use ERB-based view templates to format the prompt sent to the AI. You can access parameters passed via .with using the params hash within the template.

translate: <%= params[:message] %>; to <%= params[:locale] %>

The OpenAI provider supports two distinct API modes. Choosing the right one depends on whether you need built-in tools or standard chat capabilities.

Responses API (Default)

• Use case: Accessing OpenAI-specific built-in tools like web search, image generation, and MCP integration.
• Recommended Models: gpt-5, gpt-4.1, o3.
• Configuration: This is the default mode. No extra configuration is needed to use it.

Chat Completions API

• Use case: Standard chat interactions, vision capabilities (GPT-4o), and using models that don't support the Responses API tools.
• Recommended Models: gpt-4o, gpt-4o-mini, gpt-4-turbo.
• Configuration: You must explicitly set api_version: :chat in your agent configuration.

The Mock provider is a testing-only provider designed to allow agent development without making actual API calls or incurring costs. It provides deterministic, predictable responses by converting input text into Pig Latin and generates random embeddings. This makes it ideal for offline development and CI/CD environments where network connectivity or API costs are concerns.

Key Features:

• Pig Latin Responses: Converts user messages to Pig Latin (e.g., "hello" becomes "ellohay") to ensure predictable output.
• Offline Capability: Works entirely without network connectivity.
• Standard Response Structure: Returns responses that follow the same schema as real providers, allowing for seamless testing of agent logic.