Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Fluent, by-value agent composition.

Implementations

impl AgentBuilder

pub fn new() -> Self

A builder with defaults for everything but the model, which is required.

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

Name the agent, for logs and diagnostics. Defaults to "agent".

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

The agent’s own instructions. Capability contributions are appended to this when a turn assembles its prompt.

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

The model, by value — see ModelSpec. Required.

pub fn capability(self, capability: impl Capability + 'static) -> Self

Attach a capability by object — no registry, no string reference.

pub fn capability_arc(self, capability: Arc<dyn Capability>) -> Self

Attach a capability you already hold as an Arc — the way to share one between agents, or keep a handle on its state.

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

Attach a single tool directly (wrapped in an implicit capability).

pub fn driver(self, driver: impl ChatDriver + 'static) -> Self

Register an extra or replacement LLM driver.

pub fn listener(self, listener: impl EventListener + 'static) -> Self

Observe every event this agent’s sessions emit. Listeners cannot change a turn — see AgentBuilder::middleware for that.

pub fn listener_arc(self, listener: Arc<dyn EventListener>) -> Self

Attach a listener you already hold as an Arc — the way to keep a handle to inspect its state (e.g. a test collector) after the agent is built.

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

Ceiling on reason/act iterations within one turn (default: 16).

pub fn middleware(self, middleware: impl TurnMiddleware + 'static) -> Self

Intercept points inside the turn loop, in attachment order — deny a tool call, rewrite it before it runs, or transform its output. What approval gating, guardrails, and redaction are built on; see agentyk_core::middleware::TurnMiddleware.

pub fn middleware_arc(self, middleware: Arc<dyn TurnMiddleware>) -> Self

Attach middleware you already hold as an Arc — the way to keep a handle on it (e.g. an approver whose state a test inspects).

pub fn hook(self, hook: impl Hook + 'static) -> Self

Attach a user hook by value.

Hooks cover the same six lifecycle events as Everruns: session start/end, prompt submission, pre/post tool use, and turn end. They compose in attachment order within each event.

pub fn hook_arc(self, hook: Arc<dyn Hook>) -> Self

Attach a user hook already held behind an Arc.

pub fn budget_checker(self, checker: impl BudgetChecker + 'static) -> Self

Stop a turn deliberately rather than letting it run to MaxIterations — checked once per action, like cancellation. See agentyk_core::budget::BudgetChecker. No default policy: unset means a turn never seals for budget reasons.

pub fn model_catalog(self, catalog: impl ModelCatalog + 'static) -> Self

Teach the builder what models support, so a composition the provider would reject fails here instead — see agentyk_core::profile::ModelCatalog.

Nothing is baked in: agentyk ships no model list, because a list in a library is stale by its next release and a wrong entry is worse than a missing one. A model the catalog does not know is passed through untouched, so attaching one can only reject combinations you described.

A catalog states what a model takes, and build() refuses a model spec that contradicts it — Error::InvalidAgent, naming the supported values, before a turn ever runs:

use agentyk_core::{DriverId, InMemoryModelCatalog, ModelCatalog, ModelProfile, ModelSpec};

let catalog = InMemoryModelCatalog::new().with(
    DriverId::openai(),
    "gpt-5.5",
    ModelProfile::new().reasoning_efforts(["low", "high"]),
);

let profile = catalog.profile(&DriverId::openai(), "gpt-5.5").unwrap();
let error = profile
    .validate(&ModelSpec::openai("gpt-5.5").reasoning_effort("medium"))
    .unwrap_err();
assert!(error.contains("low, high"));

pub fn model_catalog_arc(self, catalog: Arc<dyn ModelCatalog>) -> Self

Attach a catalog you already hold as an Arc — the way to share one across agents.

pub fn context_assembler( self, assembler: impl ContextAssembler + 'static, ) -> Self

Replace how replayed history is turned into what’s sent to the model each turn (default: send it unchanged) — trimming, compaction, and memory injection are implementations of this seam, not changes to the turn machine. See agentyk_core::context::ContextAssembler.

pub fn context_token_limit(self, token_limit: usize) -> Self

Tell context assembly the maximum input-token budget for each model call. The assembler owns estimation and reduction; the engine does not silently trim messages.

Left unset, an attached AgentBuilder::model_catalog can supply it: a profile stating both a context window and an output ceiling implies the input budget (window minus output). Only both, because with just the window there is no defensible number — reserving room for the response would mean inventing a figure the host never stated.

pub fn extension<T: Send + Sync + 'static>(self, value: T) -> Self

Make a service available to every tool call via agentyk_core::tool::ToolContext::extensions — a credential store, a workspace handle, anything a tool needs but core shouldn’t know the shape of. Replaces any previous value of the same type.

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

Finish composing.

Fails if no model was set, or if no driver is registered for the one that was — both are wiring mistakes worth catching before a turn runs rather than during one.

Trait Implementations

impl Default for AgentBuilder

fn default() -> Self

Returns the “default value” for a type.