Agent Management

Agents are the top-level entity in Kurral. Every session, scan, and metric is tied to an agent. Register your agents, track their health, and manage configuration via the dashboard or API.

---

Registering an Agent

Dashboard

1. Go to Agents in the sidebar
2. Click Register Agent
3. Fill in: - Agent key (required) — immutable slug, minimum 3 characters (e.g., support-bot). This is what you pass in the x-kurral-agent header. - Description — what the agent does - Model — the LLM model (for labeling; does not affect proxy routing) - Environment — production, staging, or development
4. Click Register

Note: The agent key cannot be changed after creation. Choose a descriptive, stable slug.

API

curl -X POST https://kurral-api.onrender.com/api/web/agents \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "support-bot",
    "description": "Customer support agent",
    "model": "claude-sonnet-4-5",
    "environment": "production"
  }'

Auto-Registration via Proxy

When you send an LLM call through the proxy with an x-kurral-agent header that doesn't match an existing agent, Kurral automatically creates the agent for you.

---

Agent Detail View

Each agent has four tabs:

Overview

• Health score (0-100) — calculated from success rate, latency, and error frequency
• Status — healthy, degraded, critical, offline, or inactive
• Sessions chart — 7-day session volume with real data
• Configuration — agent key, ID, model, environment
• Recent sessions — last 5 sessions with status and timing

Sessions

Full list of agent sessions with:

• Status (completed, running, failed, blocked)
• Duration
• Token count
• Tool calls
• Model used
• Timestamp

Click any session to open the Flight Recorder view.

Secure

Security scan history for this agent:

• Security score trend
• Finding counts by severity
• Run Scan button to trigger a new scan
• Click any scan to see detailed findings

Settings

• Edit display name and description
• Change model label and environment
• Copy agent ID and agent key
• Delete agent

---

Health Score

The health score (0-100) is calculated from the agent's recent performance:

---

Agent Metrics

Access metrics for any agent via the dashboard or API:

# Get 7-day metrics
curl https://kurral-api.onrender.com/api/web/agents/{agent_id}/metrics?days=7 \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"

Response:

{
  "period_days": 7,
  "total_sessions": 142,
  "total_tokens": 89420,
  "total_cost": 1.2340,
  "avg_latency_ms": 1250,
  "p50_latency_ms": 980,
  "p90_latency_ms": 2100,
  "p99_latency_ms": 4500,
  "avg_security_score": 78.5,
  "total_scans": 3,
  "daily_breakdown": {
    "2025-01-08": {"count": 18, "tokens": 12400, "cost": 0.18},
    "2025-01-09": {"count": 22, "tokens": 14200, "cost": 0.21}
  }
}

---

API Reference

All /api/web/ endpoints require Clerk JWT authentication.