Struct Agent 

pub struct Agent {

    pub name: String,
    pub model: String,
    pub history: Vec<Message>,
    pub local_tools: Option<Vec<Tool>>,
    pub mcp_servers: Option<Vec<McpServerType>>,
    pub tools: Option<Vec<Tool>>,
    pub response_format: Option<Value>,
    pub system_prompt: String,
    pub stop_prompt: Option<String>,
    pub stopword: Option<String>,
    pub strip_thinking: bool,
    pub temperature: Option<f32>,
    pub top_p: Option<f32>,
    pub presence_penalty: Option<f32>,
    pub frequency_penalty: Option<f32>,
    pub num_ctx: Option<u32>,
    pub repeat_last_n: Option<i32>,
    pub repeat_penalty: Option<f32>,
    pub seed: Option<i32>,
    pub stop: Option<String>,
    pub num_predict: Option<i32>,
    pub top_k: Option<u32>,
    pub min_p: Option<f32>,
    pub keep_alive: Option<String>,
    pub stream: bool,
    pub notification_channel: Option<Sender<Notification>>,
    pub template: Option<Arc<Mutex<Template>>>,
    pub max_iterations: Option<usize>,
    pub clear_history_on_invoke: bool,
    pub state: HashMap<String, Value>,
    /* private fields */
}

Fields

name: String

Human-readable name of the agent.

model: String

Underlying model identifier.

history: Vec<Message>

Conversation history with the model.

local_tools: Option<Vec<Tool>>

Locally registered tools (before MCP merge).

mcp_servers: Option<Vec<McpServerType>>

Configured MCP server endpoints.

tools: Option<Vec<Tool>>

Fully compiled tool set (local + MCP).

response_format: Option<Value>

JSON schema format for responses, if any.

system_prompt: String

System prompt injected at the start of the conversation.

stop_prompt: Option<String>

Optional stop prompt inserted on tool branches.

stopword: Option<String>

Stopword to detect end of generation.

strip_thinking: bool

Whether <think> blocks should be stripped from outputs.

temperature: Option<f32>

Sampling temperature.

top_p: Option<f32>

Nucleus sampling top-p parameter.

presence_penalty: Option<f32>

Presence penalty parameter.

frequency_penalty: Option<f32>

Frequency penalty parameter.

num_ctx: Option<u32>

Maximum context window size.

repeat_last_n: Option<i32>

Last-N window for repetition penalty.

repeat_penalty: Option<f32>

Repetition penalty multiplier.

seed: Option<i32>

RNG seed for reproducibility.

stop: Option<String>

Hard stop sequence.

num_predict: Option<i32>

Maximum tokens to predict.

top_k: Option<u32>

Top-K sampling cutoff.

min_p: Option<f32>

Minimum probability threshold.

keep_alive: Option<String>

Keep alive - keep model in memory

stream: bool

Whether to stream token notifications.

notification_channel: Option<Sender<Notification>>

Notification channel for emitting agent events.

template: Option<Arc<Mutex<Template>>>

Optional reusable template for prompt building.

max_iterations: Option<usize>

Maximum allowed iterations during a conversation.

clear_history_on_invoke: bool

If true, clears history on every invocation.

state: HashMap<String, Value>

State for custom data

Implementations

impl Agent

pub async fn invoke_flow<T>(&mut self, prompt: T) -> Result<Message, AgentError>

where T: Into<String>,

Invoke the agent with a raw string prompt.

This is the most direct way to ask the agent something: the given prompt string it is conveterd to a user message and appended to history. It is passed through the configured Flow (either Default or Custom).

Returns the raw Message produced by the flow.

pub async fn invoke_flow_structured_output<T, O>( &mut self, prompt: T, ) -> Result<O, AgentError>

where T: Into<String>, O: DeserializeOwned,

Invoke the agent expecting structured JSON output.

Works like [invoke_flow], but attempts to deserialize the model’s response into type O which must be deserializable.

Use this when you constrain the response with a JSON schema (response_format) and want the result to be typed.

pub async fn invoke_flow_with_template<K, V>( &mut self, template_data: HashMap<K, V>, ) -> Result<Message, AgentError>

where K: Into<String>, V: Into<String>,

Invoke the agent using a prompt compiled from a template.

The provided template_data is substituted into the configured Template before invoking the flow. This allows building prompts from reusable templates instead of raw strings.

Returns the raw Message produced by the flow.

pub async fn invoke_flow_with_template_structured_output<K, V, O>( &mut self, template_data: HashMap<K, V>, ) -> Result<O, AgentError>

where K: Into<String>, V: Into<String>, O: DeserializeOwned,

Invoke the agent with a template and parse structured output.

Combines [invoke_flow_with_template] with [invoke_flow_structured_output]: first compiles the prompt from the agent’s Template and template_data, then invokes the flow and tries to deserialize the result into type O.

Use this when you constrain the response with a JSON schema (response_format) and want the result to be typed.

pub fn clear_history(&mut self)

Reset conversation history to contain only the system prompt.

pub fn save_history<P: AsRef<Path>>( &self, path: P, ) -> Result<(), Box<dyn Error>>

Persist the conversation history to disk in pretty-printed JSON.

pub async fn new_notification_channel( &mut self, ) -> Result<Receiver<Notification>, AgentError>

Create a new notification channel for this agent.

This re-initializes MCP tool connections so they bind to the new channel.

pub async fn get_compiled_tools( &self, ) -> Result<Option<Vec<Tool>>, AgentBuildError>

Build and return the tool set (local tools + MCP tools).

pub async fn get_compiled_mcp_tools( &self, ) -> Result<Option<Vec<Tool>>, AgentBuildError>

Build tool definitions from configured MCP servers.

pub fn get_tool_ref_by_name<T>(&self, name: T) -> Option<&Tool>

where T: Into<String>,

Find a tool reference by name, if it exists.

pub fn export_client_config(&self) -> ClientConfig

Export current client configuration (provider, base URL, keys, etc.).

pub fn export_model_config(&self) -> ModelConfig

Export current model configuration (temperature, top_p, penalties, etc.).

pub async fn export_prompt_config(&self) -> Result<PromptConfig, Error>

Export prompt-level configuration (system prompt, tools, template, etc.).

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&Agent> for ChatRequest

fn from(val: &Agent) -> Self

Converts to this type from the input type.

impl NotificationHandler for Agent

fn get_outgoing_channel(&self) -> &Option<Sender<Notification>>

fn get_channel_name(&self) -> &String

async fn notify(&self, content: NotificationContent) -> bool

Send a notification with the given content.

fn forward_notifications(&self, from_channel: Receiver<Notification>)

Forward notifications from an external receiver into this agent’s notification output channel.

fn forward_multiple_notifications<I>(&self, channels: I)

where I: IntoIterator<Item = Receiver<Notification>>,

Merge any number of Receiver<Notification> streams into one, and forward all messages into this agent’s notification output channel.

async fn notify_done(&self, success: Success, resp: Response) -> bool

async fn notify_prompt_request(&self, req: ChatRequest) -> bool

async fn notify_poompt_success(&self, resp: ChatResponse) -> bool

async fn notify_prompt_error(&self, error_message: String) -> bool

async fn notify_tool_request(&self, tool_call: ToolCall) -> bool

async fn notify_tool_success(&self, tool_result: String) -> bool

async fn notify_tool_error(&self, error_message: String) -> bool

async fn notify_token(&self, token: Token) -> bool

async fn notify_mcp_tool_notification(&self, notification: String) -> bool

async fn notify_custom(&self, custom_val: Value) -> bool