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

# Variable System Overview

> Variables for flow builder and single-prompt agents—overview, quick start, and architecture

## Overview

This document covers the variable system used across all agent types. Variables enable dynamic data flow so you can capture, transform, and use data in your conversational agents.

**Applies to:**

* **Flow Builder Agents**: Multi-node workflows with variable extraction (AI, toolpath, DTMF), static variables, and flow logic
* **Single Prompt Agents**: Standalone conversational agents with a simplified variable model (system + custom only)

Variables provide context, enable personalization, and allow data to flow between parts of your agent—whether across nodes in a flow or within a single prompt configuration.

## Quick Start: Tool Testing & Variable Extraction

The steps below apply to **Flow Builder agents** only (tool nodes and variable extraction). Single prompt agents use only system and custom variables—see [Single Prompt Agent Variables](./availability-and-context#single-prompt-agent-variables) and [Example 6: Single Prompt Agent](./examples#example-6-single-prompt-agent-with-variables).

### For API Tool Nodes (Flow Builder)

1. ⚙️ **Configure Tool** → Set up endpoint, headers, parameters
2. 🧪 **Test Tool** → Click "Test Tool" to run with real data
3. ✅ **Verify Response** → Confirm the tool returns the expected shape
4. 📤 **Extract Variables** → Use the path selector with the test response
5. 👁️ **Preview Values** → Check that extracted values are correct
6. 💾 **Save** → Variables are available to successor nodes

**Why this matters:** Validates the API before deployment, avoids JSONPath mistakes, and surfaces issues at design time.

### For Web Tool Nodes (Flow Builder)

1. ⚙️ **Configure Web Tool** → Set up browser instructions and actions
2. 📋 **Define Expected Response** → Paste or type the expected structure (JSON object or string)
3. 📤 **Extract Variables** → Use the path selector against that expected structure
4. 👁️ **Preview Values** → Confirm extraction paths
5. 🧪 **Manually Verify** → Run the web tool to confirm the real response format
6. 💾 **Save** → Variables are available to successor nodes

**Why this matters:** Documents the response contract, supports JSON and string responses, and lets you use the path selector without server-side testing.

> **Important**
>
> * **API tools**: Test before configuring extraction; the path selector uses the actual test response.
> * **Web tools**: Define the expected response; the path selector validates against that format.

## Variable Architecture

The system has four main categories:

| Category                | Flow Builder Agents | Single Prompt Agents | Description                                             |
| ----------------------- | ------------------- | -------------------- | ------------------------------------------------------- |
| **System Variables**    | ✅                   | ✅                    | Platform-provided, always available (15+ variables)     |
| **Custom Variables**    | ✅                   | ✅ (as `params`)      | Workflow-level; in single-prompt, converted to `params` |
| **Extracted Variables** | ✅                   | ❌                    | From nodes (AI, toolpath, DTMF)—flow only               |
| **Static Variables**    | ✅                   | ❌                    | Node-level, fixed or templated—flow only                |

## Jinja2 Template Support

Prompts support the full **Jinja2** template language. This is not a partial implementation or a JavaScript approximation — templates are rendered by a real Python Jinja2 engine running server-side, before the prompt ever reaches the LLM. The LLM receives plain text; it never sees template syntax.

Beyond simple `{{variable_name}}` substitution, you can use:

* **Conditionals** — `{% if direction == "outbound" %}...{% else %}...{% endif %}`
* **Filters** — `{{ customer_name | default("there") | upper }}`
* **Local variables** — `{% set greeting = "Hello" %}`
* **Expressions** — any standard Jinja2 expression

For the full syntax reference, see the [Jinja2 Template Designer Documentation](https://jinja.palletsprojects.com/en/stable/templates/).

### Template Editor

When writing templates in the flow agent, prompts open in an **Expert Mode** editor with full Jinja2 tooling:

* **Syntax highlighting** — Jinja2 tags, variables, and filters are visually distinguished from plain text
* **Autocomplete** — press `{` to get snippet suggestions for `{{ }}` and `{% %}` blocks; inside a block, your available variables and all Jinja2 keywords and filters are suggested automatically
* **Real-time linting** — undefined variables are flagged immediately with a warning; if it looks like a typo, the editor suggests the correct variable name and offers a one-click fix
* **Type-aware property suggestions** — if a variable is typed as a string, array, or object, the editor suggests relevant properties and methods (`.length`, `| join`, `.first`, etc.)
* **Smart block closing** — the editor detects open `{% if %}` or `{% for %}` blocks and suggests the correct closing tag
* **Live preview** — supply test values for your variables and see the fully rendered output in real time, exactly as the LLM will receive it; syntax and runtime errors are surfaced immediately with the affected line number

See [Prompt Engineering Guide](/overview/guides/prompt-engineering) for examples.

## Next steps

* [System Variables](./system-variables) — Time, call, user, and agent variables
* [Custom Variables](./custom-variables) — Workflow-level variables for both agent types
* [Extracted Variables](./extracted-variables) — AI, toolpath, and DTMF extraction (flow only)
* [Static Variables](./static-variables) — Node-level values (flow only)
* [Availability & Context](./availability-and-context) — Where each type is available, including [Single Prompt Agent Variables](./availability-and-context#single-prompt-agent-variables)