Observability
Sessions
A session is the top-level unit of agent execution in Niitaka. Every time your agent runs — from the first API call to the final output — one session captures the full trace: goals, costs, events, errors, and outcome metrics.
Session lifecycle
A session moves through three states. There is no error state.
running
- Session open
- Events streaming in
- Cost accumulating
done
- Context manager exited
- Metrics finalised
- Cost locked
stale
- No heartbeat for 5 min
- Auto-closed by server
- error_count unchanged
status = 'error'. To detect failed runs, check error_count > 0 instead.Key fields
running while active · done on clean exit · stale if no heartbeat for 5 minutesStarting a session
Use the start_session() context manager. The session is opened on entry and closed automatically on exit — even if the agent raises an exception.
import niitaka
with niitaka.start_session(
goal="Summarise the weekly sales report",
agent_id="report-summariser",
) as session:
result = run_agent(report_text)
session.set_metrics({
"goal_completed": result.success,
"score": result.quality, # float 0–1
})Child sessions
Pass parent_session_id to link a sub-session to its parent. The Dashboard renders these as a collapsible tree so you can trace multi-agent orchestration flows end-to-end.
# Top-level session
with niitaka.start_session(
goal="Process customer support ticket",
agent_id="support-router",
) as parent:
intent = classify_intent(ticket)
# Sub-session linked to the parent
with niitaka.start_session(
goal="Draft reply for billing query",
agent_id="reply-drafter",
parent_session_id=parent.session_id,
) as child:
reply = draft_reply(ticket, intent)
child.set_metrics({"goal_completed": reply is not None})Detecting errors programmatically
# Do NOT check session.status == 'error' — sessions never have that status.
# Instead, check error_count:
sessions = niitaka_api.list_sessions(agent_id="report-summariser")
failed = [s for s in sessions if s["error_count"] > 0]Sessions dashboard
The Sessions page gives you a real-time view of all runs in your organisation.
Total Sessions
Count for the selected date range.
Running
Sessions currently open (live count).
Total Cost
Summed LLM spend across all sessions.
Unique Agents
Distinct agent IDs seen in the range.
Filtering and search
- Date range — presets for last 24 h, 7 d, 30 d, or a custom range.
- Status — filter to running, done, or stale sessions.
- Agent — scope the list to a single agent ID.
- Search — full-text match against the session goal.
Tree view
Sessions with parent_session_id set are rendered as a collapsible subtree under their parent. Expand a row to see all child sessions without leaving the list. Depth is limited to prevent runaway recursion in deeply nested orchestrators.
Session drawer
Click any row to open the session drawer. It shows the event timeline, cost breakdown, signals fired during the run, and the decision traces from the policy engine.
Export
Use the Export button to download the current filtered view as CSV. Useful for offline analysis or sharing a slice of sessions with your team.
Live updates
The session list streams updates in real time via Server-Sent Events (SSE). New sessions appear at the top, and running sessions update their cost and status without a page refresh.
Next steps
- Agent Dashboard — monitor agent health and manage lifecycle across all agents.
- Signals & Alerts — see what the policy engine emitted during each session.
- Experiments — attach sessions to A/B experiments and compare variants.