Skip to main content
A trace describes one execution. Send the full original history available at each capture point, using the same id until that execution ends. Create a new ID for a new execution, including after restarting your process. For a chat agent, use one execution per user turn, covering all of its model calls, tool calls and streaming. See agent harness integration for the placement of capture, retrieval and completion hooks.

Map your harness history

Capture from the history your application owns, before adding Reflect context to the provider request. Each capture is a complete snapshot, not a message delta. If your provider stores the system prompt separately from messages, include that base prompt when building the canonical snapshot. Do not pass a native provider request with signals, functions or tool definitions as a trace. The examples below use TypeScript. Python uses dictionaries and Ruby uses string-key hashes with the same canonical keys, including camelCase callId, entryPoint, conversationId, and conversationRevision; do not convert these keys to snake_case or Ruby symbols. See the Python and Ruby quickstarts for examples.
This is an illustrative completed conversation. Map your application’s actual history into this format; do not substitute the example for real evidence.

System prompt

With a compatible TypeScript SDK artifact and backend, pass configuration from the same application state you use to assemble the provider request:
Use the base prompt before adding Reflect context. This is an explicit text input; the SDK does not inspect files or provider requests. This does not replace the original message history or change what the model receives. The same optional field can accompany getContext. Include it again on the final capture to retain it in annotations.agent_context; omission on the final means unknown even if an earlier snapshot included it. Snapshots are independent, so concurrent runs can supply different prompts. See the SDK reference for bounds. Verify both the installed artifact and deployed API/worker readers support this source feature before sending it; publication and deployment are separate steps. Ruby accepts the same prompt-only object as { "agentContext" => { "systemPrompt" => base_system_prompt } }; see the Ruby reference.

Conversation identity

TypeScript SDK 0.7.0, Python source SDK 0.1.0, and Ruby SDK 0.2.0 can connect successive executions to one logical conversation. Add both fields to every capture and context request after the compatible backend is deployed:
persistedRun is the application’s durable run record, not an SDK helper. Allocate the revision atomically when the run starts, persist it before any SDK request, and reuse it for every snapshot and retry in that execution. It must be a positive safe integer greater than all earlier revisions for this conversation. Do not use a timestamp, message count or in-memory counter. Gaps between revisions are allowed. Use the same conversation ID for later turns and after restarting the application, with a fresh execution ID and revision for each new run. Give branched/copied chats distinct conversation IDs. IDs allow letters, digits, _, ., and -, with a maximum of 128 characters; scope them uniquely within each agent. Two executions claiming the same conversation revision conflict. The compatible backend keeps the latest finalized revision as the conversation’s current snapshot, even if older executions arrive later. Older snapshots and their evidence links are retired. This is why later runs must send full cumulative original history: they cannot depend on the older snapshots remaining available. Keep the two fields fixed within the execution. They are optional together: legacy integrations omitting both retain their independent-trace behavior.

Preserve the source

Messages support system, user, assistant, and tool roles. Content can be a string or ordered blocks: text, reasoning, tool-call, tool-result, or media. Preserve tool-call IDs and their corresponding results, including error flags. Include reasoning only when it is already present in the source history. The canonical wire format can represent more than the current analysis pipeline supports: media and provider-executed tools can produce an unsupported_history ingestion receipt. Do not remove them to make a trace appear supported. Do not invent missing messages, flatten tool results into unrelated text, mutate original history, or capture Reflect-added context as an original instruction. If the source is incomplete, use the trace’s completeness fields to describe that fact rather than representing it as a complete execution. Keep completeness, model, entryPoint, and the conversation fields unchanged for a trace across capture and context requests. Use final and terminal to report live completion; these metadata fields are not a progress indicator. The SDK rejects malformed evidence and limits a canonical snapshot to 1,000,000 encoded bytes and 10,000 messages. Do not silently truncate data to fit. Decide which conversations can be captured faithfully and inspect dropped receipts.

Capture and completion

TypeScript’s captureTrace({ trace, final: false }), Python’s capture_trace(trace, final=False), and Ruby’s capture_trace(trace, final: false) queue background capture without waiting for network delivery. On completion, send the full final snapshot with final: true (TypeScript and Ruby) or final=True (Python), and the appropriate terminal status. Accepted final captures queue ingestion when the history supports analysis. A receipt with ingestion unsupported_history has no analysis job; inspect the original message structure and supported content. One execution is one billable turn. It is counted as soon as Reflect returns context for it, and otherwise when its final capture is stored. A finished execution ID cannot be used again. final ends this execution; the logical chat can continue with a new execution ID and revision. Preserve the application’s existing run completion, failure and cancellation hooks. Returning a stream object or receiving a tool result does not mean the execution ended. An explicit end-chat button is not required. If execution fails or is canceled, capture the original evidence available at that point with terminal status "failed" or "canceled". If no final evidence is available, use releaseTrace(traceId) in TypeScript or release_trace(trace_id) in Python and Ruby for local cleanup. Do not reuse the ID. A completed terminal status means the loop finished, not that the agent’s answer was correct. All three SDKs expose ticket.receipt. Outside model execution, TypeScript can await ticket.done; Python can call ticket.wait(timeout=2) or await ticket.wait_async(timeout=2); Ruby can call ticket.wait(2). Python and Ruby ticket timeouts are seconds, and a bounded wait may still return a pending receipt. Capture uses bounded in-memory queues; it does not promise durable delivery after a crash. At shutdown, flush pending captures before disposing the client. Python and TypeScript give the flush result’s complete flag different meanings; see shutdown troubleshooting and the Python SDK reference. Ruby’s close(timeout_ms: 2000) flushes and disposes; its complete? is true only when all covered tickets were accepted. See the Ruby lifecycle reference.