Quickstart

This guide takes you from an empty project to a running AI agent. An agent is a model wrapped with a system prompt (a “preamble”) and, optionally, tools. Rig handles the request/response plumbing so you just call .prompt(...).

By the end you’ll have a program that sends a question to OpenAI’s gpt-5.5 and prints the reply.

1. Create a project

You’ll need Rust 1.95 or newer. Create a new binary crate:

cargo init my-first-agent
cd my-first-agent

2. Add dependencies

Add rig, plus Tokio for the #[tokio::main] entry point and anyhow for error handling:

cargo add rig anyhow
cargo add tokio --features macros,rt-multi-thread

3. Set your API key

Provider clients read credentials from the environment. For OpenAI, set OPENAI_API_KEY:

export OPENAI_API_KEY="sk-..."

Using a different provider such as Anthropic, Gemini, or DeepSeek? Each reads its own environment variable; see Model Providers.

4. Build and prompt an agent

Replace the contents of src/main.rs with the following:

use rig::prelude::*;
use rig::providers::openai::{self, OpenAI};

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // A client for OpenAI, configured from OPENAI_API_KEY.
    let client = OpenAI::from_env()?;

    // An agent: a completion model plus a system prompt (the "preamble").
    let agent = AgentBuilder::new(client.completion(openai::GPT_5_5))
        .preamble("You are a helpful assistant.")
        .build();

    // Send a prompt and await the model's reply.
    let response = agent.prompt("What is the Rust programming language?").await?;

    println!("{}", response.output());

    Ok(())
}

That’s the whole program: create a client, pick a model from it, build an agent, and .prompt(...) it.

5. Run it

cargo run

You’ll see the model’s answer printed to your terminal, something like:

Rust is a modern, statically typed systems programming language focused on
safety, speed, and concurrency without a garbage collector. Its ownership and
borrowing model guarantees memory safety at compile time, while zero-cost
abstractions keep it as fast as C/C++...

The exact text varies from run to run. That’s the model, not a bug.

If it doesn’t compile or fails at runtime, see Troubleshooting.

What just happened

OpenAI::from_env() created a provider client from your API key. It sends requests through Rig’s shared HTTP client.
client.completion(openai::GPT_5_5) returned a Model: a handle for one model at that provider. You can call it directly, or hand it to an agent.
AgentBuilder::new(model) started an agent; .preamble(...) set the system prompt and .build() finished it.
.prompt(...) ran the agent and returned a PromptResponse. .output() is the final text; the response also carries token usage and the run’s messages.

Agents can do far more than single-turn Q&A: attach tools so the model can call your code, add a knowledge base for retrieval-augmented generation (RAG), stream tokens as they arrive with .stream(), or keep conversation history.

Next steps