Struct ToolLoopAgentBuilder 

pub struct ToolLoopAgentBuilder<Opt, Out> { /* private fields */ }

Builder for ToolLoopAgent. Besides the methods below it accepts every call setting of generate_text (prompt-independent ones).

Implementations

impl<Opt, Out> ToolLoopAgentBuilder<Opt, Out>

pub fn system(self, instructions: impl Into<Instructions>) -> Self

Sets system instructions.

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

Sets a single user prompt (mutually exclusive with messages).

pub fn messages(self, messages: impl IntoIterator<Item = Message>) -> Self

Sets the conversation messages (mutually exclusive with prompt).

pub fn allow_system_in_messages(self) -> Self

Allows system messages inside messages.

pub fn settings(self, settings: CallSettings) -> Self

Replaces all sampling settings.

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

Sets the maximum number of output tokens.

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

Sets the sampling temperature.

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

Sets nucleus sampling.

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

Sets top-k sampling.

pub fn presence_penalty(self, p: f64) -> Self

Sets the presence penalty.

pub fn frequency_penalty(self, p: f64) -> Self

Sets the frequency penalty.

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

Sets stop sequences.

pub fn seed(self, seed: u64) -> Self

Sets the random seed.

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

Sets the reasoning effort.

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

Sets the tool set.

pub fn tool_choice(self, choice: ToolChoice) -> Self

Sets the tool choice.

pub fn active_tools( self, names: impl IntoIterator<Item = impl Into<ToolName>>, ) -> Self

Restricts the tools sent to the model.

pub fn tool_order( self, names: impl IntoIterator<Item = impl Into<ToolName>>, ) -> Self

Sets the order in which tools are sent (listed first, rest alphabetical).

pub fn tools_context(self, context: JsonValue) -> Self

Sets the shared tools context (validated against each tool’s context schema).

pub fn runtime_context(self, context: JsonValue) -> Self

Sets application state for step preparation, approval and lifecycle hooks. This value is separate from tool execution context and is never sent to models.

pub fn tool_approval(self, policy: impl ApprovalPolicy + 'static) -> Self

Sets the call-level approval policy.

pub fn tool_approval_secret(self, secret: SecretBox<[u8]>) -> Self

Sets the secret used to sign approval requests.

pub fn tool_callers(self, callers: ToolCallers) -> Self

Restricts which callers may trigger each tool.

pub fn repair_tool_call(self, repair: impl ToolCallRepair + 'static) -> Self

Sets the tool call repair function.

pub fn refine_tool_input( self, name: impl Into<ToolName>, refine: impl Fn(JsonValue) -> BoxFuture<'static, Result<JsonValue, Error>> + Send + Sync + 'static, ) -> Self

Rewrites the validated input of name before execution.

pub fn sandbox(self, sandbox: Arc<dyn Sandbox>) -> Self

Sets the sandbox handed to tools.

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

Limits how many tools execute concurrently within a step.

pub fn stop_when(self, condition: impl StopCondition + 'static) -> Self

Adds a stop condition (any-of). Without conditions the loop stops after one step.

pub fn prepare_step(self, prepare: impl PrepareStep + 'static) -> Self

Sets the per-step preparation callback.

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

Sets the maximum number of retries (exponential backoff).

pub fn retry_policy(self, policy: RetryPolicy) -> Self

Replaces the retry policy.

pub fn timeout(self, timeout: impl Into<Timeout>) -> Self

Sets timeouts.

pub fn cancellation(self, token: CancellationToken) -> Self

Sets the cancellation token.

pub fn headers(self, headers: Headers) -> Self

Adds request headers.

pub fn provider_options(self, options: ProviderOptions) -> Self

Adds provider options.

pub fn download(self, download: Arc<dyn DownloadFn>) -> Self

Sets the download function for file URLs.

pub fn include(self, include: Include) -> Self

Controls which payloads are kept in step results.

pub fn clock(self, clock: Arc<dyn Clock>) -> Self

Sets the clock used for response.timestamp when the provider sends none.

pub fn id_generator(self, generator: Arc<dyn IdGenerator>) -> Self

Sets the id generator.

pub fn telemetry(self, options: TelemetryOptions) -> Self

Sets telemetry options.

pub fn hooks(self, hooks: Hooks) -> Self

Adds all hooks of hooks.

pub fn on_start(self, f: impl HookFn<StartEvent>) -> Self

Runs when the call starts.

pub fn on_step_start(self, f: impl HookFn<StepStartEvent>) -> Self

Runs when a step starts.

pub fn on_language_model_call_start( self, f: impl HookFn<ModelCallStartEvent>, ) -> Self

Runs before each model call.

pub fn on_language_model_call_end( self, f: impl HookFn<ModelCallEndEvent>, ) -> Self

Runs after each model call.

pub fn on_tool_execution_start( self, f: impl HookFn<ToolExecutionStartEvent>, ) -> Self

Runs before each tool execution.

pub fn on_tool_execution_end( self, f: impl HookFn<ToolExecutionEndEvent>, ) -> Self

Runs after each tool execution.

pub fn on_step_end(self, f: impl HookFn<StepResult>) -> Self

Runs when a step finishes.

pub fn on_end(self, f: impl HookFn<EndEvent>) -> Self

Runs when the call finishes.

impl<Opt, Out> ToolLoopAgentBuilder<Opt, Out>

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

Sets the agent id (also the default telemetry function_id).

pub fn instructions(self, instructions: impl Into<Instructions>) -> Self

Sets the system instructions (alias of system).

pub fn output<T>(self, output: Output<T>) -> ToolLoopAgentBuilder<Opt, T>

Sets the structured output.

pub fn call_options<O>(self) -> ToolLoopAgentBuilder<O, Out>

Sets the per-call options type, resetting preparation and validation callbacks configured for the previous type.

pub fn prepare_call(self, prepare: impl PrepareCall<Opt> + 'static) -> Self

Sets the function that rewrites settings per call.

pub fn call_options_schema(self, schema: Schema<Opt>) -> Self

where Opt: Serialize + 'static,

Validates and normalizes call options before preparing a generation or stream.

The schema receives serialized options and its validated value replaces them. Validation failures return Error::InvalidArgument before callbacks or model calls start. Without this option, call options need not implement Serialize. Changing the option type with Self::call_options clears this schema.

Examples

use ferrin_core::ToolLoopAgent;
use ferrin_schema::Schema;
use serde_json::{Value, json};

let agent = ToolLoopAgent::builder("provider:model")
    .call_options::<Value>()
    .call_options_schema(Schema::from_json_schema(json!({
        "type": "object", "required": ["tenant"],
        "properties": { "tenant": { "type": "string" } }
    })))
    .build();

pub fn build(self) -> ToolLoopAgent<Opt, Out>

Finishes the agent.

Trait Implementations

impl<Opt, Out> Debug for ToolLoopAgentBuilder<Opt, Out>

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

Formats the value using the given formatter.