test_framework

Create an AI voice agent

Changed on Nov 3, 2026

Register a new AI voice agent. Required fields: name, description, project, inbound. Provider credentials are nested under provider.{type, agent_id, credentials} instead of flat fields. transcript_provider defaults to provider.type when omitted.

provider.credentials keys by type (voice providers only):

vapi: api_key + config.{public_key, trigger_url}
retell: api_key + agent_id + optional chat_agent_details.config.agent_id
elevenlabs: api_key + config.{trigger_url}
bland: api_key + agent_id (pathway_id) + config.{encrypted_key} for Twilio
livekit: api_key + config.{api_secret (required), url (required)}
pipecat: api_key + config.{webhook_url}
cisco: no credentials needed to dial; connect Webex Contact Center from the dashboard for transcripts
gemini_cx: no api_key; agent_id (CX agent id) + config.{service_account_email, location}; config.project_id defaults from the email
self-hosted chat: provider.type=custom + chat_agent_details.{type: self_hosted, config.{url (wss://), headers}} Note: agentforce goes in chat_agent_details; koreai/genesys/synthflow use the v1 API.

Auto-import from a cloud provider — set provider.configure_from_provider: true (vapi/retell/elevenlabs/synthflow/bland) with provider.agent_id + provider.credentials.api_key, or agentforce with chat_agent_details.config.{agent_id, client_id, client_secret, domain} (omit the key to use the project's saved provider key; list importable ids with GET /v2/aiagents/provider-assistants/). An assistant already imported into the project is refused with 409. Cekura fetches the prompt, name, language, who-speaks-first, phone number, tool calls, dynamic variables and knowledge base and configures the agent automatically — name and description become optional (auto-fetched). The response is 202 with the created agent plus a progress_id; poll auto-fetch-progress/ to follow the staged import.

See examples below for full per-provider payloads.

post/test_framework/v2/aiagents/

Request

Base URL
https://api.cekura.ai
URL
https://api.cekura.ai/test_framework/v2/aiagents/
Auth
- API key in header X-CEKURA-API-KEY
- or HTTP bearer
- or HTTP bearer

Request body

idinteger

Agent ID. Example: 2142

namestring

Agent name. Optional when configure_from_provider is set — it's fetched from the provider.

descriptionstring required

A detailed description of what this agent does and how it should interact Example:

AI agent for handling customer support inquiries and resolving technical issues

projectinteger

The project this agent belongs to

language'af' | 'ar' | 'bn' | 'bg' | 'zh' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'gu' | 'hi' | 'he' | 'hu' | 'id' | 'it' | 'ja' | 'kn' | 'kk' | 'ko' | 'ms' | 'ml' | 'mr' | 'multi' | 'no' | 'pl' | 'pa' | 'pt' | 'ro' | 'ru' | 'sk' | 'es' | 'sv' | 'th' | 'tr' | 'tl' | 'ta' | 'te' | 'uk' | 'uz' | 'vi'

The primary language this agent uses for communication (e.g. 'en' for English)

af - Afrikaans
ar - Arabic
bn - Bengali
bg - Bulgarian
zh - Chinese Simplified
cs - Czech
da - Danish
nl - Dutch
en - English
et - Estonian
fi - Finnish
fr - French
de - German
el - Greek
gu - Gujarati
hi - Hindi
he - Hebrew
hu - Hungarian
id - Indonesian
it - Italian
ja - Japanese
kn - Kannada
kk - Kazakh
ko - Korean
ms - Malay
ml - Malayalam
mr - Marathi
multi - Multilingual
no - Norwegian
pl - Polish
pa - Punjabi
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
es - Spanish
sv - Swedish
th - Thai
tr - Turkish
tl - Tagalog
ta - Tamil
te - Telugu
uk - Ukrainian
uz - Uzbek
vi - Vietnamese

enabled_connectionsstring[]

Transports an evaluator run can use against this agent, as accepted by the unified run endpoint's transport field. Omitted from list responses.

agent_speaks_firstboolean nullable

True = agent speaks first; False = test user speaks first; null = auto-detect.

predefined_metricsunknown

enabled_personalitiesinteger[]

Personality profiles enabled for this agent Example: [1, 2, 3]

webhook_urlstring uri

Webhook URL for this agent. When set, overrides the project-level webhook URL for events from this agent.

webhook_secretstring

Secret sent in X-CEKURA-SECRET header. Applies when agent webhook_url is set. Write-only — never returned in API responses. Use webhook_secret_configured to check whether one is set.

webhook_secret_configuredstring

mock_tools_enabledboolean

Whether mock tools should be selected by default when configuring a run.

mock_tools_providerstring nullable

Provider the mock tools were fetched from (vapi, retell, elevenlabs, custom). Null until auto-fetch has been run.

created_atstring date-time

Timestamp when the agent was created Example: "2021-01-01T00:00:00Z"

updated_atstring date-time

Timestamp when the agent was last updated Example: "2021-01-01T00:00:00Z"

email_idstring email nullable

Email address this agent receives at. When set, enables email-based test runs.

Response