ai-agent-runtime-architecture

# AI Agent Runtime Architecture ## Operating contract ## Inputs | Artefact | Required? | Purpose | |---|---|---| | Task state model, tools, durability, timeout, retry, cancellation, tenant, memory, and budget boundaries | yes | Define safe runtime transitions | ## Outputs - Produce the runtime state machine, persistence contract, failure matrix, operational controls, and test evidence. ## Capability and permission boundaries Read/search are required. Runtime implementation, queue changes, migrations, replay, and cancellation tests require explicit authority and isolated fixtures. ## Degraded mode Fallback without a runnable environment: produce the state machine and unverified test plan; do not claim runtime enforcement. ## Decision rules | Workload | Runtime choice | Failure avoided | |---|---|---| | Short, deterministic, read-only request | Bounded synchronous flow | Unnecessary orchestration | | Long, retryable, or externally waiting | Durable state machine | Lost or duplicated work | | Irreversible or costly step | Approval and checkpoint | Unbounded blast radius | ## Anti-Patterns - Running side effects in an HTTP request. Fix: use a durable worker. - Retrying without idempotency. Fix: derive stable keys from task and step state. - Keeping state only in prompts. Fix: persist every transition before the next step. - Ignoring cancellation during tool calls. Fix: propagate and test cancellation. - Sharing memory or run state across tenants. Fix: enforce tenant-scoped...