# UiPath Low-Code Agent Authoring

Entry point for low-code agent work. Read this first after low-code mode is detected.

## When to Use

- Create a new low-code agent project (standalone or inline in a flow)
- Edit `agent.json` — prompts, model, schemas, settings
- Add tools, contexts, escalations, or MCP servers as files in `resources/{Name}/resource.json`
- Add memory spaces or seed memory items with `uip agent memory`
- Wire agent-to-agent calls within a solution or to an external deployed agent
- Design input/output schemas and sync with `entry-points.json`
- Validate agent project structure
- Publish agent to Studio Web, pack and deploy to Orchestrator
- Debug / run a low-code agent end-to-end on Studio Web and inspect its output

## Autonomous and Conversational Variant

UiPath low-code agents come in **two variants**, both sharing this skill.

1. Autonomous agents are intended for any general use-cases involving execution from input → output. They may be standalone or inline in a flow.
   
2. Conversational agents are intended for use-cases involving multi-turn conversations / fast latency with real-time user-interaction / streamed responses.

> After deployment, conversational agents are interacted with through the UiPath Conversation Service, which manages conversation history and exposes a CLI/SDK for client UIs. Each user-initiated exchange invokes the agent for a single turn, streaming events back to the client.
> A standalone conversational agent is the simplest way to build a back-and-forth chat assistant driven by a single system prompt. For chats that need more — routing between several agents, deterministic replies, or behind-the-scenes automations running while the conversation continues — direct the user to the `uipath-maestro-flow` skill.

In summary:
| Signal | Variant |
|---|---|
| User wants general input → output execution | **Autonomous** |
| `agent.json` has `metadata.isConversational: false` or unset | **Autonomous** |
| User wants multi-turn chat / fast latency with real-time user-interaction / streamed responses | **Conversational** |
| Existing `agent.json` has `metadata.isConversational: true` | **Conversational** |
| Ambiguous | Ask the user |

Although most of the lifecycle and capabilities are shared between both autonomous and conversational agents, some files will have distinguishing differences between the two (for example, mark that certain features do not apply for conversational agents). You can assume that when not labeled otherwise, content from files would apply to both variants.

## Critical Rules

[critical-rules/critical-rules.md](critical-rules/critical-rules.md) is the canonical source for low-code agent rules and anti-patterns. Read it every session. The rules below are the operational must-knows; the rest live in the canonical file.

1. **Edit JSON files directly, except CLI-managed memory features.** The CLI provides `init` (scaffold), `refresh` (apply migrations + regenerate derived files), `validate` (strict read-only check), and `memory` (writes memory feature files). Resources live in `resources/{Name}/resource.json`; memory features live in `features/{Name}/feature.json`.
2. **Use `--output json`** on every `uip` command.
3. **Refresh and validate after every bulk of related edits**, not after each line. Run `uip agent refresh --output json` to apply pending migrations and regenerate `entry-points.json` and `bindings_v2.json`, then `uip agent validate --output json` to verify the project is clean.
4. **Keep `agent.json` schemas correct** — `uip agent refresh` regenerates `entry-points.json` from `agent.json`'s `inputSchema`/`outputSchema` automatically.
5. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit source files and re-run refresh.
6. **Do not publish or deploy without user consent.** Ask before `uip solution upload`, `publish`, or `deploy`.
7. **Never invoke other skills automatically.** For Orchestrator setup, tell the user to use the `uipath-platform` skill; for flow wiring, tell them to use the `uipath-maestro-flow` skill.

## Quick Start

Standard workflow for any low-code agent task:

1. **Scaffold** — `uip solution init` (if no solution exists), then `uip agent init "<AgentName>" --output json`. Full walkthrough in [project-lifecycle.md](project-lifecycle.md) § End-to-End Example.
2. **Edit** — open `agent.json` and `entry-points.json`. Schema reference in [agent-definition.md](agent-definition.md). **Override the scaffold model** (`gpt-4o-2024-11-20`) per [model-selection-guide.md](model-selection-guide.md) and write robust prompts per [prompting/agent-prompting-guide.md](prompting/agent-prompting-guide.md) — the scaffold ships a stale model and toy prompts.
3. **Add capabilities** — pick from the Capability Registry below. Most add `resources/{Name}/resource.json`; memory uses `uip agent memory` and writes `features/{Name}/feature.json`.
4. **Refresh** — `uip agent refresh --output json`. Applies pending migrations and regenerates `entry-points.json` and `bindings_v2.json`. Confirm `MigrationApplied`, `StorageVersion`.
5. **Validate** — `uip agent validate --output json`. Strict read-only. Confirm `Status: "Valid"`, `Validated` counts.
6. **Refresh solution resources** — `uip solution resources refresh --output json` if any capability needs solution-level files (external tools, IS tools, index contexts, memory spaces, escalations).
7. **Upload** — `uip solution upload . --output json` (bundles and uploads in one pass; with user consent per Rule 6).

To **run the agent end-to-end** (test it live, not just upload), use `uip agent debug <AGENT_PROJECT_DIR> --inputs '<json>' --output json` — it uploads the enclosing solution and runs it on Studio Web in one step, so it's an alternative to the Upload step, not an addition. Executes the agent for real — confirm with the user first (Rule 6). See [debug.md](debug.md).

Capabilities are **orthogonal**: there is no ordering requirement among them. Adding a tool and an escalation in parallel is safe — they do not interact at the file level. Validate and refresh once after all capability edits are complete, not after each one.

