agent-approval-interchange

Agent Approval Interchange Specification (AAIS)

A transport-neutral contract for asking a human to authorize an exact agent action.

Specification 1.0 release candidate · support libraries 0.1.0 · Released · Python library 0.2.0 released

Specification · Security · Conformance · Integration guide · WebMCP mapping

AAIS lets a harness pause any chat, bot, subagent, or graph node and hand a portable approval request to a CLI, web UI, desktop app, policy service, or other trusted decision surface. The response is cryptographically bound to the exact action shown to the user, is idempotent, expires predictably, and cannot grant a broader scope than the harness offered.

{
  "aais": "1.0",
  "type": "approval.requested",
  "id": "evt_01JQ8QH80E4M7KJ6J7J7Y2RKSC",
  "occurred_at": "2026-08-30T18:00:00Z",
  "sequence": 41,
  "request": {
    "id": "apr_01JQ8QH80E4M7KJ6J7J7Y2RKSC",
    "created_at": "2026-08-30T18:00:00Z",
    "expires_at": "2026-08-30T18:10:00Z",
    "status": "pending",
    "origin": {"harness": "example", "session_id": "s-1", "run_id": "r-7"},
    "action": {
      "kind": "tool.call",
      "name": "shell.exec",
      "summary": "Run the JavaScript syntax check",
      "arguments": {"command": "node --check script.js"}
    },
    "action_digest": "sha256:...",
    "risk": {"level": "medium", "reasons": ["executes a local process"]},
    "choices": [
      {"decision": "approve", "scope": "once", "label": "Allow once"},
      {"decision": "approve", "scope": "session", "label": "Allow for this session",
       "scope_constraints": {"action_name": "shell.exec"}},
      {"decision": "deny", "scope": "once", "label": "Deny"}
    ]
  }
}

Scope

AAIS standardizes the authority-bearing boundary only:

• exact-action requests, human-readable presentation, risk, and provenance;
• explicit approve, deny, and cancel decisions with bounded scopes;
• action digests, expiry, idempotency, stale-decision rejection, and receipts;
• durable snapshots and ordered events for reconnecting clients;
• adapter mappings for AG-UI interrupts, MCP hosts, HTTP/SSE, WebSocket, and stdio.

It does not define chat messages, model reasoning, tool discovery, agent profiles, workflow graphs, authentication, or a network transport. Those remain the responsibility of AG-UI, MCP, OAP, AGS, the host application, or another runtime protocol.

Support libraries

The repository contains release-candidate libraries with a shared API and conformance corpus for Python, TypeScript, Go, Rust, and Java. Each library can:

• validate AAIS envelopes;
• compute RFC 8785 / SHA-256 action digests;
• create approval requests and decisions;
• maintain a fail-closed, replay-safe pending-approval store;
• emit and restore durable snapshots.

The Python library adds aais.store.FileApprovalStore in 0.2.0. It is a stdlib-only approval authority that several processes can share through one JSON file. It locks whole transactions across processes, writes atomically with fsync, quarantines corrupt state instead of reading it as empty, compacts resolved history with an explicit replay-gap signal, and tracks owners by PID, start time, and host so that PID reuse cannot keep a stopped owner alive. Storage is pluggable: ApprovalAuthority accepts any backend that implements the aais.backends protocols, and aais.testing provides a conformance kit for third-party backends. See the Python durable file store guide.

Published packages:

• PyPI
• npm
• Go module
• crates.io
• Maven Central

See release preparation for coordinates and verification.

Repository layout

Design principles

1. The harness remains the authority. A UI conveys a decision; the harness revalidates it against current policy and current action state.
2. Approval is exact by default. Every approval carries the digest of the canonical action reviewed by the user.
3. Scopes are offered, never invented. A client may select only a choice present in the request.
4. Reconnect is normal. Pending approvals are durable state, not a terminal prompt waiting on stdin.
5. No hidden reasoning is required. AAIS carries concise activity, provenance, and risk explanations—not private chain-of-thought.

License

Apache License 2.0. See LICENSE.