The HumeAI Speech-to-Speech (STS) integration enables Agent Voice Response to connect directly to HumeAI’s real-time conversational voice API, allowing voice-to-voice interactions with emotional intelligence and low latency.
This integration bypasses the traditional ASR → LLM → TTS pipeline and provides a single real-time speech loop, ideal for natural, expressive, and emotionally aware AI conversations.
Official website: https://www.hume.ai
Realtime API documentation: https://dev.hume.ai
HumeAI is uniquely focused on emotion-aware conversational AI, making it an excellent choice for applications where tone, empathy, and emotional context matter.
Clone the official integration repository:
git clone https://github.com/agentvoiceresponse/avr-sts-humeai.git
| Variable | Description | Default | Required |
|---|---|---|---|
HUMEAI_API_KEY |
Your HumeAI API key | — | Yes |
PORT |
Local service port | 6039 |
Optional |
HUMEAI_WS_URL |
HumeAI WebSocket endpoint | wss://api.hume.ai/v0/evi/chat |
Optional |
HUMEAI_WELCOME_MESSAGE |
Initial greeting message | "Hello, how can I help you today?" |
Optional |
HUMEAI_INSTRUCTIONS |
System prompt when no config ID is used | "You are a helpful assistant" |
Optional |
HUMEAI_CONFIG_ID |
HumeAI config ID (overrides instructions/voice) | — | Optional |
HUMEAI_VOICE_ID |
Voice ID (used when no config ID is provided) | — | Optional |
.envHUMEAI_API_KEY=your_humeai_api_key
PORT=6039
HUMEAI_WS_URL=wss://api.hume.ai/v0/evi/chat
HUMEAI_WELCOME_MESSAGE="Hello, how can I help you today?"
HUMEAI_INSTRUCTIONS="You are a helpful assistant"
HUMEAI_CONFIG_ID=
HUMEAI_VOICE_ID=
avr-sts-humeai:
image: agentvoiceresponse/avr-sts-humeai
platform: linux/x86_64
container_name: avr-sts-humeai
restart: always
environment:
- PORT=6039
- HUMEAI_API_KEY=${HUMEAI_API_KEY}
- HUMEAI_WS_URL=${HUMEAI_WS_URL:-wss://api.hume.ai/v0/evi/chat}
- HUMEAI_WELCOME_MESSAGE=${HUMEAI_WELCOME_MESSAGE:-Hello, how can I help you today?}
- HUMEAI_INSTRUCTIONS=${HUMEAI_INSTRUCTIONS:-You are a helpful assistant}
- HUMEAI_CONFIG_ID=${HUMEAI_CONFIG_ID}
- HUMEAI_VOICE_ID=${HUMEAI_VOICE_ID}
networks:
- avr
To use HumeAI as your Speech-to-Speech provider, configure STS_URL in avr-core:
STS_URL=http://avr-sts-humeai:6039/speech-to-speech-stream
⚠️ When
STS_URLis configured, ASR_URL, LLM_URL, and TTS_URL must be commented out, as AVR Core switches to STS mode.
All communication is handled via WebSocket streaming, ensuring low latency and natural conversational flow.
HUMEAI_CONFIG_ID)When a config ID is provided, HumeAI fully controls:
This is the recommended approach for production use.
If no config ID is set, AVR will use:
HUMEAI_WELCOME_MESSAGEHUMEAI_INSTRUCTIONSHUMEAI_VOICE_IDThis mode is useful for quick testing and experimentation.
The integration includes robust handling for:
Errors are logged to the console for easier debugging.
INTERRUPT_LISTENING are ignored in STS mode