Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Builder for Agent.

Implementations

impl AgentBuilder

pub fn model<M>(self, model: M) -> Self

where M: ChatModel + 'static,

Sets the model adapter used by the agent.

Examples found in repository

examples/local_loop.rs (line 90)

fn build_agent(responses: Vec<Result<ModelCompletion, ProviderError>>) -> Agent {
    Agent::builder()
        .model(ScriptedModel::new(responses))
        .tool(add_tool())
        .tool(done_tool())
        .build()
        .expect("agent builds")
}

examples/di_override.rs (line 97)

async fn main() -> Result<(), Box<dyn Error>> {
    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
        .with_schema(json!({
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
        }))?
        .with_handler(|_args, deps| {
            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
            async move { Ok(ToolOutcome::Text(value.to_string())) }
        });

    let done_tool = ToolSpec::new("done", "finish")
        .with_schema(json!({
            "type": "object",
            "properties": {
                "message": {"type": "string"}
            },
            "required": ["message"],
            "additionalProperties": false
        }))?
        .with_handler(|args, _deps| async move {
            let message = args
                .get("message")
                .and_then(|v| v.as_str())
                .unwrap_or("done");
            Ok(ToolOutcome::Done(message.to_string()))
        });

    let model = ScriptedModel::new(vec![
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_1".to_string(),
                name: "read_dep".to_string(),
                arguments: json!({}),
            }],
            usage: None,
        }),
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_2".to_string(),
                name: "done".to_string(),
                arguments: json!({"message": "dependency override applied"}),
            }],
            usage: None,
        }),
    ]);

    let mut agent = Agent::builder()
        .model(model)
        .tool(read_dep_tool)
        .tool(done_tool)
        .dependency(1_u32)
        .dependency_override(9_u32)
        .build()?;

    let response = agent.query("use dependency").await?;
    println!("final: {response}");

    Ok(())
}

pub fn tool(self, tool: ToolSpec) -> Self

Adds one tool to the registry.

Examples found in repository

examples/local_loop.rs (line 91)

fn build_agent(responses: Vec<Result<ModelCompletion, ProviderError>>) -> Agent {
    Agent::builder()
        .model(ScriptedModel::new(responses))
        .tool(add_tool())
        .tool(done_tool())
        .build()
        .expect("agent builds")
}

examples/di_override.rs (line 98)

async fn main() -> Result<(), Box<dyn Error>> {
    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
        .with_schema(json!({
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
        }))?
        .with_handler(|_args, deps| {
            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
            async move { Ok(ToolOutcome::Text(value.to_string())) }
        });

    let done_tool = ToolSpec::new("done", "finish")
        .with_schema(json!({
            "type": "object",
            "properties": {
                "message": {"type": "string"}
            },
            "required": ["message"],
            "additionalProperties": false
        }))?
        .with_handler(|args, _deps| async move {
            let message = args
                .get("message")
                .and_then(|v| v.as_str())
                .unwrap_or("done");
            Ok(ToolOutcome::Done(message.to_string()))
        });

    let model = ScriptedModel::new(vec![
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_1".to_string(),
                name: "read_dep".to_string(),
                arguments: json!({}),
            }],
            usage: None,
        }),
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_2".to_string(),
                name: "done".to_string(),
                arguments: json!({"message": "dependency override applied"}),
            }],
            usage: None,
        }),
    ]);

    let mut agent = Agent::builder()
        .model(model)
        .tool(read_dep_tool)
        .tool(done_tool)
        .dependency(1_u32)
        .dependency_override(9_u32)
        .build()?;

    let response = agent.query("use dependency").await?;
    println!("final: {response}");

    Ok(())
}

pub fn tools(self, tools: Vec<ToolSpec>) -> Self

Adds multiple tools to the registry.

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

Replaces the full agent config.

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

Sets the system prompt.

pub fn require_done_tool(self, require_done_tool: bool) -> Self

Enables or disables explicit done completion mode.

pub fn max_iterations(self, max_iterations: u32) -> Self

Sets max iterations for each query.

pub fn tool_choice(self, tool_choice: AgentToolChoice) -> Self

Sets tool-choice policy for model invocations.

pub fn llm_retry_config( self, max_retries: u32, base_delay_ms: u64, max_delay_ms: u64, ) -> Self

Configures request retry behavior (exponential backoff).

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

Sets a hidden user prompt injected once if model returns no tool calls.

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

where T: Send + Sync + 'static,

Inserts a typed runtime dependency.

Examples found in repository

examples/di_override.rs (line 100)

