Skip to content

Custom Agent Configuration Guide

This guide covers advanced configuration options for agents that require customization beyond what's available in the admin dashboard. These configurations are applied directly to the database agent table.

Configuration Options

1. Custom Prompts

By default, an agent uses a prompt that is defined in the prompt table. In the agent table, you'll find two important columns that control the agent's prompt:

  • prompt_id: Links to an entry in the prompt table
  • override_prompt: Takes a direct string input for a custom prompt

There are two approaches to implementing custom prompts for agents:

Option A: Shared Prompts (Multiple Agents)

If you're creating a prompt that could be used by multiple agents, this approach makes more sense as it provides better control:

  1. Create a new entry in the prompt table
  2. Link the prompt using the prompt_id column in the agent table

This approach is ideal when you want to:

  • Maintain a standardized prompt across multiple agents
  • Have better version control over your prompts
  • Make centralized updates that affect multiple agents

Option B: Agent-Specific Prompts

For one-time use cases where only a specific agent requires a customized prompt:

  1. Use the override_prompt column in the agent table
  2. Input your custom prompt string directly

This approach is perfect for:

  • Testing new prompt variations
  • Creating agent-specific customizations
  • Quick modifications without affecting other agents

Note

The override_prompt takes precedence over the prompt_id. If both are set, the system will use the override_prompt. This allows you to temporarily override a standard prompt while maintaining the link to the original.

2. Custom Voices

The agent table includes a voice column that stores voice IDs from the Ultravox APIs. While you can easily change public voices through the dashboard, there's a straightforward way to use private voices (like cloned voices or external voices added through Ultravox dashboard):

  1. Add your custom voice through the Ultravox dashboard
  2. Get the voice ID from Ultravox
  3. Update the voice column in the agent table with the voice ID

The process is pretty straightforward - just add the voice on Ultravox dashboard, get the voice ID, and paste it directly in the database against that agent.

Warning

When using private voice IDs, the voice selection dropdown in the admin dashboard UI may appear blank. This is expected behavior as these private voice IDs are not part of the public list of options.

3. Custom Avatar Configuration

Custom avatar images and videos are configured through the ui_config column in the agent table. This column stores asset URLs in a JSON format.

To customize:

  1. Upload your custom avatar assets to your hosting solution
  2. Update the ui_config JSON object with the new asset URLs

→ Link the AgentUIConfig class (schema)

4. Custom Agent Name

Right now, the agent's name "Angel" is defined in the prompt by default. However, there are two aspects to consider when customizing an agent's name:

Display Name

The display name shown in the bot UI can be configured through the ui_config JSON object. This change only affects what users see in the bot interface but does NOT change the AI agent's internal name.

Core Agent Name

To modify the agent's core identity (currently defaulted to "Angel"), you have two options:

  1. Update the name column in the agent table (once we expose this via the admin dashboard API)
  2. Use a placeholder in the prompt like {agent_name}
  3. Inject inside the prompt text using this custom name

--- OR ---

For a complete name change, you'll need to:

  1. Modify the display name in the ui_config
  2. Inject this name into the prompt using the {agent_name} placeholder
  3. Update the name column in the database

Tip

For consistent agent identity, make sure to update both the display name and the prompt to reference the same name. This ensures a coherent experience for users interacting with the agent.