Struct Agent 

#[non_exhaustive]
pub struct Agent<M>
where
    M: CompletionModel,
{

    pub name: Option<String>,
    pub description: Option<String>,
    pub model: Arc<M>,
    pub preamble: Option<String>,
    pub static_context: Vec<Document>,
    pub temperature: Option<f64>,
    pub max_tokens: Option<u64>,
    pub additional_params: Option<Value>,
    pub tool_server_handle: ToolServerHandle,
    pub dynamic_context: Arc<Vec<(usize, Arc<dyn VectorStoreIndexDyn + Send + Sync>)>>,
    pub tool_choice: Option<ToolChoice>,
    pub default_max_turns: Option<usize>,
    pub hooks: HookStack<M>,
    pub output_schema: Option<Schema>,
    pub output_mode: OutputMode,
    pub memory: Option<Arc<dyn ConversationMemory>>,
    pub default_conversation_id: Option<String>,
}

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.

Default hooks attached with AgentBuilder::add_hook are used for every prompt request, plus any added on the request or runner.

Example

use rig_core::{
    client::{CompletionClient, ProviderClient},
    completion::Prompt,
    providers::openai,
};

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

let comedian_agent = openai
    .agent(openai::GPT_5_2)
    .preamble("You are a comedian here to entertain the user using humour and jokes.")
    .temperature(0.9)
    .build();

let response = comedian_agent.prompt("Entertain me!").await?;

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: Option<String>

Name of the agent used for logging and debugging

description: Option<String>

Agent description. Primarily useful when using sub-agents as part of an agent workflow and converting agents to other formats.

model: Arc<M>

Completion model (e.g.: OpenAI’s gpt-3.5-turbo-1106, Cohere’s command-r)

preamble: Option<String>

System prompt

static_context: Vec<Document>

Context documents always available to the agent

temperature: Option<f64>

Temperature of the model

max_tokens: Option<u64>

Maximum number of tokens for the completion

additional_params: Option<Value>

Additional parameters to be passed to the model

tool_server_handle: ToolServerHandle

dynamic_context: Arc<Vec<(usize, Arc<dyn VectorStoreIndexDyn + Send + Sync>)>>

List of vector store, with the sample number

tool_choice: Option<ToolChoice>

Whether or not the underlying LLM should be forced to use a tool before providing a response.

default_max_turns: Option<usize>

Default total model-call budget, including the initial call and every retry or continuation. None uses the implicit budget of one.

hooks: HookStack<M>

Default hook stack applied to every prompt request and runner created from this agent. Empty by default.

output_schema: Option<Schema>

Optional JSON Schema for structured output. When set, providers that support native structured outputs will constrain the model’s response to match this schema.

output_mode: OutputMode

