VoltAgent Best Practices

# VoltAgent Best Practices for State Management

## Key Guidelines

### 1. **Use Immutable State Where Possible**
Avoid mutating state directly in agents. Instead, use VoltAgent’s `update_state()` method to ensure traceability and debugging ease. Example:
```python
# ❌ Avoid: Direct mutation
agent.state.counter += 1

# ✅ Prefer: Immutable update
agent.update_state(counter=agent.state.counter + 1)
```

### 2. **Leverage State Hooks for Side Effects**
Use `on_state_change` hooks to trigger actions like logging or external API calls when state updates. This keeps your agents reactive without cluttering core logic.
```python
@agent.on_state_change('counter')
def log_counter_change(old, new):
    print(f"Counter updated from {old} to {new}")
```

### 3. **Validate State Transitions**
Define allowed state transitions in your agent’s schema to prevent invalid workflows. For example, restrict a `payment_processing` agent from skipping the `validation` step.
```python
class PaymentAgent(VolAgent):
    state_schema = {
        'status': ['pending', 'validated', 'processing', 'completed', 'failed'],
        'valid_transitions': [('pending', 'validated'), ('validated', 'processing')]
    }
```

## Common Pitfalls
- **Overwriting State**: Never replace `agent.state` entirely. Use `update_state()` to merge changes.
- **Unbounded State Growth**: Trim unused state keys with `agent.trim_state(['old_key1', 'old_key2'])` to avoid memory bloat.

Need help debugging a specific state issue? Share your agent’s state structure and error logs!