Dynamic Variables

An agent’s published configuration is shared by every caller — dynamic variables personalize it per session. Write {{variable_name}} placeholders in your agent’s system prompt or first message and supply values when you create the session. Substitution happens once, when the published configuration is assembled for the session.

System prompt

You are a support agent for {{company}}. The caller's name is {{customer_name}}
and they are on the {{plan}} plan. Greet them by name.

Pass values as a flat object of strings, numbers, or booleans. Variable names must match [A-Za-z][A-Za-z0-9_]* (no hyphens or dots), string values are capped at 1,000 characters, and a request can carry at most 50 variables — violations reject session creation with 422:

curl --request POST https://api.fish.audio/v1/agent/sessions \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "YOUR_AGENT_ID",
    "dynamic_variables": {
      "company": "Acme",
      "customer_name": "Ada",
      "plan": "Pro"
    }
  }'

import { AgentSession } from "@fishaudio/agent-client";

// Public agent: the SDK creates the session and sends the variables for you.
const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
  dynamicVariables: { company: "Acme", customer_name: "Ada", plan: "Pro" },
});

Placeholders with no matching variable are not removed — the literal {{variable_name}} text stays in the prompt, visible to the model. Make sure every placeholder in your configuration has a value at session creation.

Session records never store dynamic variable values.

You don’t need a variable for the current date or time — the agent already knows both, in the session’s timezone. See Time & timezone.

Variables fill placeholders in the configured text. To replace whole configuration fields for a session — the prompt itself, the opener, voice, language — use overrides on the same request; {{placeholders}} render inside overridden text too.

Who supplies the values

Where variable values come from depends on the session’s access mode:

Mode	Who creates the session	Who supplies the values
`agentId` (public agents)	The SDK, directly from the browser	The browser, via `AgentSession.start()` options
`sessionToken` (private agents)	Your backend, with your API key	Your backend, in its `POST /v1/agent/sessions` call

In sessionToken mode the SDK’s dynamicVariables option has no effect — the session already exists by the time the token reaches the browser. Attach personalization server-side instead:

Backend (sessionToken mode)

// Your backend endpoint, called by your own frontend
const response = await fetch("https://api.fish.audio/v1/agent/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FISH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "YOUR_AGENT_ID",
    dynamic_variables: { customer_name: user.name, plan: user.plan },
  }),
});
const sessionToken = await response.json(); // pass to AgentSession.start({ sessionToken })

In agentId mode, values arrive from the end user’s browser — treat them as untrusted input, and use sessionToken mode when personalization must come from data only your backend knows.

Going further

Agent configuration

The fields your placeholders act on.

Overrides

Replace whole configuration fields for one session.

Versions & publishing

Sessions assemble the published configuration.

Web SDK

Every AgentSession.start() option.

Get Started

Build

Test

Deploy

Telephony

Monitor

Who supplies the values

Going further

Agent configuration

Overrides

Versions & publishing

Web SDK

​Who supplies the values

​Going further

Agent configuration

Overrides

Versions & publishing

Web SDK

Who supplies the values

Going further