Struct AgentBuilder 

pub struct AgentBuilder<Deps = (), Output = String> { /* private fields */ }

Builder for creating agents.

Implementations

impl<Deps, Output> AgentBuilder<Deps, Output>

where Deps: Send + Sync + 'static, Output: Send + Sync + 'static,

pub fn new<M>(model: M) -> AgentBuilder<Deps, Output>

where M: Model + 'static,

Create a new agent builder with the given model.

This is the most flexible constructor, accepting any type that implements the Model trait. Use this when you need full control over model configuration.

Example

use serdes_ai_agent::AgentBuilder;
use serdes_ai_models::openai::OpenAIChatModel;

let model = OpenAIChatModel::new("gpt-4o", "sk-your-api-key");
let agent = AgentBuilder::new(model)
    .system_prompt("You are helpful.")
    .build();

pub fn from_arc(model: Arc<dyn Model>) -> AgentBuilder<Deps, Output>

Create a new agent builder from an Arc<dyn Model>.

This is useful when you already have a model wrapped in an Arc, such as from infer_model().

Example

use serdes_ai_agent::AgentBuilder;
use serdes_ai_models::infer_model;

let model = infer_model("openai:gpt-4o")?;
let agent = AgentBuilder::from_arc(model)
    .system_prompt("You are helpful.")
    .build();

pub fn from_model( spec: impl Into<String>, ) -> Result<AgentBuilder<Deps, Output>, ModelError>

Create a new agent builder from a model spec string.

This is the simplest way to create an agent when you just need to specify the model. API keys are read from environment variables.

Model Spec Format

The spec should be in provider:model format:

• "openai:gpt-4o" - OpenAI GPT-4o
• "anthropic:claude-3-5-sonnet-20241022" - Anthropic Claude
• "groq:llama-3.1-70b-versatile" - Groq
• "ollama:llama3.1" - Local Ollama

If no provider prefix is given, OpenAI is assumed.

Example

use serdes_ai_agent::AgentBuilder;

let agent = AgentBuilder::from_model("openai:gpt-4o")?
    .system_prompt("You are helpful.")
    .build();

Errors

Returns an error if the model cannot be created (e.g., missing API key, unsupported provider, or disabled feature).

pub fn from_config( config: ModelConfig, ) -> Result<AgentBuilder<Deps, Output>, ModelError>

Create a new agent builder from a model configuration.

This allows specifying custom API keys, base URLs, and other options while still using the convenient string-based model spec.

Example

use serdes_ai_agent::{AgentBuilder, ModelConfig};

let config = ModelConfig::new("openai:gpt-4o")
    .with_api_key("sk-your-api-key")
    .with_base_url("https://your-proxy.com/v1");

let agent = AgentBuilder::from_config(config)?
    .system_prompt("You are helpful.")
    .build();

Errors

Returns an error if the model cannot be created.

pub fn name(self, name: impl Into<String>) -> AgentBuilder<Deps, Output>

Set agent name.

pub fn model_settings( self, settings: ModelSettings, ) -> AgentBuilder<Deps, Output>

Set model settings.

pub fn temperature(self, temp: f64) -> AgentBuilder<Deps, Output>

Set temperature.

pub fn max_tokens(self, tokens: u64) -> AgentBuilder<Deps, Output>

Set max tokens.

pub fn top_p(self, p: f64) -> AgentBuilder<Deps, Output>

Set top-p.

pub fn instructions( self, instructions: impl Into<String>, ) -> AgentBuilder<Deps, Output>

Add static instructions.

pub fn instructions_fn<F, Fut>(self, f: F) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<String>> + Send + 'static,

Add dynamic instructions function (async).

pub fn instructions_fn_sync<F>(self, f: F) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>) -> Option<String> + Send + Sync + 'static,

Add dynamic instructions function (sync).

pub fn system_prompt( self, prompt: impl Into<String>, ) -> AgentBuilder<Deps, Output>

