Documentation

Everything you need to integrate, trace, and evaluate your AI agents with KATE.

Quick Start

Get up and running in under 5 minutes with the KATE CLI or API.

Using the CLI

# Install the CLI
pip install kate

# Register and get your API key
kate register --name "Your Name" --email "you@example.com"

# Create an agent
kate agent create --name "My Agent" --domain "customer-support" \
  --description "Handles customer inquiries"

# Feed it knowledge
kate agent feed <agent_id> --file knowledge.txt

# Run an evaluation
kate eval run <agent_id>

Using the API

# Create an agent
curl -X POST https://api.kate.dev/agents \
  -H "X-API-Key: kate_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "domain": "support", "description": "Handles inquiries"}'

Core Concepts

Two Tracing Methods

KATE supports two ways to capture agent execution traces. Every framework integration uses one of these.

	KATE Auto-Tracing	KATE Manual Tracing
How	Your agent emits traces automatically via the KATE SDK	You POST spans to KATE's API after each run
Best for	Frameworks with built-in support (LangChain, LlamaIndex, CrewAI, PydanticAI, OpenAI Agents SDK, Google ADK)	Custom agents, lightweight setups, any framework
Setup	Install SDK + one-line init	Call 3 API endpoints per run
Trace detail	Automatic: captures every LLM call, retrieval, tool use	Manual: you decide what to capture

Agent Run Lifecycle

Every agent execution follows this lifecycle:

1. Create Run  →  POST /agents/{agent_id}/runs
2. Execute     →  Your agent does its work (traces captured via Auto or Manual tracing)
3. Complete    →  POST /agents/{agent_id}/runs/{run_id}/complete
4. Auto-Eval   →  KATE automatically evaluates the run in the background

Scoring

KATE produces an auto-eval score (0–100) based on a weighted average across quality, safety, task, performance, and knowledge metrics. When user ratings exist, a composite score blends 60% auto-eval with 40% user ratings.

Authentication

API Key (recommended for agents & scripts)

curl -H "X-API-Key: kate_yourkey" https://api.kate.dev/agents

Bearer Token (JWT)

curl -H "Authorization: Bearer eyJhbG..." https://api.kate.dev/agents

Google OAuth (for the dashboard)

Navigate to the login page and sign in with Google. A JWT is set as a session cookie automatically.

Getting an API Key

Via CLI:

kate register --name "Your Name" --email "you@example.com"
# API key is printed once and saved to ~/.kate/config.json

Via API:

curl -X POST https://api.kate.dev/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@example.com"}'
# Response includes api_key (shown only once)