Empathic Voice Interface (EVI)Configuration

Configuring EVI

Guide to configuring the Empathic Voice Interface (EVI).

EVI is designed to be highly configurable, enabling developers to adjust behavior and functionality to meet specific application needs. An EVI Config is a reusable set of settings that can be applied when starting a chat session. This guide details available configuration options, default settings, example templates, and instructions for creating and applying your own EVI Config.

EVI Configs are persisted and applied at the start of a Chat. To modify EVI settings dynamically during a Chat session, see the Session settings guide.

Configuration options

The following options are available when building an EVI Config:

OptionDescription
VoiceSelect a voice from a list of 8 preset options.
EVI version

Choose which EVI version to use. For a detailed version comparison, see the EVI version feature comparison.

Prompt

Provide a system prompt to define how EVI responds. For guidance on prompt engineering, refer to our prompting guide.

Language model

Select the language model that best fits your needs. For details, see our language model guide.

Event messages

Configure custom messages EVI sends in response to specific events. See our event messages guide and API reference.

Timeouts

Define conversation time limits and other timeout parameters. For more details, see our timeouts guide and API reference.

Webhooks

Provide a webhook URL to subscribe to events such as the start or end of a Chat session. See our webhooks guide.

Configs, Prompts, and Tools are versioned to support iterative development—refine your setup over time and roll back to earlier versions whenever you need.

Default configuration options

EVI includes a set of default config options that apply automatically when not explicitly specified. By default, EVI uses a preset voice, language model, and system prompt, and does not include any tools.

Defaults vary between EVI versions:

OptionEVI 1EVI 2
VoiceITOITO
Language modelclaude-3-5-sonnet-latesthume-evi-2
System promptHume defaultHume default
ToolsNoneNone

Default config options may change over time. To maintain consistent behavior, explicitly set all config options in your configuration. For reference, see the default system prompt in our Hume API Examples repository.

Template configurations

When creating an EVI configuration in the Platform UI, you can select a prebuilt template as your starting point. Each template provides a recommended voice, language model, and system prompt tailored to a sample voice-assistant use case.

Expand the template config options below for more details:

Interview Prep Assistant: a voice assistant that conducts tailored mock interviews, offers personalized advice, and delivers detailed feedback to help candidates excel.

OptionSelection
VoiceITO
Language modelGemini 2.0 Flash (gemini-2.0-flash)
System prompt
1Assistant is an AI interview coach to help job seekers across many industries. Your function is to offer
2tailored advice, conduct mock interviews, and provide detailed feedback to help candidates excel in
3their job interviews. Format all messages as spoken words for a voice conversation.
4
5When a user engages with you, first ask about their target role, industry, and experience level. Use this
6information to customize your guidance. Then, immediately ask them if they’re ready for a quick simulated
7practice interview for this role. If they confirm, start asking interview questions. Conduct a realistic
8mock interview tailored closely to their specific role, industry, and experience level. Ask 5 total main
9questions in the interview. For a few of the questions, ask intelligent, relevant, and specific follow-up
10questions based on the user’s responses.
11
12After asking 5 questions and receiving the user’s answers, end the interview. Then, give the user feedback
13on the interview - their language, the accuracy and quality of the content of the answers, tone of voice, and
14professional presentation. Provide constructive feedback, highlighting strengths and areas for improvement.
15Offer specific strategies for addressing weaknesses and emphasizing strengths. Always maintain a friendly and
16supportive tone, being honest and critical where appropriate while providing helpful, actionable advice.
1curl https://api.hume.ai/v0/evi/configs \
2  -H "X-Hume-Api-Key: $HUME_API_KEY" \
3  --json '{
4    "evi_version": "2",
5    "name": "<CONFIG_NAME>",
6    "voice": {
7      "provider": "HUME_AI",
8      "name": "ITO"
9    },
10    "language_model": {
11      "model_provider": "GOOGLE",
12      "model_resource": "gemini-2.0-flash"
13    },
14    "prompt": {
15      "text": "$SYSTEM_PROMPT"
16    }
17  }'

Mental Health Support Assistant: a voice assistant designed to provide compassionate, non-judgmental support—actively listening, offering evidence-based coping strategies, and encouraging professional help when needed.

OptionSelection
VoiceStella
Language modelClaude 3.5 Sonnet (claude-3-5-sonnet-202440620)
System prompt
1<role>
2Assistant is a compassionate mental health support AI designed to provide empathetic, non-judgmental support to
3users seeking emotional guidance. Your primary function is to offer a safe space for users to express their
4feelings, provide evidence-based coping strategies, and encourage professional help when necessary. You have a
5deep understanding of psychological principles and can maintain context over long conversations for personalized
6support.
7</role>
8<communication_style>
9Communicate with warmth, patience, and genuine care. Use a calm, reassuring tone while remaining professional.
10Actively listen and reflect key points to show understanding. Ask open-ended questions to encourage expression.
11Adapt your language to the user's emotional state, whether they need comfort, motivation, or practical advice. Be
12prepared to recognize signs of crisis and respond appropriately with emergency resources. Always emphasize that
13while you offer support, you recommend they reach out to a professional for therapy.
14</communication_style>
1curl https://api.hume.ai/v0/evi/configs \
2  -H "X-Hume-Api-Key: $HUME_API_KEY" \
3  --json '{
4    "evi_version": "2",
5    "name": "Mental Health Support Voice Assistant",
6    "voice": {
7      "provider": "HUME_AI",
8      "name": "STELLA"
9    },
10    "language_model": {
11      "model_provider": "ANTHROPIC",
12      "model_resource": "claude-3-5-sonnet-202440620"
13    },
14    "prompt": {
15      "text": "$SYSTEM_PROMPT"
16    }
17  }'

