Struct AgentBuilder 

pub struct AgentBuilder<S: StateStoreBackend = StateStore, D: DatabaseBackend = Database, P: ProviderBackend = Provider, T: ToolsetBackend = Toolset> { /* private fields */ }

Configures creation or reopening of one durable Agent.

The builder accepts already-built provider, tool, and storage values without exposing their implementation details through agents-kit.

The hierarchy preserves concrete S, D, P and T types, with no Clone requirement on caller backends or T::Handler. New identity creation and durable reopen use separate constructors; reopening resupplies integrations instead of reconstructing credentials or lower configuration from records.

Native Codex/OpenCode can select P as static composition context without owning a provider value. Custom requires a value through Self::with_provider. The builder owns supplied values, while Self::build accepts construction and cleanup work. Await consuming AgentBackend::shutdown on the built Agent while its runtime remains driven.

The local example uses memory Lance and a passively constructed Provider. It selects an exact model without verifying a running service or generating output.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
// This constructs local owners and selects a model; it makes no generation request.
let agent = AgentBuilder::create(config, storage).with_provider(provider).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
agent.shutdown().await?;

Implementations

impl<S: StateStoreBackend> AgentBuilder<S, Database, Provider>

pub fn create(config: AgentConfig, storage: AgentStorage<S>) -> Self

Configures a new durable agent over the required control-plane store.

This records creation intent without opening a backend. Self::build creates a fresh durable identity. Storage is required up front and retains its exact associated transaction type. For an existing identity use Self::reopen.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
let builder = AgentBuilder::create(config, storage);
let agent = builder.with_provider(provider).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
agent.shutdown().await?;

pub fn create_for_backends<P2: ProviderBackend, T2: ToolsetBackend>( config: AgentConfig, storage: AgentStorage<S>, ) -> AgentBuilder<S, Database, P2, T2>

Configures a new agent with fixed Provider and Toolset implementation types.

Codex and OpenCode retain their native providers, so this selects only the static provider type shared with other agents in a caller-owned composition. Custom agents receive their provider value through Self::with_provider. Repeated Self::with_toolset calls append T2 values to one homogeneous inventory without normalization or a Clone bound.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
let builder = AgentBuilder::create_for_backends::<Provider, tools_kit::Toolset>(config, storage);
// Selecting P alone does not supply the provider required by Custom.
let agent = builder.with_provider(provider).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
agent.shutdown().await?;

pub fn reopen( config: AgentConfig, storage: AgentStorage<S>, id: AgentId, ) -> Self

Configures reopening of an existing durable agent.

Selects an existing identity; it never falls back to creating one. Build checks stored compatibility and the storage clone family’s live-ownership claim. Resupply fresh provider/tool/database values required by that identity. An AgentStorage clone shares coordination without requiring S: Clone.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
let agent = AgentBuilder::create(config.clone(), storage.clone())
    .with_provider(provider).build().await?;
let id = agent.id();
agent.shutdown().await?;
// Reuse the same storage family, and supply a fresh provider after shutdown.
let reopened = AgentBuilder::reopen(config, storage, id.clone())
    .with_provider(Provider::from_config(provider_config)?).build().await?;
assert_eq!(reopened.id(), id);
reopened.shutdown().await?;

pub fn reopen_for_backends<P2: ProviderBackend, T2: ToolsetBackend>( config: AgentConfig, storage: AgentStorage<S>, id: AgentId, ) -> AgentBuilder<S, Database, P2, T2>

Configures reopening with fixed Provider and Toolset implementation types.

This is the reopening counterpart to Self::create_for_backends. It selects no provider value and performs no provider operation.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
let agent = AgentBuilder::create(config.clone(), storage.clone())
    .with_provider(provider).build().await?;
let id = agent.id();
agent.shutdown().await?;
let builder = AgentBuilder::reopen_for_backends::<Provider, tools_kit::Toolset>(
    config, storage, id.clone(),
);
let reopened = builder.with_provider(Provider::from_config(provider_config)?).build().await?;
assert_eq!(reopened.id(), id);
reopened.shutdown().await?;

impl<S: StateStoreBackend, D: DatabaseBackend, P: ProviderBackend, T: ToolsetBackend> AgentBuilder<S, D, P, T>

pub fn with_provider<P2: ProviderBackend>( self, provider: P2, ) -> AgentBuilder<S, D, P2, T>

Supplies the already-built provider required by the Custom backend.

Consumes the provider and changes the builder’s concrete provider parameter; accepted Toolsets and the Database remain attached. Replacing an earlier value drops that value, so complete any required lower lifecycle work before replacing it. Codex/OpenCode reject a supplied provider value during build; use typed construction to select their static provider parameter without a value.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
let agent = AgentBuilder::create(config, storage)
    .with_provider(provider).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
// Shutdown includes the transferred provider; do not reuse it afterward.
agent.shutdown().await?;

Direct lower implementations and non-Clone tools

