> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Run works

> Every way work reaches an agent, what one execution records, and where to look when you need to know what happened.

Building an agent is only half of it — the other half is work actually arriving and getting done.
This page maps every path by which work reaches an agent in the Komodor Agentic Operation Platform
(KAOP), explains what a run is and what it leaves behind, and points you at the page for each
surface.

## Eight ways work starts

Work arrives from wherever your team already is. Whatever starts it, the result is the same object:
a **run**.

| Path                  | What starts it                                                 | Where it is set up                                                   |
| --------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Manual invocation** | You open an agent and start it with a prompt or a JSON payload | The agent's page in Fleet, or the API                                |
| **Cron trigger**      | A recurring schedule fires                                     | [Triggers & schedules](/manage-your-agents/build/triggers-schedules) |
| **Inbound endpoint**  | An external system posts to a URL you created                  | Integrations → **Endpoints (inbound)**                               |
| **Channel**           | A Slack message matches a routing rule                         | [Channels](/manage-your-agents/run/channels)                         |
| **Chat**              | You send a message in a conversation with a chat-capable agent | [Chat & history](/manage-your-agents/run/chat-history)               |
| **Workflow step**     | A step delivers its task to the agents bound to it             | [Orchestration](/manage-your-agents/run/orchestration)               |
| **Module**            | One of a module's workflows reacts to something in its domain  | [Modules & workflows](/modules-and-workflows/overview)               |
| **Another agent**     | An agent delegates to an agent it is allowed to reach          | [Orchestration](/manage-your-agents/run/orchestration)               |

Every run records the surface that started it, so an alert-driven investigation is never confused
with a manual one:

| Recorded channel | Started by                               |
| ---------------- | ---------------------------------------- |
| `ui`             | A person in the console                  |
| `api`            | A direct API call                        |
| `webhook`        | An inbound endpoint                      |
| `cron`           | A schedule                               |
| `slack`          | A channel routing rule                   |
| `agent`          | Another agent, including a workflow step |

<Note>
  A **trigger** in KAOP is a recurring cron schedule. Inbound webhook URLs are a separate object —
  they live under Integrations → **Endpoints (inbound)** and are covered with the rest of
  [Integrations](/manage-your-agents/build/integrations-overview).
</Note>

## What a run is

A run is one execution of one agent, recorded durably from the moment it is created to the moment
it reaches a terminal state. It carries its own input, its own evidence, its own output, and its own
cost, and it is addressable forever after.

Runs move through a small set of statuses:

| Status      | Meaning                                     |
| ----------- | ------------------------------------------- |
| `queued`    | Created, waiting for a worker to claim it   |
| `claimed`   | A worker has taken it and is starting       |
| `running`   | The agent is working and streaming progress |
| `succeeded` | It finished and produced its output         |
| `failed`    | It stopped with an error                    |
| `cancelled` | Someone stopped it before it finished       |

Work is never pushed at a worker — a worker claims runs from the control plane's queue. That is why
an agent needs only outbound access to KAOP, and why a run that is waiting is honestly reported as
`queued` rather than quietly stalling. See [Architecture](/get-started/architecture).

## What a run leaves behind

Nothing about a run is reconstructed after the fact. The agent streams its evidence back to the
control plane while it works, and that stream is what you read later:

* **Transcript** — the human-readable narration: progress notes, tool calls and their results, data
  the agent pulled, drafts it produced.
* **Trace timeline** — the structured span tree of reasoning, model calls, and tool calls, with the
  time each took.
* **Logs** — timestamped log lines, at the usual levels.
* **Output** — the final result, in two channels: machine-readable fields for automation, plus an
  optional human-readable markdown rendering.
* **Artifacts** — discrete files the run produced, which you can open and download.
* **Usage** — model, token counts by class, and cost.
* **Guardrail decisions** — any action a policy blocked, redacted, or held for approval.

That collection is what makes an agent's conclusion auditable instead of something you take on
trust. [Runs & evidence](/manage-your-agents/run/runs-evidence) is the page on how to read it.

## Where the work is visible

* **History** lists every run and every chat session in one ledger, newest first, filterable by
  type, status, agent, and free-text search.
* **A run's own page** holds its evidence, and the composer beneath a finished run's output lets you
  ask a follow-up, re-run the agent, or hand the run to a local coding agent.
* **Attention** lists everything currently waiting on a person — a held action to approve, a choice
  to make, a workflow run that stopped and needs review.

## Explore Run

<CardGroup cols={2}>
  <Card title="Orchestration" href="/manage-your-agents/run/orchestration" icon="diagram-project">
    Workflows, steps, agent binding, and how an orchestrator coordinates specialists.
  </Card>

  <Card title="Chat & history" href="/manage-your-agents/run/chat-history" icon="comments">
    Conversational work with agents, resumable sessions, and the unified ledger.
  </Card>

  <Card title="Runs & evidence" href="/manage-your-agents/run/runs-evidence" icon="list-check">
    What a run records, and how to read it well enough to trust or challenge it.
  </Card>

  <Card title="Outbound webhooks" href="/manage-your-agents/run/outbound-webhooks" icon="paper-plane">
    Have KAOP post signed, retried events to your own systems as agents work.
  </Card>

  <Card title="Channels" href="/manage-your-agents/run/channels" icon="slack">
    Slack — connect a workspace, route messages, and get answers in-thread.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Triggers & schedules" href="/manage-your-agents/build/triggers-schedules">
    Put an agent on a cron schedule.
  </Card>

  <Card title="Approvals" href="/security-and-governance/controls/approvals">
    How a risky action pauses for a human decision.
  </Card>

  <Card title="Modules & workflows" href="/modules-and-workflows/overview">
    The prebuilt outcomes whose workflows drive most automated runs.
  </Card>

  <Card title="Fleet health" href="/manage-your-agents/optimize/fleet-health">
    Read the fleet once runs are flowing.
  </Card>
</CardGroup>


## Related topics

- [Runs & evidence](/manage-your-agents/run/runs-evidence.md)
- [How it works](/manage-your-agents/build/how-it-works.md)
- [Optimize — how it works](/manage-your-agents/optimize/how-it-works.md)
- [Architecture](/get-started/architecture.md)