Cookbook

Every example below lives in the Rig examples directory and is a complete, runnable program. Use this page to find a starting point for the thing you’re building, then read the source for the details.

Running an example

Each example is its own package. Clone the repo, set the API key(s) the example needs, and run it by package name:

git clone https://github.com/0xPlaygrounds/rig
cd rig

# Set the key(s) the example uses (see its source for specifics)
export OPENAI_API_KEY=...
# export ANTHROPIC_API_KEY=...
# export GEMINI_API_KEY=...
# export COHERE_API_KEY=...

cargo run -p agent

Recipes

Short, complete programs you can copy and run. Each one is compile-checked against the current Rig release. Set OPENAI_API_KEY before running.

Give an agent a tool

Demonstrates: Agents, Tools. The model decides when to call your Rust function and Rig runs the tool loop for you.

use rig::client::{CompletionClient, ProviderClient};
use rig::completion::{Prompt, ToolDefinition};
use rig::providers::openai;
use rig::tool::Tool;
use serde::{Deserialize, Serialize};
use serde_json::json;

#[derive(Deserialize)]
struct AddArgs { a: i32, b: i32 }

#[derive(Debug, thiserror::Error)]
#[error("math error")]
struct MathError;

#[derive(Deserialize, Serialize)]
struct Adder;

impl Tool for Adder {
    const NAME: &'static str = "add";
    type Error = MathError;
    type Args = AddArgs;
    type Output = i32;

    async fn definition(&self, _prompt: String) -> ToolDefinition {
        ToolDefinition {
            name: "add".to_string(),
            description: "Add two integers together".to_string(),
            parameters: json!({
                "type": "object",
                "properties": { "a": { "type": "number" }, "b": { "type": "number" } },
                "required": ["a", "b"]
            }),
        }
    }

    async fn call(&self, args: Self::Args) -> Result<Self::Output, Self::Error> {
        Ok(args.a + args.b)
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = openai::Client::from_env()?
        .agent(openai::GPT_5_5)
        .preamble("Use the add tool for arithmetic.")
        .tool(Adder)
        .build();

    let answer = agent.prompt("What is 21 + 21?").await?;
    println!("{answer}");
    Ok(())
}

21 + 21 = 42.

Extract typed data from text

Demonstrates: Structured Output. Define a struct, get it back filled in — no manual JSON parsing.

use rig::client::{CompletionClient, ProviderClient};
use rig::providers::openai;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
struct Person {
    name: String,
    /// The person's age in years, if stated.
    age: Option<u8>,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let extractor = openai::Client::from_env()?
        .extractor::<Person>(openai::GPT_5_5)
        .build();

    let person = extractor
        .extract("Marie Curie was 66 years old when she passed away.")
        .await?;

    println!("{person:?}");
    Ok(())
}

Person { name: "Marie Curie", age: Some(66) }

Basics

Start here to see the smallest useful programs for the core building blocks. Concepts: Agents, Completions, Structured Output, Workflows.

Run	What it shows
`cargo run -p agent`	The smallest useful agent setup with OpenAI.
`cargo run -p extractor`	Typed extraction into a struct, with usage metadata.
`cargo run -p sentiment_classifier`	The smallest typed extractor used for classification.
`cargo run -p multi_extract`	Fan-out structured extraction over several inputs concurrently.
`cargo run -p chain`	A retrieval-augmented workflow: embed, retrieve with `lookup`, then answer.
`cargo run -p transcription`	Audio transcription through a provider transcription model.

Providers

Provider-specific examples showing configuration, streaming, multimodal input, and OpenAI-compatible endpoints. See Model Providers for the full list and how to configure any provider.

Run	What it shows
`cargo run -p openai_agent_completions_api_otel`	Using OpenAI’s Completions API from an agent.
`cargo run -p openai_streaming_per_call_usage`	Inspecting per-completion-call usage in an agent stream.
`cargo run -p gemini_video_understanding`	Gemini video understanding via provider-specific request params.
`cargo run -p gemini_default_api_recovery`	Recovering when Gemini emits a legacy `default_api` tool name.
`cargo run -p rag_ollama`	RAG against a local model served by Ollama.
`cargo run -p vector_search_cohere`	Vector search with separate Cohere document and query embeddings.

RAG & vector search

Retrieval-augmented generation and vector-store usage. Concepts: Vector Stores & RAG, Embeddings; build a full system in Build a RAG system; stores in Vector Stores.

Run	What it shows
`cargo run -p rag`	A basic RAG pipeline: embed documents, retrieve, and answer.
`cargo run -p vector_search`	Embedding documents and querying an in-memory vector index with OpenAI.
`cargo run -p rag_dynamic_tools`	RAG where retrieved documents become dynamically-available tools.
`cargo run -p rag_dynamic_tools_multi_turn`	Dynamic-tool RAG across a multi-turn conversation.
`cargo run -p pdf_agent`	An agent that answers questions over PDF documents.
`cargo run -p custom_vector_store`	Implementing a custom vector-store backend.
`cargo run -p gemini_extractor_with_rag`	Combining a typed extractor with retrieval on Gemini.

Tools

Give agents callable tools, including approval gates and Model Context Protocol servers. Concept: Tools; MCP: Model Context Protocol.

Run	What it shows
`cargo run -p agent_with_tools`	Registering boxed tools on an agent.
`cargo run -p calculator_chatbot`	A chatbot agent backed by calculator tools.
`cargo run -p manual_tool_calls`	Manual tool-call handling with `Agent::completion()`.
`cargo run -p rmcp`	Driving an MCP-friendly agent with the `rmcp` crate.
`cargo run -p agent_with_human_in_the_loop`	Human-in-the-loop tool-call approval via an `AgentHook`.
`cargo run -p agent_with_approval_policy`	Policy-based, non-interactive tool approval (allow-list, fail-closed).

Agents & orchestration

Multi-turn, multi-agent, memory, streaming, and agent-loop control. Concepts: Agents, Streaming, Memory; guide: Multi-agent systems.

Run	What it shows
`cargo run -p multi_turn_agent`	An agent that carries conversation state across turns.
`cargo run -p multi_agent`	Coordinating multiple agents on a task.
`cargo run -p agent_orchestrator`	An orchestrator that dispatches work to other agents.
`cargo run -p agent_routing`	Routing one prompt into different follow-up prompts.
`cargo run -p agent_prompt_chaining`	Prompt chaining with two agents in sequence.
`cargo run -p agent_parallelization`	Running agent work in parallel.
`cargo run -p agent_evaluator_optimizer`	An evaluator/optimizer loop between agents.
`cargo run -p agent_with_memory`	Rig-managed conversation memory with an in-memory backend.
`cargo run -p agent_stream_chat`	`stream_chat` with prior conversation history.
`cargo run -p agent_with_loaders`	Loading real files into an agent’s context.
`cargo run -p agent_run_stepping`	Driving the agent loop by hand with the sans-IO `AgentRun` state machine.

Deployment & production

Running agents as real services, plus observability and networking concerns. Guides: Discord bot, Deploy to AWS Lambda, Deploy with LanceDB, Observability.

Run	What it shows
`cargo run -p discord_bot`	Wiring a Rig agent into a Discord bot.
`cargo run -p agent_with_tools_otel`	A tools agent that ships logs/traces to an OpenTelemetry collector.
`cargo run -p request_hook`	Observing prompt/response/tool lifecycle events by stacking `AgentHook`s.
`cargo run -p reqwest_middleware`	Supplying a custom reqwest client with retry middleware.