Dynamic Variables & Overrides

An agent’s published configuration is shared by every caller — but each session can be personalized at creation time. Two mechanisms cover this, and both travel in the same POST /v1/agent/sessions request:

Mechanism	What it does	Gated by
`dynamic_variables`	Fills `{{placeholder}}` templates in your configuration text	Nothing per-agent — no allowlist
`overrides`	Replaces whole configuration fields for this session	Per-agent allowlist of overridable fields

Dynamic variables

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.

Overrides

Overrides replace configuration fields wholesale for one session — for example, forcing a different language for a caller. Because they change agent behavior, each agent declares which fields callers may override; everything else is rejected.

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",
    "overrides": { "language": "ja" }
  }'

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

const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
  overrides: { language: "ja" },
});

The `language` shorthand

Overriding the session language is common enough that the request accepts a top-level language field as shorthand for overrides.language. Both forms pass through the same allowlist gate — if language is not overridable on the agent, both are rejected.

{ "agent_id": "YOUR_AGENT_ID", "language": "ja" }

Validation

Case	Result
Override field not on the agent’s allowlist	`400`
Unknown field inside `overrides`	`422`
Unknown top-level field in the request	`422`

The session record stores which overrides took effect.

Who supplies the values

Where variables and overrides come from depends on how the session is authenticated:

Mode	Who creates the session	Who supplies variables and overrides
`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 overrides, dynamicVariables, and language options have 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 },
    overrides: { language: user.locale },
  }),
});
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. Keep the override allowlist limited to fields you are comfortable letting anyone set, and use sessionToken mode when personalization must come from data only your backend knows.

Going further

Agent configuration

The fields your placeholders and overrides act on.

Authentication

API keys, session tokens, and the two session modes.

Versions & publishing

Sessions assemble the published configuration.

Web SDK

Every AgentSession.start() option.

Get Started

Build

Test

Deploy

Telephony

Monitor

Dynamic Variables & Overrides