Use the runtime API

For: application developers.

Call oz0.runtime.v1.RuntimeService on the edge's HTTPS port, 7443, to run agents and inspect their jobs. The API supports Connect with JSON or protobuf, gRPC and gRPC-Web. The CLI uses this same API, and an application can use an HTTP client, gRPC library or client SDK.

Listing waiting approvals

The approvals list shows what waits for a person's decision across the tenant's running jobs, oldest first. job narrows it to one job; adding tree includes jobs it delegated to.

Across tenants, every_tenant or tenants (at most 20 named tenants) lists approvals in each tenant the caller may read. Each approval names its tenant. The answer reports tenants_read, tenants_refused where the caller lacks the required role, and tenants_unread for tenants beyond the first 20 by name or served by another region. One unread or refused tenant does not fail the whole request.

Listing startable agents and flows

The startable catalog lists agents and flows that StartJob would accept from the caller now. It applies start permissions or agent grants, key scopes, retirement and kill switches.

Entries say whether they take part in conversations and whose conversations they may continue. conversations_only narrows new-chat choices; continues narrows hand-over targets. A reader gets an empty list with the reason. The console's chat picker uses this catalog. See the chat drawer.

MCP, A2A and AG-UI

The same agents, for the same callers, are also an MCP server at POST /mcp/<tenant>, with tasks for long jobs, A2A agents with signed Agent Cards at /a2a/<tenant>/<agent>, and an AG-UI route at POST /v1/agui/agents/<agent> for apps built on an AG-UI client, where approvals and questions are the protocol's interrupts. All of them start jobs through StartJob, so its rules hold there too.

Typed HTTP routes and the OpenAPI document

Next to the Connect API, the edge has plain HTTP routes, for the same callers:

The streams, their tickets and the tenant's allowed origins for pages elsewhere are on Live feeds. An API key in a URL is refused on them.

curl --cacert ca.crt -H "Authorization: Bearer $OZ0_API_KEY" -H 'Content-Type: application/json' \
  -d '{"repo": "acme/api", "pr": 42}' 'https://edge.example.com:7443/v1/agents/acme-reviewer/jobs?tenant=acme'
curl --cacert ca.crt -H "Authorization: Bearer $OZ0_API_KEY" 'https://edge.example.com:7443/v1/openapi.json?tenant=acme' > oz0.json

The document has one operation per agent, run_<name>. Its request body is the agent's input schema, and its response is the job, with output typed by the agent's output schema. Generate a client from it with any OpenAPI generator. It changes when a plugin changes an agent or a schema, and its ETag says when. A plugin installed before Orchestrator Zero put schemas in plugins' bundles needs plugin update before its agents' schemas appear.

With thousands of agents the whole document is megabytes (17.6 MB for 10,000): ?plugin=<name>, and oz0 client generate --plugin <name>, describe one plugin's agents and flows, under an ETag that names the plugin.

Start a job with curl

curl --cacert ca.crt -H "Authorization: Bearer $OZ0_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"agent": "acme-reviewer", "input": {"repo": "acme/api", "pr": 42}, "timeout": "900s", "tenant": "acme"}' \
  https://edge.example.com:7443/oz0.runtime.v1.RuntimeService/StartJob

{ "job": { "id": "job-bb270cf1-...", "agent": "acme-reviewer", "status": "JOB_STATUS_RUNNING", "startedAt": "..." } }

Then poll it:

curl --cacert ca.crt -H "Authorization: Bearer $OZ0_API_KEY" \
  -H 'Content-Type: application/json' -d '{"id": "job-bb270cf1-...", "tenant": "acme"}' \
  https://edge.example.com:7443/oz0.runtime.v1.RuntimeService/GetJob

Requests and responses

StartJob takes:

A Job has id, agent, status, startedAt, closedAt, output (the answer, text or JSON), error, children (direct child job IDs), approvals (what it waits for, while it runs), flow (true for a flow's job), recording (for a job started with recordedCalls: how many it had, how many were used, and what differed) and cost. cost holds the totals (usd, calls, inputTokens, outputTokens) and branches: one entry per job in the tree, the job itself first, with its agent, models, nodes, tokens, cached tokens and cost, and translated when its calls went through a translating provider.

StartJob answers with job and retried, which is true when the start was a retry and nothing started again.

Job IDs and retries

A start may reach the edge and be applied even when its answer is lost on the way back, so a client that retries must not start a second job. The job's ID is the start's idempotency key:

• The same start again under an ID, the same agent, input, tags, team, budget, timeout, data subjects, conversation and other options, from the same caller, answers with the job of that ID as it is, running or ended, with retried: true. Nothing runs again, nothing is counted against a quota again, and nothing is audited as a start.
• Another start under the ID (another input, agent, option or caller) is refused with already_exists (HTTP 409) and a detail, oz0.runtime.v1.IdConflict, whose reason is oz0_id_conflict, with the job's ID and, when you may read that job, its start time. The refusal comes before anything of the start happens: no quota, budget, turn or file hand-over. A job that ended never runs again under its ID: start a new job under a new ID.
• Without an ID, send an Idempotency-Key header (1 to 128 visible ASCII characters, such as a UUID) instead: the edge derives the job's ID from you and the key, so the same start with the same key is the same job, and the same key with another request is refused as above. oz0 run and the SDKs send one on every start without an ID and retry unavailable with it. A start with recordedCalls takes none: it always gets a new ID.
• An ID the edge gave (a start without an ID or a key) is the job's alone: no start with that id is a retry of it.
• How long: an ID stays taken for as long as its job's history is kept, the tenant's retention. After that it is free again.
• Another caller's job: the caller is part of the request, so a start under someone else's job ID is refused, never joined.

RetryJob and FireRoutine take the Idempotency-Key header the same way: a retry of the call answers with the job or fire the first call started (retried: true), and another request under the key is refused.

The REST start (POST /v1/agents/{agent}/jobs) takes the header too, answers a retry with 200 instead of 201, and its JSON error carries reason, job and started_at for a refused ID.

An AG-UI resume sent again with the same run ID (or Idempotency-Key) answers the decisions its first try made as made, and decides what is left. The admin API's calls take the same header: see the admin API.

The protobuf definition is in proto/oz0/runtime/v1/ in the repository: the service in runtime.proto, its messages in the runtime_*.proto files beside it.

Client SDKs

Typed clients for three languages are built from that file in the same change as the API, and carry the server's version: the Python SDK (oz0-client), the TypeScript SDK (@oz0/client, Node 24) and the Go SDK. Each starts a job and waits for it, watches it, answers its questions and decides its approvals, and reads the catalog and what jobs cost; every other method is there too, typed. For one tenant's agents with their own input and output types, generate wrappers from its OpenAPI document:

oz0 client generate --tenant acme --lang python --out src/oz0agents

--lang is python, ts or go. The command reads the document with the CLI context's operator certificate, or with an API key from OZ0_API_KEY when --url or OZ0_URL names the edge (--ca-file for its CA), or from a saved file with --from. Run again, it leaves a file generated from the same catalog alone, so an app's CI can run it on every build; a file from another version of the generator, or for another tenant or Go package, is written again.

From v1.0 the API only grows: make proto-breaking checks every change against the last release with buf breaking, so an SDK or a client you generated yourself keeps working with newer servers. For another language, generate a client from the protobuf file with buf or protoc.

Related tasks

• Runtime API authentication: Authenticate clients and apps acting for individual people.