cekura-create-agent
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCekura Create Agent
Cekura 创建Agent
Purpose
用途
Collect comprehensive context about a client's voice AI agent and set it up on Cekura — ready for testing and observability. This is an interactive, multi-step flow that creates the agent, configures provider integration, sets up mock tools, uploads knowledge base files, and adds dynamic variables.
收集客户语音AI Agent的全面上下文信息,并在Cekura平台上完成设置——使其可用于测试和可观测性。这是一个交互式的多步骤流程,涵盖创建Agent、配置提供商集成、设置模拟工具、上传知识库文件以及添加动态变量。
Performing Platform Actions
执行平台操作
When this skill suggests creating, listing, updating, or evaluating something on Cekura, prefer using available platform tools over describing API calls or dashboard steps. In Claude Code with the Cekura plugin installed, these tools are auto-configured and handle authentication, parameter validation, and error handling for you. Fall back to direct API endpoints or dashboard guidance only when no tools are available in the current session.
当此Skill建议在Cekura上创建、列出、更新或评估内容时,优先使用可用的平台工具,而非描述API调用或控制台步骤。在安装了Cekura插件的Claude Code中,这些工具已自动配置,可帮您处理身份验证、参数验证和错误处理。仅当当前会话中没有可用工具时,才退回到直接API端点或控制台指导。
How to Use This Skill
如何使用此Skill
This is an interactive collection-and-configuration flow. Walk the user through each phase:
- Collect information conversationally — ask for what you need, don't dump a form
- Perform each step via the Cekura API or dashboard
- Validate each step before moving to the next
- The user may already have some steps done — skip what's complete
这是一个交互式的信息收集与配置流程。请引导用户完成每个阶段:
- 以对话方式收集信息——按需询问,不要直接抛出表单
- 通过Cekura API或控制台执行每个步骤
- 进入下一阶段前验证当前步骤的完成情况
- 用户可能已完成部分步骤——跳过已完成的环节
Phase 1: Collect Agent Context
阶段1:收集Agent上下文
1.1 Basic Information
1.1 基础信息
Ask for these essentials:
- Agent name — Descriptive (e.g., "Customer Support Bot", "Scheduling Assistant")
- Project ID — Which Cekura project to add the agent to. If they don't know, list their projects first.
- Language — Primary language (default "en"). Supported: af, ar, bn, bg, zh, cs, da, nl, en, et, fi, fr, de, el, gu, hi, he, hu, id, it, ja, kn, ko, ms, ml, mr, multi, no, pl, pa, pt, ro, ru, sk, es, sv, th, tr, ta, te, uk, vi
- Inbound vs Outbound — Does the agent receive calls (, default) or make calls (
inbound: true)?inbound: false
询问以下必要信息:
- Agent名称——具有描述性(例如“客户支持机器人”“日程安排助手”)
- 项目ID——要添加Agent的Cekura项目。如果用户不清楚,先列出他们的所有项目。
- 语言——主要语言(默认值为“en”)。支持的语言:af, ar, bn, bg, zh, cs, da, nl, en, et, fi, fr, de, el, gu, hi, he, hu, id, it, ja, kn, ko, ms, ml, mr, multi, no, pl, pa, pt, ro, ru, sk, es, sv, th, tr, ta, te, uk, vi
- 呼入 vs 呼出——Agent是接收来电(,默认值)还是主动外呼(
inbound: true)?inbound: false
1.2 Agent Description (Critical)
1.2 Agent描述(关键)
The agent description is the most important field. It powers:
- Automatic evaluator generation
- Metrics that reference
{{agent.description}} - Topic/dropoff classification
- Hallucination detection
Collect the full system prompt. Ask:
- "Can you paste your agent's full system prompt or agent description?"
- "If your agent has multiple states/nodes, paste the complete configuration (JSON or text)"
Provider-specific exports:
- Retell: Agents → Select agent → Export (downloads )
.json - VAPI: Workflows → Select agent → Code button → Copy
- Multi-state agents: Can be structured as JSON array
- Workflow agents: Paste the full exported workflow JSON
If the description is very long (>10K chars), that's fine — Cekura handles it. Don't truncate.
Agent描述是最重要的字段,它支撑以下功能:
- 自动生成评估器
- 引用的指标
{{agent.description}} - 主题/通话中断分类
- 幻觉检测
收集完整的系统提示词。询问:
- “能否粘贴您的Agent完整系统提示词或Agent描述?”
- “如果您的Agent有多个状态/节点,请粘贴完整配置(JSON或文本格式)”
特定提供商的导出方式:
- Retell:Agents → 选择Agent → Export(下载文件)
.json - VAPI:Workflows → 选择Agent → 代码按钮 → 复制
- 多状态Agent:可整理为JSON数组格式
- 工作流Agent:粘贴完整导出的工作流JSON
如果描述内容非常长(>10K字符),无需担心——Cekura可处理此类内容。请勿截断。
1.3 Contact Number (for phone-based agents)
1.3 联系号码(适用于电话类Agent)
Format: (must start with , 8-30 chars). This is the number Cekura will call for testing.
+1234567890+Ask: "What's your agent's phone number? This is the number Cekura will call during tests."
If WebRTC/WebSocket only (no phone), this can be skipped.
格式:(必须以开头,长度为8-30字符)。这是Cekura用于测试的呼叫号码。
+1234567890+询问:“您的Agent的电话号码是什么?这是Cekura在测试期间会呼叫的号码。”
如果仅使用WebRTC/WebSocket(无电话功能),可跳过此步骤。
Phase 2: Create the Agent
阶段2:创建Agent
Once you have the basics, create the agent (POST to ) with:
/test_framework/v1/aiagents/json
{
"agent_name": "Customer Support Bot",
"project": 123,
"language": "en",
"description": "<full system prompt>",
"contact_number": "+14155551234",
"inbound": true
}Save the returned — you'll need it for all subsequent steps.
id收集完基础信息后,通过POST请求到创建Agent,请求体如下:
/test_framework/v1/aiagents/json
{
"agent_name": "Customer Support Bot",
"project": 123,
"language": "en",
"description": "<full system prompt>",
"contact_number": "+14155551234",
"inbound": true
}保存返回的——后续所有步骤都需要用到此ID。
idHandling Large Agent Descriptions
处理长Agent描述
For agent descriptions longer than ~4 KB (multi-state agents, full system prompts, exported workflows), send the request as a direct JSON body via the API rather than relying on tools that may URL-encode parameters — large URL-encoded payloads can hit URI length limits.
bash
curl -X POST https://api.cekura.ai/test_framework/v1/aiagents/ \
-H "X-CEKURA-API-KEY: $CEKURA_API_KEY" \
-H "Content-Type: application/json" \
-d @agent.jsonWhere contains the full payload (including the long ). This is the safest way to create agents with long system prompts or large state-machine configs.
agent.jsondescription对于Agent描述超过约4 KB的情况(多状态Agent、完整系统提示词、导出的工作流),请通过API直接发送JSON请求体,而非依赖可能会对参数进行URL编码的工具——大型URL编码负载可能会触发URI长度限制。
bash
curl -X POST https://api.cekura.ai/test_framework/v1/aiagents/ \
-H "X-CEKURA-API-KEY: $CEKURA_API_KEY" \
-H "Content-Type: application/json" \
-d @agent.json其中包含完整请求体(包括长字段)。这是创建带有长系统提示词或大型状态机配置的Agent最安全的方式。
agent.jsondescriptionPhase 3: Configure Provider Integration
阶段3:配置提供商集成
Ask: "What provider does your agent use? (VAPI, Retell, ElevenLabs, LiveKit, Pipecat, or self-hosted/custom?)"
Provider vs connection mode — keep these distinct. is where the agent lives (the platform it's built on). How Cekura dials into it for a test run (PSTN / WebRTC / WebSocket / SIP / chat) is the connection mode, picked separately below. Never offer SIP / WebSocket / Voice / Text as a provider choice — they are connection modes for (or any) agents.
assistant_providerself_hostedThen collect provider-specific credentials and configure. See for full details on each provider.
references/integrations.md询问:“您的Agent使用哪个提供商?(VAPI、Retell、ElevenLabs、LiveKit、Pipecat,还是自建/自定义?)”
提供商与连接模式的区别——请明确区分两者。是Agent所在的平台(即构建Agent的平台)。Cekura在测试运行时接入Agent的方式(PSTN / WebRTC / WebSocket / SIP / 聊天)是连接模式,需单独选择。请勿将SIP / WebSocket / 语音 / 文本作为提供商选项——它们是(或其他)Agent的连接模式。
assistant_providerself_hosted然后收集特定提供商的凭证并完成配置。有关每个提供商的详细信息,请参阅。
references/integrations.mdQuick Reference — Required Fields by Provider
快速参考——各提供商所需字段
Provider ( | Key Fields |
|---|---|
VAPI ( | |
Retell ( | |
ElevenLabs ( | |
LiveKit ( | |
Pipecat ( | |
Self-hosted / Custom ( | Webhook URL or WebSocket URL — they push calls to Cekura |
Apply via PATCH :
/test_framework/v1/aiagents/{id}/json
{
"assistant_provider": "vapi",
"vapi_api_key": "...",
"assistant_id": "asst_...",
"transcript_provider": "vapi"
}提供商 ( | 关键字段 |
|---|---|
VAPI ( | |
Retell ( | |
ElevenLabs ( | |
LiveKit ( | |
Pipecat ( | |
自建/自定义 ( | Webhook URL或WebSocket URL——它们会将通话推送到Cekura |
通过以下方式应用配置:PATCH请求到:
/test_framework/v1/aiagents/{id}/json
{
"assistant_provider": "vapi",
"vapi_api_key": "...",
"assistant_id": "asst_...",
"transcript_provider": "vapi"
}Connection Mode
连接模式
After setting the provider, confirm how Cekura should connect to the agent during test runs. This is independent of the provider — a agent can be reached over SIP, WebSocket, or chat; a VAPI agent over PSTN or VAPI WebRTC; etc.
self_hosted- Phone (PSTN) — Add phone number via field. Simplest.
contact_number - WebRTC / SDK — For LiveKit, Pipecat, ElevenLabs WebSocket. Lower latency.
- WebSocket — Custom WebSocket URL (typically self-hosted agents). Set .
websocket_url - SIP — Direct SIP endpoint. Set , optionally
sip_endpoint. Typically used withsip_authprovider.self_hosted - Chat / Text — Text-based testing. 10x faster, 90% cheaper than voice. Set .
chat_assistant_id
Recommend chat/text for initial iteration, voice for final validation.
设置提供商后,确认Cekura在测试运行时应如何连接到Agent。这与提供商无关——Agent可通过SIP、WebSocket或聊天访问;VAPI Agent可通过PSTN或VAPI WebRTC访问,等等。
self_hosted- 电话(PSTN)——通过字段添加电话号码。最简单的方式。
contact_number - WebRTC / SDK——适用于LiveKit、Pipecat、ElevenLabs WebSocket。延迟更低。
- WebSocket——自定义WebSocket URL(通常用于自建Agent)。设置。
websocket_url - SIP——直接SIP端点。设置,可选设置
sip_endpoint。通常与sip_auth提供商配合使用。self_hosted - 聊天/文本——基于文本的测试。比语音测试快10倍,成本低90%。设置。
chat_assistant_id
建议初始迭代使用聊天/文本模式,最终验证使用语音模式。
Optional: Auto-Fetch and Auto-Sync
可选:自动获取与自动同步
For VAPI/Retell, offer to enable:
- — Auto-imports production calls every 30 seconds (for observability)
auto_fetch_calls_enabled: true - — (Retell only) Auto-syncs prompt changes every 30 seconds
auto_sync_prompt_enabled: true
对于VAPI/Retell,可启用以下功能:
- ——每30秒自动导入生产环境通话(用于可观测性)
auto_fetch_calls_enabled: true - ——(仅Retell)每30秒自动同步提示词变更
auto_sync_prompt_enabled: true
Phase 4: Set Up Mock Tools
阶段4:设置模拟工具
Ask: "Does your agent call external APIs or tools during calls? (e.g., booking systems, CRMs, payment APIs)"
If yes, there are two paths:
询问:“您的Agent在通话期间是否会调用外部API或工具?(例如预订系统、CRM、支付API)”
如果是,有两种设置方式:
Option A: Auto-Fetch (Recommended for VAPI/Retell/ElevenLabs)
选项A:自动获取(推荐用于VAPI/Retell/ElevenLabs)
If the provider integration is configured with API key + assistant ID:
- Tell the user to go to Agent Settings → Mock Tools → click "Auto-Fetch"
- Cekura fetches all tool definitions from the provider and generates sample I/O data
- The user can then toggle mock mode per tool
Note: Auto-fetch is done in the UI — there's no API-only equivalent. After auto-fetch, you can manage tools via API.
如果已配置提供商集成的API密钥和assistant ID:
- 告知用户进入Agent设置 → 模拟工具 → 点击“自动获取”
- Cekura会从提供商获取所有工具定义并生成示例输入/输出数据
- 用户可针对每个工具切换模拟模式
**注意:**自动获取需在UI中完成——没有仅通过API实现的等效方式。自动获取完成后,可通过API管理工具。
Option B: Manual Setup (for all providers)
选项B:手动设置(适用于所有提供商)
For each tool the agent uses:
-
Identify tools — Read the agent description to find all tool references. Ask: "What tools does your agent call? Give me the tool names and what each one does."
-
Create each mock tool (POST to):
/test_framework/v1/aiagents/{agent_id}/tools/
json
{
"name": "get_user_info",
"description": "Retrieves user data based on phone number or user ID",
"information": [
{
"input": {"phone_number": "8645239892"},
"output": {"borrower_id": "B001", "first_name": "John", "last_name": "Doe", "dob": "01/15/1990"}
},
{
"input": {"phone_number": "18645239892"},
"output": {"borrower_id": "B001", "first_name": "John", "last_name": "Doe", "dob": "01/15/1990"}
}
],
"freetext_params": ["notes", "reason"]
}Key rules:
- must exactly match the tool name in the agent description (max 64 chars, alphanumeric + underscores + hyphens)
name - is an array of input/output mappings — Cekura matches incoming tool calls to the closest input and returns the corresponding output
information - — Parameter names that should be skipped during mock matching (free-text fields like "notes" or "reason" that vary per call)
freetext_params - Phone format variants — For phone-based lookups, add mappings for ALL variants: 10-digit, 11-digit with leading 1, and full E.164
- Chain dependencies — If tool B depends on output from tool A (e.g., needs
get_loansfromborrower_id), the mock data must be consistent across toolsget_user_info
对于Agent使用的每个工具:
-
识别工具——阅读Agent描述以找到所有工具引用。询问:“您的Agent会调用哪些工具?请提供工具名称及每个工具的功能。”
-
创建每个模拟工具(POST请求到):
/test_framework/v1/aiagents/{agent_id}/tools/
json
{
"name": "get_user_info",
"description": "Retrieves user data based on phone number or user ID",
"information": [
{
"input": {"phone_number": "8645239892"},
"output": {"borrower_id": "B001", "first_name": "John", "last_name": "Doe", "dob": "01/15/1990"}
},
{
"input": {"phone_number": "18645239892"},
"output": {"borrower_id": "B001", "first_name": "John", "last_name": "Doe", "dob": "01/15/1990"}
}
],
"freetext_params": ["notes", "reason"]
}关键规则:
- ****必须与Agent描述中的工具名称完全匹配(最多64字符,允许字母、数字、下划线和连字符)
name - ****是输入/输出映射数组——Cekura会将传入的工具调用与最匹配的输入关联,并返回对应的输出
information - ——在模拟匹配时应跳过的参数名称(如“notes”或“reason”等每次调用都会变化的自由文本字段)
freetext_params - 电话号码格式变体——对于基于电话号码的查询,添加所有格式的映射:10位数字、带前导1的11位数字、完整E.164格式
- 链式依赖——如果工具B依赖工具A的输出(例如需要
get_loans返回的get_user_info),则模拟数据在各工具间必须保持一致borrower_id
Mock Data Design — Key Principles
模拟数据设计——核心原则
- Per-input branching: one mapping per distinct input the agent sends; not one mapping per tool
- Append-not-replace: PATCHing REPLACES the array; always GET → merge → PATCH
information - Chain dependencies: downstream tool inputs must match upstream tool outputs
- Phone format variants: add 10-digit, 11-digit-with-1, and E.164 forms
See for examples, the design questionnaire, and full guidance.
references/mock-tool-design.md- 按输入分支:为Agent发送的每个不同输入创建一个映射,而非每个工具仅创建一个映射
- 追加而非替换:PATCH会替换整个数组;请始终先GET → 合并 → 再PATCH
information - 链式依赖:下游工具的输入必须与上游工具的输出匹配
- 电话号码格式变体:添加10位、带前导1的11位以及E.164格式的映射
**请参阅**获取示例、设计问卷和完整指南。
references/mock-tool-design.mdPhase 5: Upload Knowledge Base
阶段5:上传知识库
Ask: "Does your agent reference any knowledge base documents? (e.g., FAQs, product guides, policy docs)"
If yes, upload files via the agent knowledge base upload endpoint.
Supported formats: PDF, text files, documents.
Purpose: Knowledge base files enable:
- More accurate evaluator generation (Cekura understands what the agent should know)
- Hallucination detection (compare agent responses against KB content)
- Richer test scenarios that exercise KB retrieval
After upload, the files appear in Agent Settings → Agent's Knowledge.
Optional: Link KB files to hallucination detection by PATCHing the agent with .
{"hallucination_metric_kb_files": [<file_id_1>, <file_id_2>]}询问:“您的Agent是否会参考任何知识库文档?(例如常见问题、产品指南、政策文档)”
如果是,通过Agent知识库上传端点上传文件。
支持的格式:PDF、文本文件、文档。
**用途:**知识库文件可实现以下功能:
- 生成更准确的评估器(Cekura了解Agent应掌握的知识)
- 幻觉检测(将Agent响应与知识库内容进行对比)
- 构建更丰富的测试场景,验证知识库检索能力
上传完成后,文件会显示在Agent设置 → Agent知识库中。
**可选:**通过PATCH请求将知识库文件与幻觉检测关联,请求体为。
{"hallucination_metric_kb_files": [<file_id_1>, <file_id_2>]}Phase 6: Dynamic Variables
阶段6:动态变量
Ask: "Does your agent use per-call variables? (e.g., customer name, account ID, appointment details, different system prompts per call)"
询问:“您的Agent是否会使用每次通话专属的变量?(例如客户姓名、账户ID、预约详情、每次通话不同的系统提示词)”
Auto-Detection
自动检测
If the agent description contains patterns, Cekura auto-detects them. After creating the agent, check if any were detected.
{{variableName}}如果Agent描述中包含格式的内容,Cekura会自动检测这些变量。创建Agent后,检查是否有检测到的变量。
{{variableName}}Manual Addition
手动添加
If the user has dynamic variables that aren't in the description pattern:
Via API: Dynamic variables are managed through the agent description. Add placeholders to the description where the variable should be injected.
{{variableName}}What dynamic variables enable:
- Per-call system prompt injection (for multi-agent flows)
- Caller-specific data (name, account ID, employment type)
- Feature flags (enable/disable features per call)
- Configuration data (reconnection context, prior call summaries)
Key insight: For clients with multi-agent flows where each node has its own system prompt, recommend using dynamic variables (one per node) rather than putting everything in the agent description. This enables per-node metrics using .
{{dynamic_variables.nodeName}}如果用户有未按上述格式出现在描述中的动态变量:
**通过API:**动态变量通过Agent描述进行管理。在描述中变量需要注入的位置添加占位符。
{{variableName}}动态变量的作用:
- 每次通话注入系统提示词(适用于多Agent流程)
- 呼叫者专属数据(姓名、账户ID、雇佣类型)
- 功能开关(按通话启用/禁用功能)
- 配置数据(重连上下文、历史通话摘要)
**核心提示:**对于每个节点都有独立系统提示词的多Agent流程客户,建议使用动态变量(每个节点对应一个变量),而非将所有内容放入Agent描述。这样可使用实现按节点的指标统计。
{{dynamic_variables.nodeName}}Phase 7: Verify Setup
阶段7:验证设置
After all steps are complete, verify:
- Agent exists: GET the agent — confirm description, provider, contact number
- Provider connected: Check that , API key, and
assistant_providerare setassistant_id - Mock tools configured: List tools on the agent — confirm all tools have mappings
- Knowledge base uploaded: Check on the agent object
knowledge_base_files - Test connectivity: Suggest running a single simple evaluator to confirm end-to-end connectivity
Summary for the user:
Agent: [name] (ID: [id])
Project: [project_id]
Provider: [provider] (assistant: [assistant_id])
Connection: [phone/WebRTC/chat]
Mock tools: [count] configured
Knowledge base: [count] files uploaded
Dynamic variables: [list or "none"]
Ready for: evaluator generation → cekura-eval-design skill
metric setup → cekura-metric-design skill完成所有步骤后,进行验证:
- Agent已存在:GET Agent信息——确认描述、提供商、联系号码
- 提供商已连接:检查、API密钥和
assistant_provider是否已设置assistant_id - 模拟工具已配置:列出Agent的工具——确认所有工具都有映射
- 知识库已上传:检查Agent对象的字段
knowledge_base_files - 测试连通性:建议运行一个简单的评估器,确认端到端连通性
给用户的总结:
Agent: [名称](ID: [id])
项目: [project_id]
提供商: [provider](assistant: [assistant_id])
连接方式: [电话/WebRTC/聊天]
模拟工具: [数量]个已配置
知识库: [数量]个文件已上传
动态变量: [列表或“无”]
下一步可执行:生成评估器 → 调用cekura-eval-design skill
设置指标 → 调用cekura-metric-design skillNext Steps
后续步骤
After agent setup, the user typically needs:
- Generate first evaluators → invoke cekura-eval-design
- Create custom metrics → invoke cekura-metric-design
- Run guided onboarding → invoke cekura-onboarding for full platform walkthrough
完成Agent设置后,用户通常需要:
- 生成首个评估器 → 调用cekura-eval-design
- 创建自定义指标 → 调用cekura-metric-design
- 执行引导式入门 → 调用cekura-onboarding完成平台完整演练
Documentation
文档
- Public docs: https://docs.cekura.ai
- Integrations: https://docs.cekura.ai/documentation/integrations/
- Dashboard: https://dashboard.cekura.ai
Additional Resources
额外资源
Reference Files (loaded on demand)
参考文件(按需加载)
- — Full provider integration details (VAPI, Retell, ElevenLabs, LiveKit, Pipecat, self-hosted) plus connection-mode reference (PSTN, WebRTC, WebSocket, SIP, chat)
references/integrations.md - — Per-input branching examples, design questionnaire, append-not-replace pattern
references/mock-tool-design.md - — Complete agent API endpoints and schemas
references/api-reference.md
- ——完整的提供商集成细节(VAPI、Retell、ElevenLabs、LiveKit、Pipecat、自建)以及连接模式参考(PSTN、WebRTC、WebSocket、SIP、聊天)
references/integrations.md - ——按输入分支示例、设计问卷、追加而非替换模式
references/mock-tool-design.md - ——完整的Agent API端点和模式
references/api-reference.md
Scripts (executable via bash)
脚本(可通过bash执行)
- — Curl wrapper to create or update an agent with a large system prompt (>4 KB), bypassing URI-length limits. Reads payload from a JSON file.
scripts/upload-agent.sh
- ——Curl封装脚本,用于创建或更新带有长系统提示词(>4 KB)的Agent,绕过URI长度限制。从JSON文件读取请求体。
scripts/upload-agent.sh