Reusable Agent Configurations

Learn how to create, store, and reuse agent configurations for the Voice Agent API.

Reusable Agent Configurations allow you to define and persist the agent block of your Settings message using the Deepgram API. Once created, you receive a UUID that can be passed in place of the full agent object—simplifying your client code and enabling consistent agent behavior across sessions.

Reusable Agent Configurations are managed via the API. UI support is not yet available.

Overview

When using the Voice Agent API, you typically send a full agent configuration object inside every Settings message. With Reusable Agent Configurations, you can:

  • Store a reusable agent block using the Console API and receive a unique UUID.
  • Reference that UUID in your Settings message instead of repeating the full configuration.
  • Use template variables to define reusable values that can be shared across multiple agent configurations.

All agent configurations and template variables are visible to every member of your Deepgram project—including members, admins, and owners. Do not store secrets such as API keys or passwords in agent configurations or template variables.

Common use cases

  • Per-customer configurations — Platforms that resell agent functionality can give each customer a distinct voice, persona, or model without maintaining separate codebases.
  • Regional and regulatory compliance — Maintain separate configurations for different markets (for example, EU vs. US) to enforce data-handling, language, or disclosure requirements without code branching.
  • A/B testing voices or prompts — Run two configurations in parallel and measure conversion, CSAT, or containment rate to pick a winner—no code deploy required.
  • Multi-agent architectures — Store and manage all of the agents used in your multi-agent architecture from a single project.

Using a reusable agent configuration

Once you’ve created an agent configuration (see Create an Agent Configuration below), pass its UUID as the value of the agent field in your Settings message:

1{
2  "type": "Settings",
3  "audio": {
4    "input": {
5      "encoding": "linear16",
6      "sample_rate": 24000
7    },
8    "output": {
9      "encoding": "linear16",
10      "sample_rate": 24000,
11      "container": "none"
12    }
13  },
14  "agent": "your-agent-config-uuid"
15}

Deepgram will look up the reusable configuration by UUID, interpolate any template variables, and apply the resulting agent block to your session.

Agent Configuration API

The base URL for all Agent Configuration endpoints is:

https://api.deepgram.com/v1

Create an Agent Configuration

$POST /projects/{project_id}/agents

Request body:

ParameterTypeDescription
configStringA valid JSON string representing the agent block of a Settings message
metadataObjectOptional. A map of arbitrary key-value pairs for labeling or organizing your agent configuration
api_versionIntegerOptional. API version. Defaults to 1

Example request:

$curl -X POST https://api.deepgram.com/v1/projects/{project_id}/agents \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "config": "{\"language\": \"en\", \"listen\": {\"provider\": {\"type\": \"deepgram\", \"model\": \"nova-3\"}}, \"think\": {\"provider\": {\"type\": \"open_ai\", \"model\": \"gpt-4o-mini\"}, \"prompt\": \"You are a helpful customer service agent.\"}, \"speak\": {\"provider\": {\"type\": \"deepgram\", \"model\": \"aura-2-thalia-en\"}}}",
>    "metadata": {
>      "name": "customer-service-agent",
>      "environment": "production"
>    }
>  }'

Response:

1{
2  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "config": { ... },
4  "metadata": {
5    "name": "customer-service-agent",
6    "environment": "production"
7  }
8}

The returned agent_id is the UUID you’ll pass in place of the agent block in future Settings messages.

List Agent Configurations

$GET /projects/{project_id}/agents

Returns all agent configurations for the specified project. Configurations are returned in their uninterpolated form—template variable placeholders will appear as-is rather than with their substituted values.

Example request:

$curl https://api.deepgram.com/v1/projects/{project_id}/agents \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY"

Get an Agent Configuration

$GET /projects/{project_id}/agents/{agent_id}

Returns the specified agent configuration in its uninterpolated form.

Example request:

$curl https://api.deepgram.com/v1/projects/{project_id}/agents/{agent_id} \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY"

Update Agent Metadata

$PUT /projects/{project_id}/agents/{agent_id}

Updates the metadata associated with an agent configuration. The config itself is immutable—to change the configuration, delete the existing agent and create a new one.

Request body:

ParameterTypeDescription
metadataObjectA map of string key-value pairs to associate with this agent configuration

Example request:

$curl -X PUT https://api.deepgram.com/v1/projects/{project_id}/agents/{agent_id} \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "metadata": {
>      "name": "customer-service-agent-v2",
>      "environment": "production"
>    }
>  }'

