Struct LlmTextAgent 

pub struct LlmTextAgent { /* private fields */ }

Core text agent — calls BaseLlm::generate(), dispatches tools, loops until the model produces a final text response.

Middleware hooks fire at each lifecycle point:

• before_model / after_model — wraps each BaseLlm::generate() call; before_model may return a cached response to skip the LLM entirely.
• before_tool / after_tool / on_tool_error — wraps each tool dispatch.
• on_error — called when run() is about to return an error.

Note: before_agent/after_agent are Live-session hooks that require an InvocationContext (a Live WebSocket concept) and are therefore not invoked by LlmTextAgent. Use before_model or wrap in a custom TextAgent if you need entry/exit hooks for the text path.

Implementations

impl LlmTextAgent

pub fn new(name: impl Into<String>, llm: impl BaseLlm + 'static) -> Self

Create a new LLM text agent.

llm is any BaseLlm: a GeminiLlm, a shared Arc<dyn BaseLlm>, or a MockLlm in tests.

pub fn instruction(self, inst: impl Into<String>) -> Self

Set the system instruction.

pub fn instruction_provider( self, provider: impl InstructionProvider + 'static, ) -> Self

Set a dynamic instruction source — an InstructionProvider (any Fn(&State) -> String closure, or a TemplateInstruction under the templates feature) resolved against session state at the start of every run. Wins over instruction.

pub fn llm_provider<F>(self, provider: F) -> Self

where F: Fn(&State) -> Arc<dyn BaseLlm> + Send + Sync + 'static,

Set a dynamic model source, resolved against session state at the start of every run — risk-based escalation to a stronger model, cost routing to a cheaper one, per-tenant model selection — without rebuilding the agent. Wins over the constructor’s model when set.

pub fn tools(self, dispatcher: Arc<ToolDispatcher>) -> Self

Set the tool dispatcher.

pub fn model(self, model: impl Into<String>) -> Self

Call model instead of the provider’s default model, e.g. "gemini-2.5-pro".

pub fn temperature(self, t: f32) -> Self

Set temperature.

pub fn max_output_tokens(self, n: u32) -> Self

Set max output tokens.

pub fn top_p(self, p: f32) -> Self

Set the nucleus sampling threshold.

pub fn top_k(self, k: u32) -> Self

Sample from the k most likely tokens.

pub fn stop_sequences( self, sequences: impl IntoIterator<Item = impl Into<String>>, ) -> Self

End generation when the model produces any of sequences.

pub fn thinking_budget(self, tokens: u32) -> Self

Give the model a thinking budget, in tokens.

pub fn built_in_tool(self, tool: Tool) -> Self

Add a built-in tool (Google Search, code execution, URL context), sent alongside the dispatcher’s function declarations.

pub fn response_schema(self, schema: Value) -> Self

Constrain the reply to JSON matching schema.

pub fn output_key(self, key: impl Into<String>) -> Self

Also write the final text to state under key (it is always written to "output").

pub fn add_middleware(self, mw: Arc<dyn Middleware>) -> Self

Append a middleware layer to the chain.

Layers are run in insertion order for before_* / on_error hooks and in reverse insertion order for after_* hooks (outermost last).

pub fn with_middleware_chain(self, chain: MiddlewareChain) -> Self

Replace the entire middleware chain (advanced — prefer add_middleware).

Trait Implementations

impl TextAgent for LlmTextAgent

fn name(&self) -> &str

Human-readable name for logging and debugging.

fn run<'life0, 'life1, 'async_trait>( &'life0 self, state: &'life1 State, ) -> Pin<Box<dyn Future<Output = Result<String, AgentError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Execute this agent. Reads/writes state. Returns the final text output.

fn run_with<'life0, 'life1, 'async_trait>( &'life0 self, request: RunRequest, state: &'life1 State, ) -> Pin<Box<dyn Future<Output = Result<RunResult, AgentError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run one request and report everything it produced: the reply, the turns to append to a conversation, token usage and tool calls.

fn run_stream<'a>( &'a self, request: RunRequest, state: State, ) -> BoxStream<'a, Result<RunEvent, AgentError>>

Run one request as a stream of RunEvents: text as the model writes it, each tool call and result, then RunEvent::Finished.

fn stream( &self, prompt: impl Into<String>, ) -> BoxStream<'_, Result<RunEvent, AgentError>>

where Self: Sized,

Stream the reply to one question, with no history and fresh state.

fn ask<'life0, 'async_trait>( &'life0 self, prompt: impl 'async_trait + Into<String> + Send, ) -> Pin<Box<dyn Future<Output = Result<String, AgentError>> + Send + 'async_trait>>

where Self: Sized + 'async_trait, 'life0: 'async_trait,

Ask one question, with no history and fresh state, and get the reply.

fn ask_as<'life0, 'async_trait, T>( &'life0 self, prompt: impl 'async_trait + Into<String> + Send, ) -> Pin<Box<dyn Future<Output = Result<T, AgentError>> + Send + 'async_trait>>

where Self: Sized + 'async_trait, T: DeserializeOwned + JsonSchema + Send + 'async_trait, 'life0: 'async_trait,

Ask one question and get the reply as a T.

fn chat(&self) -> Chat<&Self>

where Self: Sized,

Start a conversation that remembers its turns. See Chat.