Real-time Web Search Assistant: a voice assistant designed to leverage our built-in web search tool to fetch real-time information and deliver quick answers during a chat session.

System prompt
1Assistant is a web search voice assistant. Eliminate all filler language. Speak concisely and use the web_search
2tool to execute searches to directly answer questions when asked. Never repeat the question or any user messages,
3simply answer immediately. Format all responses as spoken words for a human-like voice conversation. Don't refer
4to or mention sources. Instead of lists, use transition phrases like "First," "Another point," etc. Use web search
5only if it is appropriate and relevant to the user's query, but always use web search to get recent data when
6necessary.
OptionSelection
VoiceKORA
Language modelGPT-4o mini (gpt-4o-mini)
ToolsWeb search (web_search)
1curl https://api.hume.ai/v0/evi/configs \
2  -H "X-Hume-Api-Key: $HUME_API_KEY" \
3  --json '{
4    "evi_version": "2",
5    "name": "<CONFIG_NAME>",
6    "voice": {
7      "provider": "HUME_AI",
8      "name": "KORA"
9    },
10    "language_model": {
11      "model_provider": "OPEN_AI",
12      "model_resource": "gpt-4o-mini"
13    },
14    "prompt": {
15      "text": "$SYSTEM_PROMPT"
16    },
17    "builtin_tools": [
18      {
19        "name": "web_search"
20      }
21    ]
22  }'

Creating a configuration

See instructions below for creating an EVI configuration through the Platform.

1

Navigate to the Configurations page

In the Platform, find the EVI Configurations page. Click the Create Configuration button to begin.

Navigating to the configurations page, the first step of EVI configuration
2

Select a template

Select a template to get started quickly, or create a configuration from scratch. This guide demonstrates creating a configuration from scratch.

Template selection, the second step of EVI configuration
3

Choose EVI version

To learn more about the differences between EVI versions 1 and 2, please see the feature comparison guide.

Version selection, the third step of EVI configuration
4

Choose voice

Select a voice from Hume’s 8 presets, or create your own custom voice. To learn more about voice customization options on the Hume Platform, please visit the Voices page. The system default voice will be used if no voice is selected.

Voice selection, the fourth step of EVI configuration
5

Set up the LLM

Select a supported language model and specify a system prompt. The system prompt is crucial for defining your assistant’s personality, capabilities, and behavior. For guidance on writing effective prompts, visit our Prompting Guide. If no system prompt is provided, the system default prompt will be used.

Supplemental LLM setup, the fifth step of EVI configuration
6

Add tools

EVI comes with built-in tools (Web search and Hang up) that you can enable.

To add custom tools, click the + Add button, which allows you to either select from your existing custom tools or create a new one. For more information about tools and creating custom tools, visit the Tools page.

Tool use addition, the sixth step of EVI configuration
7

Name config

Name your EVI configuration and add an optional description.

Providing a name and description, the seventh and final step of EVI configuration
8

Test the configuration

The newly created configuration can now be tested. From the Config edit page, click Run in playground to test your configuration in the EVI Playground. This allows you to interact with EVI using your custom settings and verify that the configuration works as expected.

The page shown after a successful EVI configuration; the ID and name are displayed, and two buttons appear ("Run in playground" and "Edit configuration")
Successful EVI config creation

Once in the EVI Playground, click Start call to begin testing your configuration. You can speak with EVI using your microphone or type messages in the chat interface.

EVI playground
Using an EVI configuration in the Playground
9

Set additional configuration options

Additional configuration options can be set after the initial config creation flow:

  • Event messages and timeouts can be configured through the Platform (either in the Playground or Config edit page)
  • Webhooks can be configured through the API. They are not currently configurable through the Platform. For detailed instructions and code examples, see our webhooks guide.
Event message and timeout options in playground
Event message and timeout options in the Playground
Event message and timeout options on edit page
Event message and timeout options in the Config edit page
10

Apply the configuration

After creating an EVI configuration, you can use it in your conversations with EVI by including the config_id in the query parameters of your connection request. Here’s how to locate your config_id:

  1. Navigate to the Configurations page.
  2. Click the More Options button next to your desired configuration.
  3. Copy the Configuration ID.
Configuration ID

See the code snippets below for how to apply your configuration:

1from hume import HumeVoiceClient, MicrophoneInterface
2from hume.empathic_voice.chat.socket_client import ChatConnectOptions
3
4client = HumeVoiceClient(HUME_API_KEY)
5
6# Specify Config ID on connect
7async with client.empathic_voice.chat.connect_with_callbacks(
8    options=ChatConnectOptions(config_id=HUME_CONFIG_ID),
9) as socket:
10    # ...