Struct AgentLoopBuilder 

pub struct AgentLoopBuilder<Ctx, P, H, M, S> { /* private fields */ }

Builder for constructing an AgentLoop.

Example

let agent = AgentLoop::builder()
    .provider(my_provider)
    .tools(my_tools)
    .config(AgentConfig::default())
    .build();

Implementations

impl<Ctx> AgentLoopBuilder<Ctx, (), (), (), ()>

pub fn new() -> Self

Create a new builder with no components set.

impl<Ctx, P, H, M, S> AgentLoopBuilder<Ctx, P, H, M, S>

pub fn provider<P2: LlmProvider>( self, provider: P2, ) -> AgentLoopBuilder<Ctx, P2, H, M, S>

Set the LLM provider.

pub fn tools(self, tools: ToolRegistry<Ctx>) -> Self

Set the tool registry.

pub fn hooks<H2: AgentHooks>( self, hooks: H2, ) -> AgentLoopBuilder<Ctx, P, H2, M, S>

Set the agent hooks.

pub fn message_store<M2: MessageStore>( self, message_store: M2, ) -> AgentLoopBuilder<Ctx, P, H, M2, S>

Set the message store.

pub fn state_store<S2: StateStore>( self, state_store: S2, ) -> AgentLoopBuilder<Ctx, P, H, M, S2>

Set the state store.

pub fn event_store(self, store: Arc<dyn EventStore>) -> Self

Set the authoritative event store for the loop lifecycle.

pub fn event_authority(self, authority: Arc<dyn EventAuthority>) -> Self

Set the event authority for envelope creation.

When set, the authority governs how events are wrapped in envelopes (sequence numbers, event IDs, timestamps). In server mode the authority seeds sequences from durable storage so ordering is continuous across turns within a thread.

When not set, a fresh LocalEventAuthority starting at sequence 0 is created for each run.

