rig/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//! ```rust
21//! use rig::{
22//!     client::ProviderClient,
23//!     completion::{Chat, Completion, Prompt},
24//!     providers::openai,
25//! };
26//!
27//! let openai = openai::Client::from_env()?;
28//!
29//! // Configure the agent
30//! let agent = openai.agent("gpt-4o")
31//!     .preamble("System prompt")
32//!     .context("Context document 1")
33//!     .context("Context document 2")
34//!     .tool(tool1)
35//!     .tool(tool2)
36//!     .temperature(0.8)
37//!     .additional_params(json!({"foo": "bar"}))
38//!     .build();
39//!
40//! // Use the agent for completions and prompts
41//! // Generate a chat completion response from a prompt and chat history
42//! let chat_response = agent.chat("Prompt", chat_history)
43//!     .await
44//!     .expect("Failed to chat with Agent");
45//!
46//! // Generate a prompt completion response from a simple prompt
47//! let chat_response = agent.prompt("Prompt")
48//!     .await
49//!     .expect("Failed to prompt the Agent");
50//!
51//! // Generate a completion request builder from a prompt and chat history. The builder
52//! // will contain the agent's configuration (i.e.: preamble, context documents, tools,
53//! // model parameters, etc.), but these can be overwritten.
54//! let completion_req_builder = agent.completion("Prompt", chat_history)
55//!     .await
56//!     .expect("Failed to create completion request builder");
57//!
58//! let response = completion_req_builder
59//!     .temperature(0.9) // Overwrite the agent's temperature
60//!     .send()
61//!     .await
62//!     .expect("Failed to send completion request");
63//! ```
64//!
65//! RAG Agent example
66//! ```rust
67//! use rig::{
68//!     client::ProviderClient,
69//!     completion::Prompt,
70//!     embeddings::EmbeddingsBuilder,
71//!     providers::openai,
72//!     vector_store::{in_memory_store::InMemoryVectorStore, VectorStore},
73//! };
74//!
75//! // Initialize OpenAI client
76//! let openai = openai::Client::from_env()?;
77//!
78//! // Initialize OpenAI embedding model
79//! let embedding_model = openai.embedding_model(openai::TEXT_EMBEDDING_ADA_002);
80//!
81//! // Create vector store, compute embeddings and load them in the store
82//! let mut vector_store = InMemoryVectorStore::default();
83//!
84//! let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
85//!     .simple_document("doc0", "Definition of a *flurbo*: A flurbo is a green alien that lives on cold planets")
86//!     .simple_document("doc1", "Definition of a *glarb-glarb*: A glarb-glarb is a ancient tool used by the ancestors of the inhabitants of planet Jiro to farm the land.")
87//!     .simple_document("doc2", "Definition of a *linglingdong*: A term used by inhabitants of the far side of the moon to describe humans.")
88//!     .build()
89//!     .await
90//!     .expect("Failed to build embeddings");
91//!
92//! vector_store.add_documents(embeddings)
93//!     .await
94//!     .expect("Failed to add documents");
95//!
96//! // Create vector store index
97//! let index = vector_store.index(embedding_model);
98//!
99//! let agent = openai.agent(openai::GPT_4O)
100//!     .preamble("
101//!         You are a dictionary assistant here to assist the user in understanding the meaning of words.
102//!         You will find additional non-standard word definitions that could be useful below.
103//!     ")
104//!     .dynamic_context(1, index)
105//!     .build();
106//!
107//! // Prompt the agent and print the response
108//! let response = agent.prompt("What does \"glarb-glarb\" mean?").await
109//!     .expect("Failed to prompt the agent");
110//! ```
111mod builder;
112mod completion;
113pub(crate) mod prompt_request;
114mod tool;
115
116pub use crate::message::Text;
117pub use builder::{AgentBuilder, NoToolConfig, WithBuilderTools, WithToolServerHandle};
118pub use completion::Agent;
119pub use prompt_request::hooks::{HookAction, PromptHook, ToolCallHookAction};
120pub use prompt_request::streaming::{
121    FinalResponse, MultiTurnStreamItem, StreamingError, StreamingPromptRequest, StreamingResult,
122    stream_to_stdout,
123};
124pub use prompt_request::{PromptRequest, PromptResponse, TypedPromptRequest, TypedPromptResponse};
rig/agent/mod.rs

rig/agent/
mod.rs
