> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syllable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> How to use dynamic variables for personalized agent responses using the Syllable Console interface.

Variables enable dynamic content substitution throughout the Syllable platform. They allow you to create personalized, context-aware experiences by automatically replacing variable placeholders with actual values during runtime.

## Syntax

The platform supports three variable substitution formats. Each behaves differently when a variable is missing and supports different features.

| Syntax           | When variable exists | When variable is missing     | Default value                             |
| ---------------- | -------------------- | ---------------------------- | ----------------------------------------- |
| `{variable}`     | Replaced with value  | Left as literal `{variable}` | No                                        |
| `${variable}`    | Replaced with value  | Replaced with empty string   | Yes: `${var=fallback}` or `${var=$other}` |
| `{{ variable }}` | Replaced with value  | Replaced with empty string   | No                                        |

Variable names can include letters (A–Z, a–z), numbers (0–9), underscores (\_), and periods (.). No spaces or other symbols are allowed inside the variable name.

For `{{ variable }}`, spaces around the variable name are ignored, so `{{ x }}` and `{{x}}` are equivalent.

**`${variable}` and spaces:** Unlike `{{ variable }}`, `${...}` does not trim or ignore spaces inside the braces. `${ agent_name }` will not resolve; use `${agent_name}` with no spaces around the name.

### Choosing the right syntax

* **`{{ variable }}`** — Default for most cases: greetings, tool descriptions, tool static parameters. When the variable is missing, it becomes an empty string. Use this when you want missing values to disappear from the output.

* **`{variable}`** — Use when you want the model to see the placeholder if the variable is missing. For example, `Hello {name}` keeps `Hello {name}` in the prompt when `name` is not set, so the model can adapt instead of seeing `Hello ` with no indication a name was expected.

* **`${variable=fallback}`** — Use when a missing value should resolve to a specific default value. You can use a static default (e.g. `${vars.provider_name=your provider}`) or another variable (e.g. `${vars.provider_name=$vars.pcp}`). **Only** `${...}` supports resolving to a specific default value, `{{ variable=default }}` is invalid and will not provide a fallback.

## Variable Types

### System Variables

System variables provide access to platform-managed data and session context. **Use the `vars.session.*` path** for these values (for example `{{ vars.session.agent.name }}`). Shorter forms such as `{{ vars.agent_name }}` do **not** resolve session fields—even when a similarly named custom variable exists, they resolve to empty.

* `{{ vars.session.id }}` - Unique identifier for the current session
* `{{ vars.session.agent.name }}` - Name of the current agent
* `{{ vars.session.datetime }}` - Current timestamp, e.g., `2025-01-02 12:00`
* `{{ vars.session.date }}` - Current date, e.g., `2025-01-02`
* `{{ vars.session.day_of_week}}` - Current day of week, e.g., `Tuesday`
* `{{ vars.session.timezone}}` - Agent's timezone, e.g., `America/Los_Angeles`
* `{{ vars.session.language }}` - Current language code for the session, e.g. `en-US`
* `{{ vars.session.source }}` - ANI, e.g., "+14085555555"
* `{{ vars.session.target }}` - DNIS, e.g., "+16505555555"

### Custom Variables

Custom variables are the values you configure on the agent (for example company name, customer name, or other fields you define). **Reference them by name with no `vars.` prefix** in templates—for example `{{ agent_name }}` or `{{ customer_name }}`.

Using `{{ vars.<name> }}` for a custom agent variable does not work as a shorthand: for example `{{ vars.agent_name }}` resolves to empty even when `agent_name` is set. Use `{{ agent_name }}` instead.

* `{{ custom_field }}` — A user-defined variable configured on the agent (bare name, not `vars.custom_field` for substitution in prompts and messages)

## Usage Examples

### In Prompts

Variables can be used within prompt content to create dynamic, personalized instructions:

```markdown theme={null}
You are a helpful customer service agent for {{ company }}.
The current location is {{ location_info }}
The current date is {{ vars.session.date }}.

Greet the user: Hello {customer_name}
```

Substitution runs **before** the text is sent to the model. If `customer_name` is not set, `{{ customer_name }}` becomes `Hello ` (empty string)—the model never sees the double-curly placeholder. With **`{customer_name}`**, the placeholder stays literal in the prompt when the value is missing, so the model can see `Hello {customer_name}` and adapt.

