rig_core/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 context documents, and a set of tools. Note: both context documents and tools can be either
5//! static (i.e.: they are always provided) or dynamic (i.e.: they are RAGged 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 with a set of dynamic
9//! context documents and tools.
10//!
11//! The [Agent] struct implements the [crate::completion::Completion] and [crate::completion::Prompt] traits,
12//! allowing it to be used for generating completions responses and prompts. The [Agent] struct also
13//! implements the [crate::completion::Chat] trait, which allows it to be used for generating chat completions.
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_core::{
22//!     client::{CompletionClient, ProviderClient},
23//!     completion::{Chat, Completion, Prompt},
24//!     providers::openai,
25//! };
26//!
27//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
28//! let openai = openai::Client::from_env()?;
29//!
30//! // Configure the agent
31//! let agent = openai.agent(openai::GPT_5_2)
32//!     .preamble("System prompt")
33//!     .context("Context document 1")
34//!     .context("Context document 2")
35//!     .temperature(0.8)
36//!     .build();
37//!
38//! // Use the agent for completions and prompts
39//! // Generate a chat completion response from a prompt and chat history
40//! let chat_response = agent.chat("Prompt", &mut Vec::<rig_core::completion::Message>::new()).await?;
41//!
42//! // Generate a prompt completion response from a simple prompt
43//! let prompt_response = agent.prompt("Prompt").await?;
44//!
45//! // Generate a completion request builder from a prompt and chat history. The builder
46//! // will contain the agent's configuration (i.e.: preamble, context documents, tools,
47//! // model parameters, etc.), but these can be overwritten.
48//! let completion_req_builder = agent
49//!     .completion("Prompt", Vec::<rig_core::completion::Message>::new())
50//!     .await?;
51//!
52//! let response = completion_req_builder
53//!     .temperature(0.9) // Overwrite the agent's temperature
54//!     .send()
55//!     .await?;
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! RAG Agent example
61//! ```no_run
62//! use rig_core::{
63//!     client::{CompletionClient, EmbeddingsClient, ProviderClient},
64//!     completion::Prompt,
65//!     embeddings::EmbeddingsBuilder,
66//!     providers::openai,
67//!     vector_store::in_memory_store::InMemoryVectorStore,
68//! };
69//!
70//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
71//! // Initialize OpenAI client
72//! let openai = openai::Client::from_env()?;
73//!
74//! // Initialize OpenAI embedding model
75//! let embedding_model = openai.embedding_model(openai::TEXT_EMBEDDING_3_SMALL);
76//!
77//! // Create vector store, compute embeddings and load them in the store
78//! let mut vector_store = InMemoryVectorStore::default();
79//!
80//! let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
81//!     .documents(vec![
82//!         "Definition of a *flurbo*: A flurbo is a green alien that lives on cold planets",
83//!         "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.",
84//!         "Definition of a *linglingdong*: A term used by inhabitants of the far side of the moon to describe humans.",
85//!     ])?
86//!     .build()
87//!     .await?;
88//!
89//! vector_store.add_documents(embeddings);
90//!
91//! // Create vector store index
92//! let index = vector_store.index(embedding_model);
93//!
94//! let agent = openai.agent(openai::GPT_5_2)
95//!     .preamble("
96//!         You are a dictionary assistant here to assist the user in understanding the meaning of words.
97//!         You will find additional non-standard word definitions that could be useful below.
98//!     ")
99//!     .dynamic_context(1, index)
100//!     .build();
101//!
102//! // Prompt the agent and print the response
103//! let response = agent.prompt("What does \"glarb-glarb\" mean?").await?;
104//! # Ok(())
105//! # }
106//! ```
107mod builder;
108mod completion;
109pub(crate) mod prompt_request;
110mod tool;
111
112pub use crate::message::Text;
113pub use builder::{AgentBuilder, NoToolConfig, WithBuilderTools, WithToolServerHandle};
114pub use completion::Agent;
115pub use prompt_request::hooks::{HookAction, PromptHook, ToolCallHookAction};
116pub use prompt_request::streaming::{
117    FinalResponse, MultiTurnStreamItem, StreamingError, StreamingPromptRequest, StreamingResult,
118    stream_to_stdout,
119};
120pub use prompt_request::{PromptRequest, PromptResponse, TypedPromptRequest, TypedPromptResponse};
rig_core/agent/mod.rs

rig_core/agent/
mod.rs
