OpenAI Provider

The OpenAI provider enables integration with GPT models including GPT-5, GPT-4.1, GPT-4o, o3, and the GPT-4 family. It offers two distinct APIs: the Responses API (default) with built-in tools for web search, image generation, and MCP integration, and the traditional Chat Completions API for standard chat interactions.

Responses API vs Chat Completions API

The provider uses the Responses API by default for access to OpenAI-specific built-in tools. To use the Chat Completions API instead, set api_version: :chat in your agent configuration.

Responses API (default):

ruby

class ResponsesAgent < ApplicationAgent
  generate_with :openai,
    model: "gpt-4.1",
    api_version: :responses

  def chat
    prompt(message: params[:message])
  end
end

Chat Completions API:

ruby

class ChatAgent < ApplicationAgent
  generate_with :openai,
    model: "gpt-4o-mini",
    api_version: :chat

  def chat
    prompt(message: params[:message])
  end
end

Configuration

Basic Setup

Configure OpenAI in your agent:

ruby

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

  def ask
    prompt(message: params[:message])
  end
end

Basic Usage Example

ruby

response = Providers::OpenAIAgent.with(
  message: "What is the Model Context Protocol?"
).ask.generate_now

Response Example

Configuration File

Set up OpenAI credentials in config/active_agent.yml:

yaml

openai: &openai
  service: "OpenAI"
  access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>

Environment Variables

Alternatively, use environment variables:

bash

OPENAI_ACCESS_TOKEN=your-api-key
OPENAI_ORGANIZATION_ID=your-org-id  # Optional

Supported Models

OpenAI provides two distinct APIs with different model sets and capabilities. For the complete list of available models, see OpenAI's Models Documentation.

Responses API Models (Recommended)

The Responses API provides access to built-in tools and advanced features. These models support web search, image generation, and MCP integration:

Model	Description	Context Window	Best For
GPT-5	Most advanced model with all built-in tools	128K tokens	Complex reasoning, multi-tool tasks
GPT-4.1	Enhanced GPT-4 with tool support	128K tokens	Advanced analysis with tools
GPT-4.1-mini	Efficient version with tool support	128K tokens	Fast tool-enabled tasks
o3	Advanced reasoning model	200K tokens	Deep reasoning, complex problems
o4-mini	Compact reasoning model	128K tokens	Efficient reasoning tasks

Recommended model identifiers:

gpt-5 - Best for complex tasks requiring multiple tools
gpt-4.1 - Best for advanced reasoning with tool support
o3 - Best for specialized reasoning tasks

TIP

Use the Responses API (default) for access to OpenAI-specific built-in tools like web search, image generation, and MCP integration.

Chat Completions API Models

Standard chat models compatible with most providers. Use api_version: :chat to access these:

Model	Description	Context Window	Best For
GPT-4o	Most capable with vision	128K tokens	Vision analysis, complex reasoning
GPT-4o-mini	Fast, cost-effective	128K tokens	Most applications, embeddings
GPT-4o-search-preview	GPT-4o with web search	128K tokens	Research, current information
GPT-4o-mini-search-preview	Mini with web search	128K tokens	Fast research tasks
GPT-4 Turbo	Latest GPT-4	128K tokens	Advanced analysis
GPT-4	Original GPT-4	8K tokens	General reasoning
GPT-3.5 Turbo	Fast and economical	16K tokens	Simple tasks, high volume

WARNING

Search-preview models in Chat API provide web search but with different configuration than Responses API built-in tools. For consistent tool usage, prefer the Responses API.

Provider-Specific Parameters

Required Parameters

model - Model identifier (e.g., "gpt-4o", "gpt-3.5-turbo")

Sampling Parameters

temperature - Controls randomness (0.0 to 2.0, default: 1.0)
max_tokens - Maximum tokens in response
top_p - Nucleus sampling parameter (0.0 to 1.0)
frequency_penalty - Penalize frequent tokens (-2.0 to 2.0)
presence_penalty - Penalize new topics (-2.0 to 2.0)
seed - For deterministic outputs (integer)