These caller-owned enums deliberately expose only Provider selection and generation, and Local tool execution. Other Provider operations retain the trait’s Unsupported defaults. They delegate actual transport/handler semantics, not fabricated success. Agent uses LocalProvider::Model and LocalTools::Handler; neither tool enum implements Clone.

This example executes a real Local handler and builds Custom without model inference. A prompt would require the exact configured Ollama model. See providers_kit::ProviderBackend and tools_kit::ToolsetBackend for implementing those lower contracts rather than delegating them.

use std::{convert::Infallible, num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Model, ModelBackend, ModelId, Provider, ProviderBackend, ProviderConfig};
use providers_kit::config::{OllamaConfig, ProviderKind, TransportConfig};
use providers_kit::generation::{GenerateEventStream, GenerateRequest, GenerateResponse, GenerationContinuation};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
use tools_kit::{ToolError, ToolHandler, ToolHandlerBackend, Toolset, ToolsetBackend};
use tools_kit::declaration::{ToolInfo, ToolName};
use tools_kit::execution::{ToolHandlerInput, ToolHandlerOutput, ToolInvocation, ToolResult};
use tools_kit::{local::ToolRegistration, schema::JsonSchema};

enum LocalProvider { Ollama(Provider) }
enum LocalModel { Ollama(Model) }
enum LocalTools { Functions(Toolset) }
enum LocalHandler { Function(ToolHandler) }
impl ProviderBackend for LocalProvider {
    type Model = LocalModel;
    fn model(&self, id: ModelId) -> Result<Self::Model, providers_kit::KitError> {
        match self { Self::Ollama(value) => value.model(id).map(LocalModel::Ollama) }
    }
    async fn shutdown(&self) -> Result<(), providers_kit::KitError> {
        match self { Self::Ollama(value) => value.shutdown().await }
    }
}
impl ModelBackend for LocalModel {
    type Continuation = GenerationContinuation;
    type Session = Infallible;
    fn model_id(&self) -> &ModelId {
        match self { Self::Ollama(value) => value.model_id() }
    }
    async fn generate(&self, request: &GenerateRequest<Self::Continuation>)
        -> Result<GenerateResponse<Self::Continuation>, providers_kit::KitError> {
        match self { Self::Ollama(value) => value.generate(request).await }
    }
    async fn generate_stream(&self, request: &GenerateRequest<Self::Continuation>)
        -> Result<GenerateEventStream<Self::Continuation>, providers_kit::KitError> {
        match self { Self::Ollama(value) => value.generate_stream(request).await }
    }
}
impl ToolsetBackend for LocalTools {
    type Handler = LocalHandler;
    async fn list_tools(&self) -> Result<Vec<ToolInfo>, ToolError> {
        match self { Self::Functions(value) => value.list_tools().await }
    }
    async fn tool_handler(&self, name: ToolName) -> Result<Self::Handler, ToolError> {
        match self { Self::Functions(value) => value.tool_handler(name).await.map(LocalHandler::Function) }
    }
    async fn shutdown(&self) -> Result<(), ToolError> {
        match self { Self::Functions(value) => value.shutdown().await }
    }
}
impl ToolHandlerBackend for LocalHandler {
    async fn step(&mut self, input: ToolHandlerInput) -> Result<ToolHandlerOutput, ToolError> {
        match self { Self::Function(value) => value.step(input).await }
    }
}
let tools = LocalTools::Functions(Toolset::local(vec![ToolRegistration::function(
    ToolInfo::new(ToolName::new("ping")?, JsonSchema::strict(serde_json::json!({"type": "object"}))),
    |_| async { Ok(ToolResult::json(serde_json::json!({"reply": "pong"}))) },
)])?);
let direct = async {
    let mut handler = tools.tool_handler(ToolName::new("ping")?).await?;
    let output = handler.step(ToolHandlerInput::Invoke(ToolInvocation {
        call_id: Some("caller-ping".into()), arguments: serde_json::json!({}),
    })).await?;
    let ToolHandlerOutput::Completed(result) = output else {
        return Err(ToolError::Unsupported { operation: "ping must complete without interaction".into() });
    };
    assert!(!result.is_error);
    assert_eq!(result.structured_content, Some(serde_json::json!({"reply": "pong"})));
    Ok::<(), ToolError>(())
}.await;
if let Err(error) = direct {
    let primary = agents_kit::KitError::from(error);
    let error = match tools.shutdown().await {
        Ok(()) => primary,
        Err(cleanup) => primary.with_supplementary(agents_kit::KitError::from(cleanup)),
    };
    return Err(Box::<dyn std::error::Error>::from(error));
}
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::Auto,
    CustomLoopLimits::new(4, 4, 1)?, CustomToolApproval::Allow)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider = LocalProvider::Ollama(Provider::from_config(ProviderConfig::new(
    ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default()))?);
let agent = AgentBuilder::create_for_backends::<LocalProvider, LocalTools>(config, AgentStorage::new(store))
    .with_provider(provider).with_toolset(tools).build().await?;
