Guide

Use Trace to improve runtime choices.

Use the dashboard control plane and your saved product records before changing instructions, model policy, tools, permissions, or runtime limits.

Control plane Trace

The HarnessRouter dashboard is the control plane for observing task execution. Use Trace to inspect the selected harness, model, session status, event count, elapsed time, and the User, Agent, Tool, and Result timeline.

Trace is for diagnosis. The end user should still see a product-shaped result in your UI: status, answer, generated files, previews, downloads, and Continue or Revise actions.

Integration records

Your product should also save the records it needs to recover and render the task: response.id, response.metadata.session_id, terminal session status, turns, file records, media types, and artifact metadata.

Use the dashboard for control-plane diagnosis. Use the documented stream, session, turn, and file endpoints for product integration.

Signals to watch

Success: Did the task finish, and did the artifact satisfy your product's contract?
Latency: Use dashboard elapsed time, session elapsed, timestamps, or product-side timing across repeated runs. A single fast demo run is not enough evidence.
Recovery: If the stream drops after response.created, can the product recover from the saved session without starting duplicate work?
Event shape: Look for repeated tool/activity events, incomplete states, failures, slow startup, and unknown stream data.type values that your parser should ignore.
Artifact quality: Check the actual files, previews, diffs, or structured result your product returns to the end user.
Credits: Use credit, token, or billing data from the dashboard or billing records when evaluating efficiency.

Optimization workflow

Start with representative non-production input and approved fixtures.
Change one variable at a time: harness instructions, model policy, tool access, skill set, runtime limit, or request header mapping.
Run the same scenario enough times to see failure shape, latency, timeline shape, and artifact consistency.
Promote a configuration only after the product path handles streaming, recovery, file preview, download, Continue/Revise, and authorization checks.
Keep production evidence and non-production fixture evidence separate in your own records.

Avoid false signals

Use task-level evidence from your product instead of model reputation when choosing a production path.
Do not compare tokens as if they were the final billing or quality unit for agent work.
Do not optimize from one isolated success when stream, session, or artifact evidence shows unstable behavior.
Do not widen data access or permissions before the evidence proves the current boundary is blocking the task.