- Getting started
- UiPath Agents in Studio Web
- About UiPath Agents
- Licensing
- Building an agent in Studio Web
- Agents vs. workflows
- Best practices for building agents
- Best practices for context engineering
- Best practices for publishing and deploying agents
- Prompts
- Contexts
- Escalations and Agent Memory
- Evaluations
- Agent traces
- Agent score
- Managing UiPath agents
- UiPath Agents in Agent Builder
- UiPath Coded agents
Agents user guide
Effective Context Grounding ensures your agent has access to the right knowledge, at the right time, for the task at hand. When implemented correctly, it increases accuracy, improves performance, and reduces token costs.
This section outlines how to configure and maintain your context sources using Context Grounding, including best practices for index setup, schema design, and ongoing evaluation.
For details regarding the Context Grounding service, refer to the dedicated documentation: About Context Grounding.
Agents connect to enterprise knowledge, such as documents, FAQs, emails, and SOPs, through Context Grounding. You create indexes in Orchestrator and attach them to agents in Studio Web to enable this connection.
Context grounding helps agents:
- Reason over business-specific data.
- Avoid hallucinations or fabrication.
- Respond with up-to-date, governed knowledge.
- Cite sources when configured with schema constraints.
To build reliable, responsive agents, follow these core practices when designing and tuning your context:
Use descriptive, versioned index names
HR-Policies-2025-Q3.
This makes it easy to:
- Roll back to previous index versions.
- Perform A/B tests with different knowledge bases.
- Track updates over time.
Create a new index in Orchestrator when content changes significantly, and update the agent definition accordingly.
Choose the right ingestion mode
When creating an index, select the ingestion mode that fits your content:
- Basic mode: Ideal for documents with mostly plain text.
- Advanced mode: Use for files that combine text and images (e.g., scanned PDFs or infographics).
This impacts both coverage and OCR-related cost. Choose based on the type of documents and how critical visual content is to the retrieval.
Maintain regular sync cadence
Keeping indexes fresh ensures that agents reference up-to-date information. Use the Sync action in Orchestrator or the Update Context Grounding Index activity in Studio to refresh index contents. You can schedule periodic syncs based on the update frequency of your source content.
Calibrate the number of results and threshold score
- Number of results: Adjust this setting to control how many context chunks are retrieved. More results increase recall but also expand token usage.
- Threshold: Filters out low-relevance context. The default value is 0. You can raise it to improve precision if too many unrelated passages are being returned. However, note that setting the threshold value above 0 (zero) means relevant chunks may be filtered out of responses, which can lead to hallucinations.
Balance these parameters to ensure high-signal context without exceeding token limits.
Use clear context descriptions in agent design
When adding a context index to an agent, provide a short, accurate description of what the index contains. This helps guide the agent's retrieval and usage of the knowledge during execution.
Descriptions are particularly useful when using multiple context sources.
Align schema with agent expectations
Define a response schema when applicable, especially for structured output like JSON. This ensures the agent formats responses correctly and only includes information from context.
Include schema examples in your system prompt to improve reliability.
Revisit context configuration when:
- Agents are missing expected results.
- Irrelevant content appears in traces.
- Agents exceed token limits or fail with “tokens exceeded” errors.
- Document schemas change.
- A new use case or scope expansion occurs.
Use trace logs from test and production runs to diagnose whether the issue is with context quality, quantity, or indexing parameters.
Use this table to identify and resolve common Context Grounding problems. Each row highlights a detection signal you may observe in traces and the recommended actions to correct it.
| Mistake | Detection signal | Recommended fix |
|---|---|---|
| Agent is not answering as expected, even though it should have relevant documents in the index | No results found |
Confirm latest data, add relevant documents, and sync index Lower threshold |
| Missing expected answers | Trace shows high threshold filtering | Lower threshold or improve document coverage |
| Context window overflow | Agent fails with “tokens exceeded” | Reduce number of results or shorten user input |
| Stale information returned | Trace shows outdated timestamp | Sync or rebuild index; republish the agent |
Use evaluation runs in Agent Builder to test how well your context sources support the agent’s objectives.
Evaluation runs should:
- Include real-world, diverse prompts.
- Review traces to inspect which chunks were retrieved.
- Include regression tests when updating or replacing indexes.
You can also simulate runs using tool simulations with mocked context to preview performance before committing to a full index update.
Use the following checklist to ensure your Context Grounding setup follows best practices:
- Index names are versioned and descriptive.
- Ingestion mode matches document type.
- Indexes are synced regularly.
- Number of results and threshold are tuned.
- Context descriptions are informative.
- Schema is defined and enforced in prompt.
- Common errors are tracked and resolved using trace logs.
Use the following templates as a starting point for your Agent System prompt. Customize them to fit your specific use case.
QA / Knowledge lookup
You are an enterprise knowledge assistant.
Goal: Answer user questions using ONLY approved company documents.
Constraints:
- Cite each answer with source title and section.
- If confidence is low or no relevant context was retrieved, ask a clarifying question instead of guessing.
- Respond in Markdown unless JSON is requested.
# Processing Steps
1. Interpret the user question.
2. Review retrieved context below.
3. Use only information found in context; do not fabricate.
4. Provide a concise answer and cite sources.You are an enterprise knowledge assistant.
Goal: Answer user questions using ONLY approved company documents.
Constraints:
- Cite each answer with source title and section.
- If confidence is low or no relevant context was retrieved, ask a clarifying question instead of guessing.
- Respond in Markdown unless JSON is requested.
# Processing Steps
1. Interpret the user question.
2. Review retrieved context below.
3. Use only information found in context; do not fabricate.
4. Provide a concise answer and cite sources.Structured extraction and validation
You are an extraction agent that maps document content into a structured schema.
Goal: Populate all required fields from retrieved document snippets.
Constraints:
- Return valid JSON matching the schema.
- Use null if field not found; do NOT guess.
- Provide a confidence score 0‑1 for each field.
- Include source_span metadata (doc_id, chunk_id).
# Steps
1. Read user instruction for target doc type.
2. Review retrieved context.
3. Extract fields.
4. Validate required fields; request escalation if missing critical values.You are an extraction agent that maps document content into a structured schema.
Goal: Populate all required fields from retrieved document snippets.
Constraints:
- Return valid JSON matching the schema.
- Use null if field not found; do NOT guess.
- Provide a confidence score 0‑1 for each field.
- Include source_span metadata (doc_id, chunk_id).
# Steps
1. Read user instruction for target doc type.
2. Review retrieved context.
3. Extract fields.
4. Validate required fields; request escalation if missing critical values.Reasoning and action selection
You are an operations triage agent.
Goal: Decide the next best action based on policies and current case details.
Constraints:
- Choose only from the allowed actions list.
- Provide short rationale.
- Output as JSON: {"action":string,"reason":string,"evidence_sources":[...]}
# Allowed Actions
{{ACTION_LIST}}You are an operations triage agent.
Goal: Decide the next best action based on policies and current case details.
Constraints:
- Choose only from the allowed actions list.
- Provide short rationale.
- Output as JSON: {"action":string,"reason":string,"evidence_sources":[...]}
# Allowed Actions
{{ACTION_LIST}}