Response Configuration

response_format - Output format ({ type: "json_object" } or { type: "text" })
max_tokens - Maximum tokens to generate

Tools & Functions

tools - Array of built-in tools for Responses API
- web_search_preview - Enable web search
- image_generation - Enable DALL-E image generation
- mcp - Enable MCP integration
tool_choice - Control tool usage ("auto", "required", "none", or specific tool)
parallel_tool_calls - Allow parallel tool execution (boolean)
mcp_servers - Array of MCP server configurations (max 20)

Embeddings

embedding_model - Embedding model identifier (e.g., "text-embedding-3-large")
dimensions - Reduced dimensions for embeddings (text-embedding-3-* models only)

API Configuration

api_version - API version to use (:responses [default] or :chat)
organization_id - OpenAI organization ID
project_id - OpenAI project ID for usage tracking

Client Configuration

access_token - OpenAI API key (also accepts api_key)
host - Custom API endpoint URL (for Azure OpenAI)
request_timeout - Request timeout in seconds (default: 30)
max_retries - Maximum retry attempts (default: 3)

Advanced Options

stream - Enable streaming responses (boolean)
web_search - Web search configuration for Chat API with search-preview models
web_search_options - Alternative parameter name for web search in Chat API

Built-in Tools

OpenAI's Responses API (the default) provides access to powerful built-in tools that extend the model's capabilities beyond text generation.

Using Responses API

The Responses API is used by default. Built-in tools work with compatible Responses API models (GPT-5, GPT-4.1, o3, etc.). To switch to Chat Completions API, set api_version: :chat.

Web Search

The Responses API enables web search capabilities using the web_search_preview tool for real-time information retrieval:

ruby

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

  def search_with_tools
    @query = params[:query]
    @context_size = params[:context_size] || "medium"

    prompt(
      message: @query,
      options: {
        use_responses_api: true,
        tools: [
          {
            type: "web_search_preview",
            search_context_size: @context_size
          }
        ]
      }
    )
  end
end

Best Practice

Web search is particularly useful for questions requiring current information, recent events, or real-time data that's beyond the model's training cutoff.

Image Generation

The Responses API can generate and edit images using the image_generation tool, powered by DALL-E:

ruby

class MultimodalAgent < ApplicationAgent
  generate_with :openai, model: "gpt-4o", temperature: nil

  def create_image
    @description = params[:description]
    @size = params[:size] || "1024x1024"
    @quality = params[:quality] || "high"

    prompt(
      message: "Generate an image: #{@description}",
      options: {
        use_responses_api: true,
        tools: [
          {
            type: "image_generation",
            size: @size,
            quality: @quality,
            format: "png"
          }
        ]
      }
    )
  end
end

WARNING

Image generation is only available with Responses API models. Chat Completions API models do not support this built-in tool.

MCP (Model Context Protocol) Integration

The Responses API supports connecting to external services and MCP servers for extended functionality:

Built-in Connectors:

ruby

class McpIntegrationAgent < ApplicationAgent
  generate_with :openai, model: "gpt-5"

  def search_cloud_storage
    @query = params[:query]
    @service = params[:service] || "dropbox"
    @auth_token = params[:auth_token]

    prompt(
      message: "Search for: #{@query}",
      options: {
        use_responses_api: true,
        tools: [ build_connector_tool(@service, @auth_token) ]
      }
    )
  end

  private

  def build_connector_tool(service, auth_token)
    {
      type: "mcp",
      server_label: "connector_#{service}",
      authorization: { type: "bearer", token: auth_token }
    }
  end
end

Custom MCP Servers:

ruby

class CustomMcpAgent < ApplicationAgent
  generate_with :openai, model: "gpt-5"

  def use_custom_mcp
    @query = params[:query]
    @server_url = params[:server_url]
    @allowed_tools = params[:allowed_tools]

    prompt(
      message: @query,
      options: {
        use_responses_api: true,
        tools: [
          {
            type: "mcp",
            server_label: "Custom MCP Server",
            server_url: @server_url,
            server_description: "Custom MCP server for specialized tasks",
            require_approval: "always",
            allowed_tools: @allowed_tools
          }
        ]
      }
    )
  end
