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

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 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.
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.
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.
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.
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.
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.

​
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.
  • 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

Write a document and validate it in five minutes.

Specification

The normative text, field by field.

Privacy