ANEL — Agent-Native Execution Layer

LLMs can reason about anything, but struggle to act reliably — because the execution layer was never designed for agents. ANEL changes that: Unix pipes, NDJSON streams, zero-trust sandboxes, and self-healing errors — taking AI agents from conversation to controlled execution.

中文文档

Read more: ANEL Architecture Manifesto

---

The Problem — Why ANEL Exists

We have Einstein-level brains (GPT-4, Claude, LLaMA) but communicate with them via Morse code (JSON Schema).

The current state of agent-tool interaction is broken:

# How agents call tools today — fragile and blind
result = subprocess.run(["grep", "-r", "TODO", "."], capture_output=True, text=True)
# stdout: plain text. No schema. No structure.
# failure: returncode == 1. That's all the agent knows.
# discovery: impossible. Agent can't learn what grep accepts.
# safety: full user permissions. No sandbox.

This is the Cognitive-Execution Gap — the chasm between what LLMs can reason about and what they can actually do:

• Over-fitted API calls: Tool Calling (MCP, Function Calling) forces complex logic into JSON structures. Agents spend tokens understanding parameter definitions instead of solving problems.
• No atomicity or composability: Tools are isolated black boxes. Agents can't pipe search | filter | transform like Unix engineers. They're stuck in think-call-wait-parse loops.
• Fragile interfaces: Errors are stack traces for developers, not structured feedback for agents. When something fails, the agent can't self-correct — it spirals.
• The Wrapper Trap: Agents are locked into pre-written Python functions. If a developer didn't anticipate a use case, the agent is blind. No exploration, no discovery.

TODAY:                              WITH ANEL:

Agent ──subprocess──> Tool          Agent ──ANID Protocol──> Tool
       plain text <──                      NDJSON stream <──
       exit code 1 <──                     RFC 7807 error <──
       (no schema)                         + recovery hints
       (no sandbox)                        + WASI sandbox
       (no trace)                          + trace context
       (no composability)                  + Unix pipe composability

If LLM is the new CPU, our current APIs are tape drives. We need bus-level speed and standards. That's ANEL.

---

What is ANEL — Core Philosophy

ANEL is a standardized execution layer purpose-built for AI agents to interact with tools — analogous to how POSIX standardized how programs interact with operating systems.

Unix 2.0 for the Agent Era

ANEL returns to the most fundamental architectural philosophy in computer science: the Unix philosophy. For LLMs pre-trained on massive codebases, shell scripts and pipes are more natural than JSON APIs — they're the model's "native tongue."

• Agent-as-Operator: Agents sit at the console like human sysadmins, operating atomic tools directly. No middleware, no wrappers — direct control.
• Tools as Language: qmd search "error" | grep "critical" isn't just a command — it's the agent's thought process made executable.
• Affordance: ANEL lets agents build mental models via --help, --emit-spec, --dry-run — not blind parameter filling.

The Human Analogy

• LLM = Brain (decision, reasoning)
• Agent Skills = Professional skills (workflows, SOPs)
• ANEL = Hands and feet (precise execution, tactile feedback)

Four Core Characteristics

1. Atomicity — Minimal-granularity operations (read, write, compute), not black-box business functions
2. Determinism — Structured input/output eliminates hallucination risk in execution
3. Streaming Native — Pipe-based data flow, not request-response waiting
4. Dual-Mode I/O — Human visualization (TTY) + agent structured reading (NDJSON)

Architecture — ANEL's Position in the Stack

┌─────────────────────────────────────────────────────┐
│              AI Agent (LLM Brain)                    │
│         Claude · GPT · LLaMA · Gemini               │
└──────────────────────┬──────────────────────────────┘
                       │  Function Calls / MCP / Skills
                       ▼
┌─────────────────────────────────────────────────────┐
│           Agent Skills (Workflow Layer)              │
│      LangChain · AutoGen · CrewAI · Custom          │
└──────────────────────┬──────────────────────────────┘
                       │  Wrap & Drive
                       ▼
┌═════════════════════════════════════════════════════┐
║        ANEL — Agent-Native Execution Layer          ║
║  ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────┐ ║
║  │   ANID   │ │Hyper-Shell│ │ Polyglot │ │ Std  │ ║
║  │ Protocol │ │  Runtime  │ │ Gateway  │ │ Tools│ ║
║  └──────────┘ └───────────┘ └──────────┘ └──────┘ ║
╚═════════════════════════════════════════════════════╝
                       │  Structured I/O (NDJSON)
                       ▼
┌─────────────────────────────────────────────────────┐
│                 Infrastructure                       │
│   Databases · K8s · APIs · File Systems · IoT       │
└─────────────────────────────────────────────────────┘

---

ANEL Architecture — Four Subsystems

1. ANID Protocol (Agent-Native Interface Definition)

The "legal contract" between agents and tools. Not just I/O definitions — behavioral contracts.

Core principles:

• Stateless: Each invocation is an independent process or Wasm instance
• Dual-Stream Separation: STDOUT = business data (NDJSON), STDERR = control plane (RFC 7807)
• Zero-Ambiguity: No human-readable fuzzy text — only structured data

Mandatory control plane:

