OpenAI Provider

The OpenAI provider enables access to GPT-4o, o1, o3-mini, and other OpenAI models through the official OpenAI API.

Implementation Details

Source: ~/workspace/source/clients/agent-runtime/src/providers/openai.rs:10 The OpenAI provider implements:

✅ Native tool calling with function definitions
✅ Streaming responses
✅ Reasoning content fallback for o1/o3 models
✅ Multi-turn conversations
✅ Connection warmup for reduced latency

Configuration

Basic Setup

In ~/.config/corvus/config.toml:

[runtime]
provider = "openai"
model = "gpt-4o"
temperature = 0.7

API Key Setup

Set your OpenAI API key via environment variable:

export OPENAI_API_KEY="sk-proj-..."

Or in config file (not recommended for security):

[runtime.provider_config]
api_key = "sk-proj-..."

Credential resolution order (from ~/workspace/source/clients/agent-runtime/src/providers/mod.rs:301):

Explicit api_key parameter (trimmed)
OPENAI_API_KEY environment variable
CORVUS_API_KEY fallback
API_KEY fallback

Supported Models

GPT-4o Series

Best for general-purpose tasks with multimodal capabilities:

model = "gpt-4o"              # Latest GPT-4o
model = "gpt-4o-2024-11-20"   # Specific snapshot
model = "gpt-4o-mini"         # Faster, cheaper variant

Capabilities:

Native tool calling
Vision (image understanding)
128K context window
Up to 16K output tokens

o1 Series (Reasoning Models)

Advanced reasoning with chain-of-thought:

model = "o1"                  # Latest o1 model
model = "o1-preview"          # Preview release
model = "o1-mini"             # Faster, cheaper variant

Special handling:

Uses reasoning_content field for internal reasoning
Automatically falls back if content is empty
No streaming support
Higher token costs

o3-mini (Latest Reasoning Model)

model = "o3-mini"             # Latest reasoning model

Benefits:

Superior reasoning capabilities
Cost-effective compared to o1
Good for complex problem-solving

GPT-4 Turbo

model = "gpt-4-turbo"         # Latest turbo model
model = "gpt-4-turbo-preview" # Preview release

GPT-3.5 Turbo

model = "gpt-3.5-turbo"       # Fast, cost-effective

Usage Examples

Simple Chat

use corvus_runtime::providers::create_provider;

let provider = create_provider("openai", None)?;

let response = provider
    .simple_chat("Explain async/await in Rust", "gpt-4o", 0.7)
    .await?;

println!("Response: {}", response);

Chat with System Prompt

let response = provider
    .chat_with_system(
        Some("You are a Rust expert who writes concise, idiomatic code."),
        "Write a function to parse JSON",
        "gpt-4o",
        0.5,
    )
    .await?;

Multi-turn Conversation

use corvus_runtime::providers::traits::ChatMessage;

let messages = vec![
    ChatMessage::system("You are a helpful coding assistant"),
    ChatMessage::user("Write a merge sort in Rust"),
    ChatMessage::assistant("Here's an implementation..."),
    ChatMessage::user("Now make it generic over any Ord type"),
];

let response = provider
    .chat_with_history(&messages, "gpt-4o", 0.7)
    .await?;

Tool Calling

The OpenAI provider supports native function calling:

use corvus_runtime::providers::traits::{ChatRequest, ChatMessage};
use corvus_runtime::tools::ToolSpec;

let tools = vec![
    ToolSpec {
        name: "read_file".to_string(),
        description: "Read contents of a file".to_string(),
        parameters: serde_json::json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "File path to read"
                }
            },
            "required": ["path"]
        }),
        source: None,
    },
];

let request = ChatRequest {
    messages: &[
        ChatMessage::user("Read the contents of README.md")
    ],
    tools: Some(&tools),
};

let response = provider.chat(request, "gpt-4o", 0.7).await?;

if response.has_tool_calls() {
    for call in response.tool_calls {
        println!("Tool: {}", call.name);
        println!("Arguments: {}", call.arguments);
    }
}

Reasoning Models (o1/o3)

Reasoning models automatically use the reasoning_content field:

let response = provider
    .simple_chat(
        "Prove that the square root of 2 is irrational",
        "o3-mini",
        1.0,  // Higher temperature for reasoning models
    )
    .await?;

// Response contains both reasoning and final answer
println!("{}", response);

Advanced Configuration

Connection Warmup