How output_schema is enforced — tool call, native structured output, or prompt injection (see OutputMode and issue #1928).

memory: Option<Arc<dyn ConversationMemory>>

Optional conversation memory backend that loads/saves history per conversation id.

default_conversation_id: Option<String>

Optional default conversation id used when none is set per-request.

Implementations

impl<M> Agent<M>

where M: CompletionModel,

pub fn runner(&self, prompt: impl Into<Message>) -> AgentRunner<M>

Build a hook-aware AgentRunner for this agent, seeded with the agent’s default hook stack. Attach more hooks with AgentRunner::add_hook, then call AgentRunner::run.

Trait Implementations

impl<M> Chat for Agent<M>

where M: CompletionModel + 'static,

async fn chat( &self, prompt: impl Into<Message> + WasmCompatSend, chat_history: &mut Vec<Message>, ) -> Result<String, PromptError>

Send a prompt with optional chat history to the underlying completion model.

impl<M> Clone for Agent<M>

where M: CompletionModel + Clone,

fn clone(&self) -> Agent<M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M> Completion<M> for Agent<M>

where M: CompletionModel,

async fn completion<I, T>( &self, prompt: impl Into<Message> + WasmCompatSend, chat_history: I, ) -> Result<CompletionRequestBuilder<M>, CompletionError>

where I: IntoIterator<Item = T>, T: Into<Message>,

Generates a completion request builder for the given prompt and chat_history. This function is meant to be called by the user to further customize the request at prompt time before sending it.

impl<M> DiscordExt for Agent<M>

where M: CompletionModel + Send + Sync + 'static,

Available on crate feature discord-bot only.

async fn into_discord_bot(self, token: &str) -> Result<Client, DiscordBotError>

fn into_discord_bot_from_env( self, ) -> impl Future<Output = Result<Client, DiscordBotError>> + Send

impl<M> Prompt for Agent<M>

where M: CompletionModel + 'static,

fn prompt( &self, prompt: impl Into<Message> + WasmCompatSend, ) -> PromptRequest<Standard, M>

Send a simple prompt to the underlying completion model.

impl<M> Prompt for &Agent<M>

where M: CompletionModel + 'static,

fn prompt( &self, prompt: impl Into<Message> + WasmCompatSend, ) -> PromptRequest<Standard, M>

Send a simple prompt to the underlying completion model.

impl<M> StreamingChat<M, <M as CompletionModel>::StreamingResponse> for Agent<M>

where M: CompletionModel + 'static, M::StreamingResponse: GetTokenUsage,

fn stream_chat<I, T>( &self, prompt: impl Into<Message> + WasmCompatSend, chat_history: I, ) -> StreamingPromptRequest<M>

where I: IntoIterator<Item = T>, T: Into<Message>,

Stream a chat with history to the model.

impl<M> StreamingCompletion<M> for Agent<M>

where M: CompletionModel,

async fn stream_completion<I, T>( &self, prompt: impl Into<Message> + WasmCompatSend, chat_history: I, ) -> Result<CompletionRequestBuilder<M>, CompletionError>

where I: IntoIterator<Item = T> + WasmCompatSend, T: Into<Message>,

Generate a streaming completion from a request

impl<M> StreamingPrompt<M, <M as CompletionModel>::StreamingResponse> for Agent<M>

where M: CompletionModel + 'static, M::StreamingResponse: GetTokenUsage,

fn stream_prompt( &self, prompt: impl Into<Message> + WasmCompatSend, ) -> StreamingPromptRequest<M>

Stream a simple prompt to the model.

impl<M: CompletionModel + 'static> Tool for Agent<M>

async fn call_with_extensions( &self, args: Self::Args, extensions: &ToolCallExtensions, ) -> Result<Self::Output, Self::Error>

Propagate the caller’s ToolCallExtensions into the sub-agent run, so the inner agent’s own tools observe them too (sub-agent delegation / A2A chains). Without this, a sub-agent invoked as a tool would start with empty extensions.

const NAME: &'static str = "agent_tool"

The name of the tool. This name should be unique within a single ToolSet or other registration scope that dispatches tools by name.

type Error = PromptError

The error type of the tool.

type Args = AgentToolArgs

The arguments type of the tool.

type Output = String

The output type of the tool.

fn description(&self) -> String

Model-facing description of what the tool does.

fn parameters(&self) -> Value

JSON Schema for the tool arguments.

async fn call(&self, args: Self::Args) -> Result<Self::Output, Self::Error>

The tool execution method. Both the arguments and return value are a String since these values are meant to be the output and input of LLM models (respectively)

fn name(&self) -> String

A method returning the name of the tool.

fn classify_error(&self, error: &Self::Error) -> ToolFailure

Classify an error returned by this tool into a structured ToolFailure.

fn call_structured( &self, args: Self::Args, extensions: &ToolCallExtensions, ) -> impl Future<Output = Result<ToolReturn<Self::Output>, Self::Error>> + WasmCompatSend

Execute the tool, returning a structured ToolReturn instead of a bare output.

impl<M> TypedPrompt for Agent<M>

where M: CompletionModel + 'static,

fn prompt_typed<T>( &self, prompt: impl Into<Message> + WasmCompatSend, ) -> TypedPromptRequest<T, Standard, M>

where T: JsonSchema + DeserializeOwned + WasmCompatSend,

Send a prompt and receive a typed structured response.

The JSON schema for T is automatically generated and sent to the provider. Providers that support native structured outputs will constrain the model’s response to match this schema.

Example

use rig_core::prelude::*;
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct WeatherForecast {
    city: String,
    temperature_f: f64,
    conditions: String,
}

let agent = client.agent("gpt-4o").build();

// Type inferred from variable
let forecast: WeatherForecast = agent
    .prompt_typed("What's the weather in NYC?")
    .await?;

// Or explicit turbofish syntax
let forecast = agent
    .prompt_typed::<WeatherForecast>("What's the weather in NYC?")
    .max_turns(3)
    .await?;

type TypedRequest<T> = TypedPromptRequest<T, Standard, M> where T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static

The type of the typed prompt request returned by prompt_typed.

impl<M> TypedPrompt for &Agent<M>

where M: CompletionModel + 'static,

type TypedRequest<T> = TypedPromptRequest<T, Standard, M> where T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static

The type of the typed prompt request returned by prompt_typed.

fn prompt_typed<T>( &self, prompt: impl Into<Message> + WasmCompatSend, ) -> TypedPromptRequest<T, Standard, M>

where T: JsonSchema + DeserializeOwned + WasmCompatSend,

Send a prompt and receive a typed structured response.