AgentWall Protocol (Beta) v1.0 — Architecture & System Overview

Authors: Saidev Dhal
Date: 22/03/2026
Version: v1.0 (Beta)

1. Introduction

AgentWall is a dedicated control and governance layer designed for the era of autonomous AI agents. While traditional security models focus on human-to-machine or machine-to-machine (M2M) authentication, AgentWall addresses the unique challenges of agentic workflows: non-human actors that perform multi-step tasks, call external APIs, and make semi-autonomous decisions on behalf of users or organizations.

AgentWall exists to bridge the gap between "giving an agent an API key" and "retaining oversight." It provides a unified system for agent identity, capability discovery, real-time policy enforcement, and budget management. By treating the agent as a primary principal, AgentWall enables organizations to deploy AI agents with the confidence that they are bounded by programmable guardrails.

2. Mental Model: The Evaluation Layer

AgentWall can be understood as a decision layer that sits between an agent and the APIs it calls.

Instead of a binary permission check:
Agent → API → Execution

AgentWall introduces a stateful evaluation phase:
Agent → Evaluation → Decision → Execution

This shifts systems from static permission checks (granted at token issuance) to dynamic execution control (evaluated at the moment of intent). The system does not just verify identity; it continuously evaluates intent, risk, and cumulative behavior.

3. Core Problem: The Identity & Control Vacuum

Traditional authentication and authorization models (API Keys, OAuth 2.0) are insufficient for AI agents for three primary reasons:

Identity Collapse: Shared client credentials hide individual agent behavior.
Static Permissions: OAuth scopes cannot respond to dynamic session risk.
Lack of Runtime Oversight: No mechanism for real-time human-in-the-loop approval.

Comparison: Traditional Auth vs. AgentWall

Feature	Traditional Auth	AgentWall Protocol
Principal	Application	Individual Agent
Identity	Shared Secret	Ed25519 Keypair
Auth Type	Bearer Token	Typed JWTs
Control	Static Scopes	Dynamic Decisions
Oversight	Async Audit	Sync Interception

4. System Architecture

AgentWall consists of a stateful Control Plane and a high-performance Data Plane.

5. The Request Lifecycle

A typical request flows through AgentWall as follows:

Agent generates a signed agent+jwt for a specific capability.
Request enters the SDK Middleware or Gateway Proxy.
Identity is resolved (Agent, Host, Project).
Replay protection is checked via Redis (JTI tracking).
Policies are evaluated based on subject/resource selectors.
Budget is assessed against usage quotas (minute/hour/day).
Risk is scored using heuristic signals.
A Decision is produced (allow, deny, pending, rate_limit).
If allowed → forwarded to the upstream service.
Result is returned to the agent and logged to the Control Plane.

6. Decision Engine: Internal Pipeline

The Decision Engine processes every call through a deterministic pipeline to ensure consistent enforcement at the edge.

7. Identity Model: Sovereign Authenticity

AgentWall moves away from shared secrets in favor of sovereign, keypair-based identities.

Host Identity: Represents the environment (server/user device) where agents are spawned.
Agent Identity: A per-session identity with its own Ed25519 keypair.
Typed JWTs:
- host+jwt: For administrative registration.
- agent+jwt: For operational execution (60s default TTL).

8. Policy System: Capability-Based Governance

AgentWall abstracts API endpoints into Capabilities. Access is determined by Priority-Based Matching.

Priority Hierarchy: Policies are sorted by a numeric priority (lower is higher precedence).
Selectors: Use glob-style matching for subjects (agent:*) and resources (capability:user:*).
Effects: Policies can allow, deny, or monitor (audit only).

9. Budget & Quota Engine

Prevent agent runaway by enforcing economic and frequency bounds globally.

Cost-Weighting: Assign "billing" values to specific API calls.
Time Windows: Rolling counters for minute, hour, and day.
Global Sync: Redis-backed counters ensure budgets are enforced across multiple service instances.

10. Approval System: Human-in-the-Loop

For high-sensitivity actions, AgentWall supports an asynchronous "Pending" state.

Payload Hashing: The request payload is hashed and locked during the approval phase.
Verification: Upon approval, the retry is matched against the original hash to prevent "bait-and-switch" attacks by the agent.

11. Replay Protection & Security

JTI Tracking: Mandatory unique JWT IDs checked against a sliding 90s window in Redis.
SSRF Mitigation: Aggressive IP filtering for all server-side fetches (JWKS/Discovery).
Revocation Cascades: Revoking a Host automatically invalidates all ephemeral Agents under it.

12. Risk Engine: Heuristic Intelligence

Beyond static policies, the Risk Engine evaluates behavioral signals:

Agent Age: New agents are treated with higher "gravity."
Burst Rate: Sudden spikes in activity trigger automatic approval requirements.
Sensitivity: Certain capability patterns (e.g., transfer:*) increase the risk score.

13. Data Plane: Gateway & SDK

Gateway Mode: A Hono-based reverse proxy for providing zero-trust protection to legacy services.
SDK Node: Middleware for Hono/Express that provides native integration with sub-millisecond overhead.

14. Event & Observability System

AgentWall maintains a high-fidelity decision ledger:

Full Context: Every log includes matched policy, risk score, and budget state.
Auditability: Cryptographically verifiable signatures prove which specific agent identity intended which specific action.

15. Operational Excellence

Performance: Optimized for edge performance with Upstash Redis.
Developer Experience: CLI-first approach (agentwall init, protect, dev).
Explainable Decisions: Every block/requirement includes a structured reason and self-correction hint for the agent.

16. Failure Modes Prevented

Recursive Loop Exhaustion: Budget engine stops runaway agents before significant cost accumulation.
Prompt-Injection Escalation: Risk engine flags unintended capability requests.
Credential Leakage: Keypair-based identity ensures compromised agents cannot be used to forge new host identities.

17. Tradeoffs & Limitations

Complexity: Keypair management is more intensive than simple API keys.
Latency: Hot-path adds ~5-15ms overhead (mostly network round-trip to Redis).
Stateful Nature: Requires a persistent control plane for governance.

18. Roadmap v1.X

Global Reputation: Cross-host behavior analysis.
Policy Templates: Pre-built governance for major LLMs and MCP providers.
Mobile SDKs: Extending agent governance to edge devices.

19. Summary

AgentWall v1.0 establishes the foundation for a bounded agentic future. By decoupling identity from static permissions and enforcing execution control at runtime, we enable agents to act with full autonomy—within the walls we define for them.