# Critical Rules and Anti-Patterns

These rules are the canonical source for low-code agent authoring. Capability files cross-reference back here; they do not restate rules. The rules and anti-patterns in this file apply to **both** low-code autonomous and low-code conversational agents.

Some additional rules and anti-patterns may only be relevant for autonomous or conversational agents. For **low-code autonomous agents**, these are defined in [autonomous-critical-rules.md](autonomous-critical-rules.md). For **low-code conversational agents**, these are defined in [conversational-critical-rules.md](conversational-critical-rules.md). Always refer to those variant-specific rules in addition to these rules when working with low-code autonomous/conversational agents.

## Critical Rules (20)

1. **Edit JSON files directly, except CLI-managed memory features** — the CLI supports `init` (scaffold), `refresh` (apply migrations + regenerate derived files), `validate` (strict read-only check), and `memory` (writes memory feature files). Agent configuration (prompts, schemas, settings) is done by editing `agent.json`. Resources (tools, contexts, escalations) are added as individual files in `resources/{ResourceName}/resource.json` inside the agent project directory — **not** inline in `agent.json`. Memory spaces are added with `uip agent memory` and live in `features/{FeatureName}/feature.json`. The root `agent.json` should not contain `resources` or manually-authored memory feature entries. The `refresh` command reads `agent.json` and these resource files to generate `entry-points.json` and `bindings_v2.json`.

2. **Refresh and validate after every bulk of edits** — run `uip agent refresh --output json` to apply pending migrations and regenerate derived files (`entry-points.json`, `bindings_v2.json`), then `uip agent validate --output json` to verify the project is clean. Refresh applies writes only when all checks pass; validate is strict read-only (never writes files, fails if migration is pending or derived files are out of sync). Always run both in sequence after a cohesive set of related changes.

3. **Use `--output json`** on all `uip` commands when parsing output.

4. **Keep schemas in sync** — `inputSchema` and `outputSchema` in `agent.json` must exactly mirror `input` and `output` in `entry-points.json`. Update both when adding or removing fields.

5. **Use `{{input.fieldName}}` syntax** in message templates. Do not use `$vars` or `=js:` expressions — those are flow syntax, not agent syntax.

6. **Keep contentTokens in sync with content** — every message has both a `content` string and a `contentTokens` array. Update both when editing. See [agent-definition.md](../agent-definition.md) § contentTokens Construction.

7. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit `agent.json` and `resources/{Name}/resource.json`, then re-run refresh.

8. **Do not publish or deploy without user consent** — ask before running `uip solution upload`, `uip solution publish`, or `uip solution deploy`.

9. **Do not modify `projectId`** — auto-generated by `uip agent init`.

10. **Solution must exist first** — create one with `uip solution init` before scaffolding an agent.

11. **Set `folderPath` to the literal `Folder` returned by `uip solution resources list`.** Applies to both local (`Source: "Local"`) and external (`Source: "Remote"`) resources, and to tool `properties.folderPath`, context-index top-level `folderPath`, escalation `channel.properties.folderName`, and guardrail escalation `action.app.folderName`. Local resources typically carry `"solution_folder"` (their declared folder in the solution); external resources carry the human-readable, slash-separated Orchestrator folder (e.g., `"Shared"`, `"Shared/Sales/Region-EU"`). The author writes the value verbatim into `resource.json` (or into the guardrail action under `agent.json`); `uip agent refresh` propagates it into `bindings_v2.json` as `folderPath` (App resources translate `folderName` → binding `folderPath`). See [capabilities/process/process.md](../capabilities/process/process.md) § Tool resource.json Shape.

12. **Tools carry a `location` field.** Use `"solution"` when the row from `uip solution resources list` has `Source: "Local"` (resource is in the same solution); use `"external"` when `Source: "Remote"` (already deployed in Orchestrator). All other resource fields (`type`, `referenceKey`, `folderPath`, schemas, `exampleCalls`) follow the same rules in both cases. Connection (Integration Service) bindings are bound by `connection.id` and are exempt — no `folderPath` propagation.

13. **Process tools require solution-level resource files and `debug_overwrites.json`.** Whether local or external, you need the agent-level `resources/{ToolName}/resource.json`, solution-level files under `resources/solution_folder/`, AND a `userProfile/<userId>/debug_overwrites.json` for folder resolution. `uip solution resources refresh` generates these from the bindings; for in-solution agents the package + process declarations are pre-created when the project is registered with the solution (`uip agent init` registers with the parent `.uipx` inside a solution, or auto-scaffolds `<Name>Solution/` and registers when run outside one; falls back to `uip solution projects add` if registration was `Skipped` / `Failed` / `NotInSolution` — `OptedOut` means `--skip-solution-registration` was passed and both auto-scaffold and registration were skipped intentionally), and refresh resolves the binding against them. Without these, Studio Web will show "resource is missing in this environment". See [capabilities/process/solution-files.md](../capabilities/process/solution-files.md).

