Why agent reasoning visibility matters

Agent reasoning visibility means every step an agent takes — what it thought, which tool it called, what came back, and why it produced the final answer — is streamed to the caller in real time, not hidden inside a single opaque response. Most agent frameworks treat reasoning as a black box: you send a prompt, you wait, and everything between the request and the response is invisible. That's fine until an agent gets something wrong, at which point "invisible" becomes "undebuggable."

The black-box problem

A black-box agent gives you no way to distinguish between different kinds of failure. Did it retrieve the wrong document? Call the wrong tool? Reason correctly from bad data? Hallucinate a fact nothing in the conversation supports? Without visibility into the steps in between, every failure looks the same from the outside: a wrong answer, with no trail back to its cause. Teams end up debugging by resending slightly different prompts and guessing, instead of looking at what actually happened.

What UnderOcean streams, concretely

UnderOcean's agent execution engine runs a LangGraph-based ReAct loop — call the model, execute any tool calls it requests, feed the results back, repeat until a final answer — and every step of that loop is streamed over Server-Sent Events as it happens, using a small, fixed set of event types:

POST /api/v1/executions             → { exec_id, status: "pending" }
GET  /api/v1/executions/{id}/stream → EventSource SSE

event types: token · step · tool_call · observation · done · error

A step event marks a distinct point in the reasoning loop; tool_call carries exactly which tool the agent invoked and with what arguments; observation carries the result that came back; token streams the model's output as it's generated; done and error close out the run. The same generator function backs every entry point that can run an agent — the in-app test panel, the Consumer API's POST /v1/agents/{id}/execute with stream: true, and public flow-share execution — so reasoning visibility isn't a feature bolted onto one surface, it's a property of the execution engine itself.

Why this is more than a debugging nicety

Reasoning visibility earns its keep in a few concrete ways:

• Debugging. When an agent gives a wrong answer, you can see exactly which tool it called, what came back, and where its reasoning diverged from what you expected — instead of guessing at the prompt.
• Trust calibration. Users (and the teams operating an agent) can tell the difference between "the agent looked this up and got a clear answer" and "the agent is reasoning past thin or missing information" — which changes how much weight to put on the answer.
• Compliance and audit. In regulated industries, being able to reconstruct exactly which data an agent consulted and which tool produced a given output is often a hard requirement, not a nice-to-have. A streamed, structured reasoning trace is naturally auditable in a way a single text response is not.
• Faster iteration on agent design. When you're tuning a system prompt, a guardrail, or a tool's description, watching the actual reasoning trace tells you why a change helped or hurt far faster than only comparing final answers.

What this looks like in the product

The same inference_steps data streamed to an execution's SSE connection is what powers UnderOcean's flow test panel and agent chat surfaces: every tool call, every retrieved document, every intermediate thought is rendered inline as the agent runs, not collapsed into a spinner. That's a deliberate product principle, not an incidental UI choice — hiding these steps to "simplify" a view, even a public-facing one, would undercut the entire premise that these agents should be auditable rather than trusted blindly.

Guardrails run before any of this is visible

Streaming raw reasoning doesn't mean streaming unfiltered input. Every user-supplied input passes through a guardrails layer — PII detection and redaction, prompt-injection pattern screening, jailbreak/toxic-content filtering, and credential masking — before it ever reaches a model call or shows up in a reasoning trace, so visibility and safety aren't in tension with each other.

FAQ

Does streaming reasoning steps slow down the final answer? No — the reasoning trace is emitted as it happens, alongside token streaming for the answer itself; nothing is computed twice or held back to be batched later.

Can reasoning visibility be turned off for a public-facing surface? UnderOcean's position is that it shouldn't be — the same transparency principle applies whether the surface is an internal test panel or a public flow-share link. Hiding steps to simplify a public view reintroduces exactly the black-box problem this feature exists to solve.

Is the reasoning trace stored, or only streamed live? Execution steps are part of the execution record, so a completed run's reasoning trace can be reviewed after the fact, not only watched live.

Does this apply to flows as well as standalone agents? Yes — an agent_node or llm_node inside a flow streams the same step/tool_call/observation events as a standalone agent execution, since both run through the same underlying engine.