pub fn execution_store(self, store: impl ToolExecutionStore + 'static) -> Self

Set the execution store for tool idempotency.

When set, tool executions will be tracked using a write-ahead pattern:

1. Record execution intent BEFORE calling the tool
2. Update with result AFTER completion
3. On retry, return cached result if execution already completed

Example

use agent_sdk::{builder, stores::InMemoryExecutionStore};

let agent = builder()
    .provider(my_provider)
    .execution_store(InMemoryExecutionStore::new())
    .build();

pub fn execution_store_shared(self, store: Arc<dyn ToolExecutionStore>) -> Self

Set the execution store from a shared Arc.

Use this when the caller needs to retain a handle to the store (for inspection, pre-population, or sharing across loops). See Self::execution_store for the standard owned form.

pub fn audit_sink(self, sink: impl ToolAuditSink + 'static) -> Self

Set the authoritative tool audit sink.

When set, the agent loop emits a ToolAuditRecord at every tool lifecycle transition — blocked, requires-confirmation, cached, replayed, invalidated, completed, and persistence-failed. This gives servers a complete audit trail without relying on the weaker post_tool_use hook.

Defaults to NoopAuditSink when not set.

pub fn audit_sink_shared(self, sink: Arc<dyn ToolAuditSink>) -> Self

Set the audit sink from a shared Arc.

Use this when the caller needs to retain a handle to the sink (e.g. to inspect captured records from tests, or to share a single durable sink across multiple agent loops). Passing an Arc<dyn ToolAuditSink> here avoids the Arc<Arc<S>> double wrap that happens when callers Arc::clone(&sink) a sink they already wrapped and hand it to Self::audit_sink.

See Self::audit_sink for the standard owned form.

pub fn observability_store( self, store: impl ObservabilityStore + 'static, ) -> Self

Available on crate feature otel only.

Set the observability store for GenAI payload capture.

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

Set the agent configuration.

pub fn with_reminders(self, reminders: ReminderConfig) -> Self

Enable per-tool system reminders.

When set, the agent loop evaluates the configuration’s tool_reminders after each tool executes and appends any reminder whose ReminderTrigger matches (wrapped in <system-reminder> tags) to the tool result the model reads on the next turn.

Example

use agent_sdk::{builder, reminders::{ReminderConfig, ToolReminder}};

let reminders = ReminderConfig::new()
    .with_tool_reminder("write", ToolReminder::always(
        "Consider reading the file back to verify the content.",
    ));
let agent = builder()
    .provider(my_provider)
    .with_reminders(reminders)
    .build();

pub const fn with_compaction(self, config: CompactionConfig) -> Self

Enable context compaction with the given configuration.

When enabled, the agent will automatically compact conversation history when it exceeds the configured token threshold.

Example

use agent_sdk::{builder, context::CompactionConfig};

let agent = builder()
    .provider(my_provider)
    .with_compaction(CompactionConfig::default())
    .build();

pub fn with_auto_compaction(self) -> Self

Enable context compaction with default settings.

This is a convenience method equivalent to:

builder.with_compaction(CompactionConfig::default())

pub fn with_custom_compactor( self, compactor: impl ContextCompactor + 'static, ) -> Self

Override the default compactor with a custom implementation.

Guardrail and pricing boundary: the loop only wires its pre_llm_request / on_llm_response guardrail hooks into the compactor it constructs itself — it cannot reach inside an arbitrary ContextCompactor’s own LLM calls. A custom compactor that talks to a model is responsible for its own guardrail coverage (for the built-in summarizer, construct it with LlmContextCompactor::with_guardrail_hooks). Its reported usage is priced at the run’s provider/model for cost budgets, so max_cost_usd is approximate when the compactor uses a different backend.

pub fn with_skill(self, skill: Skill) -> Self

where Ctx: Send + Sync + 'static,

Available on crate feature skills only.

Apply a skill configuration.

This merges the skill’s system prompt with the existing configuration and filters tools based on the skill’s allowed/denied lists.

Available when the skills feature is enabled.

Example

let skill = Skill::new("code-review", "You are a code reviewer...")
    .with_denied_tools(vec!["bash".into()]);

let agent = builder()
    .provider(provider)
    .tools(tools)
    .with_skill(skill)
    .build();

impl<Ctx, P> AgentLoopBuilder<Ctx, P, (), (), ()>

where Ctx: Send + Sync + 'static, P: LlmProvider + 'static,

pub fn build( self, ) -> AgentLoop<Ctx, P, DefaultHooks, InMemoryStore, InMemoryStore>

Build the agent loop with default hooks and in-memory message/state stores.

This is a convenience method that uses:

• DefaultHooks for hooks
• InMemoryStore for message store
• InMemoryStore for state store
• InMemoryEventStore for the event store, when none was set
• AgentConfig::default() if no config is set

Supplying an event_store is optional for this convenience build — a fresh InMemoryEventStore is used by default so the 30-second path needs no Arc ceremony. Wire a durable store explicitly when you need persistence across process restarts.

impl<Ctx, P, H, M, S> AgentLoopBuilder<Ctx, P, H, M, S>

where Ctx: Send + Sync + 'static, P: LlmProvider + 'static, H: AgentHooks + 'static, M: MessageStore + 'static, S: StateStore + 'static,

pub fn build_with_stores(self) -> AgentLoop<Ctx, P, H, M, S>

Build the agent loop with all custom components.

provider, hooks, message_store, and state_store are guaranteed present by the type-state builder (this method is only callable once each is set to a concrete type), so they cannot be missing at runtime.

Panics

Panics if an event_store has not been set — it is the one component supplied via a plain Arc setter rather than a type-transitioning one, so it has no compile-time “set” guarantee.

Trait Implementations

impl<Ctx> Default for AgentLoopBuilder<Ctx, (), (), (), ()>

fn default() -> Self

Returns the “default value” for a type.