Struct Agent 

#[non_exhaustive]
pub struct Agent<M>
where
    M: CompletionModel,
{ /* private fields */ }

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_agent::prelude::*;
use rig_core::{client::ProviderClient, 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?;

Implementations

impl<M> Agent<M>

where M: CompletionModel,

pub fn name(&self) -> Option<&str>

Returns the configured agent name.

pub fn description(&self) -> Option<&str>

Returns the configured agent description.

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.

pub async fn tool_definitions( &self, prompt: Option<String>, ) -> Result<Vec<ToolDefinition>, ToolServerError>

Resolve the provider-facing tool definitions available for a prompt.

This read-only view does not expose tool dispatch. Agent execution and tool lifecycle hooks remain owned by Self::runner.

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

pub fn into_tool(self) -> DynamicTool

Convert this agent into a runtime-defined tool.

The configured agent name becomes the tool name. Unnamed agents use agent_tool. This explicit conversion keeps runtime identity out of the statically named Tool trait.

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>

Execute one turn and append only committed messages to chat_history.

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> 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: CompletionModel + 'static> From<Agent<M>> for DynamicTool

fn from(agent: Agent<M>) -> Self

Converts to this type from the input type.

impl<M> Prompt for Agent<M>

where M: CompletionModel + 'static,

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

Send a prompt and return accepted assistant text after runtime orchestration.

impl<M> Prompt for &Agent<M>

where M: CompletionModel + 'static,

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

Send a prompt and return accepted assistant text after runtime orchestration.

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>,

Create a classic streaming request with canonical chat history.

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>

Create a classic streaming request for prompt.

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

Request type returned for one target output type.

impl<M> TypedPrompt for &Agent<M>

where M: CompletionModel + 'static,

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

Request type returned for one target output type.

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

where T: JsonSchema + DeserializeOwned + WasmCompatSend,

Send a prompt and deserialize the accepted structured response as T.