let outcome = agent.list_workspaces().await;
let shutdown = agent.shutdown().await; // owns Provider and the non-Clone Toolset
assert!(outcome?.is_empty());
shutdown?;

pub fn with_toolset(self, toolset: T) -> Self

Appends one already-built executable Toolset implementation.

T remains fixed by construction. Changing the Provider or Database keeps every accepted Toolset; its unique Handler remains associated as T::Handler.

Each call appends a value of the construction-selected T; use caller-owned exhaustive Toolset/Handler enums for heterogeneous sources. Custom executes the associated Handler directly. Build validates unique effective names and selected tools before publication. Native support is backend-specific: OpenCode rejects supplied executable toolsets. Builder transfer alone never invokes a handler.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
use tools_kit::{Toolset, declaration::{ToolInfo, ToolName}, execution::ToolResult,
    local::ToolRegistration, schema::JsonSchema};
let tools = Toolset::local(vec![ToolRegistration::function(
    ToolInfo::new(ToolName::new("ping")?, JsonSchema::strict(serde_json::json!({"type":"object"}))),
    |_| async { Ok(ToolResult::text("pong")) },
)])?;
let agent = AgentBuilder::create(config, storage)
    .with_toolset(tools).with_provider(provider).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
// The accepted Toolset is retained across with_provider and closed by Agent shutdown.
agent.shutdown().await?;

pub fn with_knowledge_database<D2: DatabaseBackend>( self, database: D2, ) -> AgentBuilder<S, D2, P, T>

Supplies the Database used by the private managed-knowledge owner.

Consumes a direct Database implementation and changes only the builder’s concrete D parameter. Existing Toolsets and Provider remain attached. This Database is separate from AgentStorage’s control-plane records and exposes no public knowledge runtime. Reopen must resupply a compatible Database when the durable identity requires managed knowledge.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CustomAgentConfig, CustomLoopLimits, CustomToolApproval};
use agents_kit::{model::ModelSelector, tool::ToolSelection};
use providers_kit::{Provider, ProviderConfig, config::{OllamaConfig, ProviderKind, TransportConfig}};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let storage = AgentStorage::new(store);
let custom = CustomAgentConfig::new(ModelSelector::new("exact-model")?, ToolSelection::None,
    CustomLoopLimits::new(4, 0, 1)?, CustomToolApproval::Deny)?;
let config = AgentConfig::new(custom.into(), Duration::from_secs(10), NonZeroUsize::MIN)?;
let provider_config = ProviderConfig::new(ProviderKind::Ollama(OllamaConfig::local()), TransportConfig::default());
let provider = Provider::from_config(provider_config.clone())?;
use storage_kit::{Database, database::config::{DatabaseConfig, LanceConfig}};
let database = Database::connect(DatabaseConfig::lance(LanceConfig::embedded_path("memory://"))).await?;
let agent = AgentBuilder::create(config, storage).with_provider(provider)
    .with_knowledge_database(database).build().await?;
assert!(agent.list_workspaces().await?.is_empty());
agent.shutdown().await?;

pub async fn build(self) -> Result<Agent<S, D, P, T>, KitError>

Validates the complete configuration and creates or reopens the agent.

Takes ownership of construction after acceptance. On failure, prepared resources are cleaned in reverse ownership order within the lifecycle deadline; the first failure remains primary and later failures remain supplementary. Losing the caller observation does not detach accepted build/cleanup ownership.

On success the unique Agent owns its runtime and transferred integrations. Keep Tokio and lower runtimes driven through consuming shutdown. Custom model selection alone does not verify remote model availability; later provider operations own service validation.

Errors

Returns InvalidConfig for invalid backend/integration combinations (including a missing Custom provider), Unsupported for a supplied integration the selected backend cannot represent, and Conflict/Busy for incompatible or already-owned reopen state. Missing identities use NotFound; malformed durable evidence uses InvalidState. Process, transport, protocol, storage and deadline failures retain their owning portable classification. Inspect KitError::kind and KitError::context; build and reopen carry distinct operation context.

This example requires an installed, configured codex executable and its real App Server process. It does not submit a model prompt.

Examples

use std::{num::NonZeroUsize, time::Duration};
use agents_kit::{AgentBackend, AgentBuilder, AgentStorage};
use agents_kit::config::{AgentConfig, CodexConfig};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let config = AgentConfig::new(CodexConfig::spawn(Duration::from_secs(15),
    Duration::from_secs(60))?.into(), Duration::from_secs(30), NonZeroUsize::MIN)?;
let store = StateStore::connect(StateStoreConfig::Lance(LanceStateStoreConfig::memory())).await?;
let agent = AgentBuilder::create(config, AgentStorage::new(store)).build().await?;
let observed = agent.info().await;
let cleanup = agent.shutdown().await;
let info = observed?;
assert!(!info.id().as_str().is_empty());
cleanup?;