Providers & Clients

A provider client is the entry point to any LLM vendor in Rig. It authenticates against a provider (OpenAI, Anthropic, Gemini, Ollama, and more) and creates the models you actually prompt — completion, embedding, transcription, image, and audio models — depending on what that provider supports.

Before you start

• Add rig to your project (see Installation).
• Export the API key for your provider, e.g. OPENAI_API_KEY, so from_env() can find it.

use rig::providers::openai;

// Create a client from environment variables (OPENAI_API_KEY)
let client = openai::Client::from_env()?;

Everything else on this page explains the type system behind that one line.

Client architecture

The provider client system is built around a generic Client struct and a capability-based type system that checks provider support at compile time.

The Client Struct

At the core is rig::client::Client<Ext, H>, a generic struct parameterized by:

• Ext: A provider extension (implementing the Provider trait) that defines provider-specific behavior
• H: An API key type (implementing the ApiKey trait)

use rig::providers::openai;

// Create a client from environment variables
let client = openai::Client::from_env()?;

// Or with an explicit API key
let client = openai::Client::new("your-api-key");

Provider Trait

The Provider trait abstracts over provider-specific extensions and specifically handles building out the client with the provider extension. URL construction and custom instantiation are added as provided methods, should you want to implement your own version of this.

pub trait Provider: Sized {
    type Builder: ProviderBuilder;

    const VERIFY_PATH: &'static str;

    // Required method
    fn build<H>(
        builder: &ClientBuilder<Self::Builder, <Self::Builder as ProviderBuilder>::ApiKey, H>,
    ) -> Result<Self>;
}

Each provider module (e.g., rig::providers::openai, rig::providers::anthropic) implements this trait.

ProviderBuilder Trait

The ProviderBuilder trait provides a builder pattern for configuring providers:

pub trait ProviderBuilder {
    type Output: Provider;
    type ApiKey;

    const BASE_URL: &'static str;

    // Provided method
    fn finish<H>(
        &self,
        builder: ClientBuilder<Self, Self::ApiKey, H>,
    ) -> Result<ClientBuilder<Self, Self::ApiKey, H>> { ... }
}

Capabilities System

Rig introduces a type-level capabilities system via the Capabilities and Capability traits. This allows compile-time checking of what a provider supports:

pub trait Capabilities<H = Client> {
    type Completion: Capability;
    type Embeddings: Capability;
    type Transcription: Capability;
    type ModelListing: Capability;
    type ImageGeneration: Capability;
    type AudioGeneration: Capability;
}

pub trait Capability {
    const CAPABLE: bool;
}

ProviderClient Trait

The ProviderClient trait provides a unified interface for creating clients:

pub trait ProviderClient {
    type Input;
    type Error;

    /// Create a client from the process's environment.
    fn from_env() -> Result<Self, Self::Error> where Self: Sized;

    fn from_val(input: Self::Input) -> Result<Self, Self::Error> where Self: Sized;
}

Supported capabilities

Provider clients can support any combination of the following:

Capability	Trait	Description
Text Completion	CompletionClient	Create completion models for text generation
Embeddings	EmbeddingsClient	Create embedding models for vector representations
Transcription	TranscriptionClient	Create transcription models for speech-to-text
Image Generation	ImageGenerationClient	Create models for image generation (requires image feature)
Audio Generation	AudioGenerationClient	Create models for text-to-speech (requires audio feature)
Model Listing	ModelListingClient	List available models from the provider
Verification	VerifyClient	Verify client credentials and connectivity

Auth types

Rig provides typed authentication:

• BearerAuth: API key inserted as a bearer token in request headers
• NeedsApiKey: Marker indicating the provider requires an API key
• Nothing: Marker for providers that don’t need an API key (e.g., local Ollama)

Creating models

Once you have a client, create models using the corresponding client trait methods:

use rig::client::CompletionClient;

let openai = openai::Client::from_env()?;

// Create a completion model
let model = openai.completion_model("gpt-5.5");

// Create an embedding model
let embedding_model = openai.embedding_model("text-embedding-3-small");

// Create an agent (shorthand for completion_model + AgentBuilder)
let agent = openai.agent("gpt-5.5")
    .preamble("You are a helpful assistant.")
    .build();

How to Write a Custom Provider

To implement a custom provider, you need to:

1. Implement the Provider trait for your extension type
2. Implement CompletionModel for your completion model type
3. Optionally implement EmbeddingModel, TranscriptionModel, etc.
4. Implement the relevant client traits (CompletionClient, EmbeddingsClient, etc.)

For a detailed walkthrough, see the Write Your Own Provider guide.

See also

• Completions — prompting the models a client creates
• Model Providers — configuring each vendor
• Write Your Own Provider

API Reference (Client)

Next steps

CompletionsPrompt the completion models your client just created.

AgentsWrap a model with a preamble, tools, and context.

Model ProvidersPer-vendor setup, auth, and supported capabilities.