# Build a chat agent workflow

> Build a real-time, AI-powered chat experience in Maestro Flow, including capabilities like output-based routing and agent handoff.

**What you'll build:** A conversational flow demonstrating how the [core chat nodes](conversational-chat.md) can be used to orchestrate flexible chat experiences. 

This walkthrough builds a chat experience consisting of a **general helpdesk agent** that decides when to hand a conversation off to an **account specialist agent**.

## What you'll need

- A UiPath Automation Cloud account with access to Maestro Flow.
- An available LLM model for the agent to use.

## Nodes used

- [Conversation Trigger](node-conversation-trigger.md): marks the Flow as conversational and starts it when a user initiates a chat.
- [Wait for Message](node-wait-for-message.md): suspends until the user sends a message and returns the latest conversation context.
- [Conversational Agent](node-conversational-agent.md): single-prompt conversational AI node that runs a turn of responses and tool-calls given the conversation context.
- [Decision](node-decision.md): routes on an agent's structured output.
- [Send Message](node-send-message.md): send a deterministic (non-LLM) notice to the chat.

## Steps

### 1. Create the Flow and add a Conversation Trigger

1. From Studio Web, choose **Create New**, and and select **Maestro Flow**.
2. Select the default trigger (labeled **Manual Trigger**) and choose **Change trigger**.
3. In the trigger picker, select **Conversation trigger**.

### 2. Wait for the user's first message

**Wait for Message** should be the first node after the conversation trigger:

1. Drag a **Wait for Message** node from the **Conversational tools** palette onto the canvas and connect it to the Conversation Trigger.
2. In the properties panel, set **Conversation ID** to `$vars.conversationTrigger1.output.conversationId`.

The node outputs `conversationContext` — the recent chat history, user profile data, and other turn information — for the downstream chat nodes to consume.

![Conversation Trigger connected to a Wait for Message node, with the Wait for Message properties panel showing Conversation ID bound to $vars.conversationTrigger1.output.conversationId.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-conversation-trigger-and-wait-for-message-b50852d8.png)

### 3. Add a conversational agent node

The first conversational agent node we'll add is a **general helpdesk agent** for handling everyday IT questions itself, and decides — via a structured output — when to hand off to a specialist.

1. Drag a **Conversational Agent** node onto the canvas and connect it to the Wait for Message.
2. Rename it **General Helpdesk Agent**, and rename its ID in the agent's **Advanced** panel to `generalHelpdeskAgent` for easier tracking.
3. In the agent's properties panel, set the **System prompt**:

    ```
    You are the internal IT helpdesk assistant.
    Answer everyday questions about our tools, wifi, printers,
    meeting rooms, and where to find internal docs.

    When the employee is having an account problem — 
    a forgotten password, a locked account, an MFA issue, 
    or a missing permission — tell the user that they will
    be handed off to an account specialist agent.
    ```

4. Under **Conversational Agent Settings**, bind **Conversation context** to `$vars.waitForMessage1.output.conversationContext`.
5. Under **Outputs**, add an output variable:
   - **Name:** `needsAccountSpecialist`
   - **Data type:** Boolean
   - **Default:** `false`
   - **Description:** `Set to true when the employee has an account problem — a forgotten password, a locked account, an MFA issue, or a missing permission. Otherwise false.`

The **Description** on the output variable is necessary — the agent uses the description in addition to the system-prompt to generate the structured outputs after its turn in the conversation.

![General Helpdesk Agent node selected on the canvas after the Conversation Trigger and Wait for Message nodes. Its properties panel shows the system prompt, a needsAccountSpecialist boolean output, and Conversation context bound to $vars.waitForMessage1.output.conversationContext.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-general-helpdesk-agent-e4b38e61.png)

### 4. Branch on the router's decision

Follow the agent with a Decision node that routes on the structured output.

1. Drag a **Decision** node onto the canvas and connect it to the General helpdesk agent.
2. Set the condition: `$vars.generalHelpdeskAgent.output.needsAccountSpecialist`.
3. Wire the **False** branch back to the original **Wait for Message** (Step 2). The general helpdesk agent keeps the conversation — it may hand off later, or never.

Leave the **True** branch open for now; you'll build it out in the next steps.

### 5. Announce the handoff

Tell the employee what's happening and ask them for next steps before the specialist takes over.

