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.

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):

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