# What is OCP?

> An open file format for the record of an agent orchestration run.

The Orchestration Context Protocol (OCP) is an open JSON format for recording what happened in an agent orchestration run: which agents ran, in what order, with which harness, model and reasoning effort, what each attempt cost, and whether the result was accepted and how that is known.

One run is one document. A tool that runs agents writes it; a tool that compares, prices or learns from runs reads it.

## Why it exists

Agent tools record their runs in their own shapes: transcripts, SQLite tables, OpenTelemetry spans, JSON logs. To compare two workflows, to price a run, or to learn which setup works for which task, you need three facts that most of those records do not hold together:

1. **Which attempt spent which tokens.** A run is many attempts across several agents and retries. Cost per run hides which part was worth it.
2. **Why each attempt happened.** A retry sent back by a review is different from a retry after a crash. OCP records the cause of every attempt.
3. **Whether the result was accepted, and how that is known.** "The agent said it was done" and "the tests passed" are different evidence. OCP records the evidence tier of every outcome.

OCP fixes the shape once. A tool implements one writer, and every reader can use its runs.

## What a document looks like

```json
{
  "ocp": "0.3",
  "producer": { "name": "my-orchestrator", "capabilities": { "cost_tokens": true } },
  "privacy": { "profile": "metadata_only" },
  "run": { "id": "run_01" },
  "nodes": [{ "id": "implement", "kind": "impl" }],
  "attempts": [{
    "id": "implement.a1", "node": "implement", "status": "done",
    "harness": "claude-code", "model": { "raw": "claude-opus-5-5" }, "effort": "high",
    "cost": { "input_tokens": 12000, "cached_input_tokens": 410000, "output_tokens": 18500, "basis": "measured" },
    "outcome": { "result": "done", "evidence": "verified", "receipt": "tests pass 42/42" }
  }]
}
```

Five fields are required: `ocp`, `producer`, `privacy`, `run` and `nodes`. Everything else is optional, and typed when present, so a tool can start with what it knows and add more later.

## Design choices

### A small required core

A tool that only knows "these steps ran with these models and these tokens" can write valid OCP on day one. Edges, artifacts, events and the observation fields come when the tool can fill them.

### Cost per attempt, per token stream

Uncached input, cached input, cache writes and output tokens are kept apart, because they are priced very differently, and the reasoning share of output can be given too. Each cost says whether it was measured for that attempt or allocated from a coarser total.

### Evidence on every inference

Every edge, signal and inferred label carries an evidence tier: verified by a check, reported, or inferred by a rule. An outcome may say how it is known too, and one that does not counts as merely asserted, the weakest tier. See [Evidence](https://orchestrationcontextprotocol.io/docs/learn/evidence).

### Private by default

Every document declares a privacy profile. Under `metadata_only` it holds structure, models, tokens and verdicts, and no prompt, completion or transcript text. See [Privacy](https://orchestrationcontextprotocol.io/docs/learn/privacy).

### Model and effort kept apart

The model is an object that keeps the tool's own label (`raw`) next to a canonical id. Reasoning effort is its own field: a producer does not fold it into the model label, though it keeps a label that already includes it as written.

### Configurations with a content-derived id

From 0.3 a run can record the workflow and settings that ran it. Its id is a hash of the declared workflow and baseline settings, so two tools that record the same ones compute the same id. Per-attempt overrides are not part of the id. See [Configuration](https://orchestrationcontextprotocol.io/specification/0.3/configuration).

## What OCP is not

- **Not a way to run agents.** OCP never starts, schedules or coordinates anything. It is the record your orchestrator writes.
- **Not a live telemetry stream.** OpenTelemetry carries spans as they happen. OCP is the record of a run as a whole, and can be built from OpenTelemetry data; see [Implementations](https://orchestrationcontextprotocol.io/docs/implementations).
- **Not a transcript format.** Under `metadata_only` a document holds no prompt, completion or transcript text, only ids, numbers, timestamps and short labels. Under `full`, text may appear in extensions, never in core fields.

## Next

- [Quickstart](https://orchestrationcontextprotocol.io/docs/getting-started/quickstart): Write a document and validate it in five minutes.
- [Specification](https://orchestrationcontextprotocol.io/specification/latest): The normative text, field by field.