Architecture Overview

Design Philosophy

AgentZero is a small, auditable core — not a framework. Every new capability must prove it belongs inside the secure core or be implemented as an adapter/skill/package.

Data Flow

User Input
    ↓
Session Engine
    ↓
Policy Evaluation ← .agentzero/policy.yml
    ↓
┌──────────────────────────────────────┐
│  Tool Executor (host tools)          │
│  OR                                  │
│  Skill Executor (by runtime tier):   │
│    InstructionOnly → display         │
│    HostSupervised  → shell (gated)   │
│    WasmSandbox     → wasmtime engine │
│      ↕ WasmHostCallbacks (az::log,   │
│        az::read_file, az::write_file)│
│    MvmMicrovm      → MicroVM (planned)│
│    Deny            → blocked         │
│                                      │
│  Dynamic Tool Generation:            │
│    generate_tool → wasm-encoder      │
│      → DynamicToolRegistry (v1/v2/)  │
└──────────────────────────────────────┘
    ↓
Audit Logger → .agentzero/audit/<session>.jsonl
    ↓
Tool/Skill Output (labeled untrusted)
    ↓
Model (with redaction if remote)
    ↓
Response to User

Key Contracts

• Every action passes through policy before execution
• Every action emits an audit event after decision
• Secret handles — models see URIs, tools get values at runtime
• Content provenance — untrusted output wrapped with boundary markers
• Runtime isolation — WASM skills run in sandboxed wasmtime with no ambient host access; host-supervised skills go through policy + audit before any shell call
• Self-improving agent — the agent can generate new WASM tools at runtime via generate_tool, registered in a DynamicToolRegistry with per-project versioning
• WASM host imports — sandboxed modules access host functions (az::log, az::read_file, az::write_file) through the WIT-defined az:host interface, policy-enforced via SessionHostCallbacks
• Fail closed — unknown classification, permissions, or runtime → deny

Workspace Structure

agentzero/
  Cargo.toml          (workspace + facade crate)
  src/lib.rs          (re-exports all sub-crates)
  crates/
    agentzero-core/   (types, crypto, vault, trust, redaction)
    agentzero-policy/ (rule engine + TOML loader)
    agentzero-audit/  (JSONL + encrypted logging)
    agentzero-session/(engine, providers, tools, router, retry)
    agentzero-tools/  (registry + schemas)
    agentzero-skills/ (manifests, scanner, report, registry)
    agentzero-sandbox/(profiles + WASM runtime)
    agentzero-mcp/    (MCP server)
    agentzero-acp/    (ACP adapter)
    agentzero-tracing/(centralized logging)
    agentzero-cli/    (CLI binary)

ADRs

Architecture decisions are binding. See specs/adrs/ for all 13:

1. Minimal Secure Core
2. Local-First Model Routing
3. Policy/Redaction/Audit Wrap Every Action
4. Skills as First-Class Capability Bundles
5. Package Manifest & Lockfile Trust Model
6. Runtime Isolation Tiers (Host/WASM/MVM)
7. ACP is an Adapter, Not the Core
8. Prompt Injection & Untrusted Content Boundaries
9. Capability-Based Secret Handles
10. Non-Goals & Platform Creep Boundary
11. Self-Improving Agent via WASM
12. WIT Adoption for Tool Interfaces
13. MCP Deprecation to Optional Feature Flag