Trace one request through the agent loop

Verifiedon 2026-07-302026.7.1-2

A request is a sequence, not a magic answer

When an operator sees a fluent assistant reply, it is tempting to compress the whole run into “the agent did X.” That shortcut is dangerous. An OpenClaw agent turn has a lifecycle: the Gateway accepts an RPC, resolves a session, persists metadata, queues the run, assembles context, calls the model, may execute tools, streams lifecycle/tool/assistant events, persists transcript state, and eventually delivers a response through a configured route. Each stage produces different evidence and carries different authority.

The reviewed agent-loop document is precise about the distinction. An agent RPC returns an accepted runId before the turn is finished. agent.wait waits for lifecycle end/error. Per-session and global queues serialize work to avoid tool or transcript races. A tool stream shows that a tool was started or returned a result; it does not, by itself, prove that a third-party recipient received a message. The architecture source explains how the Gateway carries those typed requests and events over WebSocket.

The practical habit is to write claims at the strongest level supported by evidence. “Accepted” is a Gateway fact, “tool result returned” is an execution fact, and “recipient received” is a delivery fact. If the trace only supports the first, stop at the first. This is not pedantry: incident reviews, retries, and handoffs all become safer when an operator can tell whether a run is incomplete, refused, or successful. It also limits the amount of private data that needs to be retained. Keep identifiers categorical and redacted; a useful trace can say channel=operator, tool=lookup, and delivery=not requested without storing the underlying message.

When you need to investigate a real run later, prefer a bounded evidence query over exporting a whole transcript. Capture the run category, lifecycle state, tool name, result class, channel route, and owner decision. Do not use the trace as a second source of authority: an event can tell you what happened, while policy and ownership decide what may happen next. A good handoff therefore ends with an explicit next action such as inspect delivery record, request approval, or close as no-side-effect, never with an unqualified “done.”

Worked example: “send the status update”

Use a fictional request: “Check the synthetic queue and send the result to the team room.” The safe trace contains two separate actions: a read-only lookup and an outbound message. A model may propose both in one answer, but the operator should not collapse them.

If the run ends after the lookup because approval was denied, the correct report is “lookup returned three synthetic items; outbound send was not executed.” If the run times out while streaming, report “outcome unknown; inspect the run and channel records before retrying,” not “sent successfully.” A retry can duplicate a side effect unless the channel or workflow has a deduplication key.

Lab: trace a harmless request

Work in a disposable environment or with the instructor’s synthetic prompt: “Summarise this three-line local note and do not send it anywhere.” Do not paste a private note into the course platform. Use placeholders such as NOTE_A, NOTE_B, and NOTE_C. Record only timestamps, redacted component names, status categories, and the final outcome.

Your trace should include:

1. inbound source and a redacted request label;
2. selected sessionKey or session category, explicitly marked as routing context;
3. runId and whether the run was accepted, started, ended, errored, or timed out;
4. whether a tool was proposed, and whether it actually returned a result;
5. response route and evidence that no outbound message was requested; and
6. owner, retention choice, and follow-up if the state is ambiguous.

Now make a second, paper-only variant that asks to read a file, call a web service, or send a message. Mark the exact arrow where a new boundary appears. You are not asked to execute it. The learner artifact is a redacted request trace suitable for a reviewer who does not need the original prompt.

request: SYNTHETIC_NOTE_SUMMARY
source: disposable-local
session: route-only:session-category-A
run: run-redacted
model: response + no tool proposal
outcome: lifecycle-end
outbound: none requested
owner: lab-operator
retention: keep categories only

Failure cases and rollback

The first failure is writing “the agent sent it” when the only evidence is assistant text. The second is retrying a timeout without checking whether a channel accepted the first send. The third is treating a runId as a permission token or assuming that a session label authenticates the requester. None of those are safe shortcuts.

If you discover a trace contains a private prompt, credential, recipient identity, or raw attachment, stop sharing it. Delete the draft from the course artifact, keep only a redacted category-level record if policy permits, and notify the data owner. If the run’s side-effect status is uncertain, do not send a compensating message or repeat the action; inspect the relevant tool/channel evidence and escalate to the named operator. The rollback for this lab is intentionally non-operational: discard the synthetic trace and repeat with placeholders.

Source receipt and decision check

This lesson was reviewed against OpenClaw 2026.7.1-2 at revision 2e26244cec32e61f6117740d3ea273b1ecb54efc on 2026-07-30. Re-read the agent-loop receipt when lifecycle names, queueing, transcript persistence, or tool-stream semantics change. The source review supports the tracing method; it does not authorise a real send.

Decision check: a model says it sent a message. What evidence proves delivery? Look for the tool or channel result appropriate to the configured route, and keep only the minimum redacted identifiers needed for handoff. If the target is a real person or system and permission is unclear, stop rather than use the trace as authorization.