# Orchestration Context Protocol

> An open JSON format for agent runs: what ran, what it cost, and whether the result was accepted.

OCP is an open file format for agent orchestration runs. One JSON document records one run: the work graph, every attempt with its harness, model, reasoning effort and token cost, and each outcome with the evidence behind it. Tools that run agents write it. Tools that price, compare or learn from runs read it.

- [Read the specification](https://orchestrationcontextprotocol.io/specification/latest): Version 0.3, its JSON Schema, and the numbered rules a checker enforces.
- [Quickstart](https://orchestrationcontextprotocol.io/docs/getting-started/quickstart): Write a first document and validate it.
- [Examples](https://orchestrationcontextprotocol.io/examples): One run per workflow shape, and a pass and a fail file for every rule.

## This is an OCP document

A review sent the first attempt back, and the second attempt passed the tests. The values are made up; the checker output is real.

```json run.ocp.json lines
{
  "ocp": "0.3",
  "producer": {
    "name": "my-orchestrator", "version": "1.2.0",
    "capabilities": { "task": true, "edges_dep": true, "cost_tokens": true, "outcome_evidence": true }
  },
  "privacy": { "profile": "metadata_only" },
  "run": {
    "id": "run_7f3a",
    "started_at": "2026-09-23T10:00:00-07:00",
    "task": { "id": "tsk_42", "type": "bug_fix", "repo": "acme/api" }
  },
  "nodes": [
    { "id": "implement", "kind": "impl" },
    { "id": "review", "kind": "review" }
  ],
  "edges": [
    { "from": "implement", "to": "review", "kind": "dep", "tier": "verified" }
  ],
  "attempts": [
    {
      "id": "implement.a1", "node": "implement", "n": 1,
      "harness": "claude-code", "model": { "raw": "claude-opus-5-5" }, "effort": "high",
      "cause": { "type": "initial" },
      "status": "rejected",
      "outcome": { "result": "rejected", "evidence": "reported", "via": "review" },
      "cost": { "input_tokens": 9000, "cached_input_tokens": 210000, "output_tokens": 12000, "requests": 18, "basis": "measured" }
    },
    {
      "id": "review.a1", "node": "review", "n": 1,
      "harness": "codex", "model": { "raw": "gpt-5.6-sol" }, "effort": "high",
      "cause": { "type": "initial" },
      "status": "done",
      "outcome": { "result": "done", "evidence": "reported" },
      "cost": { "input_tokens": 4000, "cached_input_tokens": 60000, "output_tokens": 2500, "requests": 6, "basis": "measured" }
    },
    {
      "id": "implement.a2", "node": "implement", "n": 2,
      "harness": "claude-code", "model": { "raw": "claude-opus-5-5" }, "effort": "high",
      "cause": { "type": "sent_back", "ref": "review.a1", "reason": "missing error handling" },
      "status": "done",
      "outcome": { "result": "done", "evidence": "verified", "receipt": "tests pass 42/42" },
      "cost": { "input_tokens": 5000, "cached_input_tokens": 150000, "output_tokens": 7000, "requests": 11, "basis": "measured" }
    }
  ]
}
```

**What it records**

- Five parts are required: `ocp`, `producer`, `privacy`, `run` and `nodes`. Everything else is optional and typed.
- Two units of work, `implement` and `review`, joined by a `dep` edge whose evidence tier says how the edge is known.
- Three attempts. A retry is a new attempt whose `cause` points back at what triggered it, here the review.
- Each attempt names its harness, its model as the tool knew it, and its reasoning effort as a separate field.
- Cost is per attempt, with cached input kept apart from uncached input because they are priced an order of magnitude apart. `basis` says the counts were measured, not apportioned.
- Each outcome says how it is known: the rejection was `reported` by the review, the acceptance `verified` by the tests.
- `metadata_only`: no prompt, completion or transcript text anywhere in the file.

```text Terminal
$ loopmath ocp validate run.ocp.json
PASS  run.ocp.json  (ocp 0.3; 0 errors, 0 warnings)
```

## Why a format for runs

Every agent tool logs runs in its own shape. Comparing two workflows, pricing a run or learning which setup works for which task means a parser per tool, and most logs miss the three facts that matter: which attempt spent which tokens, why a retry happened, and whether the result was accepted. OCP fixes that shape once, so a tool implements one writer and every reader can use its runs.

- **Cost per attempt**: Tokens split into uncached input, cached input, cache writes and output (with its reasoning share), summed per attempt and marked as measured or allocated. Dollars are optional and carry the price table they came from.
- **Acceptance with evidence**: Every edge and every inferred label carries an evidence tier: verified by a check, inferred by a heuristic, or reported. An outcome may say how it is known too, down to merely asserted, which is how one without evidence counts. A tier is never upgraded without new evidence.
- **Private by default**: Every document declares a privacy profile. Under `metadata_only` it keeps structure, models, tokens and verdicts, and no prompt, completion or transcript text.

## What a document holds

| Part | What it records |
|---|---|
| [Run](https://orchestrationcontextprotocol.io/specification/0.3/run-graph#run) | The run's id and times; from 0.3 also the task, the configuration that ran it, its signals and the acceptance rule. |
| [Nodes and edges](https://orchestrationcontextprotocol.io/specification/0.3/run-graph) | The work graph: units of work, and typed edges between them (`dep`, `fan_in`, `spawn`, `launch`, `artifact`). |
| [Attempts](https://orchestrationcontextprotocol.io/specification/0.3/attempts) | Each try at a node: harness, model, effort, cause, status, outcome and [cost](https://orchestrationcontextprotocol.io/specification/0.3/cost). |
| [Artifacts](https://orchestrationcontextprotocol.io/specification/0.3/artifacts) | Files one attempt wrote and others read, by path, never by content. |
| [Events](https://orchestrationcontextprotocol.io/specification/0.3/events) | An optional, append-only log of what happened when. |
| [Observation](https://orchestrationcontextprotocol.io/specification/0.3/task) | What a learner needs to compare runs: the task, the [configuration](https://orchestrationcontextprotocol.io/specification/0.3/configuration) with a content-derived id, [signals](https://orchestrationcontextprotocol.io/specification/0.3/signals), [slates](https://orchestrationcontextprotocol.io/specification/0.3/slates) of runs on one task, and a [receipt](https://orchestrationcontextprotocol.io/specification/0.3/receipt) of predicted against actual. |

## Who writes and reads OCP

- [loopmath, the reference implementation](https://loopmath.ai): Stores every run it records as an OCP 0.3 document, reads them to predict success and cost for the next task, and validates and migrates any OCP file. Open source, MIT.
- [Your tool](https://orchestrationcontextprotocol.io/docs/implementations): How the records of common agent tools and frameworks map onto OCP 0.3, what each can fill, and where an exporter hooks in.

## Stable by design

A reader accepts 0.1, 0.2 and 0.3 documents and ignores fields it does not know, at every level. 0.3 is a strict superset of 0.2: every field 0.3 adds is optional. 0.2 is not a superset of 0.1, because 0.2 requires `tier` on every edge, so a 0.1 document needs `loopmath ocp migrate`, which writes the 0.3 form. A field is removed only after a deprecation notice that names its replacement and stays in the specification for at least two minor versions. See [Versioning](https://orchestrationcontextprotocol.io/specification/0.3/versioning).

> **Note:** OCP is open source under the MIT license and maintained in the open by the loopmath project. Anyone can propose a change; see [Governance](https://orchestrationcontextprotocol.io/community/governance) and [Proposals](https://orchestrationcontextprotocol.io/community/proposals).