@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/author/references/planning-impl.md

@@ -0,0 +1,302 @@
+# Planning Phase 2: Implementation Resolution
+
+Resolve all implementation details for the approved architectural plan. This phase takes the `.uipath.flow.arch.plan.md` and produces an `.uipath.flow.impl.plan.md` with concrete, build-ready values. The plugin `impl.md` files, wiring rules, and flow patterns below are also used during the build step.
+
+> **Prerequisite:** The user must have explicitly approved the architectural plan (`.uipath.flow.arch.plan.md`) before starting this phase.
+>
+> **Always validate with the registry,** even for OOTB nodes. This phase ensures that every node type (built-in or connector-based) is confirmed against the current registry state. Port names, input requirements, and output schemas can change — do not assume OOTB nodes match the planning guides without verification.
+
+---
+
+## Implementation Resolution Process
+
+### Step 1 — Identify Nodes and Validate with Registry
+
+Scan the approved `.uipath.flow.arch.plan.md` node table and connector summary. Validate each node type against the registry to confirm ports, inputs, and outputs are current:
+
+| Category          | How to identify                                                      | Action                                                                                                                                                                                                                                                                     |
+| ----------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connector nodes   | Node type starts with `uipath.connector.*` or Notes say "connector:" | Run Step 2 (follow [connector/impl.md](plugins/connector/impl.md))                                                                                                                                                                                                         |
+| Resource nodes    | Node type starts with `uipath.core.*` or Notes say "resource:"       | Run Step 3 (follow the relevant resource plugin: [rpa](plugins/rpa/impl.md), [agent](plugins/agent/impl.md), [agentic-process](plugins/agentic-process/impl.md), [flow](plugins/flow/impl.md), [api-workflow](plugins/api-workflow/impl.md), [hitl](plugins/hitl/impl.md)) |
+| Mock placeholders | Node type is `core.logic.mock`                                       | Run Step 4 (check if published, replace if available)                                                                                                                                                                                                                      |
+| OOTB nodes        | Everything else (Script, HTTP, Decision, Loop, etc.)                 | Run Step 1a below (validate with registry using the relevant plugin's `impl.md`)                                                                                                                                                                                           |
+
+**All nodes, including OOTB, must be validated via registry in Step 1a before proceeding.**
+
+#### Step 1a — Validate All Node Types with Registry
+
+Even built-in nodes can change. For each node type in your plan, read the relevant plugin's `impl.md` for the registry validation command and expected ports/inputs:
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry get <node-type> --output json
+```
+
+**Plugin impl.md files for registry validation:**
+
+| Node Type                       | Plugin impl.md                                                 |
+| ------------------------------- | -------------------------------------------------------------- |
+| `core.action.script`            | [script/impl.md](plugins/script/impl.md)                       |
+| `core.action.http.v2`           | [http/impl.md](plugins/http/impl.md)                           |
+| `core.action.transform`         | [transform/impl.md](plugins/transform/impl.md)                 |
+| `core.logic.delay`              | [delay/impl.md](plugins/delay/impl.md)                         |
+| `core.logic.decision`           | [decision/impl.md](plugins/decision/impl.md)                   |
+| `core.logic.switch`             | [switch/impl.md](plugins/switch/impl.md)                       |
+| `core.logic.loop`               | [loop/impl.md](plugins/loop/impl.md)                           |
+| `core.logic.merge`              | [merge/impl.md](plugins/merge/impl.md)                         |
+| `core.control.end`              | [end/impl.md](plugins/end/impl.md)                             |
+| `core.logic.terminate`          | [terminate/impl.md](plugins/terminate/impl.md)                 |
+| `core.subflow`                  | [subflow/impl.md](plugins/subflow/impl.md)                     |
+| `core.trigger.scheduled`        | [scheduled-trigger/impl.md](plugins/scheduled-trigger/impl.md) |
+| `core.action.queue.*`           | [queue/impl.md](plugins/queue/impl.md)                         |
+| `uipath.agent.autonomous`       | [inline-agent/impl.md](plugins/inline-agent/impl.md)           |
+| `uipath.core.agent.*`           | [agent/impl.md](plugins/agent/impl.md)                         |
+| `uipath.core.rpa-workflow.*`    | [rpa/impl.md](plugins/rpa/impl.md)                             |
+| `uipath.core.agentic-process.*` | [agentic-process/impl.md](plugins/agentic-process/impl.md)     |
+| `uipath.core.flow.*`            | [flow/impl.md](plugins/flow/impl.md)                           |
+| `uipath.core.api-workflow.*`    | [api-workflow/impl.md](plugins/api-workflow/impl.md)           |
+| `uipath.core.hitl.*`            | [hitl/impl.md](plugins/hitl/impl.md)                           |
+| `uipath.connector.uipath-uipath-dataservice.*` | [connector/data-fabric/impl.md](plugins/connector/data-fabric/impl.md) |
+| `uipath.ixp.*`                  | [ixp/impl.md](plugins/ixp/impl.md)                             |
+| `uipath.connector.*`            | [connector/impl.md](plugins/connector/impl.md)                 |
+| `uipath.connector.trigger.*`    | [connector-trigger/impl.md](plugins/connector-trigger/impl.md) |
+
+For each node type, record:
+
+- Input port names (must match `targetPort` in edges)
+- Output port names (must match `sourcePort` in edges)
+- Required input fields (`required: true` in `inputDefinition`)
+- Output variable schema (`outputDefinition`)
+
+Update your node table if any ports or required fields differ from the planning guide.
+
+### Step 2 — Resolve Connector Nodes
+
+For each connector node, follow the Configuration Workflow in [connector/impl.md](plugins/connector/impl.md). The guide covers connection binding, metadata retrieval, field resolution, and validation.
+
+Record the connection ID and resolved field values for the build step.
+
+### Step 3 — Resolve Resource Nodes
+
+For each resource node (RPA process, agent, flow, API workflow, human task), follow the discovery and validation steps in the relevant resource plugin's `impl.md`.
+
+```bash
+uip maestro flow registry get "<node-type>" --output json
+```
+
+Record `inputDefinition` and `outputDefinition` for the node table.
+
+If Phase 1 flagged a resource as not found, check two sources:
+
+**1. In-solution discovery (preferred — no login required):**
+```bash
+uip maestro flow registry list --local --output json
+```
+Run from the flow project directory. If the resource exists as a sibling project in the same `.uipx` solution, it appears here — use `registry get "<node-type>" --local --output json` to get the full manifest.
+
+**2. Tenant registry (if not in solution):**
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "<resource-name>" --output json
+```
+
+If found in neither, keep the `core.logic.mock` placeholder and note the gap.
+
+#### IxP nodes — context-dispatched, no bindings
+
+IxP extraction nodes (`uipath.ixp.*`) skip binding resolution. Design-time configuration (`folderKey`, `modelName`) is emitted into the BPMN `model.context[]` array at build time (the serializer also pins `digitizationMode` to `"fileUpload"` internally), not into a separate `bindings_v2.json` file or a top-level `bindings[]` entry. Consequence for Phase 2:
+
+- No connection ID to bind — the node carries its tenant context inline.
+- `inputs.*` is the source of truth for runtime values; validate against `registry get` `inputDefinition.properties` rather than against a binding schema.
+- The node instance also carries a structured `inputs.model` blob (extraction-model metadata) that the property panel's `ixp-model-taxonomy` component reads. Copy `inputDefaults.model` verbatim — omitting it crashes the panel with `Cannot destructure property 'modelName' of 't' as it is undefined`.
+- See [plugins/ixp/impl.md](plugins/ixp/impl.md) for the full JSON shape.
+
+### Step 4 — Replace Mock Nodes
+
+For each `core.logic.mock` node in the architectural plan:
+
+1. Check in-solution discovery first: `uip maestro flow registry list --local --output json`
+2. If found locally: replace the mock with the in-solution resource node type, update inputs/outputs
+3. If not found locally, check tenant registry: `uip maestro flow registry search "<name>" --output json`
+4. If published: replace the mock with the real resource node type, update inputs/outputs
+5. If not found in either: keep the mock and note it in the "Open Questions" section for user resolution
+
+### Step 5 — Replace Placeholders
+
+Update the node table from the `.uipath.flow.arch.plan.md`:
+
+- Replace `<PLACEHOLDER>` values with resolved IDs
+- Replace `connector: <service>` annotations with actual node types
+- Replace `resource: <name>` annotations with actual node types
+- Update inputs with resolved reference field values
+- Update outputs based on `outputDefinition` from registry
+
+### Step 6 — Write the Implementation Plan
+
+Generate a `<SolutionName>.uipath.flow.impl.plan.md` file in the **solution directory** (same location as the `.uipath.flow.arch.plan.md`).
+
+#### Output Format
+
+````markdown
+# <SolutionName> Implementation Plan
+
+## Summary
+
+2-3 sentences describing what the flow does end-to-end and what was resolved in this phase (connectors bound, resources confirmed, registry validations performed).
+
+## Flow Diagram (Mermaid)
+
+Copy the mermaid diagram from `.uipath.flow.arch.plan.md`, then update node labels if any node types changed due to mock replacement or connector resolution. Use the same diagram from architectural planning — it remains the visual reference for the flow structure.
+
+```mermaid
+graph LR
+    trigger(Manual Trigger)
+    action1[Resolved Action 1]
+    decision{Resolved Decision}
+    end1(Done)
+    trigger -->|output| action1
+    action1 -->|success| decision
+    decision -->|true| end1
+```
+````
+
+## Resolved Node Table
+
+| #   | Node ID | Name | Node Type | Inputs | Outputs | Connection ID | Notes |
+| --- | ------- | ---- | --------- | ------ | ------- | ------------- | ----- |
+
+## Resolved Edge Table
+
+(Copy from `.uipath.flow.arch.plan.md` — update only if node IDs changed due to mock replacement)
+
+## Bindings
+
+| Connector Key | Connection ID | Activity | Verified |
+| ------------- | ------------- | -------- | -------- |
+
+## Global Variables
+
+(Copy from `.uipath.flow.arch.plan.md` Inputs and Outputs section)
+
+## Changes from Architectural Plan
+
+- List what changed between `.uipath.flow.arch.plan.md` and this plan
+- Record any node type changes (connector resolutions, mock replacements)
+- Note any port or input field changes discovered during registry validation
+
+## Open Questions
+
+Prefix each with `**[REQUIRED]**` or `**[OPTIONAL]**`. If there are no open questions, write "No open questions — all details resolved."
+
+- **[REQUIRED]** Which connection should be used for the Slack connector?
+- **[OPTIONAL]** Should the retry count be increased from the default?
+
+````
+
+#### Column Additions
+
+The implementation plan adds these columns beyond the architectural plan:
+
+- **Connection ID**: The bound connection UUID (connector nodes only)
+- **Verified**: Whether the connection was pinged successfully
+
+### Step 7 — Get Approval
+
+Present a short summary in chat:
+
+1. Registry validation results — confirm all OOTB node ports and inputs match the plan
+2. How many connector/resource nodes were resolved
+3. Any port or input field changes discovered during validation
+4. Any mock placeholders remaining
+5. Any required fields that need user input
+6. Any connections that need to be created
+
+Tell the user to review `<SolutionName>.uipath.flow.impl.plan.md`, including the updated mermaid diagram and registry confirmations. Do NOT proceed to the build step until the user explicitly approves.
+
+---
+
+## Product Heuristics
+
+These are org-wide "when to use what" rules that can't be encoded in individual node descriptions. They reflect how UiPath's products fit together and which approach to prefer for a given task.
+
+### Connecting to External Services
+
+See [planning-arch.md — Selecting External Service Nodes](planning-arch.md#selecting-external-service-nodes) for the 4-tier decision order (connector -> HTTP within connector -> standalone HTTP -> RPA).
+
+### Agent Nodes vs Workflow Logic
+
+See [agent/planning.md](plugins/agent/planning.md) for the full decision table. Summary:
+
+- **Agent nodes** for ambiguous input, reasoning, judgment, NLG
+- **Script/Decision/Switch** for structured input, deterministic logic, data transformation
+
+**Anti-pattern:** Don't use an agent node for tasks that can be done with a Decision + Script. Agents are slower, more expensive (LLM tokens), and less predictable.
+
+**Hybrid pattern:** Use workflow nodes for the deterministic parts (fetch data, transform, route) and agent nodes for the ambiguous parts (classify intent, draft response, extract entities). The flow orchestrates; the agent reasons.
+
+---
+
+## Expressions and Variables
+
+For the **complete reference** on variables (declaration, types, scoping, variable updates) and expressions (`=js:`, templates, Jint constraints), see [variables-and-expressions.md](../../shared/variables-and-expressions.md).
+
+### Quick Reference
+
+Nodes communicate data through `$vars`. Every node's output is accessible downstream via `$vars.{nodeId}.{outputProperty}`.
+
+```javascript
+$vars.rollDice.output.roll              // Script return value
+$vars.fetchData.output.body             // HTTP response body
+$vars.fetchData.output.statusCode       // HTTP status code
+$vars.someNode.error.message            // Error information
+iterator.currentItem                     // Loop item (inside loop body)
+````
+
+**Expression prefixes:**
+
+- `=js:` — Full JavaScript expression evaluated by Jint: `=js:$vars.count > 10`
+- `{ }` — Template interpolation for string fields: `Order {$vars.orderId} is {$vars.status}`
+
+**Variable directions** (`variables.globals`):
+
+- `in` — External input (read-only after start)
+- `out` — Workflow output (must be mapped on End nodes)
+- `inout` — State variable (updated via `variableUpdates`)
+
+---
+
+## Wiring Rules
+
+### Port Compatibility
+
+- Edges connect a **source** port (output) on one node to a **target** port (input) on another
+- Source handles have `type: "source"`, target handles have `type: "target"`
+- You cannot wire two source ports together or two target ports together
+
+### Connection Constraints
+
+Some nodes enforce connection rules via `constraints` in their handle configuration:
+
+| Constraint                               | Meaning                                                         |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `minConnections: N`                      | Handle must have at least N edges (validation error if not met) |
+| `maxConnections: N`                      | Handle accepts at most N edges                                  |
+| `forbiddenSourceCategories: ["trigger"]` | Cannot receive connections from trigger nodes                   |
+| `forbiddenTargetCategories: ["trigger"]` | Cannot connect output to trigger nodes                          |
+
+**Key rules:**
+
+- Trigger nodes can only have outgoing connections (no input port)
+- End/Terminate nodes can only have incoming connections (no output port)
+- Control flow outputs generally cannot loop back to triggers
+- Decision and Switch nodes cannot receive connections from agent resource nodes
+
+### Dynamic Ports
+
+Some nodes create ports based on their configuration:
+
+- **HTTP Request** — One port per `branches` entry: `branch-{id}`. See [http/impl.md](plugins/http/impl.md).
+- **Switch** — One port per `cases` entry: `case-{id}`. See [switch/impl.md](plugins/switch/impl.md).
+- **Loop** — `success` port fires after completion, `output` port carries aggregated results. See [loop/impl.md](plugins/loop/impl.md).
+
+When wiring to dynamic ports, the port ID must match the configured item's `id`.

package/skills/uipath-maestro-flow/references/author/references/plugins/agent/impl.md

@@ -0,0 +1,189 @@
+# Agent Node — Implementation
+
+Agent nodes invoke UiPath AI agents via node type `uipath.core.agent.{key}`. Coded (Python) agents always use this plugin; low-code (`agent.json`) agents use it only when they are a standalone project (in-solution sibling or published). Inline low-code agents (embedded as a UUID subdirectory inside the flow project) use `uipath.agent.autonomous` — see the [inline-agent plugin](../inline-agent/impl.md).
+
+The agent lives in one of two places:
+
+- **In this solution** — sibling project inside the current solution. `{key}` is the local `resource.key` minted by `uip solution project add` (written to `resources/solution_folder/process/agent/<CodedAgentProject>.json`). The runtime resolves the node via the Studio Web projects API after `uip solution upload`. The manifest in `definitions[]` carries `model.section: "In this solution"`.
+- **Published** — deployed to Orchestrator as a tenant resource. `{key}` is the Orchestrator-assigned resource key. Discoverable via `uip maestro flow registry search`. The manifest in `definitions[]` carries `model.section: "Published"`.
+
+The node-instance shape (in `nodes[]`) is identical across the two variants — only the manifest in `definitions[]` differs (`{key}` and `model.section`).
+
+## Discovery
+
+**Published (tenant registry):**
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.agent" --output json
+```
+
+Requires `uip login`. Only published agents from your tenant appear.
+
+**In-solution (local, no login required):**
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+Run from inside the flow project directory. Discovers sibling agent projects in the same `.uipx` solution.
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get "uipath.core.agent.{key}" --output json
+uip maestro flow registry get "uipath.core.agent.{key}" --local --output json
+```
+
+Requires `uip login`. Only published agents from the tenant appear in the registry.
+
+Confirm from `registry get`:
+
+- Input port: `input`
+- Output port: `output`
+- `outputDefinition.output.schema` — contains `content` (string)
+- `outputDefinition.error.schema` — contains `code`, `message`, `detail`, `category`, `status`
+- `model.serviceType` — `Orchestrator.StartAgentJob`
+- `model.bindings.resourceSubType` — `Agent`
+- `model.bindings.resourceKey` — the `<FolderPath>.<AgentName>` string used to scope binding resolution
+- `inputDefinition` — typically empty (agents accept free-form input via the flow's wiring)
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for the node-specific `inputs`.
+
+## JSON Structure
+
+### Node instance (inside `nodes[]`) — published variant
+
+The instance carries only per-instance data (`inputs`, `outputs`, `display`). BPMN type, serviceType, version, and binding/context templates come from the definition in `definitions[]`.
+
+```json
+{
+  "id": "classifyIntent",
+  "type": "uipath.core.agent.ffa33d88-8a85-4570-933c-9a69aa2dfbb5",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Classify Intent" },
+  "inputs": {},
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the agent",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the agent fails",
+      "source": "=result.Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+The `model` block (BPMN type, `serviceType`, `bindings`, `context` template) lives on the manifest entry in `definitions[]`, not on the instance. The manifest is auto-populated by `uip maestro flow registry pull` — never hand-author it.
+
+Three values to discover — never invent:
+- **`type` suffix** — Orchestrator-assigned UUID for this agent. Per-ring and per-agent — never copy across environments. Read from `uip maestro flow registry search "uipath.core.agent"` / `registry get` as `nodeType`.
+- **`typeVersion`** — the manifest's `version` field. Read from `uip maestro flow registry get <node-type> --output json` (`.version`).
+- **`resourceKey`** — composite `<FolderPath>.<AgentName>` (e.g. `Shared.Apple Genius Agent`). Appears on each top-level `bindings[]` entry tied to this agent. Read from `registry get` (`model.bindings.resourceKey` on the manifest).
+
+Confirm all three from `registry get` before wiring.
+
+### Node instance (inside `nodes[]`) — in-solution variant
+
+```json
+{
+  "id": "codedAgent",
+  "type": "uipath.core.agent.<resourceKey>",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<Label>", "icon": "<AGENT_ICON>" },
+  "inputs": {},
+  "outputs": {
+    "output": { "type": "object", "description": "The return value of the agent", "source": "=result.response", "var": "output" },
+    "error":  { "type": "object", "description": "Error information if the agent fails", "source": "=result.Error", "var": "error" }
+  }
+}
+```
+
+`<AGENT_ICON>` depends on the agent's implementation type: `"coded-agent"` for Python-coded agents, `"autonomous-agent"` for low-code (`agent.json`) agents. Detect the type by inspecting the sibling agent project directory: if `agent.json` exists at its root, use `"autonomous-agent"`; otherwise use `"coded-agent"`. Do NOT copy `.display.icon` from `uip maestro flow registry get --local` — that manifest returns `"coded-agent"` for every in-solution agent regardless of implementation type, and the value must be corrected here.
+
+Same shape as the published variant — no `model` on the instance.
+
+**Never hand-author the `definitions[]` entry.** Run `uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json`, extract the `Data.Node` object, and paste it verbatim into `definitions[]`. Constructing it by hand risks missing required validator fields (`model.section`, `runtimeConstraints`, `supportsErrorHandling`, etc.).
+
+`<resourceKey>` is the local `resource.key` written by `uip solution project add` to `resources/solution_folder/process/agent/<CodedAgentProject>.json` — read it from that file or from `uip maestro flow registry list --local --output json`. Read `<DEFINITION_VERSION>` from `uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json` (`.version`).
+
+### Top-level `bindings[]` entries (sibling of `nodes`/`edges`/`definitions`)
+
+**Rule.** Exactly one entry per `(resourceKey, propertyAttribute)` pair. Multiple node instances referencing the same agent MUST reuse the same `bindings[].id` — never duplicate the entry.
+
+**Validate.** After writing the flow, group `bindings[]` by `(resourceKey, propertyAttribute)`. Each group must have length 1. If any group has length > 1, deduplicate before saving.
+
+```json
+"bindings": [
+  {
+    "id": "bClassifyIntentName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<resourceKey>",
+    "default": "<agent-name>",
+    "propertyAttribute": "name",
+    "resourceSubType": "Agent"
+  },
+  {
+    "id": "bClassifyIntentFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<resourceKey>",
+    "default": "<folder-path-or-empty>",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Agent"
+  }
+]
+```
+
+> For the resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## Accessing Output
+
+The agent's response is available downstream:
+
+```javascript
+// In a Script node after the agent
+const response = $vars.classifyIntent.output.content;
+return { classification: response };
+```
+
+- `$vars.{nodeId}.output.content` — the agent's text response
+- `$vars.{nodeId}.error` — error details if the agent fails
+
+## If the Agent Does Not Exist Yet
+
+Create the agent first, then wire it. Three paths:
+
+- **In-solution (sibling project, coded or low-code)** — scaffold via `uipath-agents`, register with `uip solution project add` to mint the local `resource.key`, then discover via `uip maestro flow registry list --local`. For the coded pipeline, see [coded/embedding-in-flows.md](../../../../../../uipath-agents/references/coded/embedding-in-flows.md).
+- **Published coded agent** — `uip codedagent deploy`, then `uip maestro flow registry pull --force`.
+- **Published low-code agent** — `uip solution deploy`, then `uip maestro flow registry pull --force`.
+
+## Using an Agent as a Tool Resource
+
+To use a published agent (coded or low-code) as a **tool for another agent** rather than a standalone flow node, add it as a `uipath.agent.resource.tool.agent` resource node wired to the parent agent's `tool` handle. This lives within the agent's canvas, not at the top level of the flow.
+
+For the resource file format and wiring details, see the `uipath-agents` skill:
+- Coded agents: [coded/flow-integration.md § Pattern 3](../../../../../../uipath-agents/references/coded/flow-integration.md#pattern-3-tool-resource-for-another-agent)
+- Low-code agents: see the `uipath-agents` skill's low-code references.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Agent not published, or registry stale | If in same solution: run `registry list --local`. Otherwise: run `uip login` then `uip maestro flow registry pull --force`. For coded agents, ensure `uip codedagent deploy` completed successfully |
+| In-solution node doesn't resolve | `resourceKey` was hand-invented rather than read from the resource file, or `uip solution project add` was never run for the agent project | Run `uip maestro flow registry list --local` and use the returned `resourceKey` (same value as `resource.key` in `resources/solution_folder/process/agent/<CodedAgentProject>.json`) |
+| Agent execution failed | Underlying agent errored | Check `$vars.{nodeId}.error` for details. For coded agents, test locally first with `uip codedagent run` |
+| Empty `output.content` | Agent returned no response | Verify the agent is configured correctly (published: in Orchestrator; in-solution: in Studio Web) |
+| `inputDefinition` is empty | Expected — agents accept input via flow wiring, not typed fields | Wire upstream data to the agent via `$vars` expressions |

package/skills/uipath-maestro-flow/references/author/references/plugins/agent/planning.md

@@ -0,0 +1,83 @@
+# Agent Node — Planning
+
+Agent nodes invoke UiPath AI agents from within a flow. Published agents appear in the registry after `uip login` + `uip maestro flow registry pull`. **In-solution** (unpublished) agents in sibling projects are discovered via `--local` — no login or publish required. Both **coded** (Python) and **low-code** (agent.json) agents appear here once deployed — the flow treats them identically.
+
+> **Related plugin:** [inline-agent](../inline-agent/planning.md) covers low-code agents embedded as a UUID subdirectory **inside** the flow project (`uipath.agent.autonomous`). Coded agents always use this `agent` plugin, not `inline-agent`.
+
+> **Choosing between coded and low-code, or wiring them into a flow:** see the `uipath-agents` skill — [coded-vs-lowcode-guide.md](../../../../../../uipath-agents/references/coded-vs-lowcode-guide.md) for the comparison, [coded/flow-integration.md](../../../../../../uipath-agents/references/coded/flow-integration.md) for coded-agent Flow patterns.
+
+> **If the user names an existing agent, it is a published agent — not inline.** When a prompt says "use the X agent" / "call the Y agent" / "invoke the Z coded agent" / "use the W low-code agent", the user is referring to an agent that already exists in the tenant (or in-solution). ALWAYS run `uip maestro flow registry search "<name>" --output json` BEFORE deciding to scaffold an inline agent. The words "coded" and "low-code" describe the *implementation style* of a published agent — they do NOT mean "inline". Inline (`uipath.agent.autonomous`) is only correct when the user explicitly asks to embed, inline, or create a new agent from scratch inside this flow.
+
+## Node Type Pattern
+
+`uipath.core.agent.{key}`
+
+The `{key}` is the agent's unique identifier (typically a GUID) from Orchestrator.
+
+## When to Use
+
+Use an Agent node when the flow needs to invoke a published AI agent for reasoning, judgment, or natural language processing.
+
+### Agent vs Script/Decision Decision Table
+
+| Use an Agent node when... | Use Script/Decision/Switch when... |
+| --- | --- |
+| Input is ambiguous or unstructured (free text, emails, support tickets) | Input is structured and well-defined (JSON, form data) |
+| Task requires reasoning or judgment (triage, classification, summarization) | Task is deterministic (if X then Y, map/filter/transform) |
+| Branching depends on context that can't be reduced to simple conditions | Branching conditions are explicit and enumerable |
+| You need natural language generation (draft emails, summaries) | You need data transformation or computation |
+
+### Anti-Pattern
+
+Don't use an agent node for tasks that can be done with a Decision + Script. Agents are slower, more expensive (LLM tokens), and less predictable. Use them where their flexibility is actually needed.
+
+### Hybrid Pattern
+
+Use workflow nodes for the deterministic parts (fetch data, transform, route) and agent nodes for the ambiguous parts (classify intent, draft response, extract entities). The flow orchestrates; the agent reasons.
+
+### When NOT to Use
+
+- **Agent in the same solution but not yet published** — use `--local` discovery (see below)
+- **Agent does not exist yet** — tell the user to create it in the same solution with `uipath-agents`, then use `--local` discovery
+- **Task is deterministic** — use [Script](../script/planning.md) or [Decision](../decision/planning.md)
+- **Need to call an external service API** — use [Connector](../connector/planning.md) or [HTTP](../http/planning.md)
+- **Agent should be a tool for another agent** — don't use this node; instead add the agent as a tool resource (`uipath.agent.resource.tool.agent`) wired to a parent agent node. See the `uipath-agents` skill for the resource file format
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — the agent's response (contains `content` string)
+- `$vars.{nodeId}.error` — error details if the agent fails (`code`, `message`, `detail`, `category`, `status`)
+
+## Discovery
+
+**Published (tenant registry):**
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.agent" --output json
+```
+
+Requires `uip login`. Returns published tenant resources only — for in-solution sibling projects, use the `--local` discovery below.
+
+**In-solution (local, no login required):**
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+Run from inside the flow project directory. Discovers sibling agent projects in the same `.uipx` solution.
+
+## Planning Annotation
+
+In the architectural plan:
+- If the agent exists: note as `resource: <agent-name> (agent)`
+- If it does not exist: note as `[CREATE NEW] <description>` with skill `uipath-agents`