Add system prompt.

pub fn system_prompt_fn<F, Fut>(self, f: F) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<String>> + Send + 'static,

Add dynamic system prompt function (async).

pub fn system_prompt_fn_sync<F>(self, f: F) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>) -> Option<String> + Send + Sync + 'static,

Add dynamic system prompt function (sync).

pub fn tool_with_executor<E>( self, definition: ToolDefinition, executor: E, ) -> AgentBuilder<Deps, Output>

where E: ToolExecutor<Deps> + 'static,

Add a tool with a custom executor.

pub fn tool_fn<F, Args>( self, name: impl Into<String>, description: impl Into<String>, f: F, ) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>, Args) -> Result<ToolReturn, ToolError> + Send + Sync + 'static, Args: DeserializeOwned + Send + 'static,

Add a tool from a sync function.

pub fn tool_fn_async<F, Fut, Args>( self, name: impl Into<String>, description: impl Into<String>, f: F, ) -> AgentBuilder<Deps, Output>

where F: Fn(&RunContext<Deps>, Args) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<ToolReturn, ToolError>> + Send + Sync + 'static, Args: DeserializeOwned + Send + Sync + 'static,

Add a tool from an async function.

pub fn output_schema<S>(self, schema: S) -> AgentBuilder<Deps, Output>

where S: OutputSchema<Output> + 'static,

Set custom output schema.

pub fn output_validator<V>(self, validator: V) -> AgentBuilder<Deps, Output>

where V: OutputValidator<Output, Deps> + 'static,

Add output validator.

pub fn output_validator_fn<F>(self, f: F) -> AgentBuilder<Deps, Output>

where F: Fn(Output, &RunContext<Deps>) -> Result<Output, OutputValidationError> + Send + Sync + 'static,

Add output validator from sync function.

pub fn end_strategy(self, strategy: EndStrategy) -> AgentBuilder<Deps, Output>

Set end strategy.

pub fn max_output_retries(self, retries: u32) -> AgentBuilder<Deps, Output>

Set max output retries.

pub fn max_tool_retries(self, retries: u32) -> AgentBuilder<Deps, Output>

Set max tool retries.

pub fn usage_limits(self, limits: UsageLimits) -> AgentBuilder<Deps, Output>

Set usage limits.

pub fn history_processor<P>(self, processor: P) -> AgentBuilder<Deps, Output>

where P: HistoryProcessor<Deps> + 'static,

Add history processor.

pub fn instrument( self, settings: InstrumentationSettings, ) -> AgentBuilder<Deps, Output>

Enable instrumentation.

pub fn parallel_tool_calls(self, enabled: bool) -> AgentBuilder<Deps, Output>

Enable or disable parallel tool execution.

When enabled (default), multiple tool calls from the model will be executed concurrently using futures::future::join_all.

When disabled, tools are executed sequentially in order.

pub fn max_concurrent_tools(self, max: usize) -> AgentBuilder<Deps, Output>

Set the maximum number of concurrent tool calls.

When set, limits the number of tools that can execute simultaneously using a semaphore. This is useful for rate-limiting or resource control.

Only applies when parallel_tool_calls is enabled.

pub fn build(self) -> Agent<Deps, Output>

where Output: DeserializeOwned,

Build the agent.

impl<Deps> AgentBuilder<Deps>

where Deps: Send + Sync + 'static,

pub fn output_type<T>(self) -> AgentBuilder<Deps, T>

where T: DeserializeOwned + Send + Sync + 'static,

Change output type to a JSON-parsed type.

pub fn output_type_with_schema<T>(self, schema: Value) -> AgentBuilder<Deps, T>

where T: DeserializeOwned + Send + Sync + 'static,

Change output type with JSON schema.

pub fn output_tool<T>( self, tool_name: impl Into<String>, schema: Value, ) -> AgentBuilder<Deps, T>

where T: DeserializeOwned + Send + Sync + 'static,

Use tool-based output.