Anda Framework Documentation

Anda is a Rust framework designed for building composable AI agent runtimes. It allows developers to combine models, tools, memory, and other agents into a single, unified runtime. The framework focuses on composability, type-safe extension points, asynchronous execution, and practical runtime control.

Key capabilities include:

• Model Routing: Routing requests through labeled tiers (e.g., primary, pro, flash, lite) using common request/output contracts.
• Runtime Orchestration: Managing iterative model turns, tool calls, usage accounting, and long-running session handoffs via a CompletionRunner.
• Scoped Execution: Providing isolated state and capabilities (cache, object storage, HTTP, cancellation) through BaseCtx and AgentCtx.
• Discovery-aware Tools: Allowing agents to survey tool bundles using tools_groups and expand them with tools_select on demand.

Anda's architecture is built around several key abstractions:

• Composable Agents and Tools: Registered via stable traits and function definitions, allowing components to form complex workflows.
• Model Routing: The engine routes completion requests using capability tags like primary, pro, flash, and lite. Provider adapters abstract the specific model implementation.
• Runtime Orchestration (CompletionRunner): Manages the lifecycle of model interactions, including iterating through turns, executing tool calls, calling agents, accumulating usage, summarizing artifacts, handling steering/follow-up messages, cancellation, and managing long-session continuation handoffs.
• Isolated Execution Contexts: BaseCtx and AgentCtx provide isolated state, cache, object storage, HTTP calls, signed calls, cancellation, and child contexts for each agent or tool.
• Extensible Memory and Skills: Supports extensions for conversation storage, memory tools (based on KIP), filesystem, shell, fetch, notes, todos, and file-driven skills.
• Tool Discovery: Supports a two-step discovery process where agents can browse tools_groups (static tools, dynamic providers, or MCP servers) and then use tools_select to expand a specific group when a schema is required.

The Anda Engine is a runtime that manages the lifecycle of AI agents and tools. Its core responsibilities include validating callers, creating isolated contexts, scheduling agents and tools, routing model requests, and handling tool calls.

Key architectural layers include:

• Engine Boundary: Managed by Engine (holds runtime state, default agents, hooks) and configured via EngineBuilder (registers tools, agents, models, stores, etc.). EngineCard is used to publish exported definitions for remote discovery.
• Access Control & Observability: Uses Management for visibility (Private, protected, public) and Hooks (on_agent_start/end, on_tool_start/end) to observe or modify outputs. Cancellation is handled via root and child tokens passed through contexts.
• Registry: Contains AgentSet (local agents), ToolSet / ToolProviderSet (static tools and runtime providers), and RemoteEngines (remote functions routed via RA_ and RT_ prefixes).
• Execution (Runner): AgentCtx combines BaseCtx with models, tools, and routing helpers. CompletionRunner iterates through model turns, executes tool calls, and generates final output. SubAgent sessions support both synchronous calls and background sessions with hooks.
• BaseCtx Capabilities: Provides scoped state (request meta, elapsed time), isolated Store and cache via context paths, and external call capabilities (HTTP, signed RPC, key derivation).
• Model Routing: Uses Models for tag-based routing (e.g., pro, flash, lite) and Adapters (OpenAI-compatible, Anthropic, Gemini, or custom CompletionFeaturesDyn providers).
• Storage & Extensions: Includes built-in tools (filesystem, shell, fetch, etc.) and optional persistence via Memory (AndaDB) and ObjectStore (in-memory, local, or cloud).

The Anda Engine operates on an iterative completion loop managed by a CompletionRunner. When an agent_run is triggered, the following sequence occurs:

1. Validation & Guarding: The Engine validates the request and uses a Guard to check visibility/permissions.
2. Context Initialization: An AgentCtx is created to manage the lifecycle and resources.
3. Agent Execution: The Agent starts its run loop. The AgentCtx delegates completion requests to the CompletionRunner.
4. Iterative Completion Loop:
   • The Runner resolves the model via Models (using a label or default).
   • The Model returns an AgentOutput containing content, usage, and potentially tool_calls.
   • Tool Execution: If tool_calls are present, the Runner resolves them via a Registry (identifying them as local, remote, or subagent) and executes them.
   • Feedback Loop: Tool outputs are appended to the context and fed back into the next model request.
   • This loop continues until a final output, failure, or cancellation occurs.
5. Finalization: The Engine triggers on_agent_end hooks, transforms the output, and returns the final AgentOutput to the caller.

@startuml
title Anda Engine agent_run and completion loop
# ... (Sequence diagram logic) ...
@enduml

The Anda Engine operates on an iterative completion loop managed by a CompletionRunner. When an agent_run is submitted, the engine validates the request, checks visibility via the Guard (Management + Hooks), and initializes an AgentCtx.

The Iteration Loop:

1. Model Turn: The CompletionRunner resolves the requested model (via Models routing) and sends a CompletionRequest to the model adapter (e.g., OpenAI, Anthropic, Gemini).
2. Tool/Agent Resolution: If the model returns tool_calls, the runner resolves them against registries using specific prefixes:
   • RA_: Remote Agent
   • RT_: Remote Tool
   • SA_: SubAgent
   • (Unprefixed): Local Tool or Agent
3. Execution: Depending on the type, the runner executes the call via Local::call, Agent::run, https_signed_rpc for remote calls, or spawns a SubAgent session runner for background tasks.
4. Feedback: Tool outputs are accumulated and fed back into the next model turn. This continues until the model provides a final output, a failure occurs, or the process is cancelled.
5. Steering: The runner can insert user content at safe boundaries or prune unanswered tool history to manage context size.

@startuml
title Anda Engine agent_run and completion loop
# ... (Sequence diagram logic) ...
@enduml