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

# Connect your first agent

> Install the SDK, register your agent with Ratri, and send your first telemetry event.

You want to confirm Ratri is receiving events from your agent before you instrument real workloads. When you finish this page, your agent will be registered, a test event will be in the dashboard, and you'll have a session replay URL to inspect.

## Install

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @ratri-sh/sdk
  npm install -D @ratri/cli
  ```

  ```bash Python theme={null}
  pip install ratri-sdk
  ```
</CodeGroup>

## Set your API key

Get a project key from the [Ratri dashboard](https://ratri.sh). Add it to your environment:

```env theme={null}
RATRI_API_KEY=ratri_sk_test_...
RATRI_BASE_URL=https://api.ratri.sh
```

<Note>
  For local development against a self-hosted Ratri instance, set `RATRI_BASE_URL` to your API host (default is `http://localhost:3000`).
</Note>

## Initialize your project

The CLI scaffolds a config file and `.env` template:

<CodeGroup>
  ```bash TypeScript theme={null}
  npx ratri init
  ```

  ```bash Python theme={null}
  ratri init
  ```
</CodeGroup>

This creates:

* `ratri.config.ts` (TypeScript) or `ratri.config.py` (Python) — agent identity and SDK settings
* `.env.example` — copy to `.env` and fill in your API key

## Wire the SDK

Export a configured client from your config file. One client per process — like Sentry.

<CodeGroup>
  ```ts ratri.config.ts theme={null}
  import { Ratri } from "@ratri-sh/sdk";

  const ratri = new Ratri({
    apiKey: process.env.RATRI_API_KEY,
    agent: {
      key: "my-agent",
      name: "My Agent",
    },
    runtime: {
      environment: process.env.NODE_ENV ?? "development",
      framework: "custom",
      language: "typescript",
    },
    mode: "monitor",
  });

  export default ratri;
  ```

  ```python ratri.config.py theme={null}
  from ratri import Ratri

  ratri = Ratri.create({
      "agent": {
          "key": "my-agent",
          "name": "My Agent",
      },
      "runtime": {
          "environment": "development",
          "framework": "custom",
          "language": "python",
      },
      "mode": "monitor",
  })
  ```
</CodeGroup>

In your agent entrypoint, wait for registration to complete:

<CodeGroup>
  ```ts main.ts theme={null}
  import ratri from "./ratri.config";

  await ratri.ready();
  // Agent is registered — start instrumenting
  ```

  ```python main.py theme={null}
  from ratri.config import ratri

  ratri.ready()
  # Agent is registered — start instrumenting
  ```

  ```python main_async.py theme={null}
  import asyncio
  from ratri import AsyncRatri

  async def main():
      ratri = await AsyncRatri.create({
          "agent": {"key": "my-agent", "name": "My Agent"},
      })
      await ratri.ready()
      # Agent is registered

  asyncio.run(main())
  ```
</CodeGroup>

### What you'll see

After `ready()` resolves, Ratri has called `POST /v1/agents/identify`. Your agent appears in the dashboard with an `agentId` and `agentVersionId`.

## Send a test event

Verify the full pipeline with a smoke test:

<CodeGroup>
  ```bash TypeScript theme={null}
  npx ratri send-test-event
  npx ratri send-test-event --mode proof
  # pipeline smoke test (default)
  npx ratri send-test-event --mode single
  ```

  ```bash Python theme={null}
  ratri send-test-event
  ratri send-test-event --mode proof
  ratri send-test-event --mode single
  ```
</CodeGroup>

The **pipeline** mode simulates a realistic session: orchestrator run, LLM call, workflow step, tool call, guard evaluation, handoff, child run, and worker tool. The **proof** mode adds activation-proof evidence for a safe production-like action. The **single** mode sends one minimal tool call.

### What you'll see

The CLI prints a **session replay URL**. Open it in your browser to walk through the simulated session timeline.

## Run diagnostics

If something doesn't look right:

<CodeGroup>
  ```bash TypeScript theme={null}
  npx ratri doctor
  npx ratri doctor --send-test
  ```

  ```bash Python theme={null}
  ratri doctor
  ratri doctor --send-test
  ```
</CodeGroup>

`doctor` checks your config, registration status, queue health, and event validation.

## Next steps

<CardGroup cols={2}>
  <Card title="Choose how to instrument" icon="route" href="/getting-started/choose-how-to-instrument">
    Pick MCP proxy, framework plugin, or explicit instrumentation.
  </Card>

  <Card title="Trace runs and sessions" icon="timeline" href="/observe/trace-runs-and-sessions">
    Wrap your agent work so every request creates a run.
  </Card>
</CardGroup>