mirrors-sdk@0.7.0.
The package supports ES modules and CommonJS, with no runtime or peer dependencies.
Use it in your server-side harness.
For other languages, use the Python or
Ruby quickstart.
You will add background capture and optional context retrieval. Then follow the
agent harness guide to connect your model/tool loop,
streaming, and completion hooks.
1. Copy your agent’s connection settings
No account yet? Sign up free; the Hobby plan needs no card. Working with a coding agent? Point it at mirrors.dev/agents.md. Open your agent in the Mirrors dashboard, then open Agent setup → SDK connection settings. Copy the API URL and generated agent ID together. The agent ID is not the agent’s display name. Create an SDK key for that same agent withruntime:read and runtime:write
permissions. Store the three values in your server configuration:
/v1 or a runtime route. Keep the key out of browser
bundles, source control, and logs. Use connection troubleshooting
if the selected environment, agent ID, or key scope is uncertain.
2. Install and create a shared client
mirrors.ts module:
3. Prepare the turn’s prompt
Locate the point where your harness has accepted a user message and is about to assemble the model request. Map its full original history to aCanonicalTrace. Give this execution a fresh ID and keep
that ID through its model calls, tools, and final capture.
This helper prepares a prompt; your existing harness still makes the model call:
baseSystem
and stored history unchanged so future captures contain only original evidence.
The harness guide shows where to apply the prompt and
finalize the turn.
captureTrace returns immediately with a delivery ticket. getContext sends its
own current snapshot; it does not need you to await capture first. Its total wait
budget is up to 1,000 ms, which you can shorten with timeoutMs. Call once before
the user turn’s loop; waiting again at each tool step adds delay. A blocked JavaScript
event loop can delay timers.
Empty context is normal when nothing matches, in shadow/off mode, before the first
mode refresh, or on a delivery fallback. Your harness then uses baseSystem.
4. Connect the rest of your harness
Before running real traffic, wire the remaining lifecycle hooks in the agent harness guide:- Original-history updates: preserve actual responses, tool calls, and tool results in order; capture full snapshots without injected context.
- Execution completion: send
final: trueafter the model/tool loop and stream finish, including failure and cancellation endings. - Process shutdown: stop admitting turns, await a bounded
flush, inspect delivery counts, thendisposethe shared client.
5. Verify in shadow mode
Start in shadow mode. Run a representative test conversation, inspect its final capture receipt, and confirm the conversation appears in Mirrors.accepted with ingestion queued means analysis was queued, not completed.
Then review a correction, preview its scope, and enable
active delivery deliberately. Verify that the actual model request contains the
guidance while stored history stays original. The harness guide includes
checks for tool loops, cancellation, and fallback.