# OpenWOP for AI agents > Source: https://openwop.dev/ai-tools/ · OpenWOP, the open-source protocol for multi-agent workflow orchestration. 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. ## Give your agent the docs - **[/llms.txt](https://openwop.dev/llms.txt)** is a short summary and map of the site, in the llms.txt format. - **[/llms-full.txt](https://openwop.dev/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](https://openwop.dev/spec/v2/core/runs.html.md). - **Machine-readable contracts:** the [REST API](https://openwop.dev/api/rest/) (OpenAPI) and [event stream](https://openwop.dev/api/events/) (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: ```bash 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](https://openwop.dev/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](https://openwop.dev/ai-tools/index.html.md). ### 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 `runId`s. ### 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](https://openwop.dev/quickstart/#check-a-host-with-the-conformance-suite) 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](https://openwop.dev/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](https://openwop.dev/spec/v2/core/errors.html)). - 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](https://openwop.dev/comparisons/).