Documentation

Kairos Trace

Record and replay every autonomous action. Install the SDK, instrument your agent, and replay execution in the dashboard within minutes.

Install

TypeScript / JavaScript

bash

npm install kairos-sdk

Python

bash

pip install kairos-trace

Quick Start

Three steps: create an execution, record events, complete it. Every execution is immediately replayable in the dashboard.

TypeScript

typescript

import { createKairos } from 'kairos-sdk'

const kairos = createKairos()
// Optional: createKairos({ baseUrl: 'http://localhost:8000' })

const exec = kairos.execution({ workflowName: 'my-agent' })

// Record what your agent does
exec.setPrompt('Summarise the Q3 earnings report', 'gpt-4o')
exec.toolCall({ name: 'read_file', input: { path: 'q3.pdf' }, output: { text: '...' }, latencyMs: 240 })
exec.decision('Revenue increased 18% YoY', 0.97)

await exec.complete('Q3 summary: Revenue up 18%...')

// Open /app to replay this execution

Python

python

from kairos import create_kairos

kairos = create_kairos()

exec = kairos.execution(workflow_name='my-agent')

exec.set_prompt('Summarise the Q3 earnings report', model='gpt-4o')
exec.tool_call('read_file', input={'path': 'q3.pdf'}, output={'text': '...'}, latency_ms=240)
exec.decision('Revenue increased 18% YoY', confidence=0.97)

exec.complete('Q3 summary: Revenue up 18%...')

Open the dashboard to see the execution and replay it.

Event Types

Record any of these events during execution. Each appears as a step in the replay timeline.

setPrompt(prompt, model?)The prompt sent to the model

setModel(model)The model used for this execution

toolCall({ name, input, output, latencyMs })Any tool or function called by the agent

decision(reasoning, confidence)A decision made by the agent (0–1 confidence)

policyCheck(policy, result)A governance policy that was evaluated

memoryWrite(key, value)Something written to agent memory

memoryRead(key)Something read from agent memory

setTokens(prompt, completion)Token usage for cost tracking

setCost(usd)Cost of this execution in USD

retry(reason)A retry was triggered

event(type, payload)Any custom event

complete(output)Execution completed successfully

fail(error)Execution failed with an error

Replay

Every execution is automatically replayable. No extra configuration needed.

Open the dashboard, select an execution, and use the replay controls to step through each event — forward, backward, or at any speed.

What replay shows you:

Every prompt sent to every model

Every tool called and its output

Every decision and its confidence score

Every policy that was evaluated

Every memory read and write

Total tokens, cost, and duration

Failures and retry attempts

API Reference

The Kairos API is available at:

bash

https://kairos-production-64c5.up.railway.app

Interactive docs (Swagger UI):

bash

https://kairos-production-64c5.up.railway.app/docs

Self-hosting

bash

git clone https://github.com/withkairos/kairos
cd kairos/kairos-core
pip install -r requirements.txt
# Set DATABASE_URL env var
uvicorn main:app --reload --port 8000

Then point your SDK at the local server:

typescript

const kairos = createKairos({ baseUrl: 'http://localhost:8000' })

Python SDK

bash

pip install kairos-trace

The Python SDK has zero required dependencies. It uses the standard library by default and switches to httpx automatically if installed.

python

from kairos import create_kairos

kairos = create_kairos(
    base_url='https://kairos-production-64c5.up.railway.app',  # default
    debug=False,
)

exec = kairos.execution(workflow_name='my-agent', agent_id='agent-1')

exec.set_prompt('Research EU AI Act', model='claude-sonnet-4-6')
exec.tool_call('web_search', input={'query': 'EU AI Act 2025'}, output={'results': [...]}, latency_ms=1200)
exec.decision('EUR-Lex most authoritative', confidence=0.93)
exec.memory_write('eu_act_summary', 'High-risk AI systems require...')
exec.set_tokens(prompt_tokens=312, completion_tokens=840)
exec.set_cost(0.0118)
exec.complete('Summary: ...')

Was this helpful?