SDK Reference
Core Concepts
Four building blocks underpin everything in Niitaka: Sessions, Events, Policies, and Runtime Config. Understanding these makes the rest of the SDK and dashboard obvious.
Session
A session is one complete run of your agent — everything from start to finish, scoped to your organisation.
- Created by start_session() and closed when the context manager exits.
- Tracks total cost, total tokens, error count, duration, and status.
- Status is always running or completed — never "error". Detect errors via error_count > 0.
- Every event inside the session is linked to it via session_id.
python
with niitaka.start_session(
goal="Analyse customer churn",
agent_id="churn-analyser",
) as session:
# your agent code here
pass
# Access session ID if needed
print(session.session_id)Event
Events are the structured log entries that make up a session — one per LLM call, tool invocation, or decision.
- Captured automatically by instrumentation — you never write event logs by hand.
- Events can be nested: a tool call event can have child LLM call events.
- Real latency lives in data.meta.latency (seconds). The duration_ms field is always 0 — ignore it.
- Event types: llm, tool, decision, error.
python
# Events are captured automatically — you don't log them manually.
# Every instrumented LLM call becomes an event like:
{
"type": "llm",
"data": {
"model": "gpt-4o",
"prompt_tokens": 512,
"completion_tokens": 128,
"cost_usd": 0.00384,
"meta": {
"latency": 1.43 # seconds — always read from here
}
}
}Policy
Policies are rules the Niitaka backend evaluates in real time as events arrive — without any code changes.
- Configured in the dashboard (or via YAML file), versioned, and audited.
- Policy types: cost_limit, step_limit, retry, fallback.
- Actions: warn, abort, retry, fallback (switch to a different model).
- Policies apply per-agent and execute in priority order.
python
# Policies are configured in the Niitaka dashboard, not in code.
# Example policy shape (YAML):
- type: cost_limit
condition:
threshold_usd: 0.50
action: abort
priority: 1
- type: retry
condition:
on_errors: ["rate_limit_error", "timeout"]
action:
max_retries: 3
backoff_seconds: 2
priority: 2Runtime Config
Runtime config lets the backend push model, prompt, and guardrail settings to your agent at session start — no redeploy needed.
- Schema: { llm: { model, temperature, max_tokens, system_prompt }, guardrails: { cost_limit_usd, max_steps, ... } }
- Three sources in priority order: active experiment variant, pinned agent version, live policies.
- Fetched automatically by start_session(), or explicitly via get_runtime_config().
- Lets you change model or prompt for all running agents from the dashboard instantly.
python
# SDK auto-fetches config at session start — or call explicitly:
config = niitaka.get_runtime_config(agent_id="my-agent")
model = config["llm"]["model"]
temperature = config["llm"]["temperature"]
system_prompt= config["llm"]["system_prompt"]
cost_limit = config["guardrails"]["cost_limit_usd"]Was this page helpful?