Cookbook

Every example below lives in the Rig v0.44.0 examples directory and is a complete, runnable program that Rig’s CI compiles. Use this page to find a starting point, then read the source for the details. Each example’s src/main.rs opens with a comment saying what it shows and which keys it needs.

Running an example

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

git clone --branch v0.44.0 https://github.com/0xPlaygrounds/rig
cd rig

export OPENAI_API_KEY=...
# export ANTHROPIC_API_KEY=...  GEMINI_API_KEY=...  COHERE_API_KEY=...

cargo run -p agent

Recipes

Two short, complete programs you can copy and run. Both are compile-checked against Rig v0.44.0. 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::prelude::*;
use rig::providers::openai::{self, OpenAI};
use serde::Deserialize;
use serde_json::json;

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

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

struct Adder;

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

    fn description(&self) -> String {
        "Add two integers together".to_string()
    }

    fn parameters(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": { "a": { "type": "number" }, "b": { "type": "number" } },
            "required": ["a", "b"]
        })
    }

    async fn call(&self, _ctx: &mut ToolContext, args: Self::Args) -> Result<i32, MathError> {
        Ok(args.a + args.b)
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = AgentBuilder::new(OpenAI::from_env()?.completion(openai::GPT_5_5))
        .preamble("Use the add tool for arithmetic.")
        .tool(Adder)
        .default_max_turns(2) // one turn to call the tool, one to answer
        .build();

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

21 + 21 = 42.

Extract typed data from text

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

use rig::extractor::ExtractorBuilder;
use rig::prelude::*;
use rig::providers::openai::{self, 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 model = OpenAI::from_env()?.completion(openai::GPT_5_5);
    let extractor = ExtractorBuilder::<Person>::new(model).build();

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

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

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

Basics

The smallest useful programs for the core building blocks. Concepts: Agents, Completions, Structured Output.

Example	What it shows
`agent`	The provider → model → agent → prompt flow end to end.
`extractor`	Typed extraction into a struct, with and without usage metadata.
`sentiment_classifier`	The smallest typed extractor, used to classify a sentence into an enum.
`multi_extract`	Several extractions of one text in parallel with `futures::try_join!`.
`agent_with_context`	Static context documents attached to an agent (Cohere).
`agent_with_loaders`	Loading files from disk into an agent’s context with `FileLoader`.
`frozen_api`	Eight short programs (`cargo run -p frozen_api --example p1_one_prompt`, …): one prompt, streaming, an erased model, tools, local and HTTP operations, an OpenAI-compatible vendor, a custom transport.

Providers and modalities

Provider-specific features, local models, and non-text modalities. See Model Providers for configuring any provider.

Example	What it shows
`openai_agent_completions_api_otel`	Using OpenAI’s Chat Completions API instead of the default Responses API.
`openai_streaming_per_call_usage`	Per-model-call token usage inside a streamed agent run.
`gemini_video_understanding`	Gemini video input with provider-specific request parameters.
`gemini_default_api_recovery`	Recovering when Gemini emits a legacy `default_api` tool name.
`gemini_stream_kill_token_count`	Getting a token-count estimate when a stream is cut off mid-response.
`gemini_deep_research`	Running a Gemini Deep Research agent through the Gemini extension API.
`gemini_nanobanana_image_generation`	Image generation with Gemini, written to a file.
`cohere_image_embeddings`	Embedding an image with Cohere Embed v3.
`transcription`	Audio transcription with OpenAI, Gemini, Groq and Mistral.
`candle_local`	A local chat model on Candle, from downloaded Hugging Face weights.
`candle_pose`	Human pose estimation with a YOLOv8 checkpoint on Candle.
`candle_wasm_chat`	Browser chat backed by SmolLM2 compiled to WebAssembly.
`typesafeai_triage`	Typed yes/no decisions about a support ticket with the TypesafeAI provider.
`typesafeai_chat`	Interactive TypesafeAI decisions, optionally followed by an ordinary agent.

RAG and vector search

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

Example	What it shows
`rag`	Embed documents, attach the index to an agent as dynamic context, answer.
`chain`	Retrieval by hand: look up context, fold it into the prompt, then prompt.
`rag_ollama`	The same RAG flow against a local Ollama model.
`vector_search`	An in-memory vector index with OpenAI embeddings: `top_n` vs `top_n_ids`.
`vector_search_cohere`	Separate Cohere document and query embeddings.
`vector_search_ollama`	Vector search with a local Ollama embedding model.
`rag_dynamic_tools`	Tools picked per prompt by vector search over their descriptions.
`rag_dynamic_tools_multi_turn`	Dynamic tool retrieval across a multi-turn run.
`pdf_agent`	Load and chunk PDFs, embed with Ollama, answer questions over them.
`gemini_extractor_with_rag`	A typed extractor fed by retrieval, on Gemini.
`custom_vector_store`	Implementing `VectorStoreIndex` for your own backend.

Tools

Callable tools, tool streaming, and MCP. Concept: Tools; MCP: Model Context Protocol.

Example	What it shows
`agent_with_tools`	Runtime-defined `DynamicTool`s registered on an agent.
`calculator_chatbot`	An interactive terminal chatbot (`ChatBotBuilder`) with arithmetic tools.
`agent_with_default_max_turns`	Raising the agent’s turn budget for tool-heavy prompts.
`manual_tool_calls`	Handling tool calls yourself with a raw model request, no agent loop.
`agent_tool_call_streaming`	Tool-call arguments streaming in as the provider sends them.
`tool_result_outcomes`	Tools that classify their failures as structured facts; hooks apply policy.
`force_tool_first_turn`	Forcing a tool call on the first turn only, with a request patch.
`rmcp`	Using MCP server tools from an agent via `rmcp` (package `rmcp_example`).
`agent_with_echochambers`	An agent driving a third-party HTTP API through several tools.

Agents, hooks and orchestration

Multi-turn runs, multi-agent patterns, memory, streaming, and control over the agent loop. Concepts: Agents, AgentRunner, Hooks, Streaming, Memory, Workflows; guide: Multi-agent systems.

Example	What it shows
`multi_turn_agent`	A run that takes several tool-calling turns to finish.
`complex_agentic_loop_claude`	A Claude orchestrator delegating to research, analysis and recommendation agents.
`reasoning_loop`	A chain-of-thought agent that reasons before calling tools.
`agent_stream_chat`	A streamed run that continues prior conversation history.
`agent_with_memory`	Rig-managed conversation memory with an in-memory backend.
`agent_with_memory_streaming`	The same memory setup with streamed responses.
`agent_with_agent_tool`	One agent used as a tool by another (`Agent::into_tool`).
`multi_agent`	A translator agent wrapped in a hand-written tool for a main agent.
`agent_orchestrator`	An orchestrator agent that splits a task and dispatches it to workers.
`agent_routing`	A classifier agent choosing which follow-up prompt runs.
`agent_prompt_chaining`	Two agents in sequence, the second transforming the first’s output.
`agent_parallelization`	Several agents scoring one input in parallel.
`agent_evaluator_optimizer`	A generator and an evaluator agent iterating on an answer.
`agent_autonomous`	An extractor loop that feeds its own output back in until a stop condition.
`debate`	Two agents on different providers debating each other.
`enum_dispatch`	Choosing between agents on different providers by name at runtime.
`request_hook`	Stacking several `AgentHook`s that all run on every model call.
`agent_with_retry_hook`	Retrying a model turn from a hook within the run’s turn budget.
`agent_with_human_in_the_loop`	Asking a human to approve each side-effecting tool call.
`agent_with_approval_policy`	Approval rules decided up front and applied by a hook, no human prompt.
`agent_with_durable_approval`	Pausing a run, serializing it, and resuming after out-of-process approval.
`agent_run_stepping`	Driving the loop by hand with `AgentRun`, compared with `AgentRunner`.
`agent_no_tokio`	Running an agent on `bevy_tasks` instead of tokio.

Deployment and production

Running agents as services, observability and HTTP concerns. Guides: Discord bot, Deploy to AWS Lambda, Deploy with LanceDB; concept: Observability.

Example	What it shows
`discord_bot`	A Rig agent behind a Discord slash command, with per-thread history.
`agent_with_tools_otel`	A tool-using agent exporting traces to an OpenTelemetry collector.
`openai_streaming_with_tools_otel`	The same, for a streamed run. The collector config is in `otel/`.
`http_middleware`	HTTP middleware on a provider call: add headers, log bodies, read rate-limit headers.
`reqwest_middleware`	Binding a provider to your own reqwest client with retry middleware.