Runs & evidence

An agent’s conclusion is only as good as your ability to check it. In the Komodor Agentic Operation Platform (KAOP), every execution is a run that records what it was asked, everything it did, what it produced, and what it cost. This page explains what that trail contains, how to read it, and which properties of it you can actually rely on.

​

The lifecycle of a run

cancelled is kept distinct from failed on purpose: an operator stopping a run and an agent breaking are different facts, and metrics that conflate them mislead. Every run also records the surface that started it — ui, api, webhook, cron, slack, or agent — so you can always tell an alert-driven investigation from a manual one. See How Run works for the full set of starting paths.

​

What a run was asked

A run’s input is one JSON object, however it was supplied. From the console’s run dialog you can provide it two ways:

• Prompt — free text, submitted as {"prompt": "…"}, for agents driven by a natural-language instruction.
• JSON input — an arbitrary JSON object, for agents invoked with a structured payload. JSON mode also takes an optional instruction that rides along as the prompt key.

An agent that advertises an input schema opens in JSON mode with the editor pre-seeded from that schema and the agent’s own sample values, and you can read the advertised schema in place. An agent with no schema opens in prompt mode. Either way, the stored input is the same shape, so a run started from a schedule, an endpoint, or another agent is indistinguishable in structure from one you typed.

​

What a run records

Evidence is streamed to the control plane by the agent’s worker while the run is in progress, in batches. Nothing on this list is reconstructed afterwards — which is why it is still complete for a run that failed halfway.

​

Reading a run

Open a run and you get its status, its input, and a set of tabs. Tabs appear only when there is something in them, so the shape of a run’s page tells you something before you read a word of it.

​

Output has two channels

A run’s output is one JSON object serving two audiences, and knowing which is which stops a lot of confusion:

• Structured output — the top-level machine-readable fields, the substrate that automation reads: findings, counts, verdicts, flags.
• Descriptive output — a single reserved text key holding human-readable markdown. The console, Slack replies, and History render it. It is a projection of the structured data for people, never a replacement for it.

An automation-only agent may emit no text at all, and consumers then fall back to the structured payload. An agent that owes a machine-readable answer can declare its output as a schema, in which case a shape mismatch is corrected by the agent inside the same turn rather than discovered as a parse failure afterwards — and a run that produced no structured answer fails, rather than succeeding with nothing in it.

​

Time breakdown

A finished run shows where its wall-clock time went, by category: Model, MCP tools, Other tools, Overhead, and — only when it is non-zero — Not measured. The last two are the ones worth understanding, because they are different kinds of fact:

• Overhead is the agent’s own real time that no model or tool call covers — prompt assembly, framework glue, serialization, and time spent waiting on a delegated child run. For an orchestrator this is usually mostly the waiting, which is why a large number there is not automatically a problem with your code.
• Not measured is a call that started and never reported its end. It is missing measurement, not idle time — the call may have been cut short when the run ended. It is never folded into another category and never hidden below a threshold, at any magnitude.

The breakdown is computed when you read it, not stored. A run’s span tree is not necessarily complete the instant the run reaches a terminal state, so anything cached would quietly miss late spans.

​

What a run cost

Usage counts tokens in four disjoint classes, so summing across them is honest: total_tokens is their sum, and is derived rather than authoritative. Alongside the counts, a run records its model, provider, and cost, and whether that cost was reported by the worker or estimated. Workspace and per-agent roll-ups build on the same numbers — see Agent spend.

​

When a run fails

A failed run keeps its error alongside every piece of evidence collected before the failure, so the question “how far did it get?” is answerable. Runs that failed because the model provider could not serve the request — billing, credentials, rate limits — carry classified failure metadata, so the page tells you why it failed and who can fix it. That is deliberately distinguished from an agent that ran perfectly well and found a problem.

​

Following a fan-out

Orchestrating agents delegate, and delegation is recorded as parentage rather than inferred:

• One conversation thread — the runs of a multi-turn exchange, oldest first.
• One run’s children — every run that this run delegated to, newest first.

So an orchestrator’s run page lets you walk down into each specialist it called, and each specialist’s run is a first-class run with its own evidence. Where a channel reply came from an agent that delegated, the reply itself names both agents and links both runs — attribution is added by the platform, not written by the agent, so it stays correct even when the answer is not.

​

Following up on a run

Beneath a finished run’s output sits Continue this investigation. From there you can ask a follow-up in KAOP chat, hand the run to a local coding agent, or — when the run saved a session snapshot — pick Re-run the agent to re-execute it with its tools and its earlier context, which creates a new run in the same thread. See Chat & history for what each destination carries.

​

Why the trail is trustworthy

Five properties, each of which is a design decision rather than a side effect:

• It is emitted, not inferred. Everything you read arrived from the agent while it was working.
• Secrets never enter it. A credential is delivered into a run in memory and is never exposed to you or written into its evidence. See Secrets & credential handling.
• Policy decisions are part of the record. An action a guardrail blocked, redacted, or held shows up on the run that attempted it — the absence of an action is evidence too.
• Runs are durable and scoped to one workspace. Every read and write is checked against that boundary, so a run is retrievable later and only by the workspace that owns it.
• Identity is recorded from the request, not the payload. Who started a run, and who approved or answered anything inside it, comes from the authenticated caller. See Audit log.

​

Finding runs

History is the ledger: every run and chat session, newest first, filterable by type, status, and agent, and searchable over run and session ids, a row’s title, and the agent’s name or slug. The GET /api/v1/runs API supports the same narrowing — one agent, one conversation thread, or the children of one run — which is how you walk an orchestrator’s fan-out programmatically.

​

Next steps