reflect-sdk@0.7.0. Start with the quickstart,
then follow agent harness integration to place these calls
in your loop.
For Python methods and result types, see the Python reference.
Constructor
new Reflect({ apiUrl, apiKey, agentId }) creates a client for one agent. Reuse it
across that agent’s conversations. Keep keys in server secrets. Node.js 22 or later
is required; ES modules and CommonJS are supported.
Context retrieval
getContext({ trace }, { signal?, timeoutMs? }) returns a promise for:
The call’s
timeoutMs may shorten the total 1,000 ms wait budget to 1–1,000 ms.
The SDK allows up to 16 concurrent context waits. A newer retrieval for the same
trace supersedes the older pending wait. Changed captured evidence, finalization,
release, local disable, and shutdown invalidate pending retrievals.
accepted means a server decision was received. It does not report that your
application applied the context or that the agent succeeded.
Retrieve once before the user turn’s model/tool loop. This request carries its own
full original snapshot; it does not wait for a preceding capture to upload.
Use the text immediately. If dispatch is delayed, check freshness.expiresAt; if
history changes, retrieve again. The SDK cannot withdraw a string already returned
to your application. Never cache it for another turn.
Pass the application’s abort signal and preserve its cancellation handling after
the wait, for example signal.throwIfAborted(). A canceled result is data; the SDK
does not abort or invoke your model for you.
Shadow, off, and unknown/expired mode return empty context immediately. The client
learns mode through a background heartbeat, so a first call may return
mode_unknown. See runtime modes.
Trace capture
captureTrace({ trace, final, terminal? }) returns a delivery ticket immediately.
It captures original history in the background without returning context. Call it
at your history logging boundary, then finalize after the last response, tool result
and stream completion have been recorded.
ticket.receipt is the current delivery status. ticket.done resolves with the
settled receipt. Observe it outside the model execution path. A final capture can
queue ingestion; queued analysis is not completed analysis.
The optional terminal value is completed, failed, or canceled and is valid
only on final capture. It describes the execution ending, not task success.
See trace capture for the schema and receipt meanings.
CanonicalTrace
trace.id identifies the execution. Optional trace.conversationId and
trace.conversationRevision identify its logical chat and revision; supply both
or neither. The ID follows the execution ID’s 1–128 character identifier format.
The revision is a positive safe integer, allocated atomically in durable storage
for each new execution and fixed across all its captures, retrievals and retries.
The server uses revisions to select the latest finalized snapshot. A new execution
cannot reuse another execution’s revision. See
conversation identity.
Snapshots are limited to 1,000,000 encoded bytes and 10,000 messages. Use ordinary
JSON-compatible data: cyclic objects, accessors and native provider request objects
are not canonical history. Do not silently truncate evidence to fit the limits.
System prompt
The application can pass its base system prompt throughtrace.agentContext on capture and retrieval. User prompts stay in messages.
This is optional evidence: the SDK does not read files, assemble the provider’s
prompt. Original system messages must still be
preserved in history. See the capture example.
When agentContext is present, systemPrompt is required. An empty string is a
valid explicit empty prompt. Limits: 100,000 UTF-16 code units for the prompt
and 262,144 UTF-8 JSON bytes for the context. Other fields are rejected.
The context also counts against the complete snapshot limit. Invalid data is
rejected without truncation.
Only the final capture’s context is retained in trace readback at
annotations.agent_context; earlier values are not carried forward. Values may
change between snapshots. Omission remains compatible with existing clients.
Check installed types and backend support before using this source addition.
Lifecycle
Never reuse a released or completed execution ID. Call
flush before dispose
when you want an explicit bounded capture drain.
flush.complete means no covered tickets remain pending, even if some were dropped
or unconfirmed. Inspect the counts and retain individual receipts; flush excludes
already-settled tickets and captures created after it began. It does not wait for
server analysis. Capture queues live in memory and cannot survive a process crash.
Existing integrations
sendTrace, prefetchTrace, submitTrace, injectSystemPrompt, and close remain
available for compatibility. Awaiting legacy sendTrace does not wait for fresh
context. New integrations should use getContext and captureTrace directly.
When the free plan’s monthly turns are used up
On the Hobby plan, corrections pause when the month’s free turns are used up; your agent keeps running and capture continues. Three things soften the edge:- The first time an account reaches the limit, corrections stay on for 100 more turns or 48 hours, whichever comes first.
- A run that was already in progress when the pause began keeps receiving corrections, for up to 30 minutes.
- Responses say what is happening. While the limit is in play they carry a
correctionsobject:{ paused: false, reason: "hobby_grace", turns_left, ends_at }during the grace,{ paused: true, reason: "hobby_allowance", resumes_at }once paused, and{ paused: false, reason: "hobby_run_in_progress", ends_at }for a run being served past the pause. A context request that is withheld also returnsreason: "hobby_allowance".