Quickstart

This guide takes you from an empty project to a running AI agent. An agent is an LLM 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 the Rust toolchain installed. Create a new binary crate:

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

2. Add dependencies

Add the rig crate (imported as rig) and Tokio, the async runtime Rig runs on:

cargo add rig tokio --features tokio/macros,tokio/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 the model providers list.

4. Build and prompt an agent

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

use rig::client::{CompletionClient, ProviderClient};
use rig::completion::Prompt;
use rig::providers::openai;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // Create the OpenAI client from the OPENAI_API_KEY environment variable.
    let client = openai::Client::from_env()?;

    // Build an agent: a model plus a system prompt (the "preamble").
    let agent = client
        .agent("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}");

    Ok(())
}

That’s the whole program. Three moves: create a client, .build() an agent from a model id and preamble, then .prompt(...).await? to get a response.

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.

What just happened

openai::Client::from_env() created a provider client authenticated with your API key.
.agent("gpt-5.5") selected a completion model and returned an agent builder; .preamble(...) set the system prompt and .build() finalized it.
.prompt(...) sent one message and awaited the full response as a String.

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, or keep conversation history.

Next steps