anda_engine

Runtime engine for Anda, a Rust framework for building autonomous AI agents powered by ICP identities and Trusted Execution Environments (TEEs).

anda_engine implements the runtime behind the traits and data contracts in anda_core. It wires together agent execution, tool dispatch, model providers, persistent storage, hooks, remote engines, and built-in extensions.

Full API documentation is available on docs.rs.

What It Provides

anda_engine is designed as the embeddable runtime layer for applications that host Anda agents.

• Agent and tool registration with scoped execution contexts.
• Direct agent runs and direct tool calls with cancellation support.
• Label-based model routing with primary and fallback models.
• Built-in model adapters for OpenAI-compatible APIs, Anthropic, and Gemini.
• Object storage backed by the object_store ecosystem.
• Persistent memory tools built on AndaDB, Cognitive Nexus, and KIP.
• Remote engine discovery and cross-engine tool or agent calls.
• Hook APIs for observing and transforming agent and tool execution.
• Workspace tools for filesystem access, shell execution, web fetch, extraction, notes, skills, todos, and search.
• Web3 and TEE challenge signing through the Anda Web3 stack.

Installation

cargo add anda_engine

The crate has no default optional features.

[dependencies]
anda_engine = "0.11"

Quick Start

The example below builds an engine with the built-in EchoEngineInfo agent. Real applications usually register their own anda_core::Agent and anda_core::Tool implementations.

use anda_core::AgentInput;
use anda_engine::{
    ANONYMOUS,
    engine::{AgentInfo, EchoEngineInfo, Engine},
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let echo_info = AgentInfo {
        handle: "echo".to_string(),
        name: "Echo Agent".to_string(),
        description: "Returns engine metadata as JSON.".to_string(),
        ..Default::default()
    };

    let engine = Engine::builder()
        .register_agent(Arc::new(EchoEngineInfo::new(echo_info)), None)?
        .build("echo".to_string())
        .await?;

    let output = engine
        .agent_run(
            ANONYMOUS,
            AgentInput::new("echo".to_string(), "hello".to_string()),
        )
        .await?;

    println!("{}", output.content);
    Ok(())
}

Core Concepts

Engine

Engine is the top-level runtime. It owns registered agents, tools, models, hooks, storage, management policy, Web3 or TEE identity, and remote engine metadata.

Use EngineBuilder to configure an engine, then call build(default_agent) to initialize tools and agents. The selected default agent is automatically exported.

Contexts

Agents receive AgentCtx; tools receive BaseCtx. Contexts carry caller identity, request metadata, cancellation tokens, scoped cache and storage, shared state, HTTP and canister features, Web3 signing, and remote engine access.

Context namespaces are derived from agent and tool names so cache and object storage remain isolated between components.

Models

Models is a thread-safe model registry. You can register concrete Model values under labels such as primary, fallback, pro, flash, or lite. Agents can route requests by label while applications remain free to change provider-specific model names.

Built-in provider adapters include:

• openai: OpenAI-compatible Responses API style completion.
• anthropic: Anthropic Messages API completion.
• gemini: Google Gemini completion.

Custom providers can implement CompletionFeaturesDyn and be wrapped with Model::with_completer.

Tools and Extensions

The extension module provides reusable tools for common agent capabilities:

• fetch: signed HTTP fetching and resource loading.
• fs: workspace-scoped file read, write, search, and edit tools.
• shell: native or sandboxed shell command execution.
• extractor: structured data extraction.
• note: lightweight per-agent note storage.
• skill: file-backed skill loading and lifecycle management.
• todo: session-scoped task tracking.
• google: Google web search integration.

Filesystem and shell tools are intentionally workspace-scoped. Shell commands receive a restricted environment; only allowlisted host variables and explicitly configured keys are forwarded.

Memory

The memory module stores conversations, resources, artifacts, usage, steering messages, and follow-up messages. It uses AndaDB collections and exposes KIP-backed tools for persistent agent memory through the Cognitive Nexus.

Remote Engines

Engines can register other engines by endpoint. Remote metadata is fetched through signed RPC, and exported remote functions are exposed with prefixed names:

• Tools: {handle}_{tool}
• Agents: {handle}_{agent}

This lets agents discover and call capabilities hosted by other engines without linking them into the same process.

Hooks

Engine-level hooks can observe or transform agent and tool execution. Typed hooks can be attached through context state for specific extensions, including background task lifecycle events.

SingleThreadHook is included for applications that want to limit each caller to one active prompt at a time.

Security Notes

• Engines are private by default. Configure Management when exposing an engine to external callers.
• Direct agent and tool calls validate request metadata and engine identity.
• Only exported agents and tools appear in Engine::information and are available to non-manager callers.
• Filesystem tools resolve paths under the configured workspace and reject unsafe writes through symlinks or multiply linked files.
• Shell output is truncated in responses when it exceeds the inline limit; full output can be written to a temporary file.

Related Crates

• anda_core: core traits, request/response types, messages, resources, and tool schemas.
• anda_engine_server: HTTP server for exposing one or more engines.
• anda_web3_client: Web3 integration for non-TEE environments.

Development

Useful checks while working on this crate:

cargo check -p anda_engine
cargo test -p anda_engine --lib
cargo clippy -p anda_engine --all-targets -- -D warnings

License

Copyright © 2026 LDC Labs.

ldclabs/anda is licensed under the MIT License. See the MIT license for the full license text.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in anda by you, shall be licensed as MIT, without any additional terms or conditions.