agents

latest

false

Agents user guide

Last updated Nov 20, 2025

Getting started with conversational agents

Building a conversational agent follows a structured lifecycle that includes design, testing, deployment, and monitoring. The key steps are:

Design the agent: Use Studio Web to define the agent’s system prompt, configure available tools, add context grounding, and set up escalation workflows.
Test and evaluate: Use the built-in Debug chat to test multi-turn interactions. Add real or simulated conversations to evaluation sets to validate behavior and performance.
Publish and deploy: Publish the agent as a solution package to Orchestrator. Ensure the solution folder includes a serverless and unattended robot for execution.
Access and manage: Interact with the agent through Instance Management. Monitor runtime behavior, review trace logs, and iterate based on feedback.

When designing a conversational agent, consider the following best practices:

Start with a clear persona: Define the agent’s tone and scope (e.g., “You are a friendly HR assistant...”).
Design for unpredictability: Users may provide incomplete or incorrect information. Handle ambiguity gracefully.
Guide tool use: Ensure tool descriptions clearly state when and how to use them.
Iterate with evaluations: Create test cases for both happy and unhappy paths. Update your agent logic accordingly.

Building a conversational agent

You can create conversational agents using the same low-code designer in Studio Web as autonomous agents, with key differences tailored for real-time, multi-turn dialogue.

Create the agent

To get started:

Go to studio.uipath.com.
Select Create New button, then select Agent.
Select the Conversational agent type.

Optionally, describe your agent to Autopilot to generate a starter configuration

Figure 1. Creating a new conversational agent

docs image

Note:

Starting a conversation with a conversational agent triggers an Orchestrator process dedicated to that chat. This process always appears as Running so it can respond to your messages immediately. However, it only consumes resources when you actually send a message. While idle and waiting, it does not use any resources.

Configure the system prompt

The system prompt defines the agent's persona, goals, behavioral constraints, and tool/escalation logic. Use it to instruct the agent on how to:

Greet users.
Handle unknown queries.
Escalate issues or call tools.
Maintain a consistent tone and style.

Tip:

Autopilot can help generate an effective starting prompt based on your use case.

Conversational agents do not use user prompts or Data Manager inputs/outputs, however the conversational agent will have knowledge of authenticated user's name and email.

Configure tools

Conversational agents can use the same tools as autonomous agents, including RPA workflows, API workflows, activities, other agents (excluding conversational agents), MCP servers (preview), IXP models (preview), and ready-to-use tools such as Analyze Attachments.

Tip:

For workflows that perform API calls exclusively, we recommend using API workflows for best performance in real-time chats.

Use tool-level guardrails to enforce runtime policies. Guardrails apply during both test and runtime, and are visible in trace logs. For details, refer to Guardrails.

Configure contexts

Add Context Grounding indexes to give your agent access to specific knowledge sources. The agent can query these indexes to provide informed, citation-backed responses. For details, refer to Contexts.

Use files

You can upload files directly through the chat box for analysis. This enables conversational agents to process various file-based inputs seamlessly during interactions. The pre-built Analyze Attachments tool also supports file uploads and allows agents to interpret and reason over file content using large language models (LLMs).

Note:

You cannot include attachments in evaluation runs. While conversations can be added to an evaluation set, attachments cannot be passed in through debug chat, traces, or manual uploads.

Configure escalations and agent memory

Conversational agents support escalation workflows and agent memory to improve decision-making:

Escalations allow the agent to hand off conversations to a human via Action Center when confidence is low or user intent is unclear. Conversations run synchronously, which means the agent pauses all further interaction until the escalation is resolved.
Agent Memory enables the agent to remember and reuse previously resolved escalations, reducing redundancy and improving efficiency.

For details, refer to Escalations and Agent Memory.

Evaluate and test the agent

Evaluations help ensure your conversational agent behaves reliably across varied dialogue paths. The process is similar to evaluating an autonomous agent but is adapted for dialogue.

Select Debug to run the agent in a chat-like environment, and interact with your agent using natural language.

Expand the full execution trace, which provides real-time tracing of the agent execution. It shows details such as:

Agent LLM calls and responses
Tool calls, with arguments and final outputs

Add test cases directly from the History panel by selecting Add to evaluation set after a test run. An evaluation test is created for the conversation with:

Conversation history: A record of the preceding turns in the dialogue.
Current user message: The user's latest message in the conversation.
Expected agent response.

This allows you to test how well the agent maintains context and handles follow-up questions, which is essential for a good conversational experience.

Figure 2. Creating evaluation sets

docs image

For each evaluation test, you can use the Conversation builder interface to edit the conversation history and the current user prompt. A similar interface lets you define and refine the expected agent response, ensuring accurate test validation.

Figure 3. The conversation builder window while editing an evaluation test

docs image

Figure 4. You can import a conversation from the Debug Chat by selecting Add to evaluation set

docs image

Accessing conversational agents

After you publish and deploy a conversational agent, you can interact with it through the Agents Instance Management page.

Figure 5. Agents Instance Management

docs image

Accessing agents in Microsoft Teams and Slack (Preview)

Conversational agents are available in Microsoft Teams and Slack. For details, refer to:

Embedding conversational agents in UiPath Apps

You can also embed a conversational agent directly into a UiPath App using the IFrame component.

Create and publish: First, ensure your conversational agent has been created and published.
Add IFrame: Open your App in Studio and add an IFrame component to your page.
Configure the URL: Set the IFrame's Source property to a URL constructed with the following format and parameters: "https://<cloud_env>.uipath.com/<organization>/<tenant>/autopilotforeveryone_/conversational-agents/?agentId=<agent_id>&mode=embedded&title=<title>&welcomeTitle=<welcome_title>&welcomeDescription=<welcome_description>&suggestions=<suggestions>"

See the following table for details.
Publish app: Publish your App. The agent is now be embedded and ready to use!

Table 2. URL parameters
Parameter	Required	Description
`agentId`	Yes	The Release ID of the published agent. To find it, navigate to Agents > Conversational agents, select "Chat now" on your agent, and copy the ID from the URL.
`mode`	No	Set to `embedded` to optimize as a right-rail experience within the IFrame. Set to `fullscreen` to optimize as a full-screen experience within the IFrame. The default is `fullscreen`.
`title`	No	The title displayed in the chat component's header. Defaults to the agent's name.
`welcomeTitle`	No	A title for the first-run welcome screen. Defaults to an empty string.
`welcomeDescription`	No	A description for the first-run welcome screen. Defaults to an empty string.
`suggestions`	No	An array of first-run suggested prompts for the user. Defaults to an empty array []. Note: To test on browser directly, wrap in one double quotes. Example: `["Hi, what can you do", "Hello, how are you"]` For Apps embedding, wrap in two double quotes– you need to escape the string or else UiPath Apps will throw a validation error. For example: `[""Hi, what can you do""]`.
`showHistory`	No	A boolean (`true` or `false`) to control the visibility of the chat history panel. Defaults to `true`.