# Designing conversational agents

> This page covers the design-time configuration options for conversational agents in Studio Web. Use these settings to define your agent's behavior, capabilities, and integration with enterprise systems.

This page covers the design-time configuration options for conversational agents in Studio Web. Use these settings to define your agent's behavior, capabilities, and integration with enterprise systems.

## Creating a conversational agent

1. Go to [studio.uipath.com](https://studio.uipath.com/).
2. Select **Create New**, then select **Agent**.
3. Select **Conversational**.
4. Describe your agent to Autopilot to generate a starter configuration or select **Start fresh**.

![Creating a conversational agent](https://dev-assets.cms.uipath.com/assets/images/agents/create-agent-64fda7ee.webp)

## System prompt

The system prompt is the foundation of your agent's behavior. It defines the agent's persona, goals, constraints, and instructions for handling different scenarios.

### What to include

A comprehensive system prompt should address:

* **Identity and persona**: Who is the agent? What tone should it use?
* **Scope and boundaries**: What topics should the agent handle? What should it decline?
* **Tool usage guidelines**: When should the agent use specific tools?
* **Escalation criteria**: When should the agent hand off to a human?
* **Response format**: How should the agent structure its answers?

### Example system prompt

You are an HR assistant for Contoso Corporation. Your role is to help employees with questions about company policies, benefits, and HR procedures.

#### Guidelines

* Be professional, friendly, and concise
* Always search the knowledge base before answering policy questions
* Cite specific documents when referencing policies
* If you cannot find an answer, offer to escalate to an HR representative

#### Boundaries

* Do not discuss individual employee performance or compensation
* Do not make promises about policy exceptions
* Redirect legal questions to the legal department

### Using Autopilot to generate prompts

Autopilot can help you create effective system prompts:

1. In the system prompt section, describe your use case in natural language.
2. Autopilot generates a structured prompt based on your description.
3. Review and refine the generated prompt to match your specific requirements.

:::tip
Start with Autopilot's generated prompt, then iterate based on testing. The **Debug chat** helps you identify gaps in your prompt that need addressing.
:::

### Using Agent score

The Agent score analyzes your agent's configuration and provides recommendations for improvement. The score evaluates:

* **System prompt quality**: Clarity, completeness, consistency, chain of thought, and demos.
* **Tool configuration**: Quantity, context clarity, and completeness.

To view your agent's score:

1. In the agent designer, look for the **Open health score** indicator.
2. Select it to see detailed recommendations.
3. Address the suggestions to improve your agent's effectiveness.

![Agent Health Score](https://dev-assets.cms.uipath.com/assets/images/agents/agent-health-score-8e3c03c7.webp)

For details, refer to [Agent score](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/agent-score).

## Model selection

Conversational agents support multiple large language models (LLMs). Select a model based on your requirements for capability, latency, and cost.

![Model selection](https://dev-assets.cms.uipath.com/assets/images/agents/system-prompt-43bc3521.webp)

For guidance on choosing the right model, refer to [Choosing the best model for your agent](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/choosing-the-best-model-for-your-agent).

:::note
Conversational agents are available with UiPath-managed models and support [LLM Configurations](https://docs.uipath.com/automation-cloud/automation-cloud/latest/admin-guide/managing-ai-trust-layer#configuring-llms) so you can use your own LLM subscriptions.
:::

## Tools

Tools extend your agent's capabilities beyond conversation. Conversational agents support the same tools as autonomous agents.

### Supported tool types

| Tool type | Description | Use case |
|-----------|-------------|----------|
| **Context Grounding** | Search knowledge base indexes | RAG-based Q&A on documents |
| **Analyze files** | Process uploaded files with LLM | Document analysis, form extraction |
| **Integration Service activities** | Pre-built connectors to external systems | Calendar, email, CRM operations |
| **API workflows** | Custom API-based automations | Backend integrations |
| **RPA workflows** | Cross-platform and Window-based automations | Legacy system interactions |
| **Autonomous agents** | Nested agent execution | Complex, multi-step tasks |
| **MCP servers** | Model Context Protocol integrations | External tool ecosystems |
| **IXP models** | Intelligent document processing | Structured document extraction |

### Adding tools

1. In the agent designer, select **Add tool**.
2. Choose the tool type and configure its parameters.
3. Provide a clear description of when and how the agent should use the tool.

![Adding tools](https://dev-assets.cms.uipath.com/assets/images/agents/add-tool-panel-210cd050.webp)

:::tip
For workflows that perform API calls exclusively, use API workflows instead of RPA workflows for better performance in real-time chat scenarios.
:::

### Tool descriptions

Tool descriptions guide the agent on when to use each tool. Write descriptions that clearly state:

* What the tool does
* When to use it (optional)

#### Example tool description
```
Search HR Policies: Use this tool to find information about company policies,
benefits, and HR procedures. Always use this tool before answering questions
about policies.
```

### Tool guardrails

Apply guardrails to tools to enforce runtime policies. Guardrails can:

* Restrict when a tool can be executed.
* Validate inputs before execution.
* Filter or transform outputs.

For details, refer to [Guardrails](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/tool-guardrails).

## Context

Context connects your agent to Context Grounding knowledge base indexes, enabling retrieval-augmented generation (RAG) for accurate, citation-backed responses.

### Adding a context

1. Select **Add context**.
2. Choose a Context Grounding index from your available indexes.
3. Configure search parameters (optional).

![Context Grounding setup](https://dev-assets.cms.uipath.com/assets/images/agents/add-tools-509658bd.webp)

The agent automatically queries the index when relevant to the user's question and includes citations in its responses.

For details on creating and managing indexes, refer to [Contexts](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/agent-contexts).

## File handling

Conversational agents can process files uploaded during chat. This enables use cases like document analysis, form processing, and image interpretation.

### Enabling file uploads

To enable file analysis, add a tool capable of processing files:

* **Analyze files**: Built-in tool for general file analysis using LLMs.
* **IXP models**: For structured document extraction.

### Supported file types

| File type | Recommended tool |
|-----------|------------------|
| Images (GIF, JPE, JPEG, PNG, WEBP) | Analyze files |
| PDF documents | Analyze files, IXP |

:::important
File uploads are limited to 5MB.
:::

## Escalations

Escalations allow the agent to hand off conversations to a human when it cannot confidently resolve a request.

### How escalations work

1. The agent determines it needs human assistance (based on your system prompt criteria).
2. The agent creates an escalation task in Action Center.
3. The conversation pauses until a human resolves the escalation.
4. Once resolved, the agent continues with the human's input.

### Configuring escalations

1. In the agent designer, select **Add escalation**.
2. Configure the escalation type.
3. Remember to define escalation criteria in your system prompt.

:::note
Conversations run synchronously during escalation. The agent pauses all interaction until the escalation is resolved.
:::

For details, see [Escalations and Agent Memory](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/agent-escalations-and-agent-memory).

## Design best practices

### Start with a clear persona

Define a specific identity for your agent rather than leaving it generic. A clear persona helps the agent maintain consistent tone and behavior.

**Less effective:** "You are a helpful assistant." **More effective:** "You are a friendly HR assistant for Contoso Corporation who specializes in helping employees understand company policies and benefits."

### Design for unpredictability

Users may provide incomplete, ambiguous, or incorrect information. Your system prompt should instruct the agent to:

* Ask clarifying questions when needed.
* Handle partial information gracefully.
* Recover from misunderstandings.

### Guide tool usage explicitly

Don't assume the agent knows when to use tools. Include explicit instructions:

```
## Tool usage
- ALWAYS search the knowledge base before answering policy questions
- Use the calendar tool when the user asks about scheduling
- NEVER create calendar events without explicit user confirmation
```

### Iterate with evaluations

Create test cases for both expected (happy path) and unexpected (edge case) scenarios. Update your agent's configuration based on evaluation results.

## Next steps

* [Evaluation](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-evaluation): Test your agent's behavior
* [Deployment](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-deployment): Publish and deploy your agent
* [Best practices for building agents](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/best-practices-for-building-agents): Additional design guidance