Module agent 

This module contains the implementation of the Agent struct and its builder.

The Agent struct represents an LLM agent, which combines an LLM model with a preamble (system prompt), a set of static context documents, and a set of tools. Tools can be always available or selected from a retrieval index at prompt time.

The Agent struct is highly configurable, allowing the user to define anything from a simple bot with a specific system prompt to a complex RAG system.

The Agent struct implements the runner-backed crate::completion::Prompt, crate::completion::TypedPrompt, and crate::completion::Chat traits. All agent execution goes through AgentRunner, so hooks and lifecycle policies cannot be bypassed through a raw agent request builder.

The AgentBuilder implements the builder pattern for creating instances of Agent. It allows configuring the model, preamble, context documents, tools, temperature, and additional parameters before building the agent.

Example

use rig_agent::prelude::*;
use rig_core::{client::ProviderClient, providers::openai};

let openai = openai::Client::from_env()?;

// Configure the agent
let agent = openai.agent(openai::GPT_5_2)
    .preamble("System prompt")
    .context("Context document 1")
    .context("Context document 2")
    .temperature(0.8)
    .build();

// Use the agent for chats and prompts
// Generate a chat completion response from a prompt and chat history
let chat_response = agent.chat("Prompt", &mut Vec::<rig_core::completion::Message>::new()).await?;

// Generate a prompt completion response from a simple prompt
let prompt_response = agent.prompt("Prompt").await?;

// Per-run overrides stay inside the hook-aware runner.
let response = agent.runner("Prompt").temperature(0.9).run().await?;

AgentBuilder::dynamic_context provides passive RAG through the same completion-call hook lifecycle as every other request policy. For custom query selection, filtering, reranking, caching, formatting, or failure handling, applications can instead implement AgentHook and inject documents with RequestPatch::extra_context. Active RAG exposes a vector index or custom retriever as a tool so the model decides when to search.

Passive RAG agent example

use rig_agent::{completion::Prompt, prelude::*};
use rig_core::{
    client::{EmbeddingsClient, ProviderClient},
    embeddings::EmbeddingsBuilder,
    providers::openai,
    vector_store::in_memory_store::InMemoryVectorStore,
};

// Initialize OpenAI client
let openai = openai::Client::from_env()?;

// Initialize OpenAI embedding model
let embedding_model = openai.embedding_model(openai::TEXT_EMBEDDING_3_SMALL);

// Create vector store, compute embeddings and load them in the store
let mut vector_store = InMemoryVectorStore::default();

let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
    .documents(vec![
        "Definition of a *flurbo*: A flurbo is a green alien that lives on cold planets",
        "Definition of a *glarb-glarb*: A glarb-glarb is an ancient tool used by the ancestors of the inhabitants of planet Jiro to farm the land.",
        "Definition of a *linglingdong*: A term used by inhabitants of the far side of the moon to describe humans.",
    ])?
    .build()
    .await?;

vector_store.add_documents(embeddings);

// Create vector store index
let index = vector_store.index(embedding_model);

let agent = openai.agent(openai::GPT_5_2)
    .preamble("
        You are a dictionary assistant here to assist the user in understanding the meaning of words.
        You will find additional non-standard word definitions that could be useful below.
    ")
    .dynamic_context(1, index)
    .build();

// Prompt the agent and print the response
let response = agent.prompt("What does \"glarb-glarb\" mean?").await?;

Re-exports

pub use hook::CompletionCall as CompletionCallEvent;

pub use hook::AgentHook;

pub use hook::CompletionCallAction;

pub use hook::CompletionResponse as CompletionResponseEvent;

pub use hook::HookContext;

pub use hook::HookStack;

pub use hook::InvalidToolCallAction;

pub use hook::InvalidToolCallContext;

pub use hook::ModelTurnAction;

pub use hook::ModelTurnFinished;

pub use hook::ObservationAction;

pub use hook::RequestPatch;

pub use hook::RetryRequest;

pub use hook::RunId;

pub use hook::Scratchpad;

pub use hook::StepEventKind;

pub use hook::StreamResponseFinish;

pub use hook::TextDelta;

pub use hook::ToolCall;

pub use hook::ToolCallAction;

pub use hook::ToolCallDelta;

pub use hook::ToolResultAction;

pub use hook::ToolResultEvent;

pub use run::AgentRun;

pub use run::AgentRunStep;

pub use run::ModelTurn;

pub use run::ModelTurnOutcome;

pub use run::OutputMode;

pub use run::PendingToolCall;

pub use runner::AgentRunner;

Modules

hook

Event-specific hooks for observing and steering an agent run.

run

A sans-IO, steppable, serializable state machine for the agent prompt loop.

runner

AgentRunner: the hook-aware driver that turns a sans-IO AgentRun into a complete agent loop.

Structs

Agent

Struct representing an LLM agent. An agent is an LLM model combined with a preamble (i.e.: system prompt) and a static set of context documents and tools. All context documents and tools are always provided to the agent when prompted.

AgentBuilder

A builder for creating an agent

CompletionCall

Details for one successfully completed completion request made by an agent run.

NoToolConfig

Marker type indicating no tool configuration has been set yet.

PromptRequest

A builder for creating prompt requests with customizable options. Uses generics to track which options have been set during the build process.

PromptResponse

The result of an agent run, returned by both the blocking (PromptRequest) and streaming (StreamingPromptRequest) surfaces so a call site reads identically whether it used .prompt() or .stream_prompt().

StreamingPromptRequest

A builder for creating prompt requests with customizable options. Uses generics to track which options have been set during the build process.

Text

Basic text content.

TypedPromptRequest

A builder for creating typed prompt requests that return deserialized structured output.

TypedPromptResponse

WithBuilderTools

Typestate indicating tools are being configured via the builder API.

WithToolServerHandle

Typestate indicating a pre-existing ToolServerHandle has been provided.

Enums

MultiTurnStreamItem

StreamingError

Functions

stream_to_stdout

Helper function to stream assistant-visible completion output to stdout.

Type Aliases

StreamingResultNot (target_os=unknown and WebAssembly)