Guide

Using the Kalmia SDK

Instrument a Python or TypeScript agent with the Kalmia SDK. Wrap your model client and every call is captured; use traced() to group a whole run into one trace.

Install

pip install kalmia
PythonZero external dependencies
TypeScriptAutomatic context propagation (AsyncLocalStorage)

Initialize & wrap

Call the initializer with your workspace API key (from Settings → API Keys, or the KALMIA_API_KEY env var), then wrap your OpenAI or Anthropic client. Every call is now traced.

from kalmia import init_logger, wrap_anthropic
import anthropic
init_logger(project_name="my-agent", api_key="kal_live_your_api_key", base_url="https://www.kalmia.dev")
client = wrap_anthropic(anthropic.Anthropic())

Group a run

Use traced() to capture a whole agent run — multiple calls, tools, and the full conversation — as one trace. Without it, each call is 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

Tool spans

Wrap tool executions with span_type="tool" so they appear alongside the model calls in the trace.

with traced(name="get_weather", span_type="tool") as span:
result = get_weather(city)
span.log(input={"city": city}, output=result)

Tag variants

Pass variant in the run metadata to compare versions of your agent in Metrics and Trends. Any label works.

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

See Capturing traces for OpenTelemetry and direct ingestion, and Concepts for the trace data model.