Skip to main content
An agent is a named record, not a process XORCISE launches. XORCISE never starts your agent, never dials it, and never inspects it — you register a handle plus some optional metadata, and you connect your own agent to each run yourself.

​
What you’ll learn

  • Which fields an agent record holds, and which of them XORCISE actually reads.
  • What the harness field selects, and which three harnesses ship.
  • What updating, renaming, and deleting an agent do to the runs already attached to it.

​
What an agent record holds

Only the name is required. Everything else refines how the agent is recorded, or how its telemetry is handled once it starts working. XORCISE sets three more fields itself: an internal id that survives renames, a version that starts at 1, and the time the agent was registered.
The OTel endpoint is the field that misleads people. XORCISE keeps the value you type and never consults it — not at run creation, not by the receiver, and not by any adapter. The endpoint your agent must genuinely export to is computed per run and served by that run’s launch profile, because the correct address depends on which collector the run uses and on whether your agent runs on this host or inside a container.

​
Choosing a harness

A harness is the tool that drives your model and does the work — OpenHands, the Claude Code CLI, the Codex CLI, or something you wrote yourself. The harness you record is not cosmetic and it does not only affect presentation. That single value selects three things at once:
  • The replay adapter — the code that turns your harness’s OpenTelemetry into the timeline, the terrain map, and the trace feed. A harness-specific adapter recovers real tool input and output; the generic one recovers span names and a best guess at a body.
  • The telemetry provider — which environment variables the run’s launch profile hands you, and whether the run id travels as an OpenTelemetry resource attribute or falls back to a marker in the connect prompt.
  • The launch provider — the ready-made command on the live run page that starts the harness with this run’s prompt and telemetry already wired in.
Three harnesses ship, plus a generic floor that catches everything else. Pick one of the three when it matches what you actually run. Leave the field blank when your agent is something else, or when it emits no telemetry at all — the generic adapter still produces a usable timeline from ordinary spans, and a blank harness is a supported configuration, not a broken one. Those four are the complete list. The CLI prints friendly labels for a handful of other slugs, so an agent registered with --kind gemini shows as Gemini CLI in xorcise agent list. Nothing is behind those labels — no adapter, no telemetry provider, no launch command — and such an agent replays through generic exactly as a blank one does. Do not read the label as support.
Holding the harness still is what makes several agents comparable. The experimental playbook benchmark pins every contestant to openhands for exactly that reason: with the scaffold fixed, the difference between two results is the model.

​
Running without telemetry

An agent that emits nothing still runs and still scores. Deterministic checks read the artifacts your agent submitted and the facts XORCISE observed about the run itself, so they are untouched. The judge still runs, on a prompt that says plainly that no trace exists, and any criterion it cannot evidence comes back as unknown and is dropped from the average rather than scored zero. What you lose is the replay — an empty timeline, terrain map, and trace feed — not the grade. How grading works has the arithmetic.

​
Agent versions and history

Every change to an agent bumps its version, and every result records the version the agent was on when that run was created. A score therefore always names the exact declaration that produced it, which is what makes a series of runs comparable over time. Renaming is safe. The record keeps its internal id, so the runs, results, and version history all stay attached to the new name.
The Agents page listing registered agents with their harness and run counts

The Agents page. Each row is a record, not a process — the harness column is what decides how that agent's telemetry is replayed.

​
Register an agent

Both interfaces create the same record, at version 1, immediately selectable when you create a run.
Only --name is required. --kind, --model, --endpoint, and --otel are all optional, and every flag is listed in the CLI reference.
The CLI confirms the registration and names the next step:
The web UI preselects no harness. If you accept the form as it stands, you get a valid agent that replays through generic.

​
Manage agents

List what is registered, change a declaration, review a track record, or remove an agent entirely.
update changes only the fields you pass and bumps the version; passing no field at all is refused rather than silently versioning the record.
Deleting an agent deletes its runs and its results with it. They do not outlive the agent, and there is no undo — xorcise agent rm and Delete agent both cascade. Export anything you need first with xorcise agent history scout --json.

​
Next steps

Missions

The other half of every run — what a mission contains, and where missions come from.