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(crate) mod prompt_request;
106pub mod run;
107pub mod runner;
108mod tool;
109
110/// Fallback display name used in telemetry spans and logs when an agent has no
111/// configured name.
112pub(crate) const UNKNOWN_AGENT_NAME: &str = "Unnamed Agent";
113
114pub use builder::{AgentBuilder, NoToolConfig, WithBuilderTools, WithToolServerHandle};
115pub use completion::Agent;
116pub use hook::CompletionCall as CompletionCallEvent;
117pub use hook::{
118    AgentHook, CompletionCallAction, CompletionResponse as CompletionResponseEvent, HookContext,
119    HookStack, InvalidToolCallAction, InvalidToolCallContext, ModelTurnAction, ModelTurnFinished,
120    ObservationAction, RequestPatch, RetryRequest, RunId, Scratchpad, StepEventKind,
121    StreamResponseFinish, TextDelta, ToolCall, ToolCallAction, ToolCallDelta, ToolResultAction,
122    ToolResultEvent,
123};
124pub use prompt_request::streaming::{
125    MultiTurnStreamItem, StreamingError, StreamingPromptRequest, StreamingResult, stream_to_stdout,
126};
127pub use prompt_request::{
128    CompletionCall, PromptRequest, PromptResponse, TypedPromptRequest, TypedPromptResponse,
129};
130pub use rig_core::message::Text;
131pub use run::{AgentRun, AgentRunStep, ModelTurn, ModelTurnOutcome, OutputMode, PendingToolCall};
132pub use runner::AgentRunner;
rig_agent/agent/mod.rs

rig_agent/agent/
mod.rs
