Anda Engine Architecture

This document describes the current anda_engine runtime architecture from the source code. It replaces the older deployment-first narrative that treated ICP, TEE, and IC-TEE as mandatory runtime blocks.

In the current engine, those integrations are optional backing capabilities. The practical center of the system is the Engine runtime: it validates callers, creates scoped contexts, dispatches agents and tools, routes model calls, handles tool-call loops, and exposes selected local or remote functions.

Preview note: use markdown-viewer/markdown-viewer-extension to preview this document with the embedded HTML architecture diagram and PlantUML sequence diagram rendered.

Source map:

• engine.rs: top-level Engine, EngineBuilder, exported APIs, management checks, hooks, challenge signing.
• context/agent.rs: AgentCtx, local/remote/subagent routing, CompletionRunner, CompletionStream.
• context/base.rs: BaseCtx, scoped state, cache, store, keys, HTTP, signed RPC, cancellation.
• context/tool.rs: built-in discovery agents: tools_groups, tools_search, and tools_select.
• model.rs: Models label router, provider adapters, retry and streaming helpers.
• subagent.rs: reusable subagents, background sessions, compaction and handoff.
• memory.rs: conversation/resource storage and KIP/Cognitive Nexus tools.
• extension: built-in tool libraries such as filesystem, shell, fetch, skills, notes, todos, and memory.

Runtime View

Request Sequence

@startuml
title Anda Engine agent_run and completion loop
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowColor #334155
skinparam sequenceLifeLineBorderColor #CBD5E1
skinparam sequenceParticipantBorderColor #CBD5E1
skinparam sequenceParticipantBackgroundColor #F8FAFC
skinparam sequenceGroupBorderColor #94A3B8
skinparam sequenceGroupBackgroundColor #F8FAFC
skinparam noteBackgroundColor #FFF7ED
skinparam noteBorderColor #FDBA74
actor Caller
participant "Host API\n(server / CLI / app)" as Host
participant "Engine" as Engine
participant "Management\n+ Hooks" as Guard
participant "AgentCtx\n+ BaseCtx" as Ctx
participant "Agent" as Agent
participant "CompletionRunner" as Runner
participant "Models\nlabel router" as Models
participant "Model adapter\nOpenAI / Anthropic / Gemini" as Model
participant "Tool / Agent\nregistries" as Registry
participant "Local Tool\nor Agent" as Local
participant "Remote Engine" as Remote
participant "SubAgent\nsession runner" as SubSession
Caller -> Host : submit AgentInput
Host -> Engine : agent_run(caller, input)
Engine -> Engine : validate RequestMeta\nnormalize default agent
Engine -> Guard : check_visibility(caller)
Guard --> Engine : visibility accepted
Engine -> Ctx : ctx_with(caller, agent, label, meta)
Engine -> Guard : on_agent_start(ctx, agent)
Engine -> Agent : run(ctx, prompt, resources)
Agent -> Ctx : completion(req, resources)
Ctx -> Runner : completion_iter(req, resources)
loop until final output, failure, or cancellation
Runner -> Models : resolve(req.model or ctx.label)
Models --> Runner : Model
Runner -> Model : completion(CompletionRequest)
Model --> Runner : AgentOutput\ncontent, usage, raw_history, tool_calls
alt model returned tool_calls
Runner -> Registry : resolve each tool_call name\nlocal, RA_, RT_, or SA_
par each resolved call
alt local tool
Runner -> Ctx : child_base(tool)
Ctx -> Local : Tool::call(BaseCtx, args, selected resources)
Local --> Runner : ToolOutput
else local agent or subagent without session
Runner -> Ctx : child(agent)
Ctx -> Local : Agent::run(AgentCtx, prompt, resources)
Local --> Runner : AgentOutput as ToolOutput
else remote callable
Runner -> Ctx : remote_tool_call or remote_agent_run
Ctx -> Remote : https_signed_rpc(tool_call / agent_run)
Remote --> Runner : ToolOutput or AgentOutput
else subagent session mode
Runner -> Local : SubAgent::run(session args)
Local -> SubSession : claim session and spawn background runner
Local --> Runner : ack with session id
SubSession -> Guard : on_background_start
SubSession -> Runner : unbound completion loop
SubSession -> Guard : on_background_progress / on_background_end
end
end
Runner -> Runner : accumulate usage, artifacts, tools_usage\nappend tool outputs to next request
else no tool calls
Runner -> Runner : final_output()
end
opt steering or follow-up queued
Runner -> Runner : insert user content at safe boundary\nprune unanswered tool raw history if needed
end
end
Runner --> Agent : AgentOutput
Agent --> Engine : AgentOutput
Engine -> Guard : on_agent_end(ctx, agent, output)
Guard --> Engine : transformed output
Engine -> Engine : clear provider raw_history
Engine --> Host : AgentOutput
Host --> Caller : response
@enduml

Component Notes

• Engine is the public runtime boundary. It enforces exported agent/tool lists for non-manager callers and always exports the default agent.
• EngineBuilder starts with in-memory storage, no implemented Web3 client, no external model, and built-in discovery/subagent control agents.
• AgentCtx is the main scheduling surface. It exposes local tools, dynamic tool providers, local agents, subagents, registered remote engines, and dynamic remote engines from cache.
• CompletionRunner is iterative. A model turn can return tool calls; the runner executes them and feeds tool outputs into the next model turn. Long-running runners can compact oversized history into a continuation handoff and resume from that summary.
• tools_groups, tools_search, and tools_select are agents, not side channels. tools_groups returns a compact directory of visible capability bundles; tools_select can expand one group into schemas, and discovered schemas stay in tool-output context while repeated payloads are compacted from conversation context.
• BaseCtx creates namespace-scoped child contexts. Agent paths use a_<agent>, tool paths use t_<tool>, and all store/cache operations are resolved under that path.
• Models routes by label first and then falls back to the primary/default model. Provider-specific names stay inside adapter configuration.
• SubAgentManager turns persisted or temporary SubAgent definitions into callable SA_<name> agents. Long-running subagent sessions use hooks to push progress and final output.
• Memory is an extension layer. Conversation/resource storage uses AndaDB collections, and persistent knowledge operations are exposed as KIP tools backed by Cognitive Nexus.
• Web3, TEE, ICP, and IC-COSE integrations are implementation choices behind Web3SDK, HttpFeatures, KeysFeatures, CanisterCaller, or ObjectStore. They are not mandatory architecture layers for the engine itself.