end

Available MCP Connectors:

connector_dropbox - Dropbox file access
connector_gmail - Gmail integration
connector_googlecalendar - Google Calendar
connector_googledrive - Google Drive access
connector_microsoftteams - Microsoft Teams
connector_outlookcalendar - Outlook Calendar
connector_outlookemail - Outlook Email
connector_sharepoint - SharePoint access
GitHub MCP - Use server URL: https://api.githubcopilot.com/mcp/

MCP Best Practices

Limit to 20 MCP servers maximum per request
Use built-in connectors for popular services
Implement proper authentication for custom servers
Monitor rate limits when using external MCP services

Tool Configuration Example

Here's how built-in tools are configured in the prompt options:

ruby

tools_config = [
  {
    type: "web_search_preview",
    search_context_size: "high",
    user_location: {
      country: "US",
      city: "San Francisco"
    }
  },
  {
    type: "image_generation",
    size: "1024x1024",
    quality: "high",
    format: "png"
  },
  {
    type: "mcp",
    server_label: "GitHub",
    server_url: "https://api.githubcopilot.com/mcp/",
    require_approval: "never"
  }
]

example_options = {
  use_responses_api: true,
  model: "gpt-5",
  tools: tools_config
}

Configuration Output

Vision Capabilities

GPT-4o and GPT-4o-mini models support image analysis through the Chat Completions API. Provide image URLs or base64-encoded images in your prompts.

Supported Models:

GPT-4o (Chat API)
GPT-4o-mini (Chat API)

Agent Configuration:

ruby

class VisionAgent < ApplicationAgent
  generate_with :openai,
    model: "gpt-4o",
    api_version: :chat

  def analyze_image
    prompt(message: params[:message])
  end
end

TIP

Vision capabilities require passing image data as part of the message content structure. See the integration tests for detailed examples of image analysis.

API Version Requirement

Vision capabilities are only available with Chat Completions API models (GPT-4o, GPT-4o-mini). Set api_version: :chat in your configuration.

Structured Output

OpenAI provides native structured output support with strict schema validation. For comprehensive documentation, see the Structured Output guide.

OpenAI-Specific Features:

Strict Mode - Guarantees output format conformance with strict: true
Native JSON Schema Support - Built into the API, not just prompt engineering
Model-Level Validation - The model enforces the schema during generation

Basic Example:

ruby

class DataExtractionAgent < ApplicationAgent
  generate_with :openai,
    model: "gpt-4o-mini",
    response_format: { type: "json_object" }

  def extract_colors
    prompt("Return a JSON object with three primary colors in an array named 'colors'.")
  end
end

ruby

response = DataExtractionAgent.extract_colors.generate_now
colors = response.message.parsed_json

TIP

OpenAI's strict mode ensures the model cannot produce invalid output, making it ideal for applications requiring guaranteed schema conformance.

Embeddings

Generate high-quality text embeddings using OpenAI's embedding models. For general embedding usage, see the Embeddings Documentation.

Available Embedding Models

Model	Dimensions	Cost per 1M tokens	Best For
text-embedding-3-large	3072 (configurable)	$0.13	Highest quality, semantic search
text-embedding-3-small	1536 (configurable)	$0.02	Good balance, most applications
text-embedding-ada-002	1536 (fixed)	$0.10	Legacy support

For detailed model comparisons and benchmarks, see OpenAI's Embeddings Documentation.

Configuration

ruby

class EmbeddingAgent < ApplicationAgent
  embed_with :openai, model: "text-embedding-3-small"
end

ruby

class EmbeddingAgent < ApplicationAgent
  embed_with :openai, model: "text-embedding-3-small"
end

response = EmbeddingAgent.embed("Your text to embed").embed_now
embedding_vector = response.data.first[:embedding]  # Array of floats

