Struct AgentBuilder 

pub struct AgentBuilder<M>
where
    M: ModelAdapter,
{ /* private fields */ }

Builder for constructing an Agent.

Obtained via Agent::builder. The only required field is model; all others have sensible defaults (no tools, allow-all permissions, no compaction, no observers).

Implementations

impl<M> AgentBuilder<M>

where M: ModelAdapter,

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

Set the model adapter (required).

pub fn add_tool_source<S: ToolSource + 'static>(self, source: S) -> Self

Adds a tool source to the agent. Call multiple times to compose federated sources — for example a frozen native [ToolRegistry] alongside an MCP manager’s agentkit_tools_core::CatalogReader and a skill-watcher reader. Sources are walked in registration order; the default agentkit_tools_core::CollisionPolicy is FirstWins.

Accepts any sized ToolSource; the agent owns it for the session. To share a dynamic source between the agent and the subsystem mutating it, mint a agentkit_tools_core::CatalogReader from a agentkit_tools_core::dynamic_catalog pair — the reader is sized and owned, hosts never see the underlying Arc.

pub fn tool_executor(self, executor: impl ToolExecutor + 'static) -> Self

Set a custom ToolExecutor. When provided, the agent uses it instead of building a BasicToolExecutor from the configured sources. Most hosts should use add_tool_source instead; this is for advanced cases (custom routing, instrumentation, test fakes).

pub fn task_manager(self, manager: impl TaskManager + 'static) -> Self

Set the task manager that schedules tool-call execution.

Defaults to SimpleTaskManager, which preserves the existing sequential request/response behavior.

pub fn permissions(self, permissions: impl PermissionChecker + 'static) -> Self

Set the permission checker that gates tool execution.

Defaults to allowing all tool calls without prompting.

pub fn resources(self, resources: impl ToolResources + 'static) -> Self

Set shared resources available to tool implementations.

pub fn cancellation(self, handle: CancellationHandle) -> Self

Attach a CancellationHandle for cooperative cancellation of turns.

pub fn mutator<L: LoopMutator + 'static>(self, mutator: L) -> Self

Register a LoopMutator that runs at every MutationPoint.

Multiple mutators may be registered; they run in registration order and the dirty flag propagates across the pipeline. After every pass in which any mutator dirtied the transcript, the loop validates protocol invariants (tool_use/tool_result pairing); a violation is a hard LoopError::Mutator failure.

pub fn observer<O: LoopObserver + 'static>(self, observer: O) -> Self

Register a LoopObserver that receives AgentEvents.

Multiple observers may be registered; they are called in order.

pub fn transcript_observer<O: TranscriptObserver + 'static>( self, observer: O, ) -> Self

Register a TranscriptObserver that receives an Item every time one is appended to the transcript.

Multiple observers may be registered; they are called in order. Use this when you need a loss-free view of the transcript (e.g. for persistence or replication) — LoopObserver alone is insufficient because it doesn’t expose item boundaries for model output and historically did not surface tool results at all.

pub fn transcript(self, transcript: Vec<Item>) -> Self

Preload the driver’s transcript with prior conversation state (defaults to empty).

Items pass straight into the driver’s transcript without firing TranscriptObserver::on_item_appended — the host is expected to already know about (and have persisted) anything it preloads. Use this for resumed sessions or to seed a system prompt.

pub fn input(self, input: Vec<Item>) -> Self

Preload the driver’s pending-input queue with the next user turn (defaults to empty).

When non-empty, the first LoopDriver::next dispatches the model directly instead of yielding LoopInterrupt::AwaitingInput. Use this for one-shot calls and scripts where the first user turn is known up front. Items move to the transcript on turn dispatch the same way submitted input does, firing transcript observers.

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

Consume the builder and produce an Agent.

Errors

Returns LoopError::InvalidState if no model adapter was provided.

Trait Implementations

impl<M> Default for AgentBuilder<M>

where M: ModelAdapter,

fn default() -> Self

Returns the “default value” for a type.