1. On the **True** branch of the Decision, add a **Send Message** node. Configure:
   - **Conversation ID:** `$vars.conversationTrigger1.output.conversationId`
   - **Exchange ID:** `$vars.waitForMessage1.output.conversationContext.latestExchangeId`
   - **Content:** `"You've been connected to the account specialist, which can help with password resets, unlocking your account, and permission or group membership questions. Please explain your issue."`

![Send Message node on the Decision's True branch. Its properties panel shows Conversation ID bound to the Conversation Trigger, Exchange ID bound to latestExchangeId from the first Wait for Message, and the handoff notice in Content.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-send-handoff-message-8e79041c.png)

### 6. Add a second Wait for Message loop with the account specialist

1. After the Send Message, add another **Wait for Message** node.
2. Set **Conversation ID** to `$vars.conversationTrigger1.output.conversationId`.
3. Drag a **Conversational Agent** node and connect it to this second Wait for Message.
4. Optionally rename it **Account Specialist Agent**.
5. Set the **System prompt**:

    ```
    You are the account specialist. The user has been handed off 
    to you from a general helpdesk assistant.

    Help only with account problems — password resets, unlocking
    accounts, MFA re-enrollment, and permission or group membership
    questions.
    ```

6. Under **Conversational Agent Settings**, bind **Conversation context** to `$vars.waitForMessage2.output.conversationContext`.
7. Connect the Account specialist's output back to `waitForMessage2` to close the specialist's loop.

![The complete Flow with the Account Specialist Agent selected. The canvas shows the Decision's False branch looping back to the first Wait for Message, and the True branch running Send Message, a second Wait for Message, and the specialist. The properties panel shows the specialist system prompt and Conversation context bound to $vars.waitForMessage2.output.conversationContext.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-full-flow-53e8530b.png)

:::tip
**When you have multiple Wait for Message nodes**, you might accidentally configure a downstream node to reference a stale conversation context from a Wait for Message node that executed earlier.

For easier tracking, create a Flow-level variable (for example, `$vars.globalConversationContext`), and update it from each Wait for Message node's **Update Variable** section. Downstream nodes can then reference that single source of truth instead of needing to pick the last-executed Wait for Message node's output.
:::

### 7. Debug the Flow

Select **Debug** in the top toolbar. A chat panel opens next to the canvas.

- Ask *"How do I connect to my office VPN?"* — the general helpdesk agent should answer directly and loop back for another turn.
- Ask *"I'm having issues logging in."* — the general helpdesk agent should set `needsAccountSpecialist: true`, the Decision routes to the True branch, the handoff notice appears, and the account specialist takes over.

Inspect the execution trace to see which agent ran on each turn and what structured output the general helpdesk agent produced.

![Debug run of the Flow with the Chats panel open below the canvas. The question about connecting to the office VPN is answered by the general helpdesk agent, and the message relating to login triggers the handoff notice and passes the conversation to the account specialist.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-full-flow-debug-run-9bee19a1.png)

## Result

Once published and deployed, your conversational Flow surfaces to end-users as a **Conversational Agent** on the [chat deployment channels](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-deployment). Monitor its performance, metrics, and user feedback through [chat agent observability](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-observability).

## Extend this Flow

- **Give the agents context and tools**: connect a context resource to the agent's **Context** handle so it answers from an indexed knowledge source instead of the model alone. Connect tool resources to the agent's **Tools** handle so it can act during its conversational turns, not just respond.
- **Add parallel execution branches**: In addition to routing back to **Wait for Message**, add parallel branches to perform behind-the-scenes actions without blocking the conversation. For example, a branch can launch a [Human Task](node-human-task.md) for a manager's approval, then proceed with other actions.
- **End the chat when the issue is resolved:** add a `resolved: true` output on the agent(s) that routes to a branch that ends the execution. The conversation ends gracefully and users will see that the conversation has ended.

For example, extending the walkthrough's Flow with the above capabilities may result in a complete chat experience like this:

![The walkthrough Flow extended with context and tools on the conversational agent nodes. A new Switch node after the account specialist routes between a default branch, a branch that ends the conversation, and a parallel branch that launches an Admin Approval Form for human approval before performing a task.](https://dev-assets.cms.uipath.com/assets/images/maestro/chat-agent-walkthrough-full-flow-with-extensions-7dd9faa2.png)