### Messages

Create dynamic greeting messages that adapt to different contexts:

```markdown theme={null}
Hello! Thank you for calling {{ company }}. 
My name is {{ vars.session.agent.name }} and I'm here to help you today.

{{ business_hours_message }}
```

### Tool Descriptions

Make tool descriptions more contextual and informative:

```json theme={null}
{
  "function": {
    "name": "schedule_appointment",
    "description": "Schedule an appointment for {{ customer_name }} at {{ location_name }}. Current time: {{ timestamp }}"
  }
}
```

### Tool Static Parameters

Use variables to set dynamic default values for tool parameters:

```json theme={null}
{
  "staticParameters": [
    {
      "name": "customer_id",
      "default": "{{ account_id }}",
      "description": "Customer account identifier"
    },
    {
      "name": "session_context",
      "default": "{{ vars.session.id }} - {{ vars.session.language }}",
      "description": "Session tracking information"
    }
  ]
}
```

## Best Practices

### Choose the right syntax for the context

* Use **`{{ variable }}`** for greetings, tool descriptions, and static parameters when missing values should become empty.
* Use **`{variable}`** in prompts when you want the model to see the placeholder when the variable is missing.
* Use **`${variable=fallback}`** when you need a default value. **Common pitfall:** `{{foo=bar}}` does not work as a default—only `${foo=bar}` supports default values.

### Variable Naming

* Use descriptive, lowercase names with underscores for readability
* **Custom agent variables:** use the bare name in templates (`{{ customer_name }}`), not `{{ vars.customer_name }}`
* **System/session fields:** always use `vars.session.*` (for example `{{ vars.session.date }}`)
* Avoid spaces and special characters in variable names

**Good examples:**

* `{{ customer_name }}` (custom variable configured on the agent)
* `{{ vars.session.agent.name }}` (system variable)
* `{{ order_number }}` (custom variable)

**Avoid:**

* `{{ Customer Name }}` (spaces)
* `{{ vars.customer-name }}` (hyphens)
* `{{ CUSTOMER_ID }}` (all caps)

### Error Handling

Variables that cannot be resolved will typically:

* Be replaced with blank values when using `{{ variable }}` or `${variable}` (e.g., `Welcome, {{ unknown_var }}!` becomes `Welcome, !`)
* Be left as literal text when using `{variable}` (e.g., `Hello {name}` stays `Hello {name}` if `name` is missing)
* Not break the overall functionality

Always test your variable usage to ensure proper resolution.

### Security Considerations

* Never expose sensitive information through variables
* Validate custom variable values before use
* Be cautious when using variables in tool parameters that make external API calls

## Troubleshooting

### Variable Not Resolving

If a variable is not replaced or replaced with a blank string instead of its expected value:

1. **Check spelling** - Variable names are case-sensitive
2. **Verify scope** - Ensure the variable is available in the current context, for example, a prompt can only reference variables that are available at the start of the session
3. **Check syntax** - Confirm you're using the intended format: `{{ }}`, `${}`, or `{}` depending on the behavior you want
4. **Validate data source** - For custom variables, ensure the data source is properly configured

### Variable appears as literal `{variable}` in output

If you see the placeholder (e.g. `{customer_name}`) in the final text instead of a value, you are using the **`{variable}`** syntax and the variable is missing. That format intentionally leaves the placeholder in place. With **`{{ customer_name }}`**, a missing value becomes an empty string—you would not see `{{ customer_name }}` literally in the output. To get an empty string when the variable is missing, use `{{ variable }}` or `${variable}` instead—or ensure the variable is set.

## Syntax comparison and equivalents

* **`{{ variable }}`** and **`${variable}`** both yield an empty string when the variable is missing. Use either when you want missing values to disappear.
* **`{variable}`** is the only format that leaves the placeholder in the text when the variable is missing—useful in prompts where the model should see the placeholder.
* Default values are only available with **`${variable=default_value}`**; the `{{ }}` syntax does not support `=default`.

## Related Documentation

* [Prompts](/resources/Prompts) - Learn how to use variables in prompt content
* [Tools](/resources/Tools) - Discover variable usage in tool configuration
* [Messages](/resources/Messages) - Implement variables in greeting messages
* [Agents](/workspaces/Agents) - Configure agent-level variable settings