OpenAI Provider

Configure and use OpenAI models (GPT-4o, o1, o3-mini) in Corvus

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):

1. Explicit api_key parameter (trimmed)
2. OPENAI_API_KEY environment variable
3. CORVUS_API_KEY fallback
4. 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

1. Use environment variables for API keys, never hardcode
2. Call warmup() during initialization for faster first requests
3. Use gpt-4o-mini for cost-effective tasks
4. Use reasoning models (o1/o3) for complex problem-solving
5. Enable fallback providers for production reliability
6. Set appropriate temperature:
   • 0.0-0.3 for factual/deterministic tasks
   • 0.7 (default) for balanced responses
   • 1.0+ for creative/reasoning tasks
7. Monitor token usage to control costs
8. Implement retry logic with exponential backoff
9. Use streaming for real-time user feedback (when available)
10. 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

1. Use gpt-4o-mini by default, upgrade only when needed
2. Implement prompt caching (when available)
3. Reduce system prompt length where possible
4. Trim conversation history to essential messages
5. Use function calling to reduce verbose output
6. 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

See Also

• Provider Overview
• Anthropic Provider
• Custom Provider Setup
• Tool Calling Guide
• Configuration Reference