Skip to main content
Distinguish three separate events: a context decision arrived, your harness used it in a model request, and a final trace was accepted for analysis. Success at one does not prove the others. Compare your hooks with agent harness integration.

Context is empty

Empty context can be the correct result. Inspect mode, delivery, and reason from TypeScript’s getContext or Python’s get_context together. The first retrieval may return empty while the mode heartbeat starts. Do not add a blocking startup wait solely to force nonempty context. The API must support the SDK’s mode and context endpoints; an older service may produce fallback results.

Context arrives but the model does not receive it

Both retrieval methods return a result object with a context string; they do not patch the provider request. At your prompt assembly boundary, append nonempty result.context to a copy of the base system prompt and pass that copy to the existing model request. Check that a later prompt builder does not overwrite it. Use a local fake model to inspect the outgoing request without sending private history to a new endpoint. Do not store the augmented system prompt as original history. Reusing it on later turns can duplicate a correction and teach Reflect from its own injected text. Rebuild each turn from original instructions and retrieve context for that turn.

Traces do not appear

Check the capture ticket’s receipt. A dropped receipt has a local reason, such as invalid or oversized evidence. An unconfirmed receipt means delivery is uncertain. An accepted final capture with ingestion queued means processing is pending. If ingestion is unsupported_history, no analysis job was created. Check for unsupported media or provider-executed tools, empty history, and missing or invalid tool-call/result associations. Preserve the original evidence rather than inventing missing associations or silently removing unsupported content. Send a final snapshot after the execution ends, including the final response and tool results. A chat may continue for many turns; do not wait for the user to close it. For streaming, finalize in the actual stream completion, failure or cancellation hook, after available original messages have been recorded. Inspect your history mapping and check the trace format and size limits in trace capture.

Captures conflict or later turns replace the wrong trace

Use one execution ID for a run’s snapshots and a fresh ID for the next run. Never reopen a finalized ID after a restart. A terminal_conflict receipt can indicate changed evidence or a changed terminal status after finalization; do not repeatedly submit a different final snapshot under the same ID. For a continuing chat, keep its conversationId stable and allocate a higher conversationRevision in durable storage before each new run. Keep that pair fixed within the run. Using a message count, timestamp or process counter can break ordering. Distinct branches need distinct conversation IDs. See conversation identity.

Connection settings are rejected

Copy settings from Agent setup → SDK connection settings. Use the generated agent ID, an agent-scoped key with runtime:read and runtime:write, and the API URL shown for that agent. Do not use the marketing URL or the agent display name. Use the API origin without /v1 or a runtime route; the SDK supplies those paths. The SDK requires HTTPS except for local loopback development.

Retrieval adds more delay than expected

Call getContext or get_context once at the chosen user-turn boundary. Repeated calls at internal tool steps each have their own wait budget. Measure end-to-end turn latency as well as elapsedMs (TypeScript) or elapsed_ms (Python). Scheduling delays can extend observed deadlines. In async Python, use await aget_context(...) so retrieval does not block the application’s event loop.

Shutdown loses pending captures

Drain during explicit shutdown before dispose():
  • TypeScript: await reflect.flush({ timeoutMs: 2000 }). complete: true means none of the covered tickets remain pending, even if some were dropped or unconfirmed.
  • Python: reflect.flush(timeout_ms=2000) or await reflect.aflush(timeout_ms=2000). .complete is true only if all covered tickets were accepted, or there were none.
Inspect all returned counts. Both SDKs cover only tickets pending when flush began; retain individual receipts for earlier deliveries. Abrupt termination can still lose in-memory work. For a short-lived worker, finish the run’s stream and tools, submit its final capture, then drain within the host’s available shutdown time. See the Python quickstart and Python SDK reference for its source installation and lifecycle. For help, email devs@runreflect.com with your SDK version, a minimal reproduction, and redacted result fields. Do not include API keys or private conversation content in an initial support message.