Reusable Agent Configurations

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.

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:

JSON

{
  "type": "Settings",
  "audio": {
    "input": {
      "encoding": "linear16",
      "sample_rate": 24000
    },
    "output": {
      "encoding": "linear16",
      "sample_rate": 24000,
      "container": "none"
    }
  },
  "agent": "your-agent-config-uuid"
}

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

Bash

POST /projects/{project_id}/agents

Request body:

Parameter	Type	Description
`config`	String	A valid JSON string representing the `agent` block of a `Settings` message
`metadata`	Object	Optional. A map of arbitrary key-value pairs for labeling or organizing your agent configuration
`api_version`	Integer	Optional. API version. Defaults to `1`

Example request:

Bash

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\", \"version\": \"v2\", \"model\": \"flux-kit-en\"}}}",
    "metadata": {
      "name": "customer-service-agent",
      "environment": "production"
    }
  }'

Response:

JSON

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "config": { ... },
  "metadata": {
    "name": "customer-service-agent",
    "environment": "production"
  }
}

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

List Agent Configurations

Bash

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:

Bash

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

Get an Agent Configuration

Bash

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

Returns the specified agent configuration in its uninterpolated form.

Example request:

Bash

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

Update Agent Metadata

Bash

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:

Parameter	Type	Description
`metadata`	Object	A map of string key-value pairs to associate with this agent configuration

Example request:

Bash

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

Bash

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

Deletes the specified agent configuration.

Example request:

Bash

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:

JSON

{
  "language": "en",
  "listen": {
    "provider": {
      "type": "deepgram",
      "model": DG_LISTEN_MODEL,
      "smart_format": false
    }
  },
  "think": {
    "provider": {
      "type": "open_ai",
      "model": DG_THINK_MODEL
    },
    "prompt": "You are a helpful agent."
  },
  "speak": {
    "provider": DG_SPEAK_PROVIDER
  }
}

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

Bash

GET /projects/{project_id}/agent-variables

Create an Agent Variable

Bash

POST /projects/{project_id}/agent-variables

Request body:

Parameter	Type	Description
`key`	String	The variable name, following the `DG_<VARIABLE_NAME>` format
`value`	Any	The value to substitute. Can be any valid JSON type: string, number, boolean, object, or array
`is_sensitive`	Boolean	Required. Must be `false`
`api_version`	Integer	Optional. API version. Defaults to `1`

Example request:

Bash

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",
    "is_sensitive": false
  }'

Get an Agent Variable

Bash

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

Update an Agent Variable

Bash

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

Request body:

Parameter	Type	Description
`value`	Any	The new value to substitute

Delete an Agent Variable

Bash

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

Bash

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.",
    "is_sensitive": false
  }'

Step 2: Create an agent configuration referencing the variable

Bash

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\", \"version\": \"v2\", \"model\": \"flux-kit-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

JSON

{
  "type": "Settings",
  "audio": {
    "input": {
      "encoding": "linear16",
      "sample_rate": 24000
    },
    "output": {
      "encoding": "linear16",
      "sample_rate": 24000,
      "container": "none"
    }
  },
  "agent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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

Configure the Voice Agent — see all available agent configuration options.
Voice Agent Settings — learn about the full Settings message format.
Voice Agent Message Flow — understand the correct message flow for building a Voice Agent client.

Search documentation

Self-Hosted Deployments

Reusable Agent Configurations

Overview

Common use cases

Using a reusable agent configuration

Agent Configuration API

Create an Agent Configuration

List Agent Configurations

Get an Agent Configuration

Update Agent Metadata

Delete an Agent Configuration

Template Variables

Using Template Variables in a Configuration

Agent Variable API

List Agent Variables

Create an Agent Variable

Get an Agent Variable

Update an Agent Variable

Delete an Agent Variable

Full Example

Next Steps

Self-Hosted Deployments