How-to guidesAgents

Add variables

Define dynamic variables on an agent and supply values at session start

Variables let one agent serve many contexts. For the syntax, types, and precedence, see Variables.

1

Define variables on the agent

PATCH the agent’s variable catalog. Each variable has a key, type, optional default, and optional description. The call replaces the list wholesale (up to 20 variables per agent) — send "variables": [] to clear it.

PATCH
/v1/agents/:id/variables
1curl -X PATCH https://api.speechify.ai/v1/agents/id/variables \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "variables": [
6    {
7      "key": "product_name",
8      "type": "string",
9      "default": null,
10      "description": "Product the agent is supporting."
11    },
12    {
13      "key": "support_tier",
14      "type": "number",
15      "default": null
16    },
17    {
18      "key": "account_metadata",
19      "type": "json",
20      "description": "Arbitrary account context injected into tool bodies."
21    }
22  ]
23}'
Try it
2

Reference them in the prompt and tools

Use {{key}} in the prompt, first message, or webhook tool config:

You are a {{product_name}} support agent for a tier-{{support_tier}} customer.

Inside a JSON tool body, use the {{key|json}} form so the value is safely escaped — see Variables → Interpolation.

3

Pass values at session start

Per-session values merge on top of the agent defaults.

Send dynamic_variables to POST /v1/agents/{id}/conversations (server-to-server) or /sessions (widget/browser):

POST
/v1/agents/:id/conversations
1curl -X POST https://api.speechify.ai/v1/agents/agent_01HS.../conversations \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "dynamic_variables": {
6    "product_name": "Acme Pro",
7    "support_tier": 2,
8    "account_metadata": {
9      "plan": "enterprise",
10      "seats": 50
11    }
12  }
13}'
Try it

system__* keys are reserved — they’re rejected in both the agent catalog and session overrides.