Building with Rig

Rig is a Rust library for building LLM-powered applications with a provider-agnostic API. All patterns use the builder pattern and async/await via tokio.

Quick Start

use rig::completion::Prompt;
use rig::providers::openai;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let client = openai::Client::from_env();

    let agent = client
        .agent(openai::GPT_4O)
        .preamble("You are a helpful assistant.")
        .build();

    let response = agent.prompt("Hello!").await?;
    println!("{}", response);
    Ok(())
}

Core Patterns

1. Simple Agent

let agent = client.agent(openai::GPT_4O)
    .preamble("System prompt")
    .temperature(0.7)
    .max_tokens(2000)
    .build();

let response = agent.prompt("Your question").await?;

2. Agent with Tools

Define a tool by implementing the

Tool

let agent = client.agent(openai::GPT_4O)
    .preamble("You can use tools.")
    .tool(MyTool)
    .build();

See

references/tools.md

Tool

3. RAG (Retrieval-Augmented Generation)

let embedding_model = client.embedding_model(openai::TEXT_EMBEDDING_ADA_002);
let index = vector_store.index(embedding_model);

let agent = client.agent(openai::GPT_4O)
    .preamble("Answer using the provided context.")
    .dynamic_context(5, index)  // top-5 similar docs per query
    .build();

See

references/rag.md

Embed

4. Streaming

use futures::StreamExt;
use rig::streaming::StreamedAssistantContent;
use rig::agent::prompt_request::streaming::MultiTurnStreamItem;

let mut stream = agent.stream_prompt("Tell me a story").await?;

while let Some(chunk) = stream.next().await {
    match chunk? {
        MultiTurnStreamItem::StreamAssistantItem(
            StreamedAssistantContent::Text(text)
        ) => print!("{}", text.text),
        MultiTurnStreamItem::FinalResponse(resp) => {
            println!("\n{}", resp.response());
        }
        _ => {}
    }
}

5. Structured Extraction

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, JsonSchema)]
struct Person {
    pub name: Option<String>,
    pub age: Option<u8>,
}

let extractor = client.extractor::<Person>(openai::GPT_4O).build();
let person = extractor.extract("John is 30 years old.").await?;

6. Chat with History

use rig::completion::Chat;

let history = vec![
    Message::from("Hi, I'm Alice."),
    // ...previous messages
];
let response = agent.chat("What's my name?", history).await?;

Agent Builder Methods

.preamble(str)

.context(str)

.dynamic_context(n, index)

.tool(impl Tool)

.tools(Vec<Box<dyn ToolDyn>>)

.temperature(f64)

.max_tokens(u64)

.additional_params(json!{...})

.tool_choice(ToolChoice)

.build()

Available Providers

Create a client with

ProviderName::Client::from_env()

ProviderName::Client::new("key")

openai

GPT_4O

GPT_4O_MINI

anthropic

CLAUDE_4_OPUS

CLAUDE_4_SONNET

cohere

COMMAND_R_PLUS

mistral

MISTRAL_LARGE

gemini

groq

ollama

deepseek

xai

together

perplexity

openrouter

huggingface

azure

hyperbolic

galadriel

moonshot

mira

voyageai

Vector Store Crates

rig-core

rig-mongodb

rig-lancedb

rig-qdrant

rig-sqlite

rig-neo4j

rig-milvus

rig-surrealdb

Key Rules

• All async code runs on tokio.
• Use

  WasmCompatSend

  /

  WasmCompatSync

  instead of raw

  Send

  /

  Sync

  for WASM compatibility.
• Use proper error types with

  thiserror

  — never

  Result<(), String>

  .
• Avoid

  .unwrap()

  — use

  ?

  operator.

Further Reference

Detailed API documentation (available when installed via Claude Code skills):

• tools — Tool trait, ToolDefinition, ToolEmbedding, attachment patterns
• rag — Vector stores, Embed derive, EmbeddingsBuilder, search requests
• providers — Provider-specific initialization, model constants, env vars
• patterns — Multi-agent, hooks, streaming details, chaining, extraction

For the full reference, see the Rig examples at

rig-core/examples/