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.

See the construction example and Self::reopen for durable reopen.

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.

See the construction example. To choose caller-owned lower types, see Self::with_provider and Self::with_toolset.

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.

See Self::reopen_for_backends for typed creation and reopening. Self::with_provider and Self::with_toolset accept caller-owned lower types.

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

This owns one Lance directory and reopens it through a fresh connection. Memory stores instead require the same retained storage family. Shutdown is awaited before inspection errors are propagated; unsuccessful runs retain their files.

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};
use providers_kit::config::{OllamaConfig, ProviderKind, TransportConfig};
use storage_kit::{StateStore, state::config::{LanceStateStoreConfig, StateStoreConfig}};
let directory = std::env::temp_dir().join(format!("agent-reopen-doc-{}", uuid::Uuid::new_v4()));
std::fs::create_dir(&directory)?;
let store_config = StateStoreConfig::lance(LanceStateStoreConfig::directory(&directory));
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 store = StateStore::connect(store_config.clone()).await?;
let agent = AgentBuilder::create(config.clone(), AgentStorage::new(store))
    .with_provider(Provider::from_config(provider_config.clone())?).build().await?;
let id = agent.id();
agent.shutdown().await?;

let store = StateStore::connect(store_config).await?;
let reopened = AgentBuilder::reopen(config, AgentStorage::new(store), id.clone())
    .with_provider(Provider::from_config(provider_config)?).build().await?;
let result = reopened.info().await;
let cleanup = reopened.shutdown().await;
let info = match (result, cleanup) {
    (Ok(info), Ok(())) => Ok(info),
    (Err(primary), Err(cleanup)) => Err(primary.with_supplementary(cleanup)),
    (Err(error), _) | (_, Err(error)) => Err(error),
}?;
assert_eq!(info.id(), &id);
// Only successful shutdown and readback permit deleting this owned directory.
std::fs::remove_dir_all(directory)?;

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_for_backends::<Provider, tools_kit::Toolset>(
    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?;
let reopened_id = reopened.id();
reopened.shutdown().await?;
assert_eq!(reopened_id, id);

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.

See the construction example.

Direct implementations retain P::Model and T::Handler; neither T nor its handler requires Clone. See providers_kit::ProviderBackend and tools_kit::ToolsetBackend for runnable implementations, and the Custom composition examples for their use together with the real agent loop. Other lower operations keep their owning trait’s explicit unsupported behavior.

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?;
let result = agent.list_workspaces().await;
// Shutdown settles the transferred Toolset and Provider even if listing failed.
let cleanup = agent.shutdown().await;
let workspaces = match (result, cleanup) {
    (Ok(value), Ok(())) => Ok(value),
    (Err(primary), Err(cleanup)) => Err(primary.with_supplementary(cleanup)),
    (Err(error), _) | (_, Err(error)) => Err(error),
}?;
assert!(workspaces.is_empty());

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.

See IngestKnowledgeRequest for request construction and the Custom composition examples for caller-owned knowledge storage.

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 = match (observed, cleanup) {
    (Ok(value), Ok(())) => Ok(value),
    (Err(primary), Err(cleanup)) => Err(primary.with_supplementary(cleanup)),
    (Err(error), _) | (_, Err(error)) => Err(error),
}?;
assert!(!info.id().as_str().is_empty());