14. **Never manually edit `storageVersion`.** It is managed by `uip agent refresh` (which writes the latest version on success) and by Studio Web on import. `uip agent validate` fails with `AgentValidationOutdated` if the version is behind — run `uip agent refresh` to migrate. If validate reports a `storageVersion` newer than supported, upgrade uipcli rather than editing the field by hand.

15. **Never invoke other skills automatically.** If the user needs flow operations, tell them to use the `uipath-maestro-flow` skill.

16. **Read [capabilities/guardrails/guardrails.md](../capabilities/guardrails/guardrails.md) before authoring guardrail JSON.** The schema uses discriminator fields (`$guardrailType`, `$actionType`, `$parameterType`, `$ruleType`, `$selectorType`) that cannot be guessed. Configure guardrails at the agent.json root `guardrails` array only.

17. **`{{input.<file-field>}}` exposes metadata only.** When an input field is a `job-attachment`, the variable token renders only `ID`, `FullName`, `MimeType`, and `Metadata` into the prompt — not the file contents. To let the agent read contents, configure a file-handling built-in tool (e.g. `analyze-attachments`) and instruct the agent to call it. See [capabilities/built-in-tools/built-in-tools.md](../capabilities/built-in-tools/built-in-tools.md).

18. **`job-attachment` schema is canonical — copy verbatim.** Declare file fields as `{ "$ref": "#/definitions/job-attachment" }` and place the canonical block under `definitions`. `x-uipath-resource-kind: "JobAttachment"` is required. Same schema for input and output fields. See [agent-definition.md](../agent-definition.md) § File Attachments.

19. **Built-in tools require explicit configuration.** Tools like `analyze-attachments` are not implicitly available — add them as `resources/{Name}/resource.json` with `type: "internal"` and `properties.toolType: "<kebab-lowercase-id>"`. The `toolType` discriminator is fixed per tool — copy from the capability reference, do not invent. See [capabilities/built-in-tools/built-in-tools.md](../capabilities/built-in-tools/built-in-tools.md).

20. **Built-in tools need no solution-level files and no resource refresh.** Unlike external process tools, built-in tools (`type: "internal"`) are self-contained at the agent level. Do not run `uip solution resources refresh` for them; do not author solution-level resource files. Validate the agent and bundle.

## What NOT to Do (24)

1. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit source files (`agent.json`, `resources/{Name}/resource.json`) and re-run refresh.
2. **Do not use `=js:` or `$vars` in agent messages** — use `{{input.fieldName}}` only
3. **Do not skip schema sync** — agent.json and entry-points.json must match
4. **Do not skip validation after a bulk of related edits** — validate after each cohesive set of changes (not after every line, but always before moving on to a new capability or publishing)
5. **Do not publish/deploy without validating** — always validate first
6. **Do not forget contentTokens** — editing `content` without updating `contentTokens` causes rendering issues
7. **Do not forget `uip solution resources refresh` after adding a process tool** — applies to both local and external. Creating only the agent-level `resources/{ToolName}/resource.json` is not enough. After `uip agent refresh` generates `bindings_v2.json`, run `uip solution resources refresh` from the solution root to import the bindings into the solution. For `Connection` bindings refresh also generates `debug_overwrites.json`. For `Process`, `App`, and `Index` bindings refresh imports the resource but does not hand-write the rich solution-level files — check the output and hand-author missing files per [capabilities/process/solution-files.md](../capabilities/process/solution-files.md).
8. **`uip solution resources list` returns identity only (Source/Key/Name/Type/Folder/FolderKey)** — for the full configuration run `uip solution resources get <KEY> --output json` and read `Data.spec`. Applies to `--kind Process` (argument schemas, package keys, entry-point IDs — see [capabilities/process/process.md § Discovery](../capabilities/process/process.md#discovery)) and `--kind Index` (data source type, storage bucket reference — see [capabilities/context/index.md § Discovery](../capabilities/context/index.md#discovery)).
9. **Do not copy-paste UUIDs from one resource to another** — every resource (including each guardrail) needs a unique UUID.
10. **Do not bump `storageVersion` manually** — breaks packager compatibility.
11. **Do not call raw Automation.Solutions REST APIs** — always use `uip solution` commands.
12. **Do not camelCase `contextType` or `retrievalMode` values** — write `"datafabricentityset"`, `"deeprag"`, `"batchtransform"` (all lowercase). `uip agent validate` accepts camelCase but Studio Web silently drops the resource from the agent UI on import.
13. **Discover low-code agent connectors and activities with `uip is typecache`, not `uip is connectors list` / `uip is activities list`.** Use `uip is typecache packages` for connectors and `uip is typecache activities "<connector-key>"` for activities. These call the same Agent Builder typecache endpoints the frontend uses, returning exactly what the UI shows — the curated subset from the connector's Studio NuGet package. They default to `--project-type Agent`. Activities with an empty `objectName` (deprecated stubs) are filtered out. File operation and HTTP activities are included — the UI shows them with a "Preview" chip but they are fully selectable. Connectors absent from the typecache return empty (they don't appear in the UI either). No `--agent-id` required — works for locally scaffolded agents that don't yet exist in the cloud. The general `uip is connectors list` / `uip is activities list` commands return the full Integration Service catalog, not the curated low-code set.
14. **Do not omit discriminator fields in guardrails** — every action needs `$actionType` (not `type`), every validator parameter needs `$parameterType` and `id` (not `name`), every custom rule needs `$ruleType`, every field selector needs `$selectorType`. Missing any discriminator causes `uip agent validate` to fail.
15. **Do not use lowercase scope values in guardrails** — use `"Agent"`, `"Llm"`, `"Tool"` (PascalCase), not `"agent"`, `"llm"`, `"tool"`.
16. **Do not expect `uip solution resources refresh` to wire non-StorageBucket index data sources** — GoogleDrive/OneDrive/Dropbox/Confluence/Attachments indexes, `attachments` contexts, and `datafabricentityset` contexts are not auto-generated. Refresh warns + skips them; any solution-level files for these must be hand-authored. See [capabilities/context/index.md](../capabilities/context/index.md).
17. **Do not add a Tool-scoped guardrail before the tool exists** — run `uip agent tool list` first and confirm every name in `selector.matchNames` is present. `uip agent validate` will fail with an error if a guardrail targets a tool that has not been added to the agent.
18. **Set `folderPath` on process tool resources to the literal `Folder` from `uip solution resources list`** — applies whether `Source` is `Local` or `Remote`. `uip agent validate` reads it from the agent-level `resource.json` during the schema check; `uip agent refresh` propagates it verbatim into `bindings_v2.json`. The same value goes into the matching solution-level process declaration's `folders[].fullyQualifiedName`.
19. **Do not hand-edit `bindings_v2.json`** — the file is generated by `uip agent refresh` from the agent-level `resource.json` (including `folderPath`). Edit `resource.json` and re-run refresh; never patch the binding directly.
20. **Do not pass attachments via the `uip` CLI** — runtime file inputs are not supported by `uip agent run` or solution-level CLI run paths. Test attachment-aware agents from Studio Web or via Orchestrator job invocation.
21. **Do not assume `{{input.<job-attachment>}}` lets the agent read the file** — it renders metadata only. Pair the file field with a file-handling built-in tool (e.g. `analyze-attachments`) so the agent has a way to read contents.
22. **Do not run final inline-agent refresh or validation before flow graph edits for inline-in-flow agents** — direct `.flow` authoring of the inline-agent node, capability-resource nodes, and edges is owned by the `uipath-maestro-flow` skill. Always run `uip agent refresh --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` and then `uip agent validate --inline-in-flow` **after** those flow graph edits are complete. Refresh is what propagates the inline agent's bindings into the flow project's `bindings_v2.json`; without it, `uip solution resources refresh` cannot discover them. Never hand-edit `bindings_v2.json`. See [capabilities/inline-in-flow/inline-in-flow.md](../capabilities/inline-in-flow/inline-in-flow.md).
23. **Do not switch between autonomous and conversational variants by simply editing the `agent.json` fields** — for example, never modify `metadata.isConversational`. Instead, rely on first re-initializing a new agent of the opposite variant using the `uip agent init` command with or without the `--conversational` flag, then editing the new `agent.json`. See [project-lifecycle.md](../project-lifecycle.md) § Agent Commands.
24. **Do not register a low-code conversational agent as a tool in another agent** — conversational agents are properly run through the UiPath Conversational Service per exchange with a threaded `messages` input; they do not match the input→output contract that agent-tools require. Only autonomous agents can be used as tools of other autonomous/conversational agents. Applies to both in-solution and deployed tool references.