SDK Reference

Environments

Tag sessions with a customer environment — production, staging, development, or any custom label — so your analytics, session lists, and dashboards always show the right data by default.

Why environments?

Your agents run in multiple places: CI pipelines, staging servers, and production. Without environment tagging, all those sessions mix together in your analytics, which inflates cost figures and distorts quality metrics with test runs.

Niitaka solves this with a single environment field on every session. The dashboard defaults to production everywhere — sessions, analytics, and agent views — so you always see real data unless you opt in to seeing more.

Setting the environment

Option A — environment variable (recommended)

Set NIITAKA_ENV in the process running your agent. The SDK reads it automatically and stamps every session. No code changes needed.

# In your agent process (or .env file)
NIITAKA_ENV=production   # default; can be omitted

# For a staging agent
NIITAKA_ENV=staging

# For local development
NIITAKA_ENV=development

Option B — explicit parameter

Pass environment directly to start_session() to override the env var. Useful when one process runs sessions across multiple environments.

import niitaka

# Explicit override — takes precedence over NIITAKA_ENV
with niitaka.start_session(
    goal="Analyse customer churn",
    agent_id="churn-analyser",
    environment="staging",
) as session:
    ...

Resolution order

• Explicit environment= argument → highest priority
• NIITAKA_ENV environment variable
• Default: production (if neither is set)

Common patterns

Docker / docker-compose

# docker-compose.yml
services:
  agent:
    image: my-agent:latest
    environment:
      NIITAKA_API_KEY: ${NIITAKA_API_KEY}
      NIITAKA_ENV: production

GitHub Actions

# .github/workflows/test.yml
- name: Run agent tests
  env:
    NIITAKA_ENV: development
  run: python agents/my_agent/run.py

Custom environments

The field is a free-form string — you can use any label that fits your workflow: canary, load-test, shadow, preview. The dashboard filter accepts any value, not just the preset options.

Dashboard behavior

Both the Sessions page and the Analytics page default their environment filter to production. Change the dropdown to All Envs to see every environment at once, or pick a specific one to isolate it.

• Sessions page — environment filter in the filter bar. Non-production sessions show an amber badge in the Variant column so they stand out when viewing all environments.
• Analytics page — environment picker next to the date range. Defaults to production so cost and quality charts reflect real traffic, not CI noise.