activeagent AGENTS.md

ActiveAgent - AI Code Generation Context

This file helps AI code generation tools (GitHub Copilot, Claude Code, Cursor, Codex, etc.) understand and work with the ActiveAgent codebase effectively.

Quick Reference

What	Where
Main entry point	lib/active_agent.rb
Base agent class	lib/active_agent/base.rb
Provider implementations	lib/active_agent/providers/
Agent concerns/mixins	lib/active_agent/concerns/
Agent-as-tool delegation	lib/active_agent/delegation/
Rails generators	lib/generators/active_agent/
Dashboard engine (actionagent gem)	actionagent/
Dashboard React source	actionagent/frontend/
Test suite	test/
Test Rails app	test/dummy/
Documentation source	docs/

Architecture Overview

ActiveAgent extends Rails MVC patterns to AI interactions:

Rails Pattern          →    ActiveAgent Pattern
Controllers            →    Agents (AI logic handlers)
Actions                →    Agent methods (return Generation objects)
Views                  →    Templates (ERB prompts in app/views/agents/)

Core Classes

1. ActiveAgent::Base - Base class all agents inherit from
2. ActiveAgent::Generation - Lazy execution wrapper (like ActionMailer::MessageDelivery)
3. ActiveAgent::Providers::BaseProvider - Abstract base for LLM providers

Execution Flow

# 1. Agent method is called → returns Generation (lazy)
generation = MyAgent.action_name

# 2. Execution happens only when:
generation.generate_now   # Synchronous
generation.prompt_later   # Background job (ActiveJob)

Key Patterns

Creating an Agent

class MyAgent < ApplicationAgent
  generate_with :openai, model: "gpt-4o"

  # Agent actions return Generation objects
  def analyze(text)
    @text = text  # Available in templates
    prompt(
      message: "Analyze this text",
      tools: [{
        name: "search",
        description: "Search for information",
        parameters: {
          type: "object",
          properties: {
            query: { type: "string", description: "Search query" }
          },
          required: ["query"]
        }
      }]
    )
  end

  # Tool method - name must match tool's `name` field
  def search(query:)
    SearchService.search(query)
  end
end