async fn main() -> Result<(), Box<dyn Error>> {
    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
        .with_schema(json!({
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
        }))?
        .with_handler(|_args, deps| {
            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
            async move { Ok(ToolOutcome::Text(value.to_string())) }
        });

    let done_tool = ToolSpec::new("done", "finish")
        .with_schema(json!({
            "type": "object",
            "properties": {
                "message": {"type": "string"}
            },
            "required": ["message"],
            "additionalProperties": false
        }))?
        .with_handler(|args, _deps| async move {
            let message = args
                .get("message")
                .and_then(|v| v.as_str())
                .unwrap_or("done");
            Ok(ToolOutcome::Done(message.to_string()))
        });

    let model = ScriptedModel::new(vec![
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_1".to_string(),
                name: "read_dep".to_string(),
                arguments: json!({}),
            }],
            usage: None,
        }),
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_2".to_string(),
                name: "done".to_string(),
                arguments: json!({"message": "dependency override applied"}),
            }],
            usage: None,
        }),
    ]);

    let mut agent = Agent::builder()
        .model(model)
        .tool(read_dep_tool)
        .tool(done_tool)
        .dependency(1_u32)
        .dependency_override(9_u32)
        .build()?;

    let response = agent.query("use dependency").await?;
    println!("final: {response}");

    Ok(())
}

pub fn dependency_named<T>(self, key: impl Into<String>, value: T) -> Self

where T: Send + Sync + 'static,

Inserts a named runtime dependency.

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

where T: Send + Sync + 'static,

Inserts a typed dependency override.

Examples found in repository

examples/di_override.rs (line 101)

async fn main() -> Result<(), Box<dyn Error>> {
    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
        .with_schema(json!({
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
        }))?
        .with_handler(|_args, deps| {
            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
            async move { Ok(ToolOutcome::Text(value.to_string())) }
        });

    let done_tool = ToolSpec::new("done", "finish")
        .with_schema(json!({
            "type": "object",
            "properties": {
                "message": {"type": "string"}
            },
            "required": ["message"],
            "additionalProperties": false
        }))?
        .with_handler(|args, _deps| async move {
            let message = args
                .get("message")
                .and_then(|v| v.as_str())
                .unwrap_or("done");
            Ok(ToolOutcome::Done(message.to_string()))
        });

    let model = ScriptedModel::new(vec![
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_1".to_string(),
                name: "read_dep".to_string(),
                arguments: json!({}),
            }],
            usage: None,
        }),
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_2".to_string(),
                name: "done".to_string(),
                arguments: json!({"message": "dependency override applied"}),
            }],
            usage: None,
        }),
    ]);

    let mut agent = Agent::builder()
        .model(model)
        .tool(read_dep_tool)
        .tool(done_tool)
        .dependency(1_u32)
        .dependency_override(9_u32)
        .build()?;

    let response = agent.query("use dependency").await?;
    println!("final: {response}");

    Ok(())
}

pub fn dependency_override_named<T>( self, key: impl Into<String>, value: T, ) -> Self

where T: Send + Sync + 'static,

Inserts a named dependency override.

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

Builds an Agent and validates required config.

Examples found in repository

examples/local_loop.rs (line 93)

fn build_agent(responses: Vec<Result<ModelCompletion, ProviderError>>) -> Agent {
    Agent::builder()
        .model(ScriptedModel::new(responses))
        .tool(add_tool())
        .tool(done_tool())
        .build()
        .expect("agent builds")
}

examples/di_override.rs (line 102)

async fn main() -> Result<(), Box<dyn Error>> {
    let read_dep_tool = ToolSpec::new("read_dep", "read injected value")
        .with_schema(json!({
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
        }))?
        .with_handler(|_args, deps| {
            let value = deps.get::<u32>().map(|v| *v).unwrap_or_default();
            async move { Ok(ToolOutcome::Text(value.to_string())) }
        });

    let done_tool = ToolSpec::new("done", "finish")
        .with_schema(json!({
            "type": "object",
            "properties": {
                "message": {"type": "string"}
            },
            "required": ["message"],
            "additionalProperties": false
        }))?
        .with_handler(|args, _deps| async move {
            let message = args
                .get("message")
                .and_then(|v| v.as_str())
                .unwrap_or("done");
            Ok(ToolOutcome::Done(message.to_string()))
        });

    let model = ScriptedModel::new(vec![
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_1".to_string(),
                name: "read_dep".to_string(),
                arguments: json!({}),
            }],
            usage: None,
        }),
        Ok(ModelCompletion {
            text: None,
            thinking: None,
            tool_calls: vec![ModelToolCall {
                id: "call_2".to_string(),
                name: "done".to_string(),
                arguments: json!({"message": "dependency override applied"}),
            }],
            usage: None,
        }),
    ]);

    let mut agent = Agent::builder()
        .model(model)
        .tool(read_dep_tool)
        .tool(done_tool)
        .dependency(1_u32)
        .dependency_override(9_u32)
        .build()?;

    let response = agent.query("use dependency").await?;
    println!("final: {response}");

    Ok(())
}

Trait Implementations

impl Default for AgentBuilder

fn default() -> Self

Returns the “default value” for a type.