Agent Action Protocol (AAP) – MCP got us started, but is insufficient

Defines a standardized schema for agent actions that extends beyond MCP's limitations by supporting stateful action chains, conditional branching, and multi-step workflows. Uses a declarative JSON/YAML schema format that agents can parse to understand action preconditions, postconditions, side effects, and rollback semantics. Validates action payloads against the schema before execution to prevent malformed requests from reaching tools.

Orchestrates sequences of actions where later actions depend on state changes from earlier ones, tracking state mutations across the action chain. Implements a state machine pattern where each action declares what state it reads and writes, allowing the orchestrator to detect conflicts, serialize access, and enable rollback. Supports conditional branching based on action results without requiring the agent to re-plan between steps.

Manages multiple versions of actions simultaneously, enabling agents to use different versions based on their requirements or capabilities. Implements a versioning scheme where actions declare their version and breaking changes, and the orchestrator routes requests to compatible versions. Supports gradual migration from old to new action versions without breaking existing agents.

Instruments action execution with distributed tracing to track request flow across multiple actions and agents, capturing latency, dependencies, and error paths. Implements OpenTelemetry-compatible tracing where each action execution generates spans with metadata (inputs, outputs, duration, status), enabling visualization of action chains and performance analysis. Correlates traces across agents to understand multi-agent workflows.

Provides a testing framework for validating action behavior in isolation and in composition, supporting unit tests, integration tests, and simulation of action sequences. Implements mock actions for testing without external dependencies, and a simulation engine that replays action sequences to verify correctness. Supports property-based testing to verify action invariants.

Streams action results back to the agent and client in real-time rather than waiting for full completion, enabling progressive feedback loops where agents can react to partial results. Implements a streaming protocol that emits intermediate state changes, progress indicators, and error signals as they occur, allowing agents to make early decisions (e.g., cancel a long-running action if intermediate results are unsatisfactory).

Enables agents to discover available actions and their capabilities at runtime through a capability registry, negotiating which actions are available based on agent permissions, resource constraints, and runtime conditions. Implements a service discovery pattern where actions advertise their requirements (e.g., API keys, resource limits, dependencies) and the registry matches agent capabilities to available actions. Supports dynamic capability updates when new tools are registered or permissions change.

Defines declarative error handling strategies in action schemas, specifying how agents should respond to different failure modes (retry with backoff, fallback to alternative action, escalate to human, etc.). Implements a recovery pattern where actions declare their failure modes and the orchestrator automatically applies the appropriate recovery strategy without requiring agent-level error handling logic.

Automatically logs all action executions with full context (who initiated, what action, inputs, outputs, state changes, timestamp) to an immutable audit trail. Implements a logging middleware that captures action lifecycle events (requested, started, completed, failed) and stores them in a format suitable for compliance audits, forensic analysis, and debugging. Supports filtering and querying the audit log by agent, action type, time range, or outcome.

Enforces fine-grained permissions and resource quotas at the action execution layer, preventing agents from executing unauthorized actions or exceeding resource limits. Implements a policy engine that evaluates agent credentials against action requirements before execution, and tracks resource consumption (API calls, compute time, memory) against per-agent quotas. Blocks execution if permissions are insufficient or quotas are exceeded.

Enables defining composite actions (macros) that are sequences of primitive actions with control flow, allowing agents to invoke high-level workflows as single actions. Implements a composition language where macros declare their inputs, outputs, and internal action sequences, and the orchestrator expands macros into primitive actions at execution time. Supports conditional branching, loops, and error handling within macros.

Enables multiple agents to coordinate on shared actions and synchronize their execution, preventing race conditions and ensuring consistent ordering. Implements a coordination protocol where agents can request locks on shared resources, wait for other agents to complete actions, or synchronize on barriers. Supports distributed consensus for coordinated decision-making across agents.

Caches action results based on inputs to avoid re-executing identical actions, implementing a memoization layer that stores results keyed by action type and input hash. Supports cache invalidation strategies (TTL, event-based, manual) and cache warming for frequently-used actions. Enables agents to reuse results from previous executions without re-running expensive operations.