Flag	Purpose	Behavior
--emit-spec	Introspection	Output JSON Schema to STDOUT
--dry-run	Rehearsal	Validate without side effects, output Impact Report
--output-format	Format	Accept json, ndjson, text. Default: ndjson

Environment context (injected by runtime):

Variable	Purpose
AGENT_TRACE_ID	Distributed tracing & audit
AGENT_IDENTITY_TOKEN	Downstream API authentication

Structured errors with recovery hints — the key innovation:

{
  "error_code": "INVALID_INPUT",
  "status": 400,
  "message": "Invalid URL format provided",
  "severity": "error",
  "context": { "input": "google" },
  "recovery_hints": [
    { "code": "FIX_URL", "message": "URL must start with 'http://' or 'https://'" }
  ]
}

vs. retryable error:

{
  "error_code": "BACKEND_UNAVAILABLE",
  "status": 503,
  "message": "Connection timed out after 5000ms",
  "severity": "warning",
  "recovery_hints": [
    { "code": "RETRY", "message": "Wait 5 seconds and retry" },
    { "code": "INCREASE_TIMEOUT", "message": "Increase timeout using '--timeout 15'" }
  ]
}

Atomic Capability Contracts — test fixtures that verify ANID compliance:

tests/fixtures/anel/
├── introspection.yaml          # What the tool accepts (static)
├── success.ndjson              # Expected output for known inputs
├── error_invalid_arg.json      # Fatal error: parameter correction
├── error_timeout.json          # Retryable error: retry guidance
└── error_auth_fail.json        # Auth error: credential refresh

2. Hyper-Shell (Runtime)

If Bash/Zsh is designed for humans, Hyper-Shell is designed for agents. It's the high-performance container that hosts ANEL.

Four pillars:

1. Hyper-Speed: Rust core + Wasm plugins (wasmtime). Sub-millisecond cold start. Agent's chain-of-thought is never blocked by tool startup latency.

2. Hyper-Structured: NDJSON object streams replace text bytes in pipes. Preserves Unix composability, adds SQL-like type safety. Agents parse {"status": "ok"} instead of guessing at grep output.

3. Hyper-Secure: WASI sandbox with deny-by-default capabilities. Plugins have zero permissions unless explicitly granted (--allow-read=/tmp/logs). Even prompt-injected rm -rf / is blocked.

4. Hyper-Observable: Stream Tap architecture captures all I/O without affecting execution. AGENT_TRACE_ID propagation enables full audit trails. Every atomic operation is traceable.

Hyper-Shell = Rust Performance + Wasm Security + NDJSON Structure + Unix Composability

3. Polyglot Gateway (Multi-Language Adapter)

The adapter that connects the legacy world. Enterprises have massive Python scripts, SQL queries, shell commands. The Gateway wraps them into ANID-compliant atomic capabilities without rewriting — making legacy systems instantly "Agent Ready."

• @anel.expose decorator in Python/Go/Node.js SDKs
• Auto-generates ANID metadata from existing function signatures
• Bridges old tools into the structured ANEL ecosystem

4. Standard Toolset

Enterprise-grade atomic capability library. Tools designed like curl or kubectl — general-purpose, self-documenting, composable.

Each tool ships with full ANID contracts (introspection, success fixtures, error fixtures).

---

Dynamic Runtime Model — Three Layers

L1 — Discovery Layer: "What do I know?"

• Agent searches tools via search-tools or apropos
• Dynamically loads tool usage via --emit-spec or --help
• Just-in-time knowledge acquisition, breaking context window limits

L2 — Orchestration Layer: "How do I solve this?"

• Interactive exploration: Execute probe commands, adjust strategy based on feedback
• Dynamic composition: Pipe atomic capabilities into workflows the developer never anticipated

L3 — Execution & Feedback Layer: "What happened?"

• High-performance Rust kernel executes commands
• STDOUT: Business data stream
• STDERR: Structured machine-readable status (ANID protocol), forming closed-loop control

---

ANEL vs Agent Skills — The Relationship

Conceptual boundary:

• Agent Skills = "recipes" (workflow logic, when to use, parameter preparation)
• ANEL = "knife skills and heat control" (precise execution, physical feedback)

Skills are the brain's "battle plan." ANEL is the mechanized force executing it on the ground. When facing unknown problems, agents can either invoke Skills (fixed workflows) or bypass them entirely to operate ANEL atomic tools directly for creative problem-solving.

Code-level integration:

class ServiceHealthCheckSkill(BaseTool):
    name = "service_health_check"
    description = "Check service health status. Input: service URL."

    def _run(self, target_url: str) -> dict:
        cmd = ["qmd", "query", target_url,
               "--output-format", "ndjson"]
        result = subprocess.run(cmd, capture_output=True, text=True)
        if result.returncode != 0:
            error = json.loads(result.stderr)
            return f"Failed: {error['message']}. Hint: {error['recovery_hints']}"
        return [json.loads(line) for line in result.stdout.splitlines()]

Deployment modes:

• CLI mode: Development, < 50 agents
• Server/Sidecar mode: Production, > 1000 agents (Rust async + Wasm = 1 process handles thousands of requests)

---

This Project — Reference Implementation

To prove ANEL works, we needed a real-world application as the reference implementation. We chose qmd by Tobi Lütke as the starting point — a beautifully minimal local search engine for docs, know