Providers

Providers connect your agents to AI services through a unified interface. Switch between OpenAI, Anthropic, local models, or testing mocks without changing agent code.

Available Providers

Anthropic

class AnthropicAgent < ApplicationAgent
  generate_with :anthropic, model: "claude-sonnet-4-5-20250929"

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

Ollama

class OllamaAgent < ApplicationAgent
  generate_with :ollama, model: "deepseek-r1:latest"

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

OpenAI

class OpenAIAgent < ApplicationAgent
  generate_with :open_ai, model: "gpt-4o-mini"

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

OpenRouter

class OpenRouterAgent < ApplicationAgent
  generate_with :open_router, model: "openrouter/auto"

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

Mock

class MockAgent < ApplicationAgent
  generate_with :mock

  # @return [ActiveAgent::Generation]
  def ask
    prompt(message: params[:message])
  end
end

Choosing a Provider

Anthropic

Best for: Complex reasoning, coding tasks, long context

Claude Sonnet 4.5, Haiku 4.5, and Opus 4.1 models. Extended thinking mode for deep analysis. 200K-1M context windows with up to 64K token outputs.

Choose when: You need exceptional reasoning, prefer Claude's outputs, or require very long context windows. Strong at coding and analysis.

Ollama

Best for: Local inference, privacy-sensitive data, development without API costs

Run Llama 3, Mistral, Gemma, CodeLlama, and other open models locally. No API keys required. Full control over data.

Choose when: Data cannot leave your infrastructure, you're developing offline, or you want to avoid API costs. Requires local setup.

OpenAI

Best for: Production applications, advanced reasoning, vision tasks

GPT-4o, GPT-4.1, GPT-5, and o3 models. Two APIs available: Responses API (default) with built-in web search, image generation, and MCP integration, or Chat Completions API for standard interactions. 128K-200K context windows.

Choose when: You need reliable, high-quality responses with strong reasoning. Vision support and structured output work well. Azure OpenAI compatible.

OpenRouter

Best for: Multi-model flexibility, cost optimization, experimentation

Access 200+ models from OpenAI, Anthropic, Google, Meta, and more through one API. Intelligent routing, automatic fallbacks, multimodal support, PDF processing.

Choose when: You want to compare models, need fallback options, or want flexible provider switching. Good for reducing vendor lock-in.

Mock

Best for: Testing, development, offline work

Predictable responses (pig latin conversion) with no API calls. Simulates real provider behavior for testing agent logic.

Choose when: Writing tests, developing without network access, or avoiding API costs during development.

Configuration

Configuration applies in order of precedence:

# 1. Global config (config/active_agent.yml)
# temperature: 0.7

class MyAgent < ApplicationAgent
  # 2. Agent-level config
  generate_with :openai, temperature: 0.5

  def analyze
    # 3. Runtime config (highest precedence)
    prompt(temperature: 0.9)
  end
end

For environment-specific settings and advanced configuration, see Configuration.

Response Objects

All providers return standardized response objects:

response = ApplicationAgent.prompt(message: "Hello").generate_now

# Access response content
content = response.message.content

# Access response role
role = response.message.role

# Access all messages from conversation
messages = response.messages

# Access request context
context = response.context

# Access usage statistics (if available)
usage = response.usage
input_tokens = response.usage.input_tokens
output_tokens = response.usage.output_tokens

Response Example

activeagent/test/docs/framework/providers_examples_test.rb:81

#<ActiveAgent::Providers::Common::Responses::Prompt {
  "context": {
    "model": "gpt-4o-mini",
    "messages": [
      "Hello"
    ],
    "trace_id": "81f0ca0b-bb1c-4b7d-a521-d3d764ba8a32"
  },
  "raw_request": {
    "model": "gpt-4o-mini",
    "input": "Hello"
  },
  "raw_response": {
    "id": "resp_0d635781a91856a60068fe732d41b081948926c602fc82e8e2",
    "created_at": 1761506093,
    "model": "gpt-4o-mini-2024-07-18",
    "object": "response",
    "output": [
      {
        "id": "msg_0d635781a91856a60068fe732dbf58819494749e734ff8f8d2",
        "content": [
          {
            "text": "Hello! How can I assist you today?",
            "type": "output_text"
          }
        ],
        "role": "assistant",
        "status": "completed",
        "type": "message"
      }
    ],
    "parallel_tool_calls": true,
    "temperature": 1.0,
    "tool_choice": "auto",
    "top_p": 1.0,
    "background": false,
    "service_tier": "default",
    "status": "completed",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "medium"
    },
    "top_logprobs": 0,
    "truncation": "disabled",
    "usage": {
      "input_tokens": 8,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 10,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 18
    },
    "billing": {
      "payer": "developer"
    },
    "store": true
  },
  "usages": [
    "#<ActiveAgent::Providers::Common::Usage {\n  \"input_tokens\": 8,\n  \"output_tokens\": 10,\n  \"total_tokens\": 18,\n  \"cached_tokens\": 0,\n  \"reasoning_tokens\": 0,\n  \"provider_details\": {\n    \"input_tokens_details\": {\n      \"cached_tokens\": 0\n    },\n    \"output_tokens_details\": {\n      \"reasoning_tokens\": 0\n    }\n  }\n}>"
  ],
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I assist you today?"
    }
  ]
}>

Common attributes:

• message / messages - Response content and conversation history
• usage - Normalized token usage statistics (see Usage Statistics)
• raw_request / raw_response - Provider-specific data for debugging
• context - Original request sent to provider

Embedding responses use data instead of message:

response = generation.embed_now
vector = response.data.first[:embedding]  # Array of floats

For embedding documentation including similarity search and batch processing, see Embeddings.