Delete an Agent Configuration

$DELETE /projects/{project_id}/agents/{agent_id}

Deletes the specified agent configuration.

Deleting an agent configuration can cause a production outage if your service references this agent UUID. Migrate all active sessions to a new configuration before deleting.

Example request:

$curl -X DELETE https://api.deepgram.com/v1/projects/{project_id}/agents/{agent_id} \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY"

Template Variables

Template variables let you define reusable values that can be referenced across agent configurations. When an agent configuration is used in a Settings message, Deepgram automatically interpolates the variable values before applying the configuration.

Template variable values are stored as plain text and are visible to all members, admins, and owners of your Deepgram project. Do not store secrets such as API keys or passwords in template variables.

Template variables follow the format DG_<VARIABLE_NAME>, where <VARIABLE_NAME> must consist of uppercase alphanumeric characters, underscores, or hyphens (e.g., DG_MY_MODEL, DG_DEFAULT_LANGUAGE).

Using Template Variables in a Configuration

Template variables can substitute any JSON value—a string, number, boolean, or even an entire object. For example:

1{
2  "language": "en",
3  "listen": {
4    "provider": {
5      "type": "deepgram",
6      "model": "DG_LISTEN_MODEL",
7      "smart_format": false
8    }
9  },
10  "think": {
11    "provider": {
12      "type": "open_ai",
13      "model": "DG_THINK_MODEL"
14    },
15    "prompt": "You are a helpful agent."
16  },
17  "speak": {
18    "provider": DG_SPEAK_PROVIDER
19  }
20}

In this example, DG_LISTEN_MODEL, DG_THINK_MODEL, and DG_SPEAK_PROVIDER are all template variables. DG_SPEAK_PROVIDER resolves to an entire provider object, while the others resolve to strings.

Agent Variable API

List Agent Variables

$GET /projects/{project_id}/agent-variables

Create an Agent Variable

$POST /projects/{project_id}/agent-variables

Request body:

ParameterTypeDescription
keyStringThe variable name, following the DG_<VARIABLE_NAME> format
valueAnyThe value to substitute. Can be any valid JSON type: string, number, boolean, object, or array
api_versionIntegerOptional. API version. Defaults to 1

Example request:

$curl -X POST https://api.deepgram.com/v1/projects/{project_id}/agent-variables \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "key": "DG_LISTEN_MODEL",
>    "value": "nova-3"
>  }'

Get an Agent Variable

$GET /projects/{project_id}/agent-variables/{variable_id}

Update an Agent Variable

$PATCH /projects/{project_id}/agent-variables/{variable_id}

Request body:

ParameterTypeDescription
valueAnyThe new value to substitute

Delete an Agent Variable

$DELETE /projects/{project_id}/agent-variables/{variable_id}

Full Example

The following example walks through creating an agent configuration with template variables and using it in a Voice Agent session.

Step 1: Create a template variable

$curl -X POST https://api.deepgram.com/v1/projects/{project_id}/agent-variables \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "key": "DG_SYSTEM_PROMPT",
>    "value": "You are a helpful customer service agent for Acme Corp."
>  }'

Step 2: Create an agent configuration referencing the variable

$curl -X POST https://api.deepgram.com/v1/projects/{project_id}/agents \
>  -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "config": "{\"language\": \"en\", \"listen\": {\"provider\": {\"type\": \"deepgram\", \"model\": \"nova-3\"}}, \"think\": {\"provider\": {\"type\": \"open_ai\", \"model\": \"gpt-4o-mini\"}, \"prompt\": \"DG_SYSTEM_PROMPT\"}, \"speak\": {\"provider\": {\"type\": \"deepgram\", \"model\": \"aura-2-thalia-en\"}}, \"greeting\": \"Hello! How can I help you today?\"}",
>    "metadata": {
>      "name": "acme-support-agent"
>    }
>  }'

This returns an agent_id, for example: a1b2c3d4-e5f6-7890-abcd-ef1234567890.

Step 3: Use the UUID in your Settings message

1{
2  "type": "Settings",
3  "audio": {
4    "input": {
5      "encoding": "linear16",
6      "sample_rate": 24000
7    },
8    "output": {
9      "encoding": "linear16",
10      "sample_rate": 24000,
11      "container": "none"
12    }
13  },
14  "agent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
15}

Deepgram resolves the UUID to the reusable configuration, substitutes DG_SYSTEM_PROMPT with its value, and applies the fully resolved agent block to your session.

Next Steps