Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Fluent assembly of one canonical Agent.

Registration failures are retained and returned by Self::build so Tool and child Agent calls remain chainable without silently replacing an existing name.

Implementations

impl AgentBuilder

pub fn new( name: impl Into<String>, model: Arc<dyn Model>, model_ref: ModelRef, ) -> Self

Creates a builder around the same execution path as Agent::new.

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

Appends a system instruction.

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

Adds one static document as untrusted user-level context.

The document is never promoted to a system instruction. Use Self::system for trusted application policy.

pub fn context_document(self, document: Document) -> Self

Adds one validated static context document.

pub fn artifacts( self, scope: ArtifactScope, store: Arc<dyn ArtifactStore>, ) -> Self

Configures reference-only artifact persistence for Tools and resolves those references only at the final model transport boundary.

pub fn dynamic_context<R>(self, limit: usize, retriever: R) -> Self

where R: Retriever + 'static,

Adds an owned dynamic context source.

pub fn shared_dynamic_context( self, limit: usize, retriever: Arc<dyn Retriever>, ) -> Self

Adds a shared, type-erased dynamic context source.

pub fn tool<T>(self, tool: T) -> Self

where T: Tool + 'static,

Registers an owned Tool.

pub fn shared_tool(self, tool: Arc<dyn Tool>) -> Self

Registers a shared, type-erased Tool.

pub fn child( self, descriptor: AgentDescriptor, child: Arc<Agent>, capabilities: CapabilitySet, ) -> Self

Registers a child Agent route with explicit delegated capabilities.

pub fn gateway_layer(self, middleware: Arc<dyn GatewayMiddleware>) -> Self

Appends Gateway around-middleware.

pub fn max_delegation_depth(self, max_depth: u32) -> Self

Sets the maximum nested Agent delegation depth.

pub const fn max_turns(self, max_turns: u32) -> Self

Sets the local model-turn limit.

pub const fn min_successful_tool_calls(self, minimum: u32) -> Self

Requires this many successful local Tool calls before terminal output.

The runtime requests at least one Tool while the requirement remains unsatisfied and returns an explicit error if the model violates that contract. A value of zero disables the requirement.

pub const fn tool_error_policy(self, policy: ToolErrorPolicy) -> Self

Sets Tool failure behavior.

pub const fn feature_policy(self, policy: FeaturePolicy) -> Self

Sets provider feature-degradation behavior.

pub fn output_format(self, output_format: OutputFormat) -> Self

Sets the desired terminal model-output format.

pub fn structured_output<T>(self, name: impl Into<String>) -> Self

where T: JsonSchema,

Requests strict structured output described by the Rust type T.

pub fn provider_tool(self, tool: ProviderToolSpec) -> Self

Adds a provider-hosted tool such as Ark web search.

pub fn generation(self, generation: GenerationOptions) -> Self

Replaces common model generation controls for every Agent turn.

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

Sets the sampling temperature for every Agent turn.

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

Sets nucleus sampling for every Agent turn.

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

Sets the maximum number of output tokens for every Agent turn.

pub const fn response_mode(self, response_mode: ResponseMode) -> Self

Selects streaming or complete response delivery for every Agent turn.

pub fn provider_options( self, provider: impl Into<String>, options: Value, ) -> Self

Adds namespaced provider options to every Agent turn.

pub const fn config(self, config: AgentConfig) -> Self

Replaces all local Agent configuration.

pub fn effect_executor(self, effects: EffectExecutor) -> Self

Shares a write-ahead effect coordinator with this Agent.

pub const fn effect_recovery_policy(self, policy: EffectRecoveryPolicy) -> Self

Sets recovery behavior for ambiguous callable effects.

pub fn build(self) -> Result<Agent, AgentBuildError>

Validates registrations and returns the canonical Agent.

Errors

Returns AgentBuildError for blank identity, invalid turn bounds, duplicate registrations, or Tool/Agent name collisions.

pub fn prompt( self, input: impl Into<String> + Send + 'static, ) -> AgentFuture<'static, Result<AgentOutcome, AgentPromptError>>

Builds the Agent and runs one ergonomic prompt.

This removes the explicit build step for one-shot usage while retaining the complete canonical outcome. Use Self::build when the Agent will be reused or executed with an explicit runtime context.

pub fn prompt_text( self, input: impl Into<String> + Send + 'static, ) -> AgentFuture<'static, Result<String, AgentPromptError>>

Builds the Agent, runs one ergonomic prompt, and returns only model-visible text.

This is the shortest path from provider configuration to a text answer. Use Self::prompt when transcript, usage, warnings, and provider events must be preserved.

pub fn build_structured<T>( self, name: impl Into<String>, ) -> Result<StructuredAgent<T>, AgentBuildError>

where T: JsonSchema,

Builds an Agent whose schema and local decoder are bound to T.

This is the preferred terminal builder operation for structured output because a different decode type cannot be selected later by mistake.

Errors

Returns AgentBuildError under the same validation rules as Self::build.

Trait Implementations

impl Debug for AgentBuilder

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

Formats the value using the given formatter.