OpenWOP openwop.dev

Build with AI

OpenWOP for AI agents

Coding agents and AI assistants can read the OpenWOP spec as plain markdown, drive any host through the CLI or plain HTTP, and follow the skills below to start runs, handle approvals and replay runs safely. Approvals stay with people: an agent prepares and reports, and a person decides.

Updated

Give your agent the docs

  • /llms.txt is a short summary and map of the site, in the llms.txt format.
  • /llms-full.txt is the v2 specification, guides and comparisons in one markdown file. Paste it, or point the agent at it.
  • Every page has a markdown copy at its URL with .md appended (index.html.md for a URL ending in /). For example, runs.html.md.
  • Machine-readable contracts: the REST API (OpenAPI) and event stream (AsyncAPI), and JSON schemas at their canonical $id.

Let your agent act on a host

An agent talks to a host over REST and Server-Sent Events, or through the CLI:

npm install -g @openwop/cli
export OPENWOP_BASE_URL=https://app.openwop.dev/api
openwop capabilities      # what the host advertises
openwop doctor            # connectivity and advertised-capability check

Every v2 request sends OpenWOP-Version: 2. Calls other than discovery need an API key in the Authorization header; see the CLI for keys and scopes. Give an agent the narrowest key that does the job: a read-only key cannot start a run.

Skills

Each skill is written for an agent to follow. Copy the ones you need into your agent's instructions, or point it at this page's markdown copy.

Skill: discover a host before acting

Use when you are about to call an OpenWOP host you have not inspected in this session.

  1. GET /.well-known/openwop (no credentials). Read protocolVersions, preferredVersion and the advertised capabilities.
  2. If the host does not list 2.0, stop and report: v2 calls will fail.
  3. Before using an optional feature (replay, approvals routing, triggers, extensions), confirm the host advertises it. If it does not, tell the user instead of trying the call.

Never guess a capability from a host's name or from another host. Each host advertises its own.

Skill: start a run and stream its events

Use when the user asks to run a registered workflow.

  1. Discover the host (skill above).
  2. POST /runs with {"workflowId": "…", "inputs": {…}}, the OpenWOP-Version: 2 header and an Idempotency-Key you generate once. A retry with the same key never starts a second run.
  3. Read runId from the response, then stream GET /runs/{runId}/events (Server-Sent Events) or poll GET /runs/{runId}/events/poll.
  4. Report progress from the events (run.started, node.started, agent.decided, interrupt.requested, run.completed, run.failed), not from guesses.
  5. Done when a terminal event arrives. Report the outcome and the runId.

Never put secret values in inputs. Hosts reference credentials by name (bring your own key); the values stay on the host.

Skill: handle a human approval

Use when a run emits interrupt.requested with an approval kind.

  1. Show the person what is being asked: the payload's question, context and the allowed actions (a subset of accept, reject, refine, edit-accept, ask).
  2. Wait for the person's decision. Do not choose an action yourself unless the person has explicitly told you to, for this run.
  3. Resolve with POST /runs/{runId}/interrupts/{nodeId} (or POST /interrupts/{token} when you were given a token), body {"resumeValue": {…}} carrying the chosen action, its required field (refineFeedback for refine, editedArtifactData for edit-accept) and decidedAt. Send an Idempotency-Key.
  4. A 409 interrupt_already_resolved means someone else decided first, or the run ended. Read the run's events and report; do not retry.
  5. Done when the stream shows interrupt.resolved and then run.resumed.

Skill: fork or replay a run

Use when the user wants to see a past run play out again, or try a different path from an earlier step.

  1. Confirm the host advertises replay and which modes it supports (replay, branch).
  2. POST /runs/{runId}:fork with {"mode": "replay" | "branch", "fromSeq": n}. Events before fromSeq are fixed history; events from fromSeq on run again.
  3. In replay mode the host MUST suppress side effects that were already performed, so a replay never pays an invoice twice. In branch mode the new run is independent and may act for real: confirm with the person before starting a branch that could take external actions.
  4. 422 fork_point_invalid or 400 means fromSeq is out of range. Read the source run's events to pick a valid step.
  5. Done when the fork's own run completes. Report both runIds.

Skill: check a host with the conformance suite

Use when the user is building or evaluating a host and asks whether it complies.

  1. Install the suite and its contract package at the same version, as the quickstart shows.
  2. Run npx openwop-conformance --base-url "$OPENWOP_BASE_URL" --target-major 2.
  3. Report the counts as the suite prints them: pass, fail, blocked, inapplicable and skipped. inapplicable means the host does not advertise that optional surface; it is not a failure.
  4. Never describe a host as conformant to a profile unless the bundle shows every floor requirement of that profile witnessed with nothing blocked. See conformance.

Rules for any agent working with OpenWOP

  • Inspect before you change: discovery and reads first, then writes.
  • Send an Idempotency-Key on every mutating call.
  • Leave approvals to people unless told otherwise, for that run.
  • Never send, log or echo secret values; refer to credentials by name.
  • Report what the event log says happened. Route on error codes, never on error messages (errors).
  • Prefer replay to branch when the goal is to look, not to act.

When OpenWOP is not the right tool

If you are building a single agent application, a framework such as LangGraph or CrewAI is less overhead. For production durable execution today, Temporal is more mature. For visual automation with many integrations, n8n fits better. OpenWOP is new, has one steward, and no independent organisation has implemented a host yet. See the comparisons.