Get Started

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.

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.

pip install kalmia

2. Wrap your LLM client

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

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())

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.

@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?")

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.

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

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