trace

Record a structured agent run as a navigable timeline.

When to use

Call trace_create at the start of a significant agent run, emit trace_step calls as the agent works, and trace_finish at the end. The user gets a clean timeline they can review the next morning.

Example user prompts

• Record a trace for this long refactor so I can inspect it tomorrow.
• Give me a run timeline with the commands you execute and what they returned.
• Trace this migration attempt and summarize each step.

MCP tool signature

trace_create(
    run_id: str | None = None,
    title: str | None = None,
    project: str | None = None,
) -> TraceHandle   # {trace_id, url, expires_at}

trace_step(
    trace_id: str,
    kind: Literal['thought', 'tool_call', 'tool_result', 'message', 'error'],
    content_md: str,
    kv: dict | None = None,
) -> None

trace_finish(trace_id, summary_md: str) -> None

Example call

handle = trace_create(title='Overnight refactor run')

trace_step(handle['trace_id'], kind='thought',
           content_md='Analysing existing test coverage...')
trace_step(handle['trace_id'], kind='tool_call',
           content_md='Running pytest', kv={'exit_code': 0})
# ... more steps ...

trace_finish(handle['trace_id'],
             summary_md='Refactored 4 modules. All tests pass.')

Return value

Returns a TraceHandle with trace_id, url, and expires_at. The rendered page is a collapsible per-step timeline with search, deep-linking to any step, and a share button.

Credit cost

2 actions per create call.

Notes

trace is for after-the-fact review. For a live progress feed the user watches during a run, use status instead.

Recipes

See all recipes for copy-paste patterns that use trace and other tools together.