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 kalmia2. 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, tracedimport 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.
Next steps
Tag runs and read the side-by-side comparison.
Define the behaviors you care about and find the runs that show them.
What each number in the per-variant table means.
Every endpoint, with auth modes and rate limits.