# Quickstart Guide

Get up and running with Kalmia in under 5 minutes.
Instrument your agent, run it, and your first trace appears in the dashboard within seconds.

## Using a coding agent?

Paste this prompt into Claude Code, Cursor, Codex, or any agent that can fetch a URL, with your API key filled in.
It reads `/setup.md`, picks the right integration for your repo, makes the change, and verifies the first trace arrived before reporting back.

```text
Read https://www.kalmia.dev/setup.md and follow it to set up Kalmia tracing in this repository. Use the API key kal_live_your_api_key. Store the key only in the repository's local env file; never echo it or include it in your final response. Finish by verifying a trace arrived and setting up digests (Step 8), as the instructions describe.
```

The same procedure is available as an agent skill at `/skills/kalmia-setup/SKILL.md`.
Save it as `.claude/skills/kalmia-setup/SKILL.md` (or your agent's equivalent) and it triggers whenever you ask the agent to add tracing.

## 1. Install the SDK

Prefer to do it by hand?
Install the Kalmia SDK for your language.

Python:

```bash
pip install kalmia
```

TypeScript:

```bash
npm install kalmia-sdk
```

## 2. Wrap your LLM client

Initialize the logger and wrap your OpenAI or Anthropic client.
Every LLM call is now automatically traced.

```python
from kalmia import init_logger, wrap_anthropic, traced
import anthropic

init_logger(
    api_key="kal_live_your_api_key",  # required — or set KALMIA_API_KEY
    base_url="https://www.kalmia.dev",
)

client = wrap_anthropic(anthropic.Anthropic())
```

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { initLogger, wrapAnthropic, traced } from "kalmia-sdk";

initLogger({
  apiKey: "kal_live_your_api_key", // required — or set KALMIA_API_KEY
  baseUrl: "https://www.kalmia.dev",
});

const client = wrapAnthropic(new Anthropic());
```

## 3. Trace an agent run

Use `traced()` to group multiple LLM calls into a single trace.
Without it, each call creates its own standalone trace.

```python
@traced(name="my-agent-run")
def run(prompt):
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.content[0].text

run("What is the capital of France?")
```

```typescript
await traced(async (span) => {
  const response = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: "What is the capital of France?" }],
  });
  return response.content[0].text;
}, { name: "my-agent-run" });
```

## 4. Compare variants with metadata

To compare variants (e.g. RAG vs no-RAG), tag each run with metadata and Kalmia groups and diffs them for you in the dashboard - no extra API call needed.

```python
with traced(name="my-agent-run", metadata={"variant": "rag"}) as span:
    # ... run your agent variant ...
    span.log(output=result)
```

```typescript
await traced(async (span) => {
  // ... run your agent variant ...
}, { name: "my-agent-run", metadata: { variant: "rag" } });
```

## 5. View your traces

Open Kalmia in your browser.
You'll see your traces preprocessed with metrics computed automatically - duration, tokens, tool calls, and more.

> The dashboard updates in real time - new traces appear the moment they are ingested, no refresh needed. Launch your agent variants and watch results stream in live.

## Next steps

- [Compare agent variants](https://www.kalmia.dev/docs/guides/comparing-variants.md): Tag runs and read the side-by-side comparison.
- [Set up behavior detection](https://www.kalmia.dev/docs/guides/behavior-detection.md): Define the behaviors you care about and find the runs that show them.
- [Understand variant metrics](https://www.kalmia.dev/docs/guides/variant-metrics.md): What each number in the per-variant table means.
- [Explore the API reference](https://www.kalmia.dev/docs/api-reference.md): Every endpoint, with auth modes and rate limits.