Dimension Reduction

OpenAI's text-embedding-3 models support configurable dimensions for cost optimization:

ruby

class DimensionReducedAgent < ApplicationAgent
  embed_with :openai,
    model: "text-embedding-3-small",
    dimensions: 512  # Reduce from default 1536
end

OpenAI-Specific Feature

Dimension reduction (256-3072 for text-embedding-3-large, 256-1536 for text-embedding-3-small) reduces storage costs while maintaining good performance. This feature is unique to OpenAI's text-embedding-3 models.

For similarity search, batch processing, and advanced embedding patterns, see the Embeddings Documentation.

Azure OpenAI

ActiveAgent supports Azure OpenAI Service with custom endpoint configuration.

Configuration

ruby

class AzureAgent < ApplicationAgent
  generate_with :openai,
    access_token: Rails.application.credentials.dig(:azure, :api_key),
    host: "https://your-resource.openai.azure.com",
    api_version: "2024-02-01",
    model: "your-deployment-name"
end

Key Differences

Deployment Names: Use your Azure deployment name instead of OpenAI model names
API Versions: Azure uses date-based API versions (e.g., "2024-02-01")
Authentication: Use Azure-specific API keys from your Azure portal
Endpoints: Custom host URL based on your Azure resource name

TIP

Azure OpenAI may lag behind OpenAI's latest models and features. Check Azure's model availability before planning deployments.

Error Handling

OpenAI-specific errors can be handled using standard ActiveAgent error handling patterns:

ruby

class RobustAgent < ApplicationAgent
  generate_with :openai,
    model: "gpt-4o-mini",
    max_retries: 3,
    request_timeout: 30

  # Note: OpenAI::RateLimitError is only available when the OpenAI gem is loaded
  # This is a demonstration of how to handle errors
end

Common OpenAI Error Types:

OpenAI::RateLimitError - Rate limit exceeded
OpenAI::APIError - General API error
OpenAI::TimeoutError - Request timeout
OpenAI::AuthenticationError - Invalid API key
OpenAI::InvalidRequestError - Malformed request

For comprehensive error handling strategies, retry logic, and best practices, see the Error Handling Documentation.

Providers Overview - Compare all available providers
Getting Started - Complete setup guide
Configuration - Environment-specific settings
Tools - Function calling and MCP integration
Structured Output - JSON schema validation
Messages - Work with multimodal content
Error Handling - Retry strategies and error handling
Testing - Test OpenAI integrations
OpenAI API Documentation - Official OpenAI docs

OpenAI Provider ​

Configuration ​

Basic Setup ​

Basic Usage Example ​

Configuration File ​

Environment Variables ​

Supported Models ​

Responses API Models (Recommended) ​

Chat Completions API Models ​

Provider-Specific Parameters ​

Required Parameters ​

Sampling Parameters ​

Response Configuration ​

Tools & Functions ​

Embeddings ​

API Configuration ​

Client Configuration ​

Advanced Options ​

Built-in Tools ​

Web Search ​

Image Generation ​

MCP (Model Context Protocol) Integration ​

Tool Configuration Example ​

Vision Capabilities ​

Structured Output ​

Embeddings ​

Available Embedding Models ​

Configuration ​

Dimension Reduction ​

Azure OpenAI ​

Configuration ​

Key Differences ​

Error Handling ​

Related Documentation ​

OpenAI Provider

Configuration

Basic Setup

Basic Usage Example

Configuration File

Environment Variables

Supported Models

Responses API Models (Recommended)

Chat Completions API Models

Provider-Specific Parameters

Required Parameters

Sampling Parameters

Response Configuration

Tools & Functions

Embeddings

API Configuration

Client Configuration

Advanced Options

Built-in Tools

Web Search

Image Generation

MCP (Model Context Protocol) Integration

Tool Configuration Example

Vision Capabilities

Structured Output

Embeddings

Available Embedding Models

Configuration

Dimension Reduction

Azure OpenAI

Configuration

Key Differences

Error Handling

Related Documentation