Skip to main content
An AGENTS.md file in your project root teaches AI coding agents (Claude Code, Cursor, Copilot) how to interact with Cekura for your specific project. Copy the template below and customize it.

​
Template

Copy this into AGENTS.md at your project root: 
# Cekura Voice Agent Testing

This project uses [Cekura](https://cekura.ai) for testing and monitoring AI voice agents.

## MCP Connection

Cekura is available via MCP. Add the server if not already configured:

```bash
claude mcp add --transport http cekura --scope user https://api.cekura.ai/mcp --header "X-CEKURA-API-KEY:YOUR_API_KEY"
```

## Key Concepts

| Term | Definition |
|------|-----------|
| **Agent** | A voice AI system being tested or monitored (maps to your provider: Retell, VAPI, ElevenLabs, etc.) |
| **Evaluator** (Scenario) | A test case that simulates a caller conversation with specific instructions and expected outcomes |
| **Metric** | A quality criterion scored against call transcripts (LLM-judge prompt, Python code, or predefined) |
| **Result** | A test run grouping multiple evaluator executions against an agent |
| **Run** | A single evaluator execution within a result, containing transcript, scores, and recording |
| **Call Log** | A production call captured via observability webhooks |
| **Personality** | A caller behavior profile (speaking style, patience, tone) attached to evaluators |
| **Test Profile** | Caller persona context (demographics, background) used during evaluations |

## Common Workflows

### Run regression tests
1. List agents: `list-agents`
2. Run scenarios: `scenarios-run-scenarios-create` with the agent ID and scenario IDs
3. Check results: `results-list` filtered by agent

### Create metrics from agent description
1. Get agent details: `aiagents-retrieve`
2. Generate metrics: `metrics-generate-metrics-create` with the agent ID

### Review production call quality
1. List recent calls: `call-logs-list` with date filters
2. Evaluate specific calls: `call-logs-evaluate-metrics-create`

### Create evaluators from real calls
1. Find interesting calls: `call-logs-list`
2. Generate scenarios: `call-logs-create-scenarios-create`

## Project-Specific Details

<!-- Customize below for your project -->

- **Agent ID**: `YOUR_AGENT_ID`
- **Project ID**: `YOUR_PROJECT_ID`
- **Provider**: Retell / VAPI / ElevenLabs / LiveKit / Pipecat
- **Key metrics**: List your most important metrics here

## Documentation

- [Cekura Docs](https://docs.cekura.ai)
- [API Reference](https://docs.cekura.ai/api-reference)
- [MCP Setup](https://docs.cekura.ai/mcp/overview)

​
Customization Tips

Replace YOUR_AGENT_ID and YOUR_PROJECT_ID with actual values so the AI agent can immediately start working without asking for IDs.
Add the names and IDs of your most important metrics. This helps the agent prioritize which metrics to check when reviewing results.
If your agent uses domain-specific terms (e.g., “booking flow”, “escalation protocol”), define them so the AI assistant understands your context.
Include step-by-step workflows specific to your team, like “How to investigate a failed regression test” or “How to onboard a new agent.”