Skip to main content

​
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 and Example 6: Single Prompt Agent.

​
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:
CategoryFlow Builder AgentsSingle Prompt AgentsDescription
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.

​
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 for examples.

​
Next steps