# Runs and the Event Graph

> How sessions, runs, and Events fit together, and how to connect agents and sub-agents with parents and links.

When you send [Events](https://whitecircle.com/docs/latest/events/overview.md), three identifiers decide how White Circle organizes them: the session, the run, and the Event. The `parent_event_id` and `links` fields then connect Events into a graph of how your agent worked. Browse it on the [Runs](https://eu.whitecircle.com/runs) page or load it with [Get a Run Graph](https://whitecircle.com/docs/latest/events/get-run-graph.md).

Read this page before you integrate an agent with tool calls or sub-agents.

## Sessions, Runs, and Events

| Concept | Field | What it represents | Example |
| ------- | ----- | ------------------ | ------- |
| Session | `external_session_id` | One conversation with your user, across many agent runs | A chat thread or a project |
| Run | `run_id` | One unit of agent work inside a session | One agent turn, including its sub-agents |
| Event | `event_id` | One piece of that work to check | A user message, a tool call, a tool result |

Every check result also gets an `internal_event_id`, White Circle's ID for that saved result. Use it to [retrieve the result](https://whitecircle.com/docs/latest/events/get-event.md) later.

A session usually contains many runs, and a run contains many Events. When you send no `run_id`, the run defaults to the `external_session_id`, so the whole session becomes one run.

> [!TIP]
> Send both identifiers. Use `external_session_id` for the conversation and a new `run_id` for each agent run, so each run gets its own tree in the graph.

## The Event Graph

The graph records how Events in your agent relate. You build it with two fields:

| Field | Meaning | Can point to | Per Event |
| ----- | ------- | ------------ | --------- |
| `parent_event_id` | The Event that produced this one: its structural place in the run | An `event_id` in the same run | One |
| `links` | Outputs this Event consumed | An Event in any run in the same Environment | Up to 50 |

Parent edges form a tree inside each run. White Circle uses them for the run tree and breadcrumbs. Links connect Events across that tree and across runs, for example from a final answer to the sub-agent results it merged.

Parents also pair tool calls with their results. When a `tool` or `function` Event sends `output` without a `call_id`, White Circle matches it to the call whose `event_id` equals the output's `parent_event_id`, so the model sees the arguments and the result as one call.

Targets do not have to exist yet. If you send a child before its parent, the graph keeps the reference and resolves it when the parent arrives.

## Example: An Agent with Two Sub-agents

An orchestrator agent, `agent_a`, handles a refund request and starts two sub-agents in parallel:

1. The user asks for a refund.
2. `agent_a` calls the `lookup_order` tool and gets the order.
3. `agent_a` starts `agent_b` and `agent_c`.
4. `agent_b` calls `search`, gets a result, calls `write`, and reports back.
5. `agent_c` replies with a message and calls `write`.
6. `agent_a` combines the sub-agents' results into its final answer.

Send every Event in one run. Each sub-agent's first Event names the step that started it as its `parent_event_id`, so each sub-agent becomes its own branch of the tree. The final answer links to the sub-agent outputs it used.

The [Runs](https://eu.whitecircle.com/runs) page shows this run as a tree and as a graph. Parent edges draw the structure, the link badge counts an Event's links, and a pink dot marks an Event that violated a Policy.

### Tree view

![Run tree: a user message, lookup_order arguments and output, then three branches under the output: the final assistant message with 2 links, agent_c's input, message, and write call, and agent_b's input, search call and output, write call, and message](https://whitecircle.com/docs/assets/images/runs/event-tree.png?ref=5031e8d4c735c71c7cc31f68386616035c0bc013)

Each sub-agent is a branch under the lookup_order output

### Graph view

![Run graph: the user message, lookup_order arguments, and lookup_order output in a column, fanning out into three columns: the final assistant message with 2 links, agent_c's branch ending in a write call with 1 link, and agent_b's branch ending in a message with 1 link](https://whitecircle.com/docs/assets/images/runs/event-graph.png?ref=5031e8d4c735c71c7cc31f68386616035c0bc013)

The same run with the sub-agents side by side

`agent_b` sends its branch as one batch. Its first Event names the `lookup_order` output as its parent:

```json
{
  "environment_id": "environment_123",
  "external_session_id": "conversation_456",
  "run_id": "run_refund_4815",
  "events": [
    {
      "type": "agent",
      "name": "agent_b",
      "event_id": "b_task",
      "parent_event_id": "a_lookup_result",
      "input": "Check the refund policy for order 4815 and draft the refund note."
    },
    {
      "type": "tool",
      "name": "search",
      "event_id": "b_search_args",
      "parent_event_id": "b_task",
      "arguments": { "query": "refund policy delivered orders" }
    },
    {
      "type": "tool",
      "name": "search",
      "event_id": "b_search_result",
      "parent_event_id": "b_search_args",
      "output": { "rule": "Delivered orders can be refunded within 30 days." }
    },
    {
      "type": "tool",
      "name": "write",
      "event_id": "b_write_args",
      "parent_event_id": "b_search_result",
      "arguments": { "path": "refund_4815.md", "text": "Order 4815 is eligible for a refund." }
    },
    {
      "type": "message",
      "role": "assistant",
      "event_id": "b_message",
      "parent_event_id": "b_write_args",
      "content": "Refund note drafted: order 4815 is eligible."
    }
  ]
}
```

`b_search_result` names `b_search_args` as its parent and sends no `call_id`, so the model sees the search arguments and result as one call. The orchestrator's final answer hangs off the `lookup_order` output and links to both sub-agents' results:

```json
{
  "environment_id": "environment_123",
  "external_session_id": "conversation_456",
  "run_id": "run_refund_4815",
  "event": {
    "type": "message",
    "role": "assistant",
    "event_id": "a_final_answer",
    "parent_event_id": "a_lookup_result",
    "content": "Your refund for order 4815 is approved. You'll get a confirmation email shortly.",
    "links": [
      { "event_id": "b_message" },
      { "event_id": "c_write_args" }
    ]
  }
}
```

The links omit `run_id` because their targets are in the same run. To link to an Event in another run, add that run's `run_id`.

## Execution Timing

Add `started_at` and `finished_at` to an Event to show how long that step took. Both are optional RFC 3339 timestamps, and `finished_at` must not be earlier than `started_at`. For example, `agent_b`'s search result could report when the search ran:

```json
{
  "type": "tool",
  "name": "search",
  "event_id": "b_search_result",
  "parent_event_id": "b_search_args",
  "output": { "rule": "Delivered orders can be refunded within 30 days." },
  "started_at": "2026-10-29T10:00:01Z",
  "finished_at": "2026-10-29T10:00:01.840Z"
}
```

## Retries and the Graph

`run_id` and `event_id` are your IDs, not retry keys. Sending the same pair again runs a new check and creates a new `internal_event_id`. The graph shows the latest attempt for each `event_id`, and the latest attempt's `parent_event_id` and `links` replace the earlier ones.

## Next Steps

- **[Check One Event](https://whitecircle.com/docs/latest/events/check-event.md)**: Field reference and validation rules for parents and links.
- **[Event Context](https://whitecircle.com/docs/latest/events/context.md)**: See exactly which Events the model receives for a check.
- **[Get a Run Graph](https://whitecircle.com/docs/latest/events/get-run-graph.md)**: Load nodes and edges for a run through the API.
- **[Check Multiple Events](https://whitecircle.com/docs/latest/events/check-events.md)**: Send ordered batches of up to 50 Events.
