Agent Execution Plane

agent-execution-plane is a durable execution layer for long-running AI agent tasks. An AgentDriver determines the next action while the execution plane owns persistence, tool execution, retries, leases, approvals, recovery, and run history.

Agent logic stays separate from execution semantics, so workers can fail, restart, and resume without rebuilding orchestration logic inside the agent itself.

Core capabilities

• Durable run and step state backed by SQLite
• Worker leases with expired-lease recovery
• Stable idempotency keys across tool-call retries
• Retryable and permanent failure classification with bounded exponential backoff
• Human approval gates enforced before protected tool execution
• Step budgets, cancellation, and terminal-state enforcement
• Append-only run events for traceability and debugging
• FastAPI control plane and independent worker CLI

Quick start

Requires Python 3.12+ and uv.

uv sync
uv run aep demo

Run the API and worker in separate terminals:

AEP_DB=.aep/state.db uv run aep serve

AEP_DB=.aep/state.db uv run aep worker

Check the control plane:

curl http://127.0.0.1:8000/health

Create a run:

curl -s http://127.0.0.1:8000/runs \
  -H 'content-type: application/json' \
  -d '{
    "goal": "calculate a value",
    "input": {
      "steps": [
        {"tool": "math.add", "arguments": {"a": 20, "b": 22}}
      ]
    }
  }'

Execution lifecycle

queued -> running -> succeeded
             |  \
             |   -> queued (retry / recovered lease)
             -> waiting_approval -> queued
             -> failed
             -> cancelled

The included SequenceDriver keeps the demo deterministic. Real agents integrate by implementing the small AgentDriver protocol in agent.py; execution semantics remain unchanged.

Verify

uv run pytest

The test suite covers recovered lease, approval gates, stable retry idempotency, step budgets, cancellation, and the HTTP API.

License

MIT — see LICENSE.