Struct ChatAgent 

pub struct ChatAgent { /* private fields */ }

A simple chat agent that processes messages through an LLM provider with tool support.

This is the framework’s ready-to-use agent for text message -> response flows. It manages conversation history, streams responses from the provider, and automatically dispatches tool calls through a BuiltinToolExecutor.

Example

use brainwires_agents::ChatAgent;
use brainwires_tools::{BuiltinToolExecutor, ToolRegistry};
use brainwires_core::{ChatOptions, ToolContext};
use std::sync::Arc;

let provider = /* create a provider */;
let registry = ToolRegistry::with_builtins();
let context = ToolContext::default();
let executor = Arc::new(BuiltinToolExecutor::new(registry, context));
let options = ChatOptions::default();

let mut agent = ChatAgent::new(provider, executor, options)
    .with_system_prompt("You are a helpful assistant.")
    .with_max_tool_rounds(5);

let response = agent.process_message("Hello!").await?;
println!("{}", response);

Implementations

impl ChatAgent

pub fn new( provider: Arc<dyn Provider>, executor: Arc<BuiltinToolExecutor>, options: ChatOptions, ) -> Self

Create a new ChatAgent.

Defaults max_tool_rounds to 10.

pub fn with_max_tool_rounds(self, rounds: usize) -> Self

Set the maximum number of tool-call rounds before the agent stops.

pub fn with_pre_execute_hook(self, hook: Arc<dyn ToolPreHook>) -> Self

Attach a pre-execution hook that can allow or reject tool calls before they run.

pub fn with_system_prompt(self, prompt: &str) -> Self

Add a system prompt as the first message in the conversation.

If messages already exist, the system message is inserted at position 0.

pub async fn process_message(&mut self, input: &str) -> Result<String>

Process a user message and return the final assistant text response.

This is the core completion loop:

1. Adds the user message to history
2. Streams the provider response, collecting text and tool calls
3. If tool calls are present, executes them and loops
4. Returns the final accumulated text once no more tool calls remain (or max_tool_rounds is reached)

pub async fn process_message_streaming<F>( &mut self, input: &str, on_chunk: F, ) -> Result<String>

where F: Fn(&str) + Send + Sync,

Process a user message with streaming — calls on_chunk for each text fragment as it arrives from the provider.

Returns the full accumulated text once the completion loop finishes.

pub fn messages(&self) -> &[Message]

Access the conversation history.

pub fn restore_messages(&mut self, messages: Vec<Message>)

Replace the entire message history with the provided messages.

This is used by session persistence to restore a previously saved conversation when an agent session is recreated.

pub fn clear_history(&mut self)

Clear all messages (including any system prompt).

pub fn trim_history(&mut self, max_messages: usize)

Keep only the last max_messages messages, preserving the system prompt at position 0 if one exists.

pub fn message_count(&self) -> usize

Return the number of messages in the conversation.

pub fn cumulative_usage(&self) -> &Usage

Return the accumulated token usage for this agent session.

Counts prompt + completion tokens across all completions. Updated whenever the provider emits a StreamChunk::Usage event.

pub fn reset_usage(&mut self)

Reset the cumulative token usage counter.

pub async fn compact_history(&mut self) -> Result<()>

Compact conversation history by trimming older messages.

This is a simple, LLM-free compaction that keeps the system prompt (if any) and the most recent keep messages. For LLM-powered summarisation, use the DreamSummarizer from brainwires-autonomy.