AGENTS.md · activeagents/activeagent

Sections

1. Public content boundary
2. Quick Reference
3. Architecture Overview
4. Key Patterns
5. Common Tasks
6. File Naming Conventions
7. Testing
8. Provider-Specific Notes
9. The dashboard: a second gem in this repo
10. Common Gotchas
11. Useful Commands
12. Cross-repo testing (solidagent)
13. Dependencies
14. Links

First lines (shown under the repo's MIT license)

# 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.

## Public content boundary

This is a public framework repository. Keep code, examples, tests, documentation,
issues, and PRs generic. Use independently written reproductions and synthetic
fixtures for behavior discovered while integrating a private application.

Do not include customer names, organization mappings, private repository URLs,
client source or business rules, agent instructions, evaluation prompts or
reports, records, credentials, screenshots, or logs from private projects.
Renaming identifiers in a copied customer artifact does not make it generic.
Keep each private customer's material within its own organization context.

## 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/` |
| Scenario evaluations (parser, runner, scorer, report, publisher) | `lib/active_agent/evals/` |
| Command line (`activeagent` executable) | `exe/activeagent`, `lib/active_agent/cli/` |
| 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

```ruby
# 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

```ruby
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
```

### Template Structure

Templates live in `app/views/agents/{name}/`, where `{name}` is the class name
underscored with the `_agent` suffix dropped — `TravelAgent` looks in
`app/views/agents/travel/` (`_prefixes` in `lib/active_agent/concerns/view.rb`
also searches the full underscored class name, `app/views/travel_agent/`):
- `instructions.md` - System prompt (shared across actions); `.md.erb` works too
- `{action_name}.md.erb` - Action-specific prompt template

### Provider Configuration

In `config/active_agent.yml`:
```yaml
development:
  openai:
    service: "OpenAI"
    access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>
    model: "gpt-4o-mini"
```

## Common Tasks

### Adding a New Agent

```bash
rails generate active_agent:agent AgentName action1 action2
```

Creates (the view directory drops the `_agent` suffix, the agent file keeps it):
- `app/agents/agent_name_agent.rb`
- `app/views/agents/agent_name/instructions.md`
- `app/views/agents/agent_name/action1.md.erb`
- `app/views/agents/agent_name/action2.md.erb`
- `test/agents/agent_name_agent_test.rb` and
  `test/agents/previews/agent_name_agent_preview.rb`

### Adding a Tool to an Agent

Tools are defined as hashes passed to `prompt()` and matched to methods by name:

```ruby
class MyAgent < ApplicationAgent
  generate_with :openai

  def my_action
    prompt(
      message: "Do something",
      tools: [{
        name: "my_tool",
        description: "Does something useful",
        parameters: {
          type: "object",
          properties: {
            param1: { type: "string", description: "First param" },
            param2: { type: "string", description: "Optional param" }
          },
          required: ["param1"]
        }
      }]
    )
  end

  # Method name matches tool's `name` - called automatically by LLM
  def my_tool(param1:, param2: "default")