Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Fluent builder for LoopConfig.

let config = AgentBuilder::new()
    .stream(provider)
    .tools(registry)
    .event_sink(channel_sink)
    .before_tool_call(retired_path_gate)
    .after_tool_call(repeat_detector)
    .context_transform(token_budget_pruner)
    .steering(steering_source)
    .max_iterations(50)
    .build();

Implementations

impl AgentBuilder

pub fn new() -> Self

pub fn stream(self, stream: Arc<dyn StreamFn>) -> Self

pub fn tools(self, tools: ToolRegistry) -> Self

pub fn tools_arc(self, tools: Arc<ToolRegistry>) -> Self

Variant for callers that already share a registry by Arc.

pub fn event_sink(self, sink: Arc<dyn EventSink>) -> Self

pub fn default_execution_mode(self, mode: ExecutionMode) -> Self

pub fn max_tool_calls_per_turn(self, max: usize) -> Self

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

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

pub fn reasoning(self, level: ReasoningEffort) -> Self

Set the reasoning-effort knob forwarded to the stream transport on every turn. Per-run overrides flow through this typed surface rather than through stringly-typed provider extras.

pub fn provider_extras(self, extras: Value) -> Self

Set provider-specific extras forwarded to the stream transport on every turn (e.g., response_format for structured output enforcement).

pub fn max_output_tokens_recovery(self, recovery: MaxTokensRecovery) -> Self

Enable max-output-tokens recovery. When the provider returns StopReason::MaxTokens, the loop discards the truncated turn and re-streams with a larger cap up to recovery.max_attempts times. Off by default — opt in by passing a configured MaxTokensRecovery. See the type for cost discussion.

pub fn max_iterations(self, n: usize) -> Self

pub fn empty_outcome_retry_budget(self, n: usize) -> Self

Enable the no-tool outcome watchdog. n is the number of no-tool assistant stops that recovery plugins may handle; the next no-tool stop ends the run with a typed crate::error::LoopError.

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

Convert plain assistant text into a terminal tool result on terminal-only compatibility turns. Intended for providers that reject tool_choice: "required" and therefore can leak final prose even while the host advertises only delivery tools.

pub fn plain_text_terminal_fallback_eager(self, eager: bool) -> Self

Make Self::plain_text_terminal_fallback_tool fire on the FIRST plain-text stop instead of waiting for the turn allowlist to be narrowed to terminators by a downstream tool gate. Use this for providers in the “auto-when-forced” class where wire-level forcing isn’t available, so prose is the model’s default failure mode and the nudge cycle just burns turns. Has no effect unless Self::plain_text_terminal_fallback_tool is also set.

pub fn plain_text_terminal_fallback_eager_nudge(self, on: bool) -> Self

Make the eager plain-text fallback path nudge the model with an explicit protocol-recovery system message before synthesizing a terminal tool result, giving up to a bounded number of retries to follow the protocol. Off by default — opt in for evals and runs where silently laundering prose into delivery is a worse outcome than a small number of extra streaming turns. Has no effect unless both Self::plain_text_terminal_fallback_tool and Self::plain_text_terminal_fallback_eager are set.

pub fn grace_iterations(self, n: usize) -> Self

Override the grace window used by the auto-installed graceful-turn-limit plugin. Pass 0 to disable the soft warning entirely (the loop will hit max_iterations with no advance notice). Default is DEFAULT_GRACE_ITERATIONS.

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

where F: Fn() -> String + Send + Sync + 'static,

Override the one-shot wrap-up message emitted by the auto-installed graceful-turn-limit plugin. Hosts can use this to make the warning aware of product state while keeping the core loop independent of product-specific types.

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

where F: Fn() -> usize + Send + Sync + 'static,

Supply a dynamic grace-iterations provider for the auto-installed graceful-turn-limit plugin. The callback is invoked on every steering poll, and its return value is clamped into [1, max_iterations - 1]. Use this to scale the wrap-up window with the size of the work in flight (e.g. more open plan phases ⇒ a longer wrap-up window so a partial delivery can still land). When unset, the static grace_iterations value is used.

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

Attach a conversation identifier so plugins can include conversation-scoped diagnostics or policy. The agent core itself does not consume this — it’s just metadata threaded through ToolGateContext. Optional; absent for tests and isolated subagent runs.

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

Attach a model identifier so context transforms can read it via crate::plugin::TransformContext::model_id. The loop itself does not consume this; the active StreamFn already knows its model. Optional — defaults to None (transforms see the empty string).

pub fn token_estimator<E: TokenEstimator>(self, est: E) -> Self

Plug in a token estimator for budgeting and compaction. Defaults to the char-heuristic estimator when not set. Pass an Arc if the estimator is shared across multiple builders.

pub fn token_estimator_arc(self, est: Arc<dyn TokenEstimator>) -> Self

Variant for callers that already share an estimator by Arc.

pub fn protocol_policy(self, policy: Arc<dyn ProtocolPolicy>) -> Self

Install a ProtocolPolicy — the seam through which a downstream product supplies its tool vocabulary (plain-text recovery prose, tool-call alias repair, hidden-tool errors, terminal-tool classification). Defaults to crate::DefaultProtocolPolicy when not set, which keeps the core free of any product tool names. See crate::protocol.

pub fn before_tool_call<P: BeforeToolCall + 'static>(self, plugin: P) -> Self

pub fn after_tool_call<P: AfterToolCall + 'static>(self, plugin: P) -> Self

pub fn context_transform<P: ContextTransform + 'static>(self, plugin: P) -> Self

pub fn event_observer<P: EventObserver + 'static>(self, plugin: P) -> Self

pub fn steering<P: SteeringSource + 'static>(self, plugin: P) -> Self

pub fn follow_up<P: FollowUpSource + 'static>(self, plugin: P) -> Self

pub fn before_tool_call_arc(self, plugin: Arc<dyn BeforeToolCall>) -> Self

Variant that takes pre-Arc’d trait objects, useful when the caller already has shared plugin instances.

pub fn after_tool_call_arc(self, plugin: Arc<dyn AfterToolCall>) -> Self

pub fn context_transform_arc(self, plugin: Arc<dyn ContextTransform>) -> Self

pub fn event_observer_arc(self, plugin: Arc<dyn EventObserver>) -> Self

pub fn follow_up_arc(self, plugin: Arc<dyn FollowUpSource>) -> Self

pub fn steering_arc(self, plugin: Arc<dyn SteeringSource>) -> Self

pub fn tool_gate_arc(self, plugin: Arc<dyn ToolGate>) -> Self

pub fn plugin<P>(self, plugin: Arc<P>) -> Self

where P: Plugin + BeforeToolCall + AfterToolCall + ContextTransform + EventObserver + SteeringSource + FollowUpSource + ToolGate + 'static,

Generic plugin registration. Inspects Plugin::capabilities to decide which dispatch lists to add the plugin to. Same Arc is shared across all enabled capabilities so a single plugin instance can implement multiple traits.

pub fn build(self) -> Result<LoopConfig, BuilderError>

Trait Implementations

impl Default for AgentBuilder

fn default() -> Self

Returns the “default value” for a type.