@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,291 @@
+# Planning Phase 2: Implementation Resolution
+
+Resolve every implementation detail in the approved `.uipath.flow.arch.plan.md` and produce a build-ready `.uipath.flow.impl.plan.md`, using plugin `impl.md` files, wiring rules, and flow patterns.
+
+> **Prerequisite:** `.uipath.flow.arch.plan.md` exists and its approval went through rule #5 ([planning-arch.md — Handoff to Phase 2](planning-arch.md#handoff-to-phase-2)).
+>
+> **Always validate with the registry**, including OOTB nodes. Port names, required inputs, and output schemas can change.
+
+## Implementation Resolution Process
+
+### Step 1 — Identify Nodes and Validate with Registry
+
+Scan the approved architectural-plan node table and connector summary. Classify every node:
+
+| Category | Identification | Action |
+|---|---|---|
+| Connector | Type starts with `uipath.connector.*`, or Notes say `connector:` | Run Step 2 with [connector/impl.md](plugins/connector/impl.md); for a non-catalog `uipath.connector.custom.*` type use [connector/impl-inline.md](plugins/connector/impl-inline.md). |
+| Resource | Type starts with `uipath.core.*`, or Notes say `resource:` | Run Step 3 with the relevant 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), or [hitl](plugins/hitl/impl.md). |
+| Mock | Type is `core.logic.mock` | Run Step 4. |
+| OOTB | All other nodes, including Script, HTTP, Decision, and Loop | Run Step 1a with the relevant plugin `impl.md`. |
+
+Validate **all nodes** through the registry before proceeding.
+
+#### Step 1a — Validate All Node Types with Registry
+
+For each node type, read its plugin `impl.md`, then run:
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry get <node-type> --output json
+```
+
+Use these plugin mappings:
+
+| Node type | Plugin |
+|---|---|
+| `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.trigger.conversation` | [conversational-agent/impl.md](plugins/conversational-agent/impl.md) |
+| `uipath.agent.conversational` | [conversational-agent/impl.md](plugins/conversational-agent/impl.md) |
+| `uipath.conversational.wait-for-message` | [conversational-agent/impl.md](plugins/conversational-agent/impl.md) |
+| `uipath.conversational.send-message` | [conversational-agent/impl.md](plugins/conversational-agent/impl.md) |
+| `uipath.conversational.get-conversation-context` | [conversational-agent/impl.md](plugins/conversational-agent/impl.md) |
+| `core.trigger.voice` | [inline-voice-agent/impl.md](plugins/inline-voice-agent/impl.md) |
+| `core.action.queue.*` | [queue/impl.md](plugins/queue/impl.md) |
+| `core.datafabric.*` | [data-fabric/impl.md](plugins/data-fabric/impl.md) |
+| `uipath.agent.autonomous` | [inline-agent/impl.md](plugins/inline-agent/impl.md) |
+| `uipath.agent.voice` | [inline-voice-agent/impl.md](plugins/inline-voice-agent/impl.md) |
+| `uipath.conversational.voice.create-outgoing-call` | [inline-voice-agent/impl.md](plugins/inline-voice-agent/impl.md) |
+| `uipath.conversational.voice.end-call` | [inline-voice-agent/impl.md](plugins/inline-voice-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.ixp.*` | [ixp/impl.md](plugins/ixp/impl.md) |
+| `uipath.connector.custom.*` | [connector/impl-inline.md](plugins/connector/impl-inline.md) |
+| `uipath.connector.*` | [connector/impl.md](plugins/connector/impl.md) |
+| `uipath.connector.trigger.*` | [connector-trigger/impl.md](plugins/connector-trigger/impl.md) |
+
+For every node, record input port names for edge `targetPort`, output port names for edge `sourcePort`, fields where `required: true` in `inputDefinition`, and the `outputDefinition` schema. Update the node table when registry values 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), including connection binding, metadata retrieval, field resolution, and validation. Record the connection ID and resolved field values for the build.
+
+### Step 3 — Resolve Resource Nodes
+
+For each RPA process, agent, flow, API workflow, or human-task node, follow its plugin discovery and validation steps. Run:
+
+```bash
+uip maestro flow registry get "<node-type>" --output json
+```
+
+Record `inputDefinition` and `outputDefinition` in the node table.
+
+If Phase 1 marked a resource not found, use in-solution discovery first. Run from the flow project directory:
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry search "<resource-name>" --local --output json   # keyword match when the list is long
+```
+
+For a sibling project in the same `.uipx` solution, run:
+
+```bash
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+If it is not in the solution, run:
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "<resource-name>" --output json
+```
+
+If neither source finds it, retain `core.logic.mock` and record the gap.
+
+#### IxP nodes — context-dispatched, no bindings
+
+IxP extraction nodes (`uipath.ixp.*`) skip binding resolution. At build time, emit design-time `folderKey` and `modelName` into the BPMN `model.context[]` array; the serializer pins `digitizationMode` to `"fileUpload"`. Do not put these in `bindings_v2.json`, a top-level `bindings[]`, or a connection binding.
+
+Use `inputs.*` as the runtime source of truth and validate it against `registry get` `inputDefinition.properties`. Each node must carry structured `inputs.model` extraction-model metadata read by the `ixp-model-taxonomy` property-panel component. 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:
+
+1. Run `uip maestro flow registry list --local --output json`, or run `uip maestro flow registry search "<name>" --local --output json` for a keyword match.
+2. If found locally, replace the mock with the in-solution resource type and update inputs and outputs.
+3. If not found locally, run `uip maestro flow registry search "<name>" --output json`.
+4. If published, replace the mock with the real resource type and update inputs and outputs.
+5. If absent from both, retain the mock and record it in **Open Questions** for user resolution.
+
+### Step 5 — Replace Placeholders
+
+Update the architectural-plan node table:
+
+- Replace `<PLACEHOLDER>` values with resolved IDs.
+- Replace `connector: <service>` with actual node types.
+- Replace `resource: <name>` with actual node types.
+- Add resolved reference-field values to inputs.
+- Derive outputs from registry `outputDefinition`, mirroring both keys and their `source`; an invented `source` can pass `flow validate` but resolve to null at runtime.
+
+### Step 6 — Write the Implementation Plan
+
+Create `<SolutionName>.uipath.flow.impl.plan.md` beside `.uipath.flow.arch.plan.md` in the solution directory.
+
+#### Output Format
+
+````markdown
+# <SolutionName> Implementation Plan
+
+## Summary
+
+2-3 sentences describing the end-to-end flow and what this phase resolved: connector bindings, confirmed resources, and registry validations.
+
+## Flow Diagram (Mermaid)
+
+Copy the mermaid diagram from `.uipath.flow.arch.plan.md`; update labels if mock replacement or connector resolution changes node types. Keep the same flow structure as the architectural visual reference.
+
+```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 the architectural plan's Inputs and Outputs section.
+
+## Changes from Architectural Plan
+
+- List changes between `.uipath.flow.arch.plan.md` and this plan.
+- Record connector resolutions, mock replacements, and node-type changes.
+- Record port or input-field changes found during registry validation.
+
+## Open Questions
+
+Prefix every question with `**[REQUIRED]**` or `**[OPTIONAL]**`. If none remain, write: `No open questions — all details resolved.`
+
+- **[REQUIRED]** Which connection should be used for the connector?
+- **[OPTIONAL]** Should the retry count be increased from the default?
+````
+
+Add these architectural-plan columns: **Connection ID** (bound connection UUID for connector nodes) and **Verified** (whether the connection was pinged successfully).
+
+### Step 7 — Get Approval
+
+Present a short chat summary containing:
+
+1. Registry validation results, confirming all OOTB ports and inputs match the plan.
+2. Number of resolved connector/resource nodes.
+3. Port or input-field changes found during validation.
+4. Remaining mock placeholders.
+5. Required fields needing user input.
+6. Connections needing creation.
+
+Tell the user to review `<SolutionName>.uipath.flow.impl.plan.md`, including its updated mermaid diagram and registry confirmations. **Do not build until the plan is approved, and route that approval through [SKILL.md](../../SKILL.md) rule #5 with the proceed option marked recommended** — rule #5 owns both branches, so a user approves interactively and its non-interactive fallback takes the marked option and records the unreviewed build.
+
+**Write the plan before asking, always.** The resolved node table, edge table, and bindings are what make the build mechanical instead of a per-node re-derivation.
+
+## Product Heuristics
+
+These org-wide selection rules complement individual node descriptions.
+
+### Connecting to External Services
+
+See [planning-arch.md — Selecting External Service Nodes](planning-arch.md#selecting-external-service-nodes) for the four-tier order: connector -> HTTP within connector -> standalone HTTP -> RPA.
+
+### Agent Nodes vs Workflow Logic
+
+See [agent/planning.md](plugins/agent/planning.md) for the decision table:
+
+- Use **agent nodes** for ambiguous input, reasoning, judgment, NLG, and similar tasks.
+- Use **Script/Decision/Switch** for structured input, deterministic logic, and data transformation.
+- Do not use an agent where Decision + Script is sufficient; agents are slower, more expensive due to LLM tokens, and less predictable.
+- Use the hybrid pattern: workflow nodes fetch, transform, and route; agent nodes classify intent, draft responses, or extract entities.
+
+## Expressions and Variables
+
+For declaration, types, scoping, updates, and expressions, see [variables-and-expressions.md](../shared/variables-and-expressions.md).
+
+### Quick Reference
+
+Nodes communicate through `$vars`; downstream nodes access outputs as `$vars.{nodeId}.{outputProperty}`.
+
+```javascript
+$vars.rollDice.output.roll              // Script return value
+$vars.fetchData.output.body             // HTTP response body
+$vars.fetchData.output.statusCode       // HTTP response status
+$vars.someNode.error.message            // Error information
+$vars.<loopId>.currentItem              // Loop item inside loop body
+```
+
+Prefixes:
+
+- `=js:` is a full JavaScript expression evaluated by Jint, such as `=js:$vars.count > 10`.
+- `{ }` performs string interpolation, such as `Order {$vars.orderId} is {$vars.status}`.
+
+Variable directions in `variables.globals`:
+
+- `in`: external, read-only after start.
+- `out`: workflow output; map it on End nodes.
+- `inout`: state variable updated through `variableUpdates`.
+
+## Wiring Rules
+
+### Port Compatibility
+
+- Connect a source output port to a target input port.
+- Source handles have `type: "source"`; target handles have `type: "target"`.
+- Never connect two source ports or two target ports.
+
+### Connection Constraints
+
+Nodes may enforce handle constraints:
+
+| Constraint | Meaning |
+|---|---|
+| `minConnections: N` | Handle requires at least N edges; otherwise validation fails. |
+| `maxConnections: N` | Handle accepts at most N edges. |
+| `forbiddenSourceCategories: ["trigger"]` | The handle cannot receive connections from trigger nodes. |
+| `forbiddenTargetCategories: ["trigger"]` | The output cannot connect to trigger nodes. |
+
+Additional rules:
+
+- Trigger nodes have only outgoing connections and no input port.
+- End/Terminate nodes have only incoming connections and no output port.
+- Control-flow outputs generally cannot loop to triggers.
+- Decision and Switch nodes cannot receive connections from agent resource nodes.
+
+### Dynamic Ports
+
+Some ports are configuration-generated:
+
+- **HTTP Request:** one port per `branches` entry, named `branch-{id}`; see [http/impl.md](plugins/http/impl.md).
+- **Switch:** one port per `cases` entry, named `case-{id}`; see [switch/impl.md](plugins/switch/impl.md).
+- **Loop:** `success` fires after completion; `output` carries aggregated results; see [loop/impl.md](plugins/loop/impl.md).
+
+When wiring a dynamic port, its ID must equal the configured item's `id`.

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

@@ -0,0 +1,237 @@
+# Agent Node — Implementation
+
+Agent nodes invoke UiPath AI agents through `uipath.core.agent.{key}`. Coded (Python) agents always use this plugin. Standalone low-code (`agent.json`) agents use it when in-solution siblings or published; inline low-code agents embedded as a UUID subdirectory use `uipath.agent.autonomous`—see the [inline-agent plugin](../inline-agent/impl.md).
+
+Agents are either:
+
+- **In this solution**: a sibling project. `{key}` is the local `resource.key` minted by `uip solution projects add` and written to `resources/solution_folder/process/agent/<CodedAgentProject>.json`. Runtime resolution uses the Studio Web projects API after `uip solution upload`; `definitions[]` uses `model.section: "In this solution"`.
+- **Published**: an Orchestrator tenant resource. `{key}` is the Orchestrator-assigned resource key, discoverable with `uip maestro flow registry search`; `definitions[]` uses `category: "agent.published"` (registry output omits `model.section`).
+
+The `nodes[]` shape is the same; only the `definitions[]` manifest differs.
+
+## Discovery and Registry Validation
+
+Run these commands for published agents (requires `uip login`):
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.agent" --output json
+```
+
+Only published agents from the logged-in tenant appear. Run these commands inside the flow project directory for in-solution agents; no login is required:
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+These discover sibling agent projects in the same `.uipx` solution.
+
+Run:
+
+```bash
+uip maestro flow registry get "uipath.core.agent.{key}" --output json
+uip maestro flow registry get "uipath.core.agent.{key}" --local --output json
+```
+
+The non-local command requires `uip login` and shows only published tenant agents. Confirm from `registry get`:
+
+- Ports are input `input` and output `output`.
+- `outputDefinition.output.schema` contains `content` (string).
+- `outputDefinition.error.schema` contains `code`, `message`, `detail`, `category`, `status`.
+- `model.serviceType` is `Orchestrator.StartAgentJob`.
+- `model.bindings.resourceSubType` is `Agent`.
+- `model.bindings.resourceKey` is the `<FolderPath>.<AgentName>` string used to scope binding resolution.
+- `inputDefinition` is the typed input schema, with one property per `entry-points.json` input field. Each property requires an `inputs.<field>` entry on the node instance; it is empty only for agents with no typed inputs (free-form). See [Wiring Inputs](#wiring-inputs).
+
+For add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON below for node-specific `inputs`.
+
+## Node Instances
+
+Per-instance data is `inputs`, `outputs`, and `display`; BPMN type, service type, version, and binding/context templates come from `definitions[]`.
+
+### Published
+
+```json
+{
+  "id": "<NODE_ID>",
+  "type": "uipath.core.agent.<AGENT_UUID>",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<LABEL>" },
+  "inputs": {
+    "<INPUT_FIELD>": {
+      "type": "jsExpression",
+      "expression": "$vars.<UPSTREAM_NODE_ID>.output.<FIELD>",
+      "fieldType": "<FIELD_TYPE>"
+    }
+  },
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the agent fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+Never invent these values; confirm all three with `registry get` before wiring:
+
+- `type` suffix: the Orchestrator-assigned UUID, per ring and agent; read `nodeType` from `uip maestro flow registry search "uipath.core.agent"` or `registry get`.
+- `typeVersion`: the manifest `version`, read from `uip maestro flow registry get <node-type> --output json` (`.version`).
+- `resourceKey`: composite `<FolderPath>.<AgentName>`, read from `model.bindings.resourceKey`.
+
+The `model` block belongs on the `definitions[]` manifest, not the instance. The manifest is auto-populated by `uip maestro flow registry pull`; never hand-author it.
+
+### In-solution
+
+```json
+{
+  "id": "<NODE_ID>",
+  "type": "uipath.core.agent.<resourceKey>",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<LABEL>", "icon": "<AGENT_ICON>" },
+  "inputs": {},
+  "outputs": {
+    "error": { "type": "object", "description": "Error information if the agent fails", "source": "=Error", "var": "error" }
+  }
+}
+```
+
+Declare `error` only; `output` is derived. Hand-authoring it makes the converter copy `source` verbatim, so `"=result.response"` resolves to null at runtime even when `flow validate` passes. `output` is allowed only with exactly `source: "=this"` and the agent's output schema. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+Set `display.icon` by inspecting the sibling project root: use `"autonomous-agent"` when `agent.json` exists, otherwise `"coded-agent"`. Do not copy `.display.icon` from `uip maestro flow registry get --local`; that manifest reports `"coded-agent"` for every in-solution agent.
+
+Never hand-author `definitions[]`. Run:
+
+```bash
+uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json
+```
+
+Extract the `Data.Node` object verbatim into `definitions[]`; hand construction can omit `model.section`, `runtimeConstraints`, and `supportsErrorHandling`. Read `<resourceKey>` from `resources/solution_folder/process/agent/<CodedAgentProject>.json` or from `uip maestro flow registry list --local --output json`. Read `<DEFINITION_VERSION>` from `.version` in local `registry get` output.
+
+## Top-level `bindings[]`
+
+`bindings[]` is a sibling of `nodes`, `edges`, and `definitions`. Create exactly one entry per `(resourceKey, propertyAttribute)` pair. Multiple instances referencing one agent must reuse the same `bindings[].id`; never duplicate entries.
+
+After writing the flow, group `bindings[]` by `(resourceKey, propertyAttribute)` and require each group to have length 1. Deduplicate any group longer than 1 before saving.
+
+```json
+"bindings": [
+  {
+    "id": "<BINDING_ID_NAME>",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<resourceKey>",
+    "default": "<agent-name>",
+    "propertyAttribute": "name",
+    "resourceSubType": "Agent"
+  },
+  {
+    "id": "<BINDING_ID_FOLDER>",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "<resourceKey>",
+    "default": "<folder-path-or-empty>",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Agent"
+  }
+]
+```
+
+See [file-format.md — Bindings](../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings) for resolution mechanics and why these entries are required.
+
+## Wiring Inputs
+
+Create one `inputs.<field>` entry for every property in `inputDefinition.properties`. Use either shape below with the same binding:
+
+```json
+"<INPUT_FIELD>": {
+  "type": "jsExpression",
+  "expression": "$vars.<UPSTREAM_NODE_ID>.output.<FIELD>",
+  "fieldType": "<FIELD_TYPE>"
+}
+```
+
+or:
+
+```json
+"<INPUT_FIELD>": {
+  "type": "literal",
+  "expression": "{{ $vars.<UPSTREAM_NODE_ID>.output.<FIELD> }}",
+  "fieldType": "<FIELD_TYPE>"
+}
+```
+
+`literal` may mix static text and `{{ }}` interpolation. Never use a plain `"=js:..."` string; it is sent verbatim to the activity and fails with `Cannot find name '<identifier>'`. Set `<FIELD_TYPE>` to the property's JSON-schema type (`string`, `boolean`, `number`, etc.) from `inputDefinition.properties`; do not invent it.
+
+For a trigger-to-agent flow, surface a flow input as a trigger-bound global:
+
+```json
+"variables": {
+  "globals": [
+    { "id": "<INPUT_FIELD>", "direction": "in", "type": "string", "defaultValue": "", "triggerNodeId": "<TRIGGER_ID>" }
+  ]
+}
+```
+
+Connect trigger → agent → end:
+
+```json
+"edges": [
+  { "id": "<EDGE_1>", "sourceNodeId": "<TRIGGER_ID>", "sourcePort": "output", "targetNodeId": "<AGENT_ID>", "targetPort": "input" },
+  { "id": "<EDGE_2>", "sourceNodeId": "<AGENT_ID>", "sourcePort": "output", "targetNodeId": "<END_ID>", "targetPort": "input" }
+]
+```
+
+Reference upstream values as `$vars.<nodeId>.output.<field>` and flow globals as `$vars.<global>`. Agent inputs therefore reference `$vars.<TRIGGER_ID>.output.<INPUT_FIELD>`.
+
+## Conversational Agents
+
+A conversational (text chat) agent uses this node type with a different input shape — `isConversational: true` plus a `conversationalAgentSettings` block, instead of the agent's own schema fields. It also needs the conversation trigger and wait-for-message loop around it.
+
+All of that — the five-key settings block, the node JSON, the loop, and the ports — lives in [conversational-agent/impl.md](../conversational-agent/impl.md). Come back here only for discovery: an in-solution agent is visible only with `--local`.
+
+```bash
+uip maestro flow registry get "uipath.core.agent.{key}" --local --output json
+```
+
+## Accessing Output
+
+```javascript
+const response = $vars.<AGENT_NODE_ID>.output.content;
+return { result: response };
+```
+
+- `$vars.{nodeId}.output.content`: agent text response.
+- `$vars.{nodeId}.error`: failure details.
+
+## If the Agent Does Not Exist Yet
+
+Create it before wiring:
+
+- **In-solution sibling, coded or low-code**: scaffold with `uipath-agents`, register with `uip solution projects add` to mint `resource.key`, then discover with `uip maestro flow registry list --local`. For coded agents, see [coded/embedding-in-flows.md](../../../../../uipath-agents/references/coded/embedding-in-flows.md).
+- **Published coded**: run `uip codedagent deploy`, then `uip maestro flow registry pull --force`.
+- **Published low-code**: run `uip solution deploy`, then `uip maestro flow registry pull --force`.
+
+## Using an Agent as a Tool Resource
+
+To use a published coded or low-code agent as another agent's tool, add a `uipath.agent.resource.tool.agent` resource node inside the parent agent's canvas and wire it to the parent agent's `tool` handle. Do not add it at the top level of the flow.
+
+For 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: the `uipath-agents` skill's low-code references.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Agent is unpublished or registry is stale | For an in-solution agent, 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 does not resolve | `resourceKey` was invented, or `uip solution projects add` was not run | Run `uip maestro flow registry list --local` and use its `resourceKey`, which must equal `resource.key` in `resources/solution_folder/process/agent/<CodedAgentProject>.json`. |
+| Agent execution failed | Underlying agent error | Inspect `$vars.{nodeId}.error`; for coded agents, test locally with `uip codedagent run`. |
+| Empty `output.content` | Agent returned no response | Verify configuration in Orchestrator for published agents or Studio Web for in-solution agents. |
+| `inputDefinition` is empty | Agent declares no typed input schema (free-form) | Wire upstream data through `jsExpression` inputs; see [Wiring Inputs](#wiring-inputs). |

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

@@ -0,0 +1,97 @@
+# 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
+
+## Conversational Agents
+
+A **conversational** agent — one that holds a text chat — uses this same node type. `uip agent init --conversational` and the registry mark it out:
+
+| | Autonomous | Conversational |
+| --- | --- | --- |
+| `display.icon` | `autonomous-agent` | `conversational-agent` |
+| `inputDefaults` | the agent's own input schema | `isConversational: true`, `conversationalAgentSettings: {}` |
+| Usable as another agent's tool | yes | no — no `uipath.agent.resource.tool.agent.<id>` sibling is emitted |
+
+The conversational agent node is only part of a chat. The conversation trigger, the wait-for-message loop, the `conversationalAgentSettings` wiring, and the node JSON for all three agent flavors live in [conversational-agent/planning.md](../conversational-agent/planning.md) — start there for any chat flow.
+
+A published conversational agent gets its `isConversational` flag from its Orchestrator release; an in-solution one gets it from the sibling project's `agent.json`. Either way the registry reports it, so trust `registry get` rather than guessing from the name.
+
+## 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`