Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kensa.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Auto-instrumentation

Zero code changes. kensa auto-instruments your agent at startup. Install the extra for your provider: 
uv add "kensa[anthropic]"    # Anthropic
uv add "kensa[openai]"       # OpenAI
uv add "kensa[langchain]"    # LangChain
uv add "kensa[all]"          # Everything

​
What gets captured

Each scenario runs in its own subprocess. kensa captures traces as JSONL and translates them to its internal format. Traces include:
  • LLM calls (model, tokens, cost, latency)
  • Tool invocations (name, arguments, results)
  • Span hierarchy (parent/child relationships)

​
Passive trace collection

Use kensa capture to record one real agent invocation as a trace, without writing a scenario first: 
kensa capture -i "<example input>" -- python my_agent.py
kensa capture runs your agent in a subprocess with KENSA_TRACE_DIR set and the runner’s sitecustomize.py injected via PYTHONPATH, so instrumentation happens automatically. Feed the resulting trace into kensa generate to synthesize scenarios grounded in real inputs. For environments where the runner can’t inject sitecustomize (non-Python entry points, python -S, embedded interpreters), call instrument() from your agent code as an escape hatch: 
from kensa import instrument
instrument()
Then set KENSA_TRACE_DIR=traces/ before invoking the process.

​
OTel compatibility

Spans are standard OpenTelemetry, so anything that reads OTel spans can read them. kensa writes them as JSONL locally, which is what kensa run and kensa analyze consume.

​
Cache-aware cost tracking

kensa reads cache_read token counts from spans and subtracts them from prompt token costs. Each scenario’s cost reflects actual token usage, not cached replay. Cached tokens are tracked separately in the TokenCounts model and visible in reports.
Last modified on May 1, 2026