## Reference Navigation

### Read on demand

| Read when... | File |
|---|---|
| Scaffolding, validating, or running solution lifecycle commands | [project-lifecycle.md](project-lifecycle.md) |
| Debugging / running a low-code agent end-to-end to test it | [debug.md](debug.md) |
| Editing `agent.json` (prompts, schemas, model, contentTokens) or `entry-points.json` | [agent-definition.md](agent-definition.md) |
| Choosing the LLM (`settings.model`) — discover tenant models, override the scaffold default | [model-selection-guide.md](model-selection-guide.md) |
| Writing a robust system/user prompt — skeleton, tool-call criteria, output contract, production checklist | [prompting/agent-prompting-guide.md](prompting/agent-prompting-guide.md) |
| External tools / IS tools / index contexts / memory spaces / escalations behave unexpectedly after `uip solution resources refresh` | [solution-resources.md](solution-resources.md) |
| Running evaluations, adding test cases, managing evaluators | [evaluations/evaluate.md](evaluations/evaluate.md) |

### Capability Registry

| I need to... | Read first | Then |
|--------------|------------|------|
| Understand agent.json schema | [agent-definition.md](agent-definition.md) | |
| Edit system prompt or user message | [prompting/agent-prompting-guide.md](prompting/agent-prompting-guide.md) (quality) | [agent-definition.md](agent-definition.md) § Messages, § contentTokens (mechanics) |
| Choose or change the model | [model-selection-guide.md](model-selection-guide.md) | [agent-definition.md](agent-definition.md) § Change Model Settings |
| Add/remove input or output fields | [agent-definition.md](agent-definition.md) § entry-points.json | |
| Scaffold a new agent project | [project-lifecycle.md](project-lifecycle.md) § End-to-End Example | [agent-definition.md](agent-definition.md) |
| Validate, upload, pack, publish, or deploy | [project-lifecycle.md](project-lifecycle.md) | |
| Debug / run a low-code agent end-to-end | [debug.md](debug.md) | |
| Discover solution resources (processes/apps/indexes/buckets/connections) | [project-lifecycle.md](project-lifecycle.md) § Resource Discovery | |
| Add a tool — pick the right kind | [capabilities/process/process.md](capabilities/process/process.md) | applicable sibling |
| Add a process tool (RPA / agent / API / agentic) — local or external | [capabilities/process/process.md](capabilities/process/process.md) | [capabilities/process/solution-files.md](capabilities/process/solution-files.md) |
| Wire a multi-agent solution (parent + tool agents) | [capabilities/process/process.md](capabilities/process/process.md) § Multi-Agent Solution Example | |
| Add an Integration Service tool | [capabilities/integration-service/integration-service.md](capabilities/integration-service/integration-service.md) | |
| Add an MCP (Model Context Protocol) server tool | [capabilities/mcp/mcp.md](capabilities/mcp/mcp.md) | |
| Add a built-in tool (Analyze Files) | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) | [capabilities/built-in-tools/analyze-attachments.md](capabilities/built-in-tools/analyze-attachments.md) |
| Accept a file as agent input or return a file as output | [agent-definition.md](agent-definition.md) § File Attachments | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) |
| Add a context (Context Grounding / attachments / DataFabric) | [capabilities/context/context.md](capabilities/context/context.md) | applicable sibling |
| Add an index-backed context (RAG) | [capabilities/context/index.md](capabilities/context/index.md) | |
| Add attachments context | [capabilities/context/attachments.md](capabilities/context/attachments.md) | |
| Add DataFabric entity-set context | [capabilities/context/datafabric.md](capabilities/context/datafabric.md) | |
| Add a memory space or seed memory items | [capabilities/memory/memory.md](capabilities/memory/memory.md) | |
| Add an Action Center escalation (HITL) | [capabilities/escalation/escalation.md](capabilities/escalation/escalation.md) | |
| Add guardrails (PII, harmful content, custom rules) | [capabilities/guardrails/guardrails.md](capabilities/guardrails/guardrails.md) | |
| Embed an autonomous agent inline in a flow | [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md) | |
| Set up Orchestrator resources | Tell the user to use the `uipath-platform` skill | |
| Wire agent into a flow | Tell the user to use the `uipath-maestro-flow` skill | |

## Anti-patterns

See [critical-rules/critical-rules.md](critical-rules/critical-rules.md) § What NOT to Do for the canonical list. Most expensive to get wrong:

- Editing `content` without updating `contentTokens` (causes silent rendering failures)
- Skipping `uip solution resources refresh` after adding external tools (`bindings_v2.json` never reaches the solution)
- Hand-editing memory feature JSON instead of using `uip agent memory`
- camelCasing `contextType` / `retrievalMode` enum values (validate accepts it, Studio Web silently drops the resource)
- Copy-pasting UUIDs across resources (every resource needs its own)

## Completion Output

After completing a task, report:

1. **File paths** — which files were created or modified
2. **What was configured** — summary of agent settings and schemas
3. **Validation result** — output of `uip agent refresh --output json` (`MigrationApplied`, `StorageVersion`) followed by `uip agent validate --output json` (`Status: "Valid"`, `Validated` counts)
4. **Schema sync status** — confirm agent.json and entry-points.json match
5. **Next steps** — suggest what the user should do next (publish, test in Studio Web, add resources)