Skip to main content
This guide helps you identify and fix problems with a conversation flow agent’s responses, transitions, and conversation structure.
For audio issues, such as pronunciation, see the speech settings and guides.

​
Step 1: Identify the issue

When the agent is not responding as expected, there can be several reasons:
  • The agent is not following instructions within a node
  • Node transitions are not working as expected
  • The actual conversation does not match the flow graph (e.g., users deviate from expected steps)

​
Step 2: Fix the issue

Note that these issues are not mutually exclusive - you may need to implement multiple solutions to fully resolve the problem.

​
Issue: Agent is not following instructions within a node

​
Review the prompts

Read the global prompt and the node prompt together. Check for unclear, conflicting, or unnecessary instructions before adding another rule. See the general prompting principles.

​
Split the node into multiple nodes

If the necessary instructions and tools make the node’s context too large for the model to follow reliably, splitting the task across nodes can help. However, each split also restricts how the conversation can proceed. See the conversation flow best practices before splitting related conversation into separate nodes.

​
Change the node model

If the instructions are concise but the agent struggles to follow them, try using a more capable LLM model for this node.

​
Add conversation finetune examples

To achieve a specific response style, add conversation finetune examples. Learn more in our Finetune Examples guide.

​
Adjust the LLM temperature

If the agent’s responses are inconsistent, try adjusting the LLM temperature:

​
Issue: Node transitions are not working as expected

If the agent isn’t transitioning to the expected node, try these solutions:
  • Review your transition conditions: Ensure they precisely match your intended triggers. Keep conditions clear and the number of transition choices small. See the conversation flow prompting guidelines.
  • Add transition finetune examples: Provide examples to help the model understand your expectations. See our Finetune Examples guide.
  • Remove numbered labels from prompts: Items like “PRIORITY 1” or “Step 2” in your global prompt or node instructions can be confused with transition options and trigger a transition whose condition was never met. Use letters (“PRIORITY A”) or descriptive names instead — see the transition conditions FAQ.
The node transition model evaluates conditions independently of the response model. Changing the agent’s response model does not change the node transition model. For a missing transition scenario, first consider whether the current node can handle the request. Add a separate path only when it is needed; avoid adding transitions for speculative cases.

​
Issue: Actual conversation does not match the flow graph

Callers may provide several details at once or change an earlier answer after a transition. Check whether related conversation and tool calls can stay in one subagent node. See the examples of rigid conversation flows. Use global nodes sparingly for situations that need to be handled regardless of the current node. Each global node adds transition choices throughout the conversation flow.