> ## 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.

# Best Practices

> Guidance for building reliable flow agents

<Info>
  This page covers structural and naming conventions for flow agents. Additional best practices from the Hamsa engineering team will be added here over time.
</Info>

## Node Naming

Use descriptive, action-oriented names that make the flow self-documenting:

```
✅ Welcome_and_Identify_Caller
✅ Collect_Account_Number
✅ Route_by_Issue_Type
✅ Transfer_to_Billing_Specialist

❌ Node 1
❌ Router
❌ Conversation
```

## Variable Naming

All variable names must be snake\_case (lowercase, underscores, starts with a letter):

```
✅ customer_name
✅ account_balance
✅ issue_category

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

Use specific, descriptive names rather than generic ones:

```
✅ account_number, customer_id, payment_status
❌ number, id, status
```

## Always Include a Fallback Transition

Every node that has conditional transitions needs an **Always** transition as a fallback. Without it, the conversation can stall if no conditions match.

```yaml theme={null}
Transitions:
  - Natural: "billing question" → Billing
  - Natural: "technical issue" → Tech
  - Always → General_Help    # Required fallback
```

## Use Extracted Variables Carefully

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 use extracted variables — use system variables or custom variables there instead.

## Provide Fallback Values in Messages

Use fallback syntax when referencing variables that might not be set:

```
"Hello {{customer_name || 'there'}}, your balance is {{balance || 'unavailable'}}."
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Global Settings" href="./global-settings">
    Configure agent-level defaults
  </Card>

  <Card title="Node Types" href="./nodes/overview">
    Learn about all available node types
  </Card>

  <Card title="Transitions" href="./transitions">
    Understand transition types and priority
  </Card>

  <Card title="Debugging" href="./debugging">
    Validate and test your flow
  </Card>
</CardGroup>