Why it matters
The Start Chat Agent action allows one agent to activate another AI chat agent for continued conversation handling. This is useful for routing conversations between specialized agents, escalating from a call flow to chat, or handing off to a different automation flow.
Creating the tool alone is not enough. You must assign the tool to the agent and clearly define in the agent instructions when the chat agent should be started.
Key Concepts
Action Tool: A tool created using the Execute Actions tool type that allows an agent to perform structured system actions such as starting another agent, tagging contacts, or updating records.
Execute Actions Tool Type: A tool type that enables you to configure one or more actions inside a single tool. Multiple actions can run when the tool is triggered.
Start Chat Agent Action: An action that activates a selected AI chat agent for the current contact when executed.
Initial Message Setting: A checkbox that determines whether the newly started chat agent sends the first message or waits for the contact to message first.
Conversation History Variable: A variable written as conversation_history. The chat agent cannot access previous messages unless this variable is included in its instructions.
Agent Instructions: The configuration where you define when the tool should be triggered and how the transition between agents should work.
Step-by-Step: Create a Start Chat Agent Action Tool
Navigate to Agents in the left-hand menu.
Click Tools (jigsaw icon).
Click Create Tool in the top right corner.
Select Execute Actions from the Tool Type dropdown.
Enter a Tool Name and click Save Tool.
Configure Basic Info
Enter the Label. Use only letters, numbers, underscores, or hyphens. Maximum 64 characters.
Add a clear Description explaining when the chat agent should be started.
Click Save.
Configure Tool Settings
Set the Timeout (milliseconds). Default is 5000 ms.
Toggle Speak After Execution if the current agent should confirm the handoff.
Toggle Speak During Execution if required.
Add execution speech if enabled.
Click Save.
Add the Start Chat Agent Action
In the Actions section, click Add Action.
Select Start Chat Agent from the Action Type dropdown.
In the agent selection field, choose the chat agent you want to activate.
Enable or disable Send Initial Message:
Enabled: The chat agent sends the first message.
Disabled: The chat agent waits for the contact to message first.
Click Create Action.
When the tool is triggered, the selected chat agent will be activated for the contact.
You can add additional actions to the same tool if needed.
Important: Conversation History Access
The chat agent cannot access previous messages by default.
If the new chat agent needs context from earlier messages, you must include the conversation_history variable in the chat agent’s instructions. Without this variable, the agent will not have access to past conversation content.
Ensure this is explicitly defined in the receiving agent’s instructions.
Implement the Tool in an Agent
Creating the tool does not automatically make the agent use it.
To implement it:
Open the agent that will trigger the handoff.
Select the newly created Start Chat Agent tool to give it access.
Update the Agent Instructions to clearly define:
When the chat agent should be started.
What conditions must be met.
Whether the current agent should notify the contact of the transition.
You must both assign the tool to the agent and define its trigger logic in the instructions. Without explicit conditions, the chat agent may not activate correctly.
Tips and Best Practices
Clearly define the handoff conditions in the agent instructions.
Ensure the correct chat agent is selected.
Decide whether the new agent should send the first message.
Include
conversation_historyin the receiving agent’s instructions if context is required.Test the handoff flow before deploying.
Troubleshooting
Issue | Possible Cause | Fix |
Chat agent not starting | Tool not assigned to agent | Enable the tool in the agent settings |
New agent lacks context |
| Add |
Agent does not trigger handoff | No clear trigger logic defined | Update Agent Instructions with explicit conditions |
Duplicate messages | Both agents sending initial messages | Review Send Initial Message setting |