Context is empty
Empty context can be the correct result. Inspectmode, 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 acontext 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 ingestionqueued 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. Aterminal_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 withruntime: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
CallgetContext 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 beforedispose():
- TypeScript:
await reflect.flush({ timeoutMs: 2000 }).complete: truemeans none of the covered tickets remain pending, even if some were dropped or unconfirmed. - Python:
reflect.flush(timeout_ms=2000)orawait reflect.aflush(timeout_ms=2000)..completeis true only if all covered tickets were accepted, or there were none.