ElevenLabs Voice Setup
Kravos.ai uses ElevenLabs for live conversational voice. The sync flow exists so admins can manage voice behavior in Kravos.ai, then push the matching agent ...
ElevenLabs Voice Setup
Kravos.ai uses ElevenLabs for live conversational voice. The sync flow exists so admins can manage voice behavior in Kravos.ai, then push the matching agent and tools to ElevenLabs.
Required Server Configuration
| Setting | Why it is needed |
|---|---|
ELEVENLABS_API_KEY | Lets Kravos.ai list voices and LLMs, create or update agents and tools, fetch signed URLs, and fetch audio. |
ELEVENLABS_WEBHOOK_SECRET | Verifies incoming ElevenLabs webhook events before queuing transcript work. |
PUBLIC_APP_URL or NEXTAUTH_URL | Builds public tool webhook URLs for retrieval, media search, and skill fetching. |
| worker + Redis | Processes webhook events and post-call fallback transcript jobs. |
Public URL matters
ElevenLabs must be able to reach the URLs Kravos.ai sends during sync. In development, use a public tunnel URL. In production, use the real app URL.
Basic Setup Flow
- Open the agent's Voice settings or Voice Lab.
- Enable voice.
- Pick an ElevenLabs voice.
- Pick an ElevenLabs LLM, or leave it empty to use the ElevenLabs default.
- Set the voice agent name, language, and prompt.
- Save the local config.
- Select Sync to ElevenLabs.
- Run a short Voice Lab session and inspect the transcript and tool calls.
The voice picker calls ElevenLabs voice search through Kravos.ai. The LLM picker calls the ElevenLabs conversational LLM list and shows model capabilities such as context window, output limit, image support, document support, and parallel tool support when ElevenLabs returns that metadata.
What Sync Creates Or Updates
Sync creates or patches:
- one ElevenLabs conversational agent
- a retrieval tool that calls
/api/retrieve - a media search tool that calls
/api/media/search - a skill fetch tool only when the agent has active skills
After a successful sync, Kravos.ai stores the ElevenLabs agent ID, tool IDs, lastSyncedAt, and a sync fingerprint. The fingerprint covers the synced agent name, prompt, skill catalog section, voice, LLM, and tool endpoints.
Import From ElevenLabs
Use Import from ElevenLabs when the live ElevenLabs agent has changes you want to pull into Kravos.ai.
Import reads the remote agent and overwrites these local fields when the remote value exists:
- agent name
- system prompt
- voice ID
- LLM
Import clears lastSyncedAt and the sync fingerprint because the local config now matches remote fields but has not yet been pushed by Kravos.ai. Sync again if you want the local record to become the new tracked source.
Diff And Sync Status
Voice Lab can compare local config with the live ElevenLabs agent.
The diff checks:
- agent name
- effective system prompt
- voice ID
- LLM
- which side appears newer by timestamp
- whether local config drifted since the last sync fingerprint
- whether retrieval, media, and skill tool webhook URLs match the expected app URL
Sync status is simpler. It checks whether the remote agent and required tools exist and whether their webhook URLs are wired correctly.
No rollback workflow yet
The current implementation supports compare, import, and sync. It does not store historical voice config versions or provide a one-click rollback. If you need rollback, copy the previous prompt, voice ID, and LLM before syncing.
Audit Behavior
Voice sync and import write audit log entries with the acting user and remote resource. Sync records the operation, tool IDs, and webhook endpoints. Import records the remote fields it pulled in. Tool API keys are not written to the audit payload.
Troubleshooting
ELEVENLABS_API_KEY is not configured
Set ELEVENLABS_API_KEY in the web app environment and restart the server.
Sync says the app URL is missing
Set PUBLIC_APP_URL for production or a tunnel URL for local testing. If PUBLIC_APP_URL is absent, Kravos.ai falls back to NEXTAUTH_URL where supported.
Diff shows tool URLs do not match
The ElevenLabs tool is still pointing at an older app URL. Confirm the current public URL, then run Sync to ElevenLabs again.
Remote is newer
Someone changed the ElevenLabs agent outside Kravos.ai. Use Import from ElevenLabs to pull those fields into Kravos.ai, or use Sync to ElevenLabs to overwrite the remote agent with local settings.
Voice answers without retrieved knowledge
Re-sync the agent and confirm the retrieval tool exists. The synced prompt instructs the voice agent to call search_knowledge_base before answering factual questions.
Related Docs
Voice
Understand how voice sessions map to conversations, transcripts, audio, and tools.
Skills
See how active skills add a private fetch tool during voice sync.
API Keys
Understand public API keys and the managed keys used by voice tooling.