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 availability depends on agent type and flow position. The system uses flow analysis to decide which variables each node (or single prompt) can use.
Availability by Variable Type
| Variable Type | Global Nodes | Regular Nodes | Single-Prompt Agent | Logic |
|---|
| System Variables | ✅ Yes | ✅ Yes | ✅ Yes | Always available |
| Custom Variables | ✅ Yes | ✅ Yes | ✅ Yes | Always available |
| Extracted Variables | ❌ No | ✅ Yes* | ❌ No | Only from predecessor nodes |
| Static Variables | ❌ No | ✅ Yes* | ❌ No | Only from predecessor nodes |
Flow Position Rules (Flow Agent)
- Predecessors only: A node sees variables only from nodes that run before it.
- Execution paths: All possible paths are considered when computing predecessors.
- Global nodes: Nodes with
isGlobal: true see only system and custom variables.
- Caching: Availability is cached per node and refreshed when the flow changes.
Example Flow
Start Node (creates: user_number)
↓
Conversation Node (creates: customer_name, appointment_date)
↓
Tool Node (creates: booking_id, confirmation_code)
↓
End Node
Available at each step:
- Start Node: system, custom
- Conversation Node: system, custom, user_number
- Tool Node: system, custom, user_number, customer_name, appointment_date
- End Node: system, custom, user_number, customer_name, appointment_date, booking_id, confirmation_code
Single Prompt Agent Variables
Single prompt agents are standalone conversational agents that don’t use the flow builder. They have a simplified variable model optimized for quick deployment and simple use cases.
Variable Availability
| Variable Type | Available | Notes |
|---|
| System Variables | ✅ Yes | All 15+ platform variables available |
| Custom Variables | ✅ Yes | Converted to params in configuration |
| Extracted Variables | ❌ No | No flow nodes to extract from |
| Static Variables | ❌ No | No nodes to define static variables |
How Custom Variables Work in Single Prompt Agents
Custom variables in single prompt agents act as parameters that configure the agent:
Definition (Variables Panel):
Custom Variables:
- business_name: "Acme Corporation"
- support_email: "[email protected]"
- max_conversation_turns: 10
- enable_transfers: true
// Custom variables become params in agent configuration
{
params: {
business_name: "Acme Corporation",
support_email: "[email protected]",
max_conversation_turns: 10,
enable_transfers: true
}
}
You are a customer service agent for {{business_name}}.
If customers need help, direct them to {{support_email}}.
Keep conversations under {{max_conversation_turns}} turns.
{{#if enable_transfers}}You can transfer calls to human agents.{{/if}}
Key Differences from Flow Builder Agents
| Aspect | Flow Builder Agents | Single Prompt Agents |
|---|
| Complexity | Multi-node workflows | Single prompt configuration |
| Variables | System + Custom + Extracted + Static | System + Custom only |
| Extraction | AI extraction, toolpath, DTMF | Not supported |
| Flow Logic | Conditional branching, loops | Linear conversation |
| Custom Variables | Workflow-level state | Configuration parameters |
| Use Case | Complex workflows | Simple conversational agents |
Use Cases for Single Prompt Agents
Good for:
- Simple Q&A agents
- Information lookup agents
- Basic customer service
- FAQ bots
- Quick prototypes
- Agents with minimal state
Not good for:
- Multi-step workflows
- Data collection and processing
- API integrations with variable extraction
- Complex conditional logic
- State management across multiple steps
Configuration Example
Variables Panel (Custom Variables):
working_hours: "9 AM - 5 PM EST"
support_tier: "premium"
escalation_enabled: true
System Prompt:
You are {{agent_name}}, a helpful assistant.
Our working hours are {{working_hours}}.
Current time: {{current_time}}
Current date: {{current_date}}
Instructions:
- Be friendly and professional
- Answer questions about our products
{{#if escalation_enabled}}
- Offer to escalate complex issues to human agents
{{/if}}
User's phone: {{user_number}}
Call direction: {{direction}}
- ✅
working_hours, support_tier, escalation_enabled (custom)
- ✅
agent_name, current_time, current_date, user_number, direction (system)
When to Upgrade to Flow Builder
Consider upgrading to a Flow Builder agent when you need to:
- Extract data from conversations (AI extraction)
- Integrate with APIs and parse responses (toolpath extraction)
- Use conditional branching or multi-step logic
- Collect structured information across nodes
- Use DTMF capture or static variables
For DOs and DON’Ts specific to single prompt agents, see Best Practices: Single Prompt Agent Variables.
Variable Categories & Display
Variables are grouped for the UI:
| Category | Icon | Contains |
|---|
| System | 🔧 | Platform variables |
| Custom | ⚙️ | Workflow-level variables |
| Extracted | 📤 | From nodes (AI, toolpath, DTMF) |
| Static | 📌 | Node-level set values |
Context-Aware Recommendations
The UI can suggest variables based on node type and content:
- Conversation: e.g.
customer_name, phone_number, appointment_date, issue_description
- Tool: e.g.
api_response, status_code, response_data, error_message
- Transfer: e.g.
transfer_reason, customer_context, conversation_summary
See UI Components & Validation for where these appear and Introduction for the overall model.
