First Steps

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, 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 page or load it with Get a Run Graph.

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

Sessions, Runs, and Events

ConceptFieldWhat it representsExample
Sessionexternal_session_idOne conversation with your user, across many agent runsA chat thread or a project
Runrun_idOne unit of agent work inside a sessionOne agent turn, including its sub-agents
Eventevent_idOne piece of that work to checkA 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 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.

The Event Graph

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

FieldMeaningCan point toPer Event
parent_event_idThe Event that produced this one: its structural place in the runAn event_id in the same runOne
linksOutputs this Event consumedAn Event in any run in the same EnvironmentUp 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 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.

Each sub-agent is a branch under the lookup_order output

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

Field reference and validation rules for parents and links.

Event Context

See exactly which Events the model receives for a check.

Get a Run Graph

Load nodes and edges for a run through the API.

Check Multiple Events

Send ordered batches of up to 50 Events.