Configuring EVI

The Empathic Voice Interface (EVI) is designed to be highly configurable, allowing developers to customize the interface to align with their specific requirements. Configuration of EVI can be managed through two primary methods: an EVI configuration and session settings.

EVI configuration

EVI configuration options affect the behavior and capabilities of the interface, and include the following configuration options:

• System prompt: Set the system prompt text to provide instructions and context that guide how EVI should respond.
• Language model: Select a language model that best fits your application’s needs. For details on incorporating your own language model, refer to our guide on using your own language model.
• Voice: Select a voice for EVI from a growing list of available options.
• Tools: Choose user-created tools or built-in tools for EVI to use during conversations. For details on creating tools and adding them to your configuration, see our guide on tool use.
• Event Messages: Configure messages that EVI will send in specific situations.
• Timeouts: Define limits on a chat with EVI to manage conversation flow.

Default configuration

EVI is pre-configured with a set of default values, which are automatically applied if you do not specify a configuration. The default configuration includes a preset voice and language model, but does not include a system prompt or tools. To customize these options, you will need to create and specify your own EVI configuration.

The default configuration settings are as follows:

• Language model: Claude 3.5 Sonnet
• Voice: Ito (masculine)
• System prompt: None
• Tools: None

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

Create a configuration

In the Portal, navigate to the EVI Configurations page. Click the Create configuration button to begin.

Enter a name for your configuration, and click the Create button.

Equip your configuration with a description, system prompt, voice, and any tools.

For guidance on engineering your system prompt, see our prompting guide.

Test the configuration

The newly created configuration can now be tested. From the EVI Config details page, click Run in playground to test it out.

Once in the EVI Playground, click Start call to connect to EVI with your configuration.

Apply the configuration

Once you have created an EVI configuration, you can apply it to your conversations with EVI through the API. This involves including the config_id in the query parameters of your connection request. You can find the config ID associated with your newly created configuration in the EVI Config details page.

See the sample code below which showcases how to apply your configuration:

TypeScriptPython

1
import { Hume, HumeClient } from 'hume';
2
// instantiate the HumeClient with credentials to make authenticated requests
3
const client = new HumeClient({
4
  apiKey: <YOUR_API_KEY>,
5
  secretKey: <YOUR_SECRET_KEY>,
6
});
7
// instantiate WebSocket connection with specified EVI config
8
const socket = await client.empathicVoice.chat.connect({
9
  configId: <YOUR_CONFIG_ID> // specify config ID here
10
});

Session settings

EVI configurations are persistent and version-controlled. In contrast, session settings are temporary and apply only to the current session, such as microphone settings. These parameters can be adjusted dynamically based on the requirements of each session to ensure optimal performance and user experience.

Updating the session settings is only a requirement when the audio input is encoded in PCM Linear 16. If this is the case, be sure to send the following Session Settings message prior to sending an audio input:

1
{
2
  "type": "session_settings",
3
  "audio": {
4
    "channels": 1,
5
    "encoding": "linear16",
6
    "sample_rate": 48000
7
  }
8
}

Dynamic variables

EVI can reference and update session-specific values as a conversation progresses. By including dynamic variables in the system prompt, you can personalize conversations with EVI.

To use this feature, first define a variables parameter within a Session Settings message containing one or more dynamic variables.

Each key-value pair in "variables" must have a string key representing the variable name and a string value.

For example, you can define the user’s name and set it to a default value:

1
{
2
  "type": "session_settings",
3
  "variables": {
4
    "name": "David Hume",
5
    "age": "65",
6
    "is_philosopher": "True"
7
  }
8
}

Then, include the variable surrounded by two pairs of curly braces, such as {{name}}, as a placeholder value in your system prompt:

Address the user by their name, {{name}}.
If relevant, reference their age: {{age}}.
It is {{is_philosopher}} that this user is a philosopher.  

• If you have defined a dynamic variable, reference it.

If the variable is defined but not referenced in the system prompt, then it will not be included in the conversation and EVI will not be able to refer to the variable.

• If you have referenced a dynamic variable, make sure it is defined.

If the variable is referenced in the system prompt, but it is not defined in the "variables" field, then the warning W0106 will be raised: “No values have been specified for the variables [variable_name] which can lead to incorrect text formatting. Please assign them values.”

For example, this error can occur when there are spelling mistakes or differences between the variable defined in the "variables" field and the variable referenced in the system prompt (i.e. {{firstName}} instead of {{name}}).