# Prompt editor

> Rich text editor in Agent Builder for writing system and user prompts, using the @ trigger to insert color-coded inline references to arguments, tools, contexts, escalations, and outputs.

The **Prompt editor** is the rich text area in Agent Builder where you write the system prompt and user prompt. Arguments, tools, contexts, escalations, and outputs are represented as color-coded inline references — called pills — rather than typed placeholders.

The **Prompt editor** is available for autonomous and conversational agents and applies to the system prompt and user prompt.

## The @ trigger

The **Prompt editor** uses a single trigger key for all reference types.

Typing `@` anywhere in the prompt opens the reference picker. The picker groups available references into five sections in a fixed order:

1. **Inputs** — arguments the agent receives at runtime
2. **Tools** — tools connected to the agent
3. **Context** — context grounding sources
4. **Escalations** — escalation paths
5. **Outputs** — outputs from previous steps, when applicable

Continuing to type after `@` narrows the list using fuzzy matching — an exact prefix is not required. For example, `@srch` matches `tools.web_search`.

![The @ reference picker open in the Prompt editor, showing Inputs and Outputs grouped sections with input. Content highlighted — continue typing to narrow the list by fuzzy match](https://dev-assets.cms.uipath.com/assets/images/agents/insert-argument-0da9fd5e.gif)

### Keyboard navigation in the picker

| Key | Action |
|---|---|
| ↑ / ↓ | Move selection up or down |
| Tab / Shift+Tab | Same as arrow keys |
| Enter | Insert the highlighted reference |
| Esc | Close the picker without inserting |
| Mouse select | Insert the selected reference |

### When @ does not open the picker

To avoid unintended activation during normal typing, the `@` character opens the picker only when it appears:

- at the beginning of a line, or
- immediately after a whitespace character.

Writing `team@example.com` in the middle of a sentence does not open the picker — the `@` is preserved as plain text. Typing a space before `@` forces the picker open.

### Compatibility with `{{ }}` placeholders

Existing prompts that contain `{{argument_name}}` continue to work without any migration step. When the editor loads a prompt, `{{ }}` placeholders are automatically converted to pills on screen. When the prompt is saved, input pills are written back to storage as `{{argument_name}}` and tool, context, and output pills as `@{tools.search}` — preserving compatibility with any backend systems that read prompts as text.

Typing `{{ ... }}` directly while editing is not a creation trigger — it is preserved as plain text and converts to a pill only when the prompt is saved and re-opened, provided the inner name matches an existing argument. Use `@` to insert references.

## References as pills

Every reference in a prompt is rendered as an inline **pill** containing:

- a category icon
- a label — the last segment of the reference path (for example, `web_search` rather than `tools.web_search`)
- a color reflecting the reference category: inputs in blue, tools and contexts and escalations in green, outputs in orange

![A blue input pill labeled Content and an orange output pill labeled Language shown inline in the Prompt editor, illustrating how references appear after insertion](https://dev-assets.cms.uipath.com/assets/images/agents/pills-in-prompt-1dd91640.webp)

Pills behave as single units:

- Arrow keys move the cursor across a pill in one keypress.
- **Backspace** or **Delete** removes the entire reference.
- Each pill has an **×** button on hover for removal with a mouse.
- Pills can be copied and pasted across different prompt fields in the same agent or into another agent's prompts. When pasted into a plain-text destination outside the editor, pills fall back to the `{{...}}` or `@{...}` text format.

### Invalid references

When a reference points to a resource that no longer exists — for example, a tool that was removed or an argument that was renamed manually — the pill turns red. This is a visual signal only; the prompt is still saved as-is.

An invalid reference can be resolved by deleting the red pill and selecting a replacement using `@`, or by renaming the underlying resource so the reference becomes valid again.

### Automatic rename propagation

When a tool, argument, context, escalation, or output is renamed inside the agent definition, the editor detects the change and updates every pill that referenced it across all prompt fields automatically. Nested paths are also rewritten consistently.

Renames made outside the agent definition, for example by editing raw JSON directly, are not detected.

## Edit and Preview

The toolbar at the top of the editor includes an **Edit / Preview** toggle.

- **Edit** — the live editing mode for entering text, applying formatting, and inserting references.
- **Preview** — a read-only rendering of the prompt with all pills and markdown applied. Use Preview to verify the final appearance of long or heavily formatted prompts before saving.

Switching to Preview preserves the current draft. Switching back to Edit returns to the exact editing state from before the switch.

![The Prompt editor toggling between Edit and Preview mode — Preview renders markdown formatting and pill references as formatted text](https://dev-assets.cms.uipath.com/assets/images/agents/switching-edit-preview-mode-7a953c85.gif)

## Formatting toolbar

In Edit mode, the toolbar exposes the following formatting actions:

| Button | Effect | Keyboard shortcut |
|---|---|---|
| **H** | Toggle heading on the current line | — |
| **B** | Bold the selected text | — |
| *I* | Italicize the selected text | — |
| `</>` | Inline code | — |
| Numbered list | Toggle a numbered list | — |
| Bulleted list | Toggle a bulleted list | — |
| Undo | Step backward through edits | Ctrl / ⌘ + Z |
| Redo | Step forward through edits | Ctrl / ⌘ + Shift + Z |

Markdown applied through the toolbar is preserved verbatim in the saved prompt and rendered with full markdown styling — including headings, lists, fenced code blocks, blockquotes, and tables — in Preview mode. The toolbar is disabled while Preview mode is active.

## Coverage highlights

When prompt coverage data is available after running an evaluation set, a **Coverage** toggle appears in the toolbar.

Selecting **Coverage** switches the editor to Preview with inline highlights showing which instructions in the prompt were exercised during the evaluation runs. Selecting a highlighted section opens a popover listing the specific evaluation runs that covered it. The **↻** button next to the toggle recalculates coverage when the prompt or evaluation set has changed.

Switching back to Edit deactivates coverage highlighting.

## Reviewing AI suggestions

When Autopilot or another AI assistant proposes a rewrite of your prompt, the editor enters diff mode:

- Removed content appears with a red strikethrough.
- Added content appears with a green highlight.
- The editor is read-only while the diff is displayed.

Two buttons appear at the bottom-right of the editor: **Accept** replaces the prompt with the suggested version, and **Reject** discards the suggestion and restores the original. The original prompt is preserved exactly until one of these buttons is selected.

## Fullscreen editing

The **Expand** icon at the right end of the toolbar opens the editor in a fullscreen modal. This is useful for long prompts where available screen space is limited. Edits made in the modal are kept when the modal is closed.

## Accessibility

- Every toolbar button is keyboard-reachable with **Tab** and includes a tooltip and `aria-label`.
- The reference picker is fully keyboard-driven — inserting any reference does not require a mouse.
- The **Edit / Preview** toggle and the **Coverage** toggle expose their state via `aria-pressed` semantics.
- The editor announces the active field name to screen readers — for example, "System prompt" — through its `ariaLabel` configuration.

## Frequently asked questions

**Will existing prompts break?**

No. The editor reads and writes the same format as before — `{{argument}}` for inputs and `@{path}` for tools, contexts, and outputs. Existing prompts open as pills automatically; no migration step is needed.

**Can I still type `{{` to insert an argument?**

No. `{{ }}` is no longer a creation trigger in the editor. Use `@` instead. Any `{{ ... }}` typed while editing is preserved as plain text and converts to a pill only when the prompt is saved and re-opened, provided the inner name matches an existing argument.

**Does the `@` trigger conflict with email addresses or social handles?**

No. The picker opens only when `@` appears at the start of a line or directly after a whitespace character, so `team@example.com` in the middle of a sentence is treated as plain text.

**What happens if I rename an argument or tool?**

The editor detects renames made inside the agent definition and updates every reference across all prompts automatically. A reference turns red only when the underlying resource was deleted or its path changed in a way the editor could not infer.

**Can I disable the new editor?**

The **Prompt editor** is gated by a feature flag during rollout. To return to the previous editor during the rollout window, contact your UiPath representative.

## See also

- [Prompts](agent-prompts.md) — system prompts, user prompts, and prompt writing guidance
- [Defining arguments](define-arguments.md) — create input and output arguments and reference them in prompts