OpenAWF 0.1.0 · draft
A standard document for agentic workflows.
OpenAWF describes an agentic workflow as one self-contained file. The file is a finite-state machine of tasks, and it declares every prompt, transition and dependency the workflow needs. Any tool can share, render, version and run it.
The problem
Every harness has its own workflow format.
Each agent harness and SDK defines what a workflow is, how it is stored and how it is shared. A workflow built in one tool stays in that tool. Marketplaces stay bound to the tool that hosts them, and teammates on different tools cannot share the workflows they build.
OpenAWF is one format for all of them. A workflow is written once, sealed once, and exported to each tool through an adapter.
whole
A workflow declares everything it needs.
Tasks, orchestration, models and tool dependencies live in the document. Nothing is left to the environment.
atomic
A task is a reusable unit.
A task is defined once, versioned on its own, and pinned by exact version in any number of workflows.
traceable
Every document has an identity.
A sealed document carries a sha of its content. Output stamped with that sha traces back to the exact prompts that produced it.
Playground
Edit a workflow and watch it render.
The playground runs awf-cli, one tool built on the spec, compiled to WebAssembly. Edit the YAML and the page re-renders as you type. The buttons run awf-cli's commands on files held in memory.
…Files live in memory and reset on reload.The document
A workflow is a state machine of tasks.
The flow begins at start and ends at a task whose transition is null. Each key in orchestration names a task and says where the flow goes next.
A plain transition names the next task. A task that declares outcomes branches: it emits one outcome, and the branch maps each outcome to a task. An edge can carry policy: retries caps the attempts, and session: resume keeps the prior context when the flow loops back.
A task's body is its tool-agnostic prompt. input and output are JSON Schemas for the data it takes and returns.
openawf: 0.1.0 name: review-loop model: claude-sonnet-5 version: 1.0.0 sha: sha256-… # written by seal start: write orchestration: write: review # an edge review: # a branch on outcomes pass: summarize changes: task: write retries: 3 session: resume summarize: null # terminal tasks: review: version: 1.2.3 outcomes: [pass, changes] body: | Read the diff against the request…
Sealing
Sealing gives a document its identity.
A draft is an editable document with no sha. Its tasks can live in separate files and join it through $ref. Sealing inlines every $ref, hashes the result, and writes the hash into the document as sha. A sealed document never changes. A change starts a new draft.
The sha is the identity.
The hash covers every field except sha and version. Two versions with the same content share a sha. A version is a human label; the sha is what a run records.
Anyone can verify it.
A validator recomputes the hash and compares it with sha. One changed character in any prompt is a mismatch, and the document fails to validate.
Sealed documents are whole.
A sealed workflow carries its tasks inline. It depends on no other file, so it can be copied, installed or exported as one unit.
Signatures
A hash proves integrity. A signature proves authorship.
Anyone who can overwrite a file can recompute its hash to match. The sha shows a document has not changed since it was sealed. It does not show who sealed it.
The spec leaves distribution to tools. A tool that distributes documents binds each sealed version to its publisher's key, and a consumer verifies the signature before it trusts the content.
awf-cli distributes through git, so there is no central registry to trust. awf install reads a sealed version from a repository's .awf directory, and a signed commit or tag carries the publisher's key.
# with awf-cli $ awf seal workflow review-loop .awf/_/workflow/review-loop/1.0.0.yaml sealed sha256-4351e4fd57be… $ git commit -S -m "review-loop 1.0.0" $ git push # on another machine $ awf install example.com/team/flows#review-loop@1.0.0
Provenance proposed
Trace every artifact to the version that produced it.
An artifact is external state a task creates or changes through an MCP tool call that is not read-only: a commit, a pull request, a comment, a ticket, a file. A run stamps each artifact with the workflow and task that produced it, their versions, the sha, the source, and the run id.
| Artifact | Stamp placement |
|---|---|
| Git commit | Commit trailers |
| PR, comment, ticket | Footer at the end of the body |
| File | Frontmatter, or a sidecar file |
MCP tools/call | _meta on every call |
Given any artifact, the sha resolves to one sealed document, and that document holds every prompt that ran. The commit on the right reads the document open in the playground. Seal it to see the stamp.
Loading…
The stamp format is a proposal and the field names may change.
spec
OpenAWF 0.1.0
Every field, transition rule and validation check, with the JSON Schema at /schemas/0.1.0/.
tools
Build on the document
A tool is any program that reads, checks, stores or runs OpenAWF documents. Anyone can build one. awf-cli is the first.
adapters
Export to the tools you use
Adapters turn a sealed workflow into the native format of an agent harness or SDK. Claude Code is available today.