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 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.