rig_agent/agent/
mod.rs

1//! This module contains the implementation of the [Agent] struct and its builder.
2//!
3//! The [Agent] struct represents an LLM agent, which combines an LLM model with a preamble (system prompt),
4//! a set of static context documents, and a set of tools. Tools can be always
5//! available or selected from a retrieval index at prompt time.
6//!
7//! The [Agent] struct is highly configurable, allowing the user to define anything from
8//! a simple bot with a specific system prompt to a complex RAG system.
9//!
10//! The [Agent] struct implements the runner-backed [crate::completion::Prompt],
11//! [crate::completion::TypedPrompt], and [crate::completion::Chat] traits. All
12//! agent execution goes through [AgentRunner], so hooks and lifecycle policies
13//! cannot be bypassed through a raw agent request builder.
14//!
15//! The [AgentBuilder] implements the builder pattern for creating instances of [Agent].
16//! It allows configuring the model, preamble, context documents, tools, temperature, and additional parameters
17//! before building the agent.
18//!
19//! # Example
20//! ```no_run
21//! use rig_agent::prelude::*;
22//! use rig_core::{client::ProviderClient, providers::openai};
23//!
24//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
25//! let openai = openai::Client::from_env()?;
26//!
27//! // Configure the agent
28//! let agent = openai.agent(openai::GPT_5_2)
29//!     .preamble("System prompt")
30//!     .context("Context document 1")
31//!     .context("Context document 2")
32//!     .temperature(0.8)
33//!     .build();
34//!
35//! // Use the agent for chats and prompts
36//! // Generate a chat completion response from a prompt and chat history
37//! let chat_response = agent.chat("Prompt", &mut Vec::<rig_core::completion::Message>::new()).await?;
38//!
39//! // Generate a prompt completion response from a simple prompt
40//! let prompt_response = agent.prompt("Prompt").await?;
41//!
42//! // Per-run overrides stay inside the hook-aware runner.
43//! let response = agent.runner("Prompt").temperature(0.9).run().await?;
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! [`AgentBuilder::dynamic_context`] provides passive RAG through the same
49//! completion-call hook lifecycle as every other request policy. For custom
50//! query selection, filtering, reranking, caching, formatting, or failure
51//! handling, applications can instead implement [`AgentHook`] and inject
52//! documents with [`RequestPatch::extra_context`]. Active RAG exposes a vector
53//! index or custom retriever as a tool so the model decides when to search.
54//!
55//! Passive RAG agent example
56//! ```no_run
57//! use rig_agent::{completion::Prompt, prelude::*};
58//! use rig_core::{
59//!     client::{EmbeddingsClient, ProviderClient},
60//!     embeddings::EmbeddingsBuilder,
61//!     providers::openai,
62//!     vector_store::in_memory_store::InMemoryVectorStore,
63//! };
64//!
65//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
66//! // Initialize OpenAI client
67//! let openai = openai::Client::from_env()?;
68//!
69//! // Initialize OpenAI embedding model
70//! let embedding_model = openai.embedding_model(openai::TEXT_EMBEDDING_3_SMALL);
71//!
72//! // Create vector store, compute embeddings and load them in the store
73//! let mut vector_store = InMemoryVectorStore::default();
74//!
75//! let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
76//!     .documents(vec![
77//!         "Definition of a *flurbo*: A flurbo is a green alien that lives on cold planets",
78//!         "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.",
79//!         "Definition of a *linglingdong*: A term used by inhabitants of the far side of the moon to describe humans.",
80//!     ])?
81//!     .build()
82//!     .await?;
83//!
84//! vector_store.add_documents(embeddings);
85//!
86//! // Create vector store index
87//! let index = vector_store.index(embedding_model);
88//!
89//! let agent = openai.agent(openai::GPT_5_2)
90//!     .preamble("
91//!         You are a dictionary assistant here to assist the user in understanding the meaning of words.
92//!         You will find additional non-standard word definitions that could be useful below.
93//!     ")
94//!     .dynamic_context(1, index)
95//!     .build();
96//!
97//! // Prompt the agent and print the response
98//! let response = agent.prompt("What does \"glarb-glarb\" mean?").await?;
99//! # Ok(())
100//! # }
101//! ```
102mod builder;
103mod completion;
104pub mod hook;
105pub mod model;
106pub(crate) mod prompt_request;
107pub mod run;
108pub mod runner;
109mod tool;
110
111/// Fallback display name used in telemetry spans and logs when an agent has no
112/// configured name.
113pub(crate) const UNKNOWN_AGENT_NAME: &str = "Unnamed Agent";
114
115pub use builder::{AgentBuilder, NoToolConfig, WithBuilderTools, WithToolServerHandle};
116pub use completion::Agent;
117pub use hook::CompletionCall as CompletionCallEvent;
118pub use hook::{
119    AgentHook, CompletionCallAction, CompletionResponse as CompletionResponseEvent, HookContext,
120    HookStack, InvalidToolCallAction, InvalidToolCallContext, ModelSelection, ModelSelectionAction,
121    ModelTurnAction, ModelTurnFinished, ObservationAction, ReasoningDelta, RequestPatch,
122    RetryRequest, RunId, Scratchpad, StepEventKind, StreamResponseFinish, TextDelta, ToolCall,
123    ToolCallAction, ToolCallDelta, ToolResultAction, ToolResultEvent,
124};
125pub use model::ModelHandle;
126pub use prompt_request::streaming::{
127    MultiTurnStreamItem, StreamingError, StreamingPromptRequest, StreamingResult, stream_to_stdout,
128};
129pub use prompt_request::{
130    CompletionCall, Extended, PromptRequest, PromptResponse, PromptType, ResponseIdentity,
131    Standard, TypedPromptRequest, TypedPromptResponse,
132};
133pub use rig_core::message::Text;
134pub use run::{AgentRun, AgentRunStep, ModelTurn, ModelTurnOutcome, OutputMode, PendingToolCall};
135pub use runner::AgentRunner;
rig_agent/agent/mod.rs

rig_agent/agent/
mod.rs
