SDK Quickstart

Add agent monitoring in 2 lines of code. No config files.

Install the SDK

terminal

pip install clevagent

Add 2 Lines to Your Agent

your_agent.py

# Add these 2 lines at agent startup

import os, clevagent

clevagent.init(api_key=os.environ["CLEVAGENT_API_KEY"], agent="my-agent")

# That's it. ClevAgent now:

# - Pings heartbeat every 60s in a background thread

# - Detects if process dies → fires alert → restarts container

# - Tracks token costs if auto_cost=True (default)

Get your API key from Dashboard → Settings.

Watch the Dashboard

Go to clevagent.io/dashboard. Your agent will appear automatically on the first heartbeat. No manual registration needed.

New agents are created automatically via upsert on first ping — just give them a unique agent name.

init() Options

Parameter	Default	Description
api_key	required	Your project API key (starts with `cv_`)
agent	required	Unique agent name within your project
interval	60	Heartbeat interval in seconds (min based on your tier)
auto_cost	True	Auto-capture token usage from OpenAI/Anthropic SDK calls
container_id	None	Docker container ID for auto-restart on death

Manual Cost Logging

If auto_cost doesn't work with your SDK version, log costs manually:

# Log cost after each LLM call

clevagent.log_cost(

tokens=1500,

cost=0.045,

tool_calls=3,

iteration_count=42

)

Capability Matrix

What works automatically vs. what requires manual configuration:

Feature	Auto	Manual	Not supported
Heartbeat	✅ 2 lines	—	—
Cost tracking	✅ OpenAI / Anthropic	`log_cost()` for others	—
Auto-restart	✅ Docker (set `container_id`)	—	Non-Docker
Loop detection	✅	—	—

Heartbeat API (Direct)

You can also send heartbeats directly without the SDK:

Method	Path	Auth
POST	/api/v1/heartbeat	X-API-Key header
POST	/api/v1/heartbeat/batch	X-API-Key header
GET	/api/v1/status	X-API-Key header

# Request body

{

"agent": "my-agent",

"status": "ok", // "ok" | "warning" | "error"

"tokens_used": 1500,

"cost_usd": 0.045,

"tool_calls": 3,

"iteration_count": 42

}

# Success response (200)

{

"received": true,

"agent_id": 7,

"status": "healthy"

}

Status	Meaning
200 OK	Heartbeat received
401	Invalid or missing API key
422	Validation error (missing required field)
429	Rate limit exceeded — check `Retry-After` header

Rate limit: 200 req/min (Free) · 500 (Starter) · 1,000 (Pro) · 10,000 (Enterprise) per API key

Pagination (status endpoint): ?limit=N&offset=M — default 100, max 1000

Alert Channels

Email — Enabled by default for all plans. Alerts go to your account email.
Slack (Starter+) — Set your webhook URL in Dashboard → Settings → Slack Webhook.
Discord (Starter+) — Same as Slack. Dashboard → Settings → Discord Webhook.
PagerDuty (Enterprise) — Contact support to configure.

Data Retention

Plan	History
Free	7 days
Starter	30 days
Pro	90 days
Enterprise	1 year

Questions? Email support@clevagent.io