Skip to main content
Keep your model/tool loop. Add Mirrors where your harness records history, assembles the next model request, and finishes the user turn. For other languages, see the TypeScript and Python quickstarts.

1. Install and configure

The Ruby SDK requires Ruby 3.3 or later and has no runtime gem dependencies. Add the published mirrors-sdk 0.2.0 release to your Gemfile:
Run bundle install and keep the resolved version in Gemfile.lock. Without Bundler, use gem install mirrors-sdk -v 0.2.0. No account yet? Sign up free; the Hobby plan needs no card. In the dashboard, open your agent’s Agent setup → SDK connection settings. Store its API origin, generated agent ID, and SDK key as MIRRORS_API_URL, MIRRORS_AGENT_ID, and MIRRORS_API_KEY. The key needs runtime:read and runtime:write; keep it in server secrets. Use the API origin without /v1 or a runtime route. Create one reusable client per agent configuration after worker processes fork:
A client inherited across a fork stays inactive. Construct a new client inside each child process and reuse it across that process’s turns.

2. Capture history and prepare the model request

At user-turn entry, start a timer and give the execution a fresh ID. Map your full original history into canonical messages. Ruby methods use snake_case, but canonical hashes require string keys such as "messages" and "callId". Symbol keys and custom objects are rejected. In this example, full_original_history, the request hash, model.complete, and application_cancellation_error belong to your application. The last is your existing cancellation exception. Connect your cancellation hook to cancel.cancel.
Capture copies and queues evidence without waiting for network delivery. Retrieval sends its own snapshot and has one total foreground budget of at most 1,000 ms from call entry, including copying and scheduling. Set timeout_ms from 1–1000 to shorten it. Ruby or operating-system scheduling can delay return beyond that budget. This synchronous method blocks its calling thread; use your application’s existing background execution facility when integrating with an event loop. Empty context is normal in shadow/off mode, on no match, before the first mode refresh, or during a fallback. Use the returned text promptly for this model call. Changed history requires fresh retrieval, and every retrieval adds another bounded wait. Preserve the original request and history; injected context belongs only in the outgoing prompt.

3. Finalize the whole turn

Capture updated original snapshots at your existing history logging points. After all model calls, tools, retries, and response streaming finish, send the final original history under the same execution ID:
agentContext captures the original prompt once on the turn’s final snapshot. It accepts exactly one "systemPrompt" string; omit the object when that prompt is unknown. Earlier snapshots do not supply a missing final prompt. Version 0.2.0 rejects agentContext.skills, even beside a valid prompt. Preserve original system messages without adding duplicate ones. On failure or cancellation, use terminal: "failed" or "canceled" in your existing ending hook, preserving your error handling and available original history. If no final evidence is available, call mirrors.release_trace(trace["id"]) for local cleanup. Terminal status describes how execution ended, not task success. Returning a stream handle is too early to finalize. The next turn needs a new execution ID. Use the conversation fields to group turns in a continuing chat; send the full cumulative original history each time.

4. Inspect delivery and shut down

Inspect ticket.receipt outside model execution. If confirmation matters, receipt = ticket.wait(2) waits up to two seconds and may still return pending. Other SDK timeout arguments use milliseconds. An accepted receipt with receipt.ingestion["status"] == "queued" means analysis is pending. An unconfirmed write may already have committed. At shutdown, stop admitting turns and let active turns finish:
close flushes captures pending at entry, then disposes the client. Inspect delivery.dropped, unconfirmed, and pending; delivery.complete? is true only when every covered ticket was accepted, or there were none. Keep individual receipts for captures that settled before shutdown. Queues are in memory and background threads do not keep a finished process alive.

5. Verify your integration

Start in shadow mode. Run a test conversation, inspect its final receipt, and confirm the conversation appears in Mirrors. Then verify an active correction reaches the outgoing model request while stored history stays original. Exercise tool loops, streaming, cancellation, and an unreachable API. See the Ruby SDK reference for methods and limits, or troubleshooting for empty context and missing captures.