Complete documentation for the Agent Workflow Protocol (AWP) v1.0.0.
AWP is a declarative protocol for multi-agent systems. A workflow is described in YAML across seven semantic layers, then executed by a runtime that interprets the YAML — never the other way around. The same workflow file can run on any conforming runtime, be packaged into a .awp.zip, validated statically (rules R1-R32), and graduated through five autonomy levels (A0 prescribed DAG → A4 self-organizing recursive delegation).
The documentation below is grouped by what question it answers:
- Foundations (1-3, 14-15): What is AWP? Why does it exist? How is it structured on disk and over the wire?
- Reference per layer (4-11): Field-by-field description of each YAML section.
- Autonomy & validation (12-13): How safety scales with freedom.
- Runtime & quality (16-20): How the engines actually execute, how quality is measured (evaluation) and repaired (critique), and how iterative optimization works.
- Engines, data, UI (21-24): Concrete pieces — DAG vs. delegation loop, the data importer, Workflow Studio, and OpenClaw integration.
New since 1.0: complexity-scored auto-promotion of workers to sub-managers, A4 sub-run cluster visualization, budget reservation with refund for hard termination guarantees, the B1-B6 robust tool-generation pipeline with auto-repair, and the Experiment paradigm in Workflow Studio (Sessions are now Experiments with Protocol/Memory tabs). These features are documented in architecture.md, orchestration.md, tools.md, and ui.md.
| # | Document | Description |
|---|---|---|
| 1 | overview.md | What AWP is, why it exists, and its design principles |
| 2 | architecture.md | Architecture, design decisions, and framework comparison |
| 3 | layer-model.md | The 7-layer architecture and how layers relate |
| 4 | manifest.md | workflow.awp.yaml field reference |
| 5 | agent.md | agent.awp.yaml field reference |
| 6 | orchestration.md | DAG engine, execution modes, loops, error handling |
| 7 | tools.md | MCP tools, custom tools, tool result format |
| 8 | communication.md | Message bus, channels, messaging patterns |
| 9 | memory.md | 4-tier memory system and state sharing |
| 10 | observability.md | Metrics, tracing, audit trails, health checks |
| 11 | security.md | Circuit breaker, rate limiting, access control |
| 12 | compliance.md | Autonomy levels A0 through A4 |
| 13 | validation.md | Validation rules R1 through R32 |
| 14 | file-structure.md | Required directory layout |
| 15 | packaging.md | .awp.zip format and ClawHub publishing |
| 16 | runtime.md | AWPAgent interface, standalone runtime, WorkflowRunner |
| 17 | skill-system.md | Build skill, adapters, extensions, ClawHub |
| 18 | evaluation.md | Quality scoring: metrics, thresholds, retry policy, artifacts |
| 19 | critique.md | Reflective Critique Loop: defect diagnosis, repair, pattern memory |
| 20 | iterative-optimization.md | Iterative optimization: feedback loop, capability accumulation, stall detection, budgets |
| 21 | ORCHESTRATION_ENGINES.md | DAG vs. Delegation Loop engine comparison |
| 22 | data-importer.md | Data import and Source resolvers |
| 23 | ui.md | Workflow Studio (browser UI) |
| 24 | openclaw_integration.md | OpenClaw integration guide |
AWP has a small vocabulary of concepts that reference each other. Use this as a "where does concept X live?" lookup — every architectural document should be one hop away from its neighbors via this map.
| Concept | Lives in | Authoritative doc | Referenced by |
|---|---|---|---|
| 7 semantic layers (Manifest → Identity → Capabilities → Communication → Memory → Orchestration → Observability) | The stack itself | layer-model.md | Every per-layer doc below; spec/versions/1.0/layers/ |
| Autonomy spectrum (A0 prescribed → A4 self-organizing) | Cross-cutting classification | compliance.md | overview.md, layer-model.md, architecture.md |
| Two engines (DAG, delegation loop) | Layer 5 (Orchestration) | ORCHESTRATION_ENGINES.md | orchestration.md, runtime.md |
| Agent contract (R17) | Layer 1 ↔ Layer 5 boundary | runtime.md, validation.md | agent.md, every delegation-loop concept |
| Cross-cutting mechanisms (critique, evaluation, manager intelligence, dynamic tools) | Plug into existing layers, not new layers | layer-model.md | critique.md, evaluation.md, manager-intelligence.md, runtime-tool-generation.md |
| Concept | Enforced by | Authoritative doc | Related |
|---|---|---|---|
| Budget envelope (max_loops, tokens, workers, wall-time, depth) | Deterministic check in delegation loop engine | orchestration.md, runtime.md | compliance.md, manager-intelligence.md |
| Completion gate chain (L0 → critique → deliverable_presence → placeholder → file → deliverable → structural_integrity → eval) | Runtime between manager COMPLETE and run end | critique.md, runtime.md | validation.md, evaluation.md |
| Validation rules R1-R32 (+R33 deterministic purity, R34 L0 output contract, R35 repair fixpoint, R36 empty-gradient guard) | awp validate + parse-time + runtime gates |
validation.md | Every layer doc; compliance.md, refinement.md |
| Delegation loop (manager ↔ ephemeral workers, PLAN/DELEGATE/COMPLETE) | Delegation-loop engine at A2+ | ORCHESTRATION_ENGINES.md, manager-intelligence.md | critique.md, runtime.md |
| Dynamic tool factory (B1-B6 pipeline + β auto-emergent induction) | Runtime at A3+ | runtime-tool-generation.md, tools.md | runtime.md §Framework-Fixes |
| Outer loop (A5) — SGD over prompt artifacts with TextGrad | awp optimize, never awp run |
outer-loop.md, iterative-optimization.md | refinement.md contrasts y-axis |
| Refinement mode — y-axis iteration over a seed deliverable | awp refine, never inside awp run |
refinement.md | outer-loop.md (θ-axis), critique.md (gradient source) |
If a doc names concept X, you should be able to (a) find X's authoritative doc in one of the tables above, (b) name the layer/contract/gate/engine/rule X belongs to, and (c) reach X's neighbors in one click. If any of those fails, the doc carries a linked-mental-model gap — see CLAUDE.md §2.
If you are new to AWP, start with overview.md to understand the motivation, then read layer-model.md to see how the protocol is structured.
To build a workflow, you need at minimum:
- A manifest (
workflow.awp.yaml) — Layer 0 - One or more agent configs (
agent.awp.yaml) — Layer 1 - An orchestration graph — Layer 5
- Optionally: tools (Layer 2), memory (Layer 4), observability (Layer 6), security (cross-cutting)
For the normative specification with RFC 2119 language, see spec/versions/1.0/ — the validation rules cross-reference spec/versions/1.0/validation-rules.md field-by-field.
For runnable examples, see examples/. For the governance/sync contract that keeps all of this coherent with the code, see CLAUDE.md §2.