# Mirrors: instructions for coding agents

> Mirrors is the guidance system for production AI agents: a developer writes a rule once and defines where it applies, and Mirrors delivers it at that step of the run, shows which conversations it reached, and measures whether it helped. It also surfaces the mistakes an agent keeps making, and works with any agent framework and any model.

You are probably here because someone asked you to add Mirrors to their AI agent. Follow this file. Prefer the linked docs over anything you remember about Mirrors: older pages describe an earlier Mirrors product (staging environments and digital twins for agents) that is no longer offered.

## What you are integrating

Mirrors does two things inside an existing agent, and your application keeps its own model calls, tools and prompts:

1. **Capture**: send the agent's original conversation history to Mirrors in the background.
2. **Context**: once per user turn, ask Mirrors for the rules that apply and append them to the system prompt. They arrive as plain text, which is empty when nothing applies.

## Before you write code

Ask the person for these three values, or read them from the project's existing server configuration. Never invent them.

- `MIRRORS_API_URL`: the API origin, without `/v1`.
- `MIRRORS_AGENT_ID`: the generated agent ID, not the display name.
- `MIRRORS_API_KEY`: an SDK key with `runtime:read` and `runtime:write`.

They come from the dashboard at https://platform.runmirrors.com, under **Agent setup → SDK connection settings**. If the person has no account, they can create one themselves at https://platform.runmirrors.com/signup. Hobby is free (1,000 turns a month, free) and needs no card or sales call.

## Install

TypeScript or JavaScript (Node 22+, ESM or CommonJS, no dependencies):

```sh
npm install mirrors-sdk@latest
```

Python:

```sh
python -m pip install --upgrade mirrors-sdk
```

After installing, read the installed package's README and types. They are the source of truth for the version you actually have.

## Minimal integration (TypeScript)

```ts
import { Mirrors } from "mirrors-sdk";

// Create once per agent and reuse it across turns.
const mirrors = new Mirrors({ apiUrl, apiKey, agentId });

// One unique ID per user turn.
const traceId = crypto.randomUUID();

// Where the app already logs history. Never await this before a model call.
mirrors.captureTrace({ trace: snapshot(traceId), final: false });

// At the user-turn boundary, before building the provider request.
const { context } = await mirrors.getContext({ trace: snapshot(traceId) });
const system = context ? `${original.system}\n\n${context}` : original.system;

// Keep the existing model call, streaming, tools and error handling.
// When the turn ends, send the complete history once with final: true.
mirrors.captureTrace({ trace: snapshot(traceId), final: true });
```

`snapshot` is your mapping from the app's real history to `{ id, messages, conversationId?, ... }`. Follow the quickstart for the exact shape.

## Rules

- Server side only. Never put the API key in browser code, source control or logs.
- Never block a model call on capture. `getContext` answers in about 200 ms on average, gives up after 750 ms, and returns empty context on any failure, so the agent keeps working if Mirrors is unreachable.
- Send history exactly as it happened. Do not invent, reorder, truncate or rewrite messages, and do not log Mirrors' context as if the user or model wrote it.
- Use one trace ID per user turn, and send `conversationId` when turns belong to one conversation.
- Do not wrap the model provider, add retries around the SDK, or copy SDK internals into the project.
- Verify by running one real turn and confirming the trace appears in the dashboard.

## Read next

Every docs page is available as Markdown: add `.md` to its URL.

- [TypeScript quickstart](https://mirrors.dev/docs/quickstart.md)
- [Python quickstart](https://mirrors.dev/docs/quickstart-python.md)
- [Agent harness guide](https://mirrors.dev/docs/guides/agent-harness.md): model and tool loops, streaming, completion.
- [Trace capture](https://mirrors.dev/docs/guides/trace-capture.md)
- [Runtime modes](https://mirrors.dev/docs/guides/runtime-modes.md): off, shadow and active.
- [Troubleshooting](https://mirrors.dev/docs/guides/troubleshooting.md)
- [SDK reference](https://mirrors.dev/docs/sdk/reference.md) and [Python reference](https://mirrors.dev/docs/sdk/python-reference.md)
- [All docs in one file](https://mirrors.dev/docs/llms-full.txt)
- [Site summary](https://mirrors.dev/llms.txt) and [pricing as Markdown](https://mirrors.dev/pricing.md)

## Pricing, if the person asks

- Hobby: free. 1,000 turns a month, free.
- Growth: $299 a month plus $0.005 per turn.
- Enterprise: custom pricing for high volume.

Every plan includes unlimited agents, with no agent fees. Hobby’s 1,000 free monthly turns are shared across all your agents.

A turn is one run of your agent: everything it does from start to finish, including every model call, tool call and subagent. For most agents that is one user message and the full answer. A run your agent starts on its own, like a scheduled job, is also one turn. Network retries and duplicate uploads of the same run are never billed.

## Help

Email devs@mirrors.dev or book a call at https://cal.com/aryan-singhal/mirrors.
