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
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:
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:
- The user asks for a refund.
agent_acalls thelookup_ordertool and gets the order.agent_astartsagent_bandagent_c.agent_bcallssearch, gets a result, callswrite, and reports back.agent_creplies with a message and callswrite.agent_acombines 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.
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
Field reference and validation rules for parents and links.
See exactly which Events the model receives for a check.
Load nodes and edges for a run through the API.
Send ordered batches of up to 50 Events.