Reduce first-request latency by warming up the connection:

let provider = create_provider("openai", None)?;

// Warm up HTTP/2 connection and DNS
provider.warmup().await?;

// First request is now faster
let response = provider.simple_chat("Hello", "gpt-4o", 0.7).await?;

Custom Timeouts

The provider uses these defaults:

Request timeout: 120 seconds
Connect timeout: 10 seconds

These are configured in ~/workspace/source/clients/agent-runtime/src/providers/openai.rs:141.

With Resilient Provider Chain

Automatic failover to backup providers:

[runtime]
provider = "openai"

[runtime.reliability]
fallback_providers = ["anthropic", "openrouter"]
provider_retries = 3
provider_backoff_ms = 1000

use corvus_runtime::providers::create_resilient_provider;
use corvus_runtime::config::ReliabilityConfig;

let reliability = ReliabilityConfig {
    fallback_providers: vec!["anthropic".to_string(), "openrouter".to_string()],
    provider_retries: 3,
    provider_backoff_ms: 1000,
    ..Default::default()
};

let provider = create_resilient_provider(
    "openai",
    None,
    None,
    &reliability,
)?;

Error Handling

Common errors and solutions:

Missing API Key

Error: OpenAI API key not set. Set OPENAI_API_KEY or edit config.toml.

Solution: Set the OPENAI_API_KEY environment variable.

Rate Limiting

Error: OpenAI API error (429): Rate limit exceeded

Solution:

Implement exponential backoff (automatic with create_resilient_provider)
Use fallback providers
Upgrade to higher rate limits

Invalid Model

Error: OpenAI API error (404): The model 'gpt-5' does not exist

Solution: Use a valid model name from the supported models list.

Token Limit Exceeded

Error: OpenAI API error (400): This model's maximum context length is 128000 tokens

Solution:

Reduce conversation history
Use a model with larger context (e.g., gpt-4o has 128K)
Implement conversation summarization

Best Practices

Use environment variables for API keys, never hardcode
Call warmup() during initialization for faster first requests
Use gpt-4o-mini for cost-effective tasks
Use reasoning models (o1/o3) for complex problem-solving
Enable fallback providers for production reliability
Set appropriate temperature:
- 0.0-0.3 for factual/deterministic tasks
- 0.7 (default) for balanced responses
- 1.0+ for creative/reasoning tasks
Monitor token usage to control costs
Implement retry logic with exponential backoff
Use streaming for real-time user feedback (when available)
Leverage tool calling for agent workflows

Cost Optimization

Model Selection

Model	Input (per 1M tokens)	Output (per 1M tokens)	Use Case
gpt-4o	$2.50	$10.00	General-purpose, balanced
gpt-4o-mini	$0.15	$0.60	High-volume, cost-sensitive
o1-preview	$15.00	$60.00	Complex reasoning
o1-mini	$3.00	$12.00	Cost-effective reasoning
o3-mini	$1.10	$4.40	Latest reasoning model
gpt-3.5-turbo	$0.50	$1.50	Simple tasks, legacy

Tips

Use gpt-4o-mini by default, upgrade only when needed
Implement prompt caching (when available)
Reduce system prompt length where possible
Trim conversation history to essential messages
Use function calling to reduce verbose output
Set max_tokens limits in production

Troubleshooting

Connection Issues

# Test API connectivity
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Verify Configuration

corvus config show

Enable Debug Logging

export RUST_LOG=corvus_runtime::providers=debug
corvus run

AI Providers

Channels

Tools & Capabilities

Memory & Storage

Security & Deployment

Advanced

Documentation Index

​Implementation Details

​Configuration

​Basic Setup

​API Key Setup

​Supported Models

​GPT-4o Series

​o1 Series (Reasoning Models)

​o3-mini (Latest Reasoning Model)

​GPT-4 Turbo

​GPT-3.5 Turbo

​Usage Examples

​Simple Chat

​Chat with System Prompt

​Multi-turn Conversation

​Tool Calling

​Reasoning Models (o1/o3)

​Advanced Configuration

​Connection Warmup

​Custom Timeouts

​With Resilient Provider Chain

​Error Handling

​Missing API Key

​Rate Limiting

​Invalid Model

​Token Limit Exceeded

​Best Practices

​Cost Optimization

​Model Selection

​Tips

​Troubleshooting

​Connection Issues

​Verify Configuration

​Enable Debug Logging

​See Also

Build docs developers (and LLMs) love