Best Practices

Guidance for working with variables

This page covers key constraints and patterns for variables. Additional best practices from the Hamsa engineering team will be added here over time.

Variable Naming

All variable names must be snake_case (lowercase letters, underscores, starting with a letter):

✅ customer_name
✅ account_balance
✅ is_verified

❌ customerName     (camelCase not accepted)
❌ Customer-Name    (kebab-case not accepted)
❌ customer name    (spaces not accepted)

Extraction Availability

Extracted variables are only available after the node that collects them. Do not reference an extracted variable in a transition or node that comes before it in the flow.

Global node conditions cannot reference extracted variables — use system variables or custom variables there instead.

Single Prompt Agents

Custom variables are the only type available in single prompt agents. Extracted variables and static variables are not supported. Custom variables become params in the agent configuration and must be passed when initiating a call.

Testing Tool Extraction

Always test a tool call first to see its actual response before configuring extraction. Use the path selector to pick JSONPath expressions from the real response — avoid writing JSONPath by hand.

---

Next Steps

Custom Variables

Define variables in your agent configuration

Extracted Variables

Collect data from conversations and tool responses

Troubleshooting

Diagnose common variable issues

Examples

See full flow examples with variables