Struct TokenBudgetHook 

pub struct TokenBudgetHook { /* private fields */ }

Pre-call rate-limiting hook based on a token budget + call quota.

• budget: cumulative token cap for the whole run. on_before_completion pre-checks “confirmed usage + estimated input”, returning Reject when exceeded; on_after_completion accumulates the real usage.
• max_calls: optional maximum number of LLM calls.
• Without a custom counter, input is estimated with CharRatioCounter::new(4) (characters / 4).

Example

use lc_agents::hooks::TokenBudgetHook;

let executor = AgentExecutor::new(agent, tools)
    .hook(TokenBudgetHook::new(10_000).with_max_calls(20));

Implementations

impl TokenBudgetHook

pub fn new(budget: usize) -> Self

Creates a token-budget hook. budget is the cumulative token cap for the whole run.

pub fn with_max_calls(self, max_calls: usize) -> Self

Sets the maximum number of LLM calls.

pub fn with_counter(self, counter: Arc<dyn TokenCounter>) -> Self

Uses a precise token counter instead of character-ratio estimation.

pub fn budget(&self) -> usize

Token budget cap.

pub fn tokens_used(&self) -> usize

Cumulative token usage (real usage from completed LLM calls).

pub fn calls(&self) -> usize

Number of LLM calls made so far.

pub fn remaining(&self) -> usize

Remaining token budget (floored at 0).

Trait Implementations

impl AgentHook for TokenBudgetHook

fn on_before_completion(&self, ctx: &mut CompletionContext) -> CompletionAction

Called before an LLM completion. Can modify messages or reject the call.

fn on_after_completion( &self, ctx: &mut CompletionResult, ) -> Result<(), HookError>

Called after an LLM completion. Can modify the response.

fn on_before_tool_call(&self, _ctx: &mut ToolCallContext) -> ToolCallAction

Called before a tool call. Can approve, reject, modify, or skip.

fn on_after_tool_call( &self, _ctx: &mut ToolResultContext, ) -> Result<(), HookError>

Called after a tool call. Can modify the result.

fn on_stream_chunk(&self, chunk: &str) -> StreamAction

Called for each streaming token. Can filter, replace, or forward.

fn on_agent_start(&self, _input: &str) -> Result<(), HookError>

Called when the agent starts execution.

fn on_agent_end(&self, _output: &str) -> Result<(), HookError>

Called when the agent finishes execution.

fn on_error(&self, _error: &HookError) -> ErrorAction

Called when an error occurs. Can retry, ignore, or propagate.