Dynamic variables

Dynamic variables are the way you inject per-session context into an agent without editing the persona prompt. The persona references variables as {{name}}; the runtime substitutes the resolved value before the model ever sees the prompt.

Three sources, in priority order:

1. Per-session overrides passed to POST /sessions.
2. Variable resolver — an agent-configured HTTP fetch that runs at session start.
3. Agent defaults declared on the agent’s dynamic_variables config.
4. System variables — supplied by Hyponema (clock, language, IDs, user fields).

Where variables show up

• Persona prompt — anywhere {{name}} appears in system_prompt or first_message.
• Custom tool calls — when the tool has allow_dynamic_vars: true. URL, headers, query params, and JSON body get rendered before the call.

Built-in and system tools never receive template substitution.

System variables

Hyponema computes a fixed set of system__* variables for every turn and exposes them through the dashboard variable picker. The catalog is the source of truth — pull it from your workspace:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/variables/catalog" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

Typical entries cover:

• Current UTC time, user-local date and weekday, time-of-day bucket.
• Negotiated conversation language.
• Current agent ID, agent version, conversation ID.
• The user’s display name, first name, phone, timezone, and language.

Use them in prompts like:

You are {{system__user_name}}'s reception agent. It is currently
{{system__time_of_day}} ({{system__day_of_week}}) in {{system__subject_timezone}}.

Unresolved placeholders are kept verbatim in the rendered prompt — useful for previewing.

Custom variables

A custom variable is declared on the agent’s Variables tab with:

• Name — referenced as {{name}}.
• Default value — used when no per-session override and no resolver value is supplied.
• Required — when true, an empty default + missing override leaves the placeholder verbatim, surfacing the gap in the trace.
• Source type — describes where this variable normally comes from (e.g. session, resolver). Drives dashboard validation.
• Rules — optional path/operator/value triples that compute a result from the resolver payload.

Per-session overrides

Pass dynamic_variables when creating a session:

curl -X POST "https://api.hyponema.ai/sessions" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "user_id": "user_123",
    "modality": "voice+text",
    "dynamic_variables": {
      "plan_tier": "pro",
      "open_ticket_id": "TCK-9821"
    }
  }'

The signed session token carries a dvh claim (a SHA-256 hash of the dynamic variable map). The runtime rejects mismatches between token and request to prevent client-side tampering.

Variable names must match the agent’s declared custom variables. Unknown names are rejected at session-create time.

Variable resolver

A variable resolver lets the agent fetch context from your backend at session start instead of asking the caller to pass it through. Configure one per agent:

• URL + method — your endpoint. Receives session metadata.
• Auth header — encrypted at rest.
• Timeout — 250–10000 ms.
• Required — when true, a resolver failure aborts the session with a clear error instead of falling back to defaults.

Run a preview against a real user from the dashboard or the API:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/variable-resolver/preview" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "modality": "voice",
    "dynamic_variables": { "plan_tier": "pro" }
  }'

The response shows the resolved variable map, anything that was required but missing, and the resolver status / error.

Resolution order at runtime

For each turn:

1. Build the system variable map.
2. Apply agent defaults for declared custom variables.
3. If the resolver is configured and enabled, run it and merge over defaults.
4. Apply per-session overrides last.
5. Render the persona prompt and any allowed tool calls against the merged map.

Required variables that are still empty at the end of step 4 leave the placeholder verbatim — you’ll see it in the trace.

Operational guidance

• Keep variable names short and descriptive. They show up in prompts and traces.
• Declare every variable you reference. Undeclared {{names}} survive substitution but you lose the dashboard picker, validation, and the resolver path.
• Don’t stuff PII into variable names. Names live in traces.
• Resolver endpoints should be fast (under a second). They block session start.