Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Copy-on-write immutable builder for agent construction.

Every setter returns a new AgentBuilder, leaving the original unchanged. This makes builders safe to share as templates.

Basic Usage

use gemini_adk_fluent_rs::builder::AgentBuilder;
use gemini_genai_rs::prelude::ModelId;

let agent = AgentBuilder::new("analyst")
    .model(ModelId::LIVE_2_5_FLASH_NATIVE_AUDIO)
    .instruction("Analyze the given topic")
    .temperature(0.3);

assert_eq!(agent.name(), "analyst");
assert_eq!(agent.get_temperature(), Some(0.3));

Copy-on-Write Pattern

Cloning a builder and modifying the clone leaves the original unchanged. This is useful for creating template builders with shared defaults.

use gemini_adk_fluent_rs::builder::AgentBuilder;

let base = AgentBuilder::new("researcher")
    .instruction("You are a research assistant.")
    .temperature(0.5);

let creative = base.clone().temperature(0.9);
let precise  = base.clone().temperature(0.1);

// Original unchanged
assert_eq!(base.get_temperature(), Some(0.5));
assert_eq!(creative.get_temperature(), Some(0.9));
assert_eq!(precise.get_temperature(), Some(0.1));

Sampling Parameters

use gemini_adk_fluent_rs::builder::AgentBuilder;

let agent = AgentBuilder::new("sampler")
    .temperature(0.7)
    .top_p(0.95)
    .top_k(40)
    .max_output_tokens(4096);

assert_eq!(agent.get_top_p(), Some(0.95));
assert_eq!(agent.get_top_k(), Some(40));
assert_eq!(agent.get_max_output_tokens(), Some(4096));

Built-in Tools

use gemini_adk_fluent_rs::builder::AgentBuilder;

let agent = AgentBuilder::new("searcher")
    .google_search()
    .code_execution()
    .url_context();

assert_eq!(agent.tool_count(), 3);

Thinking Budget

use gemini_adk_fluent_rs::builder::AgentBuilder;

let agent = AgentBuilder::new("thinker")
    .thinking(2048);

assert_eq!(agent.get_thinking_budget(), Some(2048));

Implementations

impl AgentBuilder

pub fn new(name: impl Into<String>) -> Self

Create a new builder with the given agent name.

pub fn name(&self) -> &str

The agent name.

pub fn get_model(&self) -> Option<&ModelId>

Configured model, if any.

pub fn get_instruction(&self) -> Option<&str>

Configured instruction, if any.

pub fn get_voice(&self) -> Option<&Voice>

Configured voice, if any.

pub fn get_temperature(&self) -> Option<f32>

Configured temperature, if any.

pub fn is_text_only(&self) -> bool

Whether text-only mode is set.

pub fn get_thinking_budget(&self) -> Option<u32>

Configured thinking budget, if any.

pub fn get_writes(&self) -> &[String]

State keys this agent writes.

pub fn get_reads(&self) -> &[String]

State keys this agent reads.

pub fn get_sub_agents(&self) -> &[AgentBuilder]

Sub-agents registered.

pub fn is_isolated(&self) -> bool

Whether agent runs in isolated state.

pub fn is_stay(&self) -> bool

Whether agent stays after transfer.

pub fn tool_count(&self) -> usize

Number of tool entries.

pub fn get_top_p(&self) -> Option<f32>

Configured top_p, if any.

pub fn get_top_k(&self) -> Option<u32>

Configured top_k, if any.

pub fn get_max_output_tokens(&self) -> Option<u32>

Configured max_output_tokens, if any.

pub fn get_stop_sequences(&self) -> &[String]

Configured stop sequences.

pub fn get_description(&self) -> Option<&str>

Configured description, if any.

pub fn get_output_schema(&self) -> Option<&Value>

Configured output schema, if any.

pub fn get_output_key(&self) -> Option<&str>

Get the configured output key.

pub fn get_transfer_to(&self) -> Option<&str>

Configured transfer target agent, if any.

pub fn middleware_layer_count(&self) -> usize

Number of registered middleware layers.

pub fn model(self, model: ModelId) -> Self

Set the Gemini model.

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

Set the system instruction.

