> ## Documentation Index
> Fetch the complete documentation index at: https://usereflect.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript quickstart

> Connect Reflect and prepare the prompt for one turn of your existing agent.

This quickstart uses **Node.js 22 or later** and the published `reflect-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](https://usereflect.dev/docs/quickstart-python.md) or
[Ruby](https://usereflect.dev/docs/quickstart-ruby.md) quickstart.

You will add background capture and optional context retrieval. Then follow the
[agent harness guide](https://usereflect.dev/docs/guides/agent-harness.md) to connect your model/tool loop,
streaming, and completion hooks.

## 1. Copy your agent's connection settings

No account yet? [Sign up free](/signup); the Hobby plan
needs no card. Working with a coding agent? Point it at
[usereflect.dev/agents.md](https://usereflect.dev/agents.md).

Open your agent in the [Reflect 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 with `runtime:read` and `runtime:write`
permissions. Store the three values in your server configuration:

```sh theme={null}
REFLECT_API_URL=your-api-origin
REFLECT_AGENT_ID=your-generated-agent-id
REFLECT_API_KEY=your-sdk-key
```

Use the API origin, without `/v1` or a runtime route. Keep the key out of browser
bundles, source control, and logs. Use [connection troubleshooting](https://usereflect.dev/docs/guides/troubleshooting.md#connection-settings-are-rejected)
if the selected environment, agent ID, or key scope is uncertain.

## 2. Install and create a shared client

```sh theme={null}
npm install reflect-sdk@latest
```

Create one client per agent configuration and reuse it across turns. For example,
put this in your server's `reflect.ts` module:

```ts theme={null}
import { Reflect } from "reflect-sdk";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export const reflect = new Reflect({
  apiUrl: requiredEnv("REFLECT_API_URL"),
  agentId: requiredEnv("REFLECT_AGENT_ID"),
  apiKey: requiredEnv("REFLECT_API_KEY"),
});
```

## 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 a
[`CanonicalTrace`](https://usereflect.dev/docs/guides/trace-capture). 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:

```ts theme={null}
import type { CanonicalTrace } from "reflect-sdk";
import { reflect } from "./reflect.js";

export async function prepareTurnPrompt(
  baseSystem: string,
  originalTrace: CanonicalTrace,
  signal: AbortSignal,
): Promise<string> {
  reflect.captureTrace({ trace: originalTrace, final: false });

  const result = await reflect.getContext(
    { trace: originalTrace },
    { signal, timeoutMs: 1000 },
  );
  signal.throwIfAborted();

  return result.context ? `${baseSystem}\n\n${result.context}` : baseSystem;
}
```

Use the returned system prompt immediately for the next model call. Keep `baseSystem`
and stored history unchanged so future captures contain only original evidence.
The [harness guide](https://usereflect.dev/docs/guides/agent-harness.md) 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](https://usereflect.dev/docs/guides/agent-harness.md):

* **Original-history updates:** preserve actual responses, tool calls, and tool
  results in order; capture full snapshots without injected context.
* **Execution completion:** send `final: true` after the model/tool loop and stream
  finish, including failure and cancellation endings.
* **Process shutdown:** stop admitting turns, await a bounded `flush`, inspect
  delivery counts, then `dispose` the shared client.

For a chat spanning several user turns, each execution gets a new trace ID. Use
the [conversation identity rules](https://usereflect.dev/docs/guides/trace-capture.md#conversation-identity) to
group those executions under a durable chat ID.

## 5. Verify in shadow mode

Start in [shadow mode](https://usereflect.dev/docs/guides/runtime-modes.md). Run a representative test conversation,
inspect its final capture receipt, and confirm the conversation appears in Reflect.
`accepted` with ingestion `queued` means analysis was queued, not completed.

Then [review a correction](https://usereflect.dev/docs/guides/corrections.md), 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](https://usereflect.dev/docs/guides/agent-harness.md#verify-the-integration).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.