behest

Rust-native building blocks for production AI agent runtimes

English · 简体中文

What this is

behest provides provider-neutral contracts for chat, streaming, tool calling, embeddings, runtime execution, storage, queues, RAG, and observability.

It is designed for systems that need explicit control over model providers, tool execution, persistence, and operational boundaries — instead of opaque "agent framework" magic.

Status: early foundation crate. Public APIs are intentionally compact, strongly typed, and documented.

Why behest

behest /bɪˈhest/ — n. a person's orders or command.

At the behest of the user, the agent acts.

The core of an agent runtime is not "autonomous consciousness" but controlled delegation: the user issues an intent, and the system composes context, invokes models, executes tools, persists state, publishes events within explicit boundaries — auditable, recoverable, constrainable, and replaceable.

The name behest deliberately avoids inflated metaphors like "brain / cognition / intelligence". It only states an engineering fact:

tool-calling, streaming, memory, queue, RAG, snapshot — all mechanisms exist because someone gave an order.

Design goals

• Rust-native first: typed APIs, explicit errors, no hidden runtime assumptions.
• Provider-neutral core: OpenAI, Anthropic, local models, proxies, or internal providers can implement the same contracts.
• Streaming-first runtime: the agent loop is designed around streamed model events, with non-streaming fallback where appropriate.
• Typed tool boundary: tools are described by JSON Schema and executed through explicit registries.
• Pluggable persistence: memory by default, external stores behind feature flags.
• Operational surface: event publishing, snapshots, session gates, compaction, retry policy, and observability hooks.
• Small public API: foundation primitives over framework sprawl.

What's inside

Quick start

[dependencies]
behest = "0.4"

Create a provider-neutral chat request:

use behest::prelude::*;

let request = ChatRequest::new(ModelName::new("example-model"))
    .with_message(Message::system_text("You are concise."))
    .with_user_text("Summarize this project in one sentence.");

Register providers in a registry and route requests:

use behest::prelude::*;

let registry = ProviderRegistry::new();
let provider_id = ProviderId::new("my-provider");

// Register a ChatProvider implementation first.
// registry.register_chat(my_provider);

// Then route through the neutral registry.
// let response = registry.complete(&provider_id, request).await?;

More examples in examples/.

Implement a custom provider

behest does not force one vendor SDK into the core. Implement ChatProvider for any model backend, gateway, local inference service, or internal provider.

use async_trait::async_trait;
use behest::prelude::*;

struct EchoProvider {
    id: ProviderId,
}

#[async_trait]
impl ChatProvider for EchoProvider {
    fn id(&self) -> ProviderId {
        self.id.clone()
    }

    fn capabilities(&self) -> ProviderCapabilities {
        ProviderCapabilities::chat()
    }

    async fn complete(&self, request: ChatRequest) -> ProviderResult<ChatResponse> {
        Ok(ChatResponse {
            provider: self.id.clone(),
            model: request.model,
            message: Message::assistant_text("echo"),
            finish_reason: FinishReason::Stop,
            usage: None,
            raw: None,
        })
    }
}

Streaming providers can override stream.

Define and execute tools

Tools are explicit runtime objects. Each tool exposes a stable name, a human-readable description, and a JSON Schema argument contract.

use behest::prelude::*;
use serde_json::{json, Value};

let tool = FunctionTool::new(
    "echo",
    "Echoes the input message.",
    json!({
        "type": "object",
        "properties": {
            "message": { "type": "string" }
        },
        "required": ["message"]
    }),
    |args: Value| async move {
        Ok(args.get("message").cloned().unwrap_or(Value::Null))
    },
)
.read_only()
.concurrency_safe();

let registry = ToolRegistry::new();
registry.register(tool);

Tool calls returned by a provider can be executed through the registry:

use behest::prelude::*;
use serde_json::json;

let call = ToolCall::new("call_1", "echo", json!({ "message": "hello" }));
let output = registry.execute(&call).await?;

Runtime model

At the runtime layer, AgentRuntime orchestrates the full agent loop, while ManagedRuntime provides a unified container for production deployments:

use behest::prelude::*;

let config = AgentConfig::builder()
    .with_file("behest.toml")?
    .with_env("BEHEST")?
    .build()?;

// One-call construction of a fully configured ManagedRuntime.
let managed = config.build_managed().await?;

// Lifecycle: init → start → serve → stop
managed.init_all().await?;
managed.start_all().await?;
managed.serve().await?; // blocks until shutdown signal
managed.stop_all().await?;

The runtime loop:

RunRequest
  -> load or create session
  -> admit input
  -> build context
  -> call model provider
  -> stream / persist assistant output
  -> execute tool calls
  -> append tool results
  -> repeat until completion, limit, or error
  -> emit AgentEvent values

The runtime brings together:

• ProviderRegistry
• ContextPipeline
• ToolRuntime
• RuntimeStore
• RuntimePolicy
• CompactionService
• SessionGate
• optional event publisher
• optional snapshot store
• optional background job pool

Configuration

AgentConfig supports layered configuration:

1. defaults
2. file sources
3. environment variables
4. manual builder setters

use behest::prelude::*;

let config = AgentConfig::builder()
    .with_file("behest.toml")?
    .with_env("BEHEST")?
    .build()?;

let runtime = config.into_runtime().await?;

Secrets can be loaded through env:VAR_NAME indirection:

[providers.openai]
api_key = "env:OPENAI_API_KEY"

See behest.toml example for full configuration structure.

Provider adapters

Concrete provider adapters are feature-gated.

Enable adapters:

[dependencies]
behest = { version = "0.4", features = ["openai", "anthropic"] }

Feature flags

Default:

Provider adapters:

TLS:

Storage:

RAG:

Queues:

Observability:

Convenience profile:

Example with selected features:

[dependencies]
behest = {
    version = "0.4",
    default-features = false,
    features = ["tls-rustls", "openai", "anthropic", "redis", "queue", "nats"]
}

Error model

behest exposes typed error categories instead of stringly framework failures:

• ProviderError
• ToolError
• StorageError
• ContextError
• RuntimeError
• top-level Error
• crate-level Result<T>

Provider errors distinguish unsupported capabilities, retryable failures, transport failures, invalid responses, and adapter-specific errors.

Tool errors distinguish missing tools, invalid arguments, execution failures, timeouts, and unimplemented external tools.

Lint policy

The crate is intentionally strict:

• unsafe_code = "forbid"
• missing_docs = "deny"
• unreachable_pub = "deny"
• clippy::all = "deny"
• dbg_macro = "deny"
• expect_used = "deny"
• todo = "deny"
• unimplemented = "deny"
• unwrap_used = "deny"

This project treats public API clarity and failure-path hygiene as part of the runtime contract.

Development

# Format
cargo fmt --all --check

# Check all targets and features
cargo check --all-targets --all-features --locked

# Lint
cargo clippy --all-targets --all-features --locked -- -D warnings

# Test
cargo test --all-features --locked

# Build documentation
RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps --locked

Run the complete local verification set:

cargo fmt --all --check && \
cargo check --all-targets --all-features --locked && \
cargo clippy --all-targets --all-features --locked -- -D warnings && \
cargo test --all-features --locked && \
RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps --locked

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.