pub fn instruction_provider( self, provider: impl InstructionProvider + 'static, ) -> Self

Set a dynamic instruction source — any Fn(&State) -> String closure or a TemplateInstruction (feature templates), resolved against live session state at the start of every run. Wins over instruction when both are set.

pub fn llm_provider( self, provider: impl Fn(&State) -> Arc<dyn BaseLlm> + Send + Sync + 'static, ) -> Self

Set a dynamic model source, resolved against session state at the start of every run — risk-based escalation to a stronger model, cost routing to a cheaper one, per-tenant model selection — without rebuilding the agent. Wins over the constructor’s model when set.

pub fn voice(self, voice: Voice) -> Self

Set the output voice.

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

Set the temperature.

pub fn text_only(self) -> Self

Set text-only mode (no audio output).

pub fn response_modalities(self, modalities: Vec<Modality>) -> Self

Set response modalities explicitly.

pub fn thinking(self, budget: u32) -> Self

Enable thinking with a token budget.

pub fn url_context(self) -> Self

Add a built-in URL context tool.

pub fn google_search(self) -> Self

Add a built-in Google Search tool.

pub fn code_execution(self) -> Self

Add a built-in code execution tool.

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

Declare a state key this agent writes.

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

Declare a state key this agent reads.

pub fn artifacts(self, artifacts: impl Into<ArtifactComposite>) -> Self

Declare the artifacts this agent consumes and produces, from the A namespace: A::text_input(..) + A::json_output(..).

Each input is a read and each output a write of the state key artifact:{name}, so check_contracts reports an artifact input no agent produces, or one produced twice, exactly as it does for state keys.

pub fn sub_agent(self, agent: AgentBuilder) -> Self

Add a sub-agent for transfer.

pub fn isolate(self) -> Self

Run this agent in isolated state (no shared state).

pub fn stay(self) -> Self

Keep this agent active after transfer (don’t tear down).

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

Set top_p (nucleus sampling).

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

Set top_k (top-k sampling).

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

Set maximum output tokens.

pub fn stop_sequences(self, seqs: Vec<String>) -> Self

Set stop sequences.

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

Set a description for this agent (used in tool/agent metadata).

pub fn output_schema(self, schema: Value) -> Self

Set a JSON schema for structured output.

pub fn output<T: JsonSchema>(self) -> Self

Constrain every reply to JSON shaped like T, using T’s schema.

Read the reply back with RunResult::parse, or ask for a T directly with TextAgent::ask_as, which also repairs a reply that does not parse.

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

Set the output key — agent’s final text response is auto-saved to this state key.

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

Set a default transfer target agent.

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

👎Deprecated since 2.1.0:

use instruction

Alias for instruction — matches upstream Python Agent.instruct().

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

👎Deprecated since 2.1.0:

use description

Alias for description — matches upstream Python Agent.describe().

pub fn tool(self, f: impl ToolFunction + 'static) -> Self

Register one tool: anything that implements ToolFunction — a SimpleTool/TypedTool, the value a #[tool] function returns, or an Arc<dyn ToolFunction> you already hold.

#[tool("Get the weather for a city")]
async fn get_weather(city: String) -> Result<serde_json::Value, ToolError> {
    Ok(serde_json::json!({"city": city, "temp": 22}))
}
let agent = AgentBuilder::new("assistant").tool(get_weather());

pub fn tools(self, tools: impl Into<ToolComposite>) -> Self

Register tools: a +-combined ToolComposite from the T namespace, or a single ToolFunction.

T::mcp(..) needs an async connection that this synchronous builder cannot perform; it is rejected by build with a ConfigError — attach MCP toolsets to a Live session instead.

let tools = T::simple("greet", "Greet", |_| async { Ok(json!({})) })
    + T::google_search();
AgentBuilder::new("assistant").tools(tools);

pub fn guard(self, guard: impl Into<GuardComposite>) -> Self

Attach output guards. Each model response is validated against every guard; if any rejects the output the agent run fails with an AgentError listing the violations.

Accepts a single guard or a +-combined GuardComposite (every guard must pass):

AgentBuilder::new("writer").guard(G::pii() + G::length(1, 2000));

The guards are installed as an after_model middleware layer, so they accumulate with .middleware(...) and honor copy-on-write.

pub fn context(self, policy: impl Into<ContextComposite>) -> Self

Attach a context policy that rewrites conversation history before each model call (e.g. windowing, role filtering, tool-result exclusion).

Accepts a single policy or a >>-chained ContextComposite (applied in order):

AgentBuilder::new("chat").context(C::window(10) >> C::user_only());

The policy is installed as a transform_request middleware layer.

pub fn no_peers(self) -> Self

👎Deprecated since 2.1.0:

use isolate, which this has always called

Disallow transfer to peer agents.

pub fn middleware(self, middleware: impl Into<MiddlewareComposite>) -> Self

Attach middleware — a >>-stacked MiddlewareComposite from the M namespace or a single Arc<dyn Middleware>. All layers are installed on the compiled LlmTextAgent in the order given.

Multiple calls to .middleware() accumulate: the new layers are appended after any previously registered layers, preserving the copy-on-write contract.

let agent = AgentBuilder::new("analyst")
    .instruction("Analyze topics")
    .middleware(M::log() >> M::latency());

pub fn confirmation_provider( self, provider: Arc<dyn ConfirmationProvider>, ) -> Self

Gate T::confirm(..) tools behind a confirmation provider, as Live::confirmation_provider does for a session.

A declined call returns ToolError::Declined with the reason to the model instead of running the tool. An agent with a confirmation-gated tool and no provider does not build.

pub fn build( self, llm: impl BaseLlm + 'static, ) -> Result<Arc<dyn TextAgent>, ConfigError>

Compile this builder into an executable TextAgent.

llm is any BaseLlm. Every setting reaches the requests the agent sends: model, instruction, sampling (temperature, top_p, top_k, max_output_tokens, stop_sequences), thinking, output_schema, built-in tools and function tools, middleware, and output_key. writes, reads and description are declarations for check_contracts and tool metadata.

Fails with a ConfigError listing every setting a text agent cannot honour, rather than dropping it: voice, audio modalities, a Live model, agent-transfer settings (sub_agent, transfer_to, stay, isolate), an MCP toolset (T::mcp), which needs the async connect only a Live session performs, and a T::confirm tool with no confirmation_provider.

let llm = Arc::new(GeminiLlm::new(GeminiLlmParams::default()));
let agent = AgentBuilder::new("analyst")
    .instruction("Analyze the topic")
    .temperature(0.3)
    .build(llm)?;

let state = State::new();
let result = agent.run(&state).await?;

Trait Implementations

impl BitOr for AgentBuilder

AgentBuilder | AgentBuilder → FanOut

type Output = Composable

The resulting type after applying the | operator.

fn bitor(self, rhs: AgentBuilder) -> Self::Output

Performs the | operation.

impl BitOr<AgentBuilder> for Composable

Composable | AgentBuilder → FanOut (flattening)

type Output = Composable

The resulting type after applying the | operator.

fn bitor(self, rhs: AgentBuilder) -> Self::Output

Performs the | operation.

impl Clone for AgentBuilder

fn clone(&self) -> AgentBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentBuilder

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

Formats the value using the given formatter.

impl Div for AgentBuilder

AgentBuilder / AgentBuilder → Fallback

type Output = Composable

The resulting type after applying the / operator.

fn div(self, rhs: AgentBuilder) -> Self::Output

Performs the / operation.

impl Div<AgentBuilder> for Composable

Composable / AgentBuilder → Fallback (flattening)

type Output = Composable

The resulting type after applying the / operator.

fn div(self, rhs: AgentBuilder) -> Self::Output

Performs the / operation.

impl From<AgentBuilder> for Composable

fn from(b: AgentBuilder) -> Self

Converts to this type from the input type.

impl Mul<LoopPredicate> for AgentBuilder

AgentBuilder * until(pred) → conditional Loop

type Output = Composable

The resulting type after applying the * operator.

fn mul(self, rhs: LoopPredicate) -> Self::Output

Performs the * operation.

impl Mul<u32> for AgentBuilder

AgentBuilder * 3 → Loop(max=3)

type Output = Composable

The resulting type after applying the * operator.

fn mul(self, rhs: u32) -> Self::Output

Performs the * operation.

impl Shr for AgentBuilder

AgentBuilder >> AgentBuilder → Pipeline

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: AgentBuilder) -> Self::Output

Performs the >> operation.

impl Shr<AgentBuilder> for StateTransform

A state transform as a pipeline step: a >> S::pick(..) >> b.

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: AgentBuilder) -> Self::Output

Performs the >> operation.

impl Shr<AgentBuilder> for StateComposite

A state transform as a pipeline step: a >> S::pick(..) >> b.

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: AgentBuilder) -> Self::Output

Performs the >> operation.

impl Shr<AgentBuilder> for Composable

Composable >> AgentBuilder → Pipeline (flattening)

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: AgentBuilder) -> Self::Output

Performs the >> operation.

impl Shr<Composable> for AgentBuilder

AgentBuilder >> Composable → Pipeline (flattening)

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: Composable) -> Self::Output

Performs the >> operation.

impl Shr<StateComposite> for AgentBuilder

A state transform as a pipeline step: a >> S::pick(..) >> b.

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: StateComposite) -> Self::Output

Performs the >> operation.

impl Shr<StateTransform> for AgentBuilder

A state transform as a pipeline step: a >> S::pick(..) >> b.

type Output = Composable

The resulting type after applying the >> operator.

fn shr(self, rhs: StateTransform) -> Self::Output

Performs the >> operation.