Skip to content

Installation

Rig ships as the rig crate on crates.io. This page covers adding it to a project, provider API keys, and the cargo features that select integrations, transports, and TLS. Once you’re set up, head to the Quickstart to build your first agent.

Prerequisites

Section titled “Prerequisites”
  • Rust 1.95 or newer. Install it with rustup and keep it current with rustup update.
  • A provider API key. The examples in these docs use OpenAI and read OPENAI_API_KEY. Other providers use their own variables, such as ANTHROPIC_API_KEY, GEMINI_API_KEY, or COHERE_API_KEY. Local models through Ollama need no key.

Add Rig to your project

Section titled “Add Rig to your project”

From inside a Cargo project, add rig and Tokio:

Terminal window
cargo add rig
cargo add tokio --features macros,rt-multi-thread

The examples use Tokio for #[tokio::main]. Rig itself does not require a particular async runtime: the bundled HTTP transport brings what it needs, and an agent run is a plain future you can drive on any executor.

Or, in Cargo.toml:

[dependencies]
rig = "0.44.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Set your API key

Section titled “Set your API key”

Provider clients created with from_env() read credentials from environment variables. Export your key before running:

Terminal window
export OPENAI_API_KEY="sk-..."

How the crates fit together

Section titled “How the crates fit together”

rig is a facade: most applications depend on it alone.

  • rig-core holds the portable contracts: messages, provider clients and models, tools, embeddings, memory, and vector-store traits.
  • rig-agent is the agent runtime: AgentBuilder, the tool-calling loop, hooks, extraction, and the steppable run state. The facade enables it by default (the agent feature).
  • Integrations (vector stores, extra providers, MCP, recording) are separate crates that the facade exposes as feature-gated modules, for example rig::qdrant behind the qdrant feature.

See Architecture for the full picture.

Cargo features

Section titled “Cargo features”

The default features are agent, derive, reqwest, and rustls: the agent runtime, the derive macros (#[derive(Embed)], #[rig::rig_tool]), the bundled HTTP transport, and rustls for TLS.

Integrations

Section titled “Integrations”

Each integration is one feature, exposed as a module of the same name:

[dependencies]
rig = { version = "0.44.0", features = ["qdrant", "fastembed"] }
KindFeatures (module rig::<name>)
Vector storeshelixdb, lancedb, milvus, mongodb, neo4j, postgres, qdrant, s3vectors, scylladb, sqlite, surrealdb, vectorize
Extra model providersbedrock, vertexai, gemini-grpc (rig::gemini_grpc), candle (local inference), typesafeai (typed judgments)
Local embeddingsfastembed (downloads models from Hugging Face and the ONNX runtime); fastembed-hf-hub and fastembed-ort-download-binaries enable only one of the two
MCP toolsrmcp (module rig::tool::rmcp)
Conversation memory policiesmemory (adds to rig::memory)
Recording and replaycassette
Test helperstest-utils (mock models and helpers in rig::test_utils; see Testing)

The built-in providers (OpenAI, Anthropic, Gemini, Cohere, Ollama, DeepSeek, Groq, Mistral, OpenRouter, xAI, and the rest) need no feature. See Integrations for the full list.

Content and loaders

Section titled “Content and loaders”
FeatureEnables
imageimage-generation models
audioaudio-generation (text-to-speech) models
pdfthe PDF file loader
epubthe EPUB file loader

Transports and TLS

Section titled “Transports and TLS”
FeatureEnables
reqwest (default)the bundled HTTP transport; clients built with from_env() or new(..) send through a shared reqwest client
reqwest-middlewarea transport built on reqwest-middleware
socksSOCKS proxy support in the reqwest transport
websocketthe bundled websocket backend for OpenAI’s Responses WebSocket sessions
websocket-rustls / websocket-native-tlswebsocket plus the matching TLS feature
rustls (default) / native-tlsthe TLS stack for the bundled transports and integrations

To pick a TLS stack explicitly, turn off the defaults and add back what you need:

[dependencies]
rig = { version = "0.44.0", default-features = false, features = ["agent", "derive", "reqwest", "native-tls"] }

You can also bring your own transport: every provider client accepts any HTTP client through with_http(..). See Providers & Clients.

WebAssembly

Section titled “WebAssembly”

Rig builds for wasm32-unknown-unknown (the browser) with no extra features: the target alone selects the wasm-compatible code paths. On wasm:

  • rig-core and the agent runtime work, with the reqwest transport using the browser’s fetch.
  • MCP tools (rmcp) and the bundled websocket backend are native-only.
  • WASI targets (wasm32-wasip1, wasm32-wasip2) are not supported.

Using rig-core directly

Section titled “Using rig-core directly”

If you only need the provider contracts and want to write your own agent loop, depend on rig-core instead of the facade. It has no default transport: add its reqwest feature for the bundled HTTP client, or pass your own with with_http. The rest of these docs use the rig facade.

Next steps

Section titled “Next steps”