@uipath/skills 1.202.0-preview.710 → 1.202.0-preview.716

package/CODEOWNERS

@@ -145,9 +145,13 @@
 /skills/uipath-maestro-flow/references/author/plugins/ixp/ @UiPath/communications-mining @constantinmuraru @vlad-crisan @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/ixp/ @UiPath/communications-mining @constantinmuraru @vlad-crisan @UiPath/maestro-cli-team
 
+# Chat — inline conversational agent node + the conversation trigger and message nodes
+/skills/uipath-maestro-flow/references/author/plugins/conversational-agent/ @UiPath/jarvis @UiPath/maestro-cli-team
+/tests/tasks/uipath-maestro-flow/conversational/ @UiPath/jarvis @UiPath/maestro-cli-team
+
 # Voice — inline voice agent node + the trigger, dial, and end-call nodes
-/skills/uipath-maestro-flow/references/author/plugins/inline-voice-agent/ @UiPath/jarvis @joshparksj @maxduu @scottcmg @andrewwan-uipath @norman-le
-/tests/tasks/uipath-maestro-flow/voice/ @UiPath/jarvis @joshparksj @maxduu @scottcmg @andrewwan-uipath @norman-le
+/skills/uipath-maestro-flow/references/author/plugins/inline-voice-agent/ @UiPath/jarvis @UiPath/maestro-cli-team
+/tests/tasks/uipath-maestro-flow/voice/ @UiPath/jarvis @UiPath/maestro-cli-team
 
 # Review skill
 /skills/uipath-review/ @AlvinStanescu @gabrielavaduva @roalexandru

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.202.0-preview.710",
+  "version": "1.202.0-preview.716",
   "description": "UiPath agent skills for Claude Code, Codex, Cursor, Copilot, Gemini and OpenCode — RPA, UI automation, UI testing, coded agents/apps/workflows, and troubleshooting. Distributed as the UiPath Claude Code plugin.",
   "author": {
     "name": "UiPath"

package/skills/uipath-agents/references/lowcode/agent-definition.md

@@ -24,7 +24,7 @@ Primary configuration file for autonomous agent. Edit directly.
 
 ```json
 {
-  "version": "1.1.0",
+  "version": "1.2.0",
   "settings": {
     "model": "<MODEL_IDENTIFIER>",
     "maxTokens": 128000,
@@ -85,12 +85,13 @@ Primary configuration file for conversational agent. Edit directly.
 
 ```json
 {
-  "version": "1.1.0",
+  "version": "1.2.0",
   "settings": {
     "model": "<MODEL_IDENTIFIER>",
     "maxTokens": 64000,
     "temperature": 0,
     "engine": "conversational-v1",
+    "maxIterations": 8,
     "mode": "standard"
   },
   "inputSchema": {
@@ -142,7 +143,7 @@ Primary configuration file for conversational agent. Edit directly.
 | `maxTokens` | Max output tokens. Must not exceed the chosen model's `MaxTokens` cap (from `uip agent model list`). |
 | `temperature` | 0 = deterministic, higher = creative |
 | `engine` | Keep `"basic-v2"` for autonomous, `"conversational-v1"` for conversational |
-| `maxIterations` | Max autonomous agent loop iterations. Default 25. Keep as omitted for conversational. |
+| `maxIterations` | Max autonomous agent loop iterations. Default 25. Default 8 for conversational. |
 | `mode` | Use `"standard"` |
 
 > Prompt **quality** (system/user prompt structure, tool-call criteria, output contract) lives in [prompting/agent-prompting-guide.md](prompting/agent-prompting-guide.md). This file owns the **mechanics** (schema, `contentTokens` sync).
@@ -208,7 +209,7 @@ Runtime note: attachments cannot be supplied via `uip` CLI. Test from Studio Web
 
 | Field | Value |
 |-------|-------|
-| `version` | `"1.1.0"` — always scaffolded at this version |
+| `version` | `"1.2.0"` — always scaffolded at this version |
 | `type` | `"lowCode"` |
 | `projectId` | Auto-generated UUID — do not edit |
 
@@ -219,7 +220,7 @@ Runtime note: attachments cannot be supplied via `uip` CLI. Test from Studio Web
 | `storageVersion` | Managed by `uip agent refresh` — do not edit |
 | `isConversational` | `false` for autonomous agents, `true` for conversational agents. Do not edit. |
 | `showProjectCreationExperience` | `false` |
-| `targetRuntime` | `"pythonAgent"` for autonomous. **`null` for conversational** — conversational agents are not yet in PROD, so the field is intentionally left null until the runtime value is finalized. |
+| `targetRuntime` | `"pythonAgent"` for standalone agents, autonomous and conversational alike. **Absent for `--inline-in-flow` scaffolds** of either flavor — see [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md). |
 
 ### Input Schema
 

package/skills/uipath-maestro-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-maestro-flow
-description: "TRIGGER for `.flow` files, UiPath Flow / Maestro Flow build/edit requests, and adding or listing IXP model/document-extraction nodes for a Flow. Build, edit, run, debug, fix, evaluate a Maestro Flow (.flow): create/connect nodes (connector, approval, script, subflow, ixp, data fabric entity), triggers, schedules, validate; upload, publish, manage runs/instances; diagnose errors, incidents, traces; design eval sets, evaluators, run Studio Web evals. `uip maestro flow` CLI. DO NOT TRIGGER for raw IXP project labelling/prediction review/prompt tuning outside Flow→uipath-ixp; C#/XAML→uipath-rpa; standalone agents→uipath-agents."
+description: "TRIGGER for `.flow` files, UiPath Flow / Maestro Flow build/edit requests, and adding or listing IXP model/document-extraction nodes for a Flow. Build, edit, run, debug, fix, evaluate a Maestro Flow (.flow): create/connect nodes (connector, approval, script, subflow, ixp, data fabric entity), triggers, schedules, validate; build conversational flows (chat, chatbot, voice, phone calls); upload, publish, manage runs/instances; diagnose errors, incidents, traces; design eval sets, evaluators, run Studio Web evals. `uip maestro flow` CLI. DO NOT TRIGGER for raw IXP project labelling/prediction review/prompt tuning outside Flow→uipath-ixp; C#/XAML→uipath-rpa; standalone agents→uipath-agents."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
@@ -25,7 +25,7 @@ Guide for creating, editing, validating, debugging, publishing, diagnosing, and
 
 ## Capabilities
 
-- **Author** — Build and edit `.flow` files; add nodes, edges, variables, subflows, transforms, and triggers; explore the registry; validate and format locally; apply node ownership; configure connectors, triggers, managed HTTP, inline-agent scaffolding, IxP/document-extraction nodes, IxP models, and Data Fabric entity nodes; plan complex flows first. Read [references/author/CAPABILITY.md](references/author/CAPABILITY.md).
+- **Author** — Build and edit `.flow` files; add nodes, edges, variables, subflows, transforms, and triggers; explore the registry; validate and format locally; apply node ownership; configure connectors, triggers, managed HTTP, inline-agent scaffolding, IxP/document-extraction nodes, IxP models, and Data Fabric entity nodes; build conversational flows for text chat or voice; plan complex flows first. Read [references/author/CAPABILITY.md](references/author/CAPABILITY.md).
   - Create projects with `uip maestro flow init`.
 - **Operate** — Publish, run, and manage deployed flows; debug real systems, trigger processes, inspect jobs/traces, and pause, resume, cancel, or retry instances. Read [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md).
   - Push to Studio Web with `uip solution upload`.

package/skills/uipath-maestro-flow/references/author/CAPABILITY.md

@@ -31,6 +31,7 @@ Every node in a `.flow` file has exactly one author. The validator enforces this
 | Human-in-the-loop | `uipath.human-in-the-loop.quick-form` (inline form), `uipath.human-in-the-loop.coded-action-app` (app-based) |
 | Patterns | `uipath.pattern.batch-transform`, `uipath.pattern.deep-rag` |
 | Agents | `uipath.agent.autonomous` (inline; after `uip agent init --inline-in-flow`) |
+| Chat | `core.trigger.conversation`, `uipath.conversational.wait-for-message`, `uipath.conversational.send-message`, `uipath.conversational.get-conversation-context`, plus the agent — `uipath.agent.conversational` (inline; after `uip agent init --inline-in-flow --conversational`) or `uipath.core.agent.*` (in-solution / published) |
 | Voice | `core.trigger.voice`, `uipath.agent.voice` (inline; after `uip agent init --inline-in-flow --conversational`), `uipath.conversational.voice.create-outgoing-call`, `uipath.conversational.voice.end-call` |
 | Resource nodes | `uipath.core.rpa-workflow.*`, `uipath.core.agent.*`, `uipath.core.flow.*`, `uipath.core.agentic-process.*`, `uipath.core.api-workflow.*`, `uipath.core.human-task.*` |
 | Document extraction | `uipath.ixp.*` — the extraction step must always land a node ([ixp/impl.md](plugins/ixp/impl.md#landing-the-node-when-you-cannot-fully-configure-it)) |
@@ -105,6 +106,7 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
 | **Wire one node's output into another node's input** | [shared/node-output-wiring.md](../shared/node-output-wiring.md) |
 | **Orchestrate RPA, agents, apps** | Relevant resource plugin: [rpa](plugins/rpa/), [agent](plugins/agent/), [agentic-process](plugins/agentic-process/), [flow](plugins/flow/), [api-workflow](plugins/api-workflow/), [hitl](plugins/hitl/) |
 | **Embed an AI agent tightly coupled to this flow** | [plugins/inline-agent/](plugins/inline-agent/) |
+| **Build a chat agent flow (model a text-based chat experience)** | [plugins/conversational-agent/](plugins/conversational-agent/) — the conversation trigger and message nodes, plus inline, in-solution, or published chat agent(s) |
 | **Build a voice agent flow (answer or place phone calls)** | [plugins/inline-voice-agent/](plugins/inline-voice-agent/) — `uipath.agent.voice` plus the nodes that start, place, and end the call |
 | **Extract structured fields from documents** | [plugins/ixp/](plugins/ixp/) — IxP extraction models for PDFs, scanned forms, receipts, invoices, contracts |
 | **List IxP models / runtime projects available in flow** | [plugins/ixp/impl.md — Listing Published Models](plugins/ixp/impl.md#listing-published-models) — read-only registry search, no `.flow` scaffold or edits |
@@ -179,6 +181,7 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
   - [hitl](plugins/hitl/) — human input via UiPath Apps
   - [agent](plugins/agent/) — published AI agent resources
   - [inline-agent](plugins/inline-agent/) — autonomous agent embedded in flow
+  - [conversational-agent](plugins/conversational-agent/) — model a text-based chat experience: conversation trigger, message nodes, and an inline, in-solution, or published chat agent
   - [inline-voice-agent](plugins/inline-voice-agent/) — voice agent on a live phone call (inbound/outbound) + the trigger, create-call, and end-call nodes
   - [ixp](plugins/ixp/) — published IxP document-extraction models (PDFs, scanned forms, receipts, invoices, contracts)
   - [queue](plugins/queue/) — Orchestrator queue item creation

package/skills/uipath-maestro-flow/references/author/brownfield.md

@@ -44,6 +44,7 @@ For edits touching multiple top-level arrays, follow [parallel same-file Edit ru
 | **Add a connector trigger** | Remove the manual trigger; add and configure the connector trigger with a connection. Use [CLI: Replace trigger](editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) and [connector-trigger/impl.md](plugins/connector-trigger/impl.md). |
 | **Add a resource node** | Discover through the registry (`--local` for in-solution, or tenant registry for published); add with `Edit`; wire edges. Use the relevant plugin's `impl.md` and [editing-operations-json.md](editing-operations-json.md). |
 | **Add an inline agent node** | Embed `uipath.agent.autonomous` with an inline agent definition in the flow project. See [inline-agent/planning.md](plugins/inline-agent/planning.md) for inline versus published selection and [inline-agent/impl.md](plugins/inline-agent/impl.md) for scaffolding, JSON, and validation. |
+| **Add chat nodes** | Turn a flow into a text-based conversation: a chat experience looping with wait-for-message, started by `core.trigger.conversation` — the trigger is what marks the package conversational. See [conversational-agent/planning.md](plugins/conversational-agent/planning.md) for the rules and when chat beats voice, and [conversational-agent/impl.md](plugins/conversational-agent/impl.md) for node JSON and the `conversationalAgentSettings` wiring. |
 | **Add voice nodes** | Turn a flow into a phone conversation: a `uipath.agent.voice` inline conversational agent wired to a live call, plus the trigger, create-call, and end-call nodes. Binding an inbound number happens at deploy time, not in the `.flow`. See [inline-voice-agent/planning.md](plugins/inline-voice-agent/planning.md) for the two topologies and trunk requirements, and [inline-voice-agent/impl.md](plugins/inline-voice-agent/impl.md) for node JSON, `callContext` wiring, and number binding. |
 | **Add a HITL QuickForm node** | Insert the human approval/review/enrichment checkpoint and wire its `completed` port. See [Edit/Write: Add a node](editing-operations-json.md) and [hitl/impl.md](plugins/hitl/impl.md). |
 

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

@@ -92,6 +92,7 @@ Read the relevant plugin `planning.md` when selecting a type.
 | `core.trigger.manual` | inline | On-demand user or API start |
 | `core.trigger.scheduled` | [scheduled-trigger](plugins/scheduled-trigger/planning.md) | Recurring schedule |
 | IS connector trigger | [connector-trigger](plugins/connector-trigger/planning.md) | External event; type `uipath.connector.trigger.<key>.<trigger>` |
+| `core.trigger.conversation` | [conversational-agent](plugins/conversational-agent/planning.md) | Flow starts when a chat conversation is created, and emits its `conversationId` |
 | `core.trigger.voice` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | Flow starts when a phone call arrives on a bound number (inbound voice topology) |
 
 Every flow has exactly one trigger, first in topology. IS connector triggers replace manual or scheduled triggers. `core.trigger.manual` has no inputs and output port `output`.
@@ -114,6 +115,9 @@ Every flow has exactly one trigger, first in topology. IS connector triggers rep
 | `core.datafabric.update` | [data-fabric](plugins/data-fabric/planning.md) | Patch named columns on one record; gated by `canvas.nodes.update-entity` |
 | `core.datafabric.delete` | [data-fabric](plugins/data-fabric/planning.md) | Delete one record; gated by `canvas.nodes.delete-entity` |
 | `uipath.human-in-the-loop.quick-form` | [hitl](plugins/hitl/planning.md) | Inline human review, approval, or data entry |
+| `uipath.conversational.wait-for-message` | [conversational-agent](plugins/conversational-agent/planning.md) | Pause until the user sends a chat message (initiates an exchange); returns the conversation context |
+| `uipath.conversational.send-message` | [conversational-agent](plugins/conversational-agent/planning.md) | Write a message the flow composes itself into the chat |
+| `uipath.conversational.get-conversation-context` | [conversational-agent](plugins/conversational-agent/planning.md) | Read latest conversation context without waiting for a new user message |
 | `uipath.conversational.voice.create-outgoing-call` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | Dial an outbound phone call and emit its `callContext` (outbound voice topology) |
 | `uipath.conversational.voice.end-call` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | End the active call in a voice flow |
 
@@ -139,6 +143,7 @@ Connector nodes are Integration Service nodes, not built-in. They appear after `
 | --- | --- | --- |
 | `uipath.agent.autonomous` | [inline-agent](plugins/inline-agent/planning.md) | Low-code agent scaffolded inside this flow via `uip agent init --inline-in-flow`, tightly coupled, not independently reused |
 | `uipath.core.agent.{key}` | [agent](plugins/agent/planning.md) | Separate in-solution or published agent, reusable and independently versioned |
+| `uipath.agent.conversational` | [conversational-agent](plugins/conversational-agent/planning.md) | AI agent that runs a single response turn given a chat-history, streaming its messages and tool-calls to the conversation. In-solution and published chat agents use `uipath.core.agent.{key}` above |
 | `uipath.agent.voice` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | AI agent that converses in real time on a live phone call — an inline conversational agent (`settings.voice` in its `agent.json`) wired to a `callContext` |
 
 See [inline-agent/planning.md — Inline vs Published Agent Decision Table](plugins/inline-agent/planning.md#inline-vs-published-agent-decision-table).
@@ -180,6 +185,7 @@ Every edge requires `sourcePort` and `targetPort`.
 | `core.trigger.manual` | — | `output` |
 | `core.trigger.scheduled` | — | `output` |
 | `uipath.connector.trigger.*` | — | `output` |
+| `core.trigger.conversation` | — | `output` |
 | `core.trigger.voice` | — | `output` |
 | `uipath.connector.event.*` | `input` | `output`, `error` |
 | `core.action.script` | `input` | `success`, `error` |
@@ -197,7 +203,11 @@ Every edge requires `sourcePort` and `targetPort`.
 | `core.subflow` | `input` | `output`, `error` |
 | `core.logic.mock` | `input` | `output` |
 | `uipath.agent.autonomous` | `input` | `success`, `error`, `tool`, `context`, `escalation` |
+| `uipath.agent.conversational` | `input` | `success`, `escalation`, `context`, `tool` |
 | `uipath.agent.voice` | `input` | `success`, `error`, `tool`, `context`, `escalation` |
+| `uipath.conversational.wait-for-message` | `input` | `output` |
+| `uipath.conversational.send-message` | `input` | `output` |
+| `uipath.conversational.get-conversation-context` | `input` | `output` |
 | `uipath.conversational.voice.create-outgoing-call` | `input` | `success`, `error` |
 | `uipath.conversational.voice.end-call` | `input` | `success`, `error` |
 | `uipath.core.agent.*` | `input` | `output`, `error` |
@@ -323,6 +333,7 @@ Before presenting the plan, validate every rule:
 - **Wait:** duration or date -> [delay](plugins/delay/planning.md); external robot result -> [queue](plugins/queue/planning.md) `create-and-wait`.
 - **Human:** approval or data entry -> [hitl](plugins/hitl/planning.md), or `core.logic.mock` if unavailable.
 - **Agent:** tightly coupled low-code agent inside flow -> [inline-agent](plugins/inline-agent/planning.md), `uipath.agent.autonomous`; coded or separate in-solution/published agent -> [agent](plugins/agent/planning.md), `uipath.core.agent.{key}`.
+- **Chat:** text-based conversation the flow holds turn by turn -> [conversational-agent](plugins/conversational-agent/planning.md), `core.trigger.conversation` plus `uipath.conversational.wait-for-message` with responding chat agent(s) and `send-message` node(s); agent inside this flow -> `uipath.agent.conversational`; sibling or published agent -> [agent](plugins/agent/planning.md), `uipath.core.agent.{key}` with `isConversational`; single approval or data-entry without a full conversation -> [hitl](plugins/hitl/planning.md).
 - **LLM over CSV/document:** CSV row columns -> [batch-transform](plugins/batch-transform/planning.md), `uipath.pattern.batch-transform`; one-document synthesis/Q&A/citations -> [summarize](plugins/summarize/planning.md), `uipath.pattern.deep-rag`; multi-step tool reasoning -> inline or published agent; ordinary reshaping -> transform.
 - **Document extraction:** variable-layout PDF, scan, photo, or attachment -> [ixp](plugins/ixp/planning.md), `uipath.ixp.{modelName}.{fullyQualifiedName}`; structured source -> script or transform; free-form reasoning -> agent; untrained IxP model -> `core.logic.mock` plus Open Question.
 - **Missing capability:** use `core.logic.mock`; identify the needed artifact and owning skill (`uipath-rpa` for desktop/browser or coded C# workflows, `uipath-agents` for agents). Phase 2 replaces the mock if published.

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

@@ -46,6 +46,11 @@ Use these plugin mappings:
 | `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) |

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

@@ -189,6 +189,16 @@ Connect trigger → agent → end:
 
 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

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

@@ -43,6 +43,20 @@ Use workflow nodes for the deterministic parts (fetch data, transform, route) an
 - **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) |

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

@@ -0,0 +1,291 @@
+# Chat (Text-based Conversation) Nodes — Implementation
+
+Wire whatever shape the conversation needs, inside the rules in [planning.md](planning.md#critical-rules-any-conversational-flow-must-follow).
+
+For a phone conversation, use [inline-voice-agent/impl.md](../inline-voice-agent/impl.md) instead.
+
+Everything here is the same for all three agent flavors except the agent node itself and its port. Settle the flavor first — [planning.md](planning.md#pick-the-agent-flavor-before-you-build).
+
+## Resolve the Agent
+
+**Inline** — scaffold it, from the solution root:
+
+```bash
+uip agent init "<FlowProjectName>" --inline-in-flow --conversational
+```
+
+Writes `<FlowProject>/<uuid>/agent.json` plus `flow-layout.json`, and returns `Data.ProjectId`. **Keep that UUID** — it is what the agent node's `inputs.source` must carry.
+
+**In-solution** — the agent is a sibling project; nothing to scaffold in the flow. Find its node type:
+
+```bash
+uip maestro flow registry list --local --output json
+```
+
+**Published** — already on the tenant:
+
+```bash
+uip maestro flow registry search "<agent name>" --output json
+```
+
+Both of the latter give a `uipath.core.agent.*` node type — suffixed with the solution resource key in-solution, the Orchestrator-assigned UUID when published. `registry get` on it returns `inputDefaults` holding `isConversational: true` and `conversationalAgentSettings`, which is how you confirm the agent really is a chat agent rather than an autonomous one. Discovery details live in [agent/impl.md](../agent/impl.md#discovery-and-registry-validation).
+
+**If an in-solution agent comes back autonomous**, the registry could not read its `agent.json` — it builds that node from the sibling project's file, and falls back to autonomous when the file is missing or malformed. Re-run with `--log-level debug` and it names the reason:
+
+```
+[DEBUG] Unparseable agent.json in <projectDir>: … The node will describe an autonomous agent.
+[DEBUG] No readable agent.json in <projectDir>; the node will describe an autonomous agent.
+```
+
+Nothing else reports it, and the authored node would run as autonomous with no error at any step. Published agents are unaffected — their flag comes from the release, not a local file.
+
+## Configure `agent.json`
+
+Edit the scaffolded file, then regenerate its derived fields:
+
+```bash
+uip agent refresh "<FlowProject>/<uuid>" --inline-in-flow
+uip agent validate "<FlowProject>/<uuid>" --inline-in-flow
+```
+
+`refresh` rebuilds `contentTokens[]` from `messages[].content`. **Skip it and `agent validate` fails** with `contentTokens has 0 entries but content requires 1` — the error does not name `agent refresh`, so it is easy to get stuck on.
+
+Run `refresh` after any `agent.json` edit — for an in-solution agent too, without the flag: `uip agent refresh "<AgentProject>"`. A published agent has no local file, so there is nothing to refresh.
+
+Settings that matter for a conversational agent:
+
+| Key | Value | Why |
+| --- | --- | --- |
+| `settings.engine` | `conversational-v1` | What makes it a chat agent rather than autonomous |
+| `metadata.isConversational` | `true` | Read by the registry to pick the icon and keep the agent out of the agent-as-tool picker |
+| `settings.maxIterations` | `8` | keep what the scaffold wrote |
+
+`uip agent init --conversational` writes all three. Do not remove them.
+
+## Registry Validation
+
+`flow validate` has **no registry fallback** — a hand-authored node must carry its manifest in the file's `definitions[]`. Fetch one per node type in the flow:
+
+```bash
+uip maestro flow registry get core.trigger.conversation --output json
+uip maestro flow registry get uipath.conversational.wait-for-message --output json
+uip maestro flow registry get uipath.agent.conversational --output json
+```
+
+Append each `Data.Node` verbatim to the `.flow`'s `definitions[]`, and set the node's `typeVersion` to exactly the `version` the command returned. Miss one and validate reports `Node type "<type>:<version>" has no matching definition`.
+
+The conversational agent node requires a login; the trigger and the tool nodes resolve from the bundled catalog.
+
+## The `conversationalAgentSettings` Wiring Rule
+
+This is the one that goes wrong silently. The agent reads the conversation through `inputs.conversationalAgentSettings`, which holds **five** keys — a `context` binding plus four fields derived from it:
+
+```json
+"conversationalAgentSettings": {
+  "mode": "simple",
+  "context":        { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext",                  "fieldType": "object" },
+  "conversationId": { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext.conversationId",   "fieldType": "string" },
+  "exchangeId":     { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext.latestExchangeId", "fieldType": "string" },
+  "messages":       { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext.messages",         "fieldType": "array"  },
+  "userSettings":   { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext.userSettings",     "fieldType": "object" }
+}
+```
+
+**`mode` and `context` exist only to restore the editor UI.** The four individual fields are what the runtime reads, in either mode, and validation requires `conversationId` regardless. `custom` is for a turn assembled from more than one source. `mode` is optional; the examples here all declare `simple`.
+
+**Write all five.** In Studio Web the author fills `context` and the panel derives the other four, but that derivation only runs in the editor — nothing derives them when the file is authored from the CLI.
+
+Validation only requires `conversationId`, so it half-helps: leave that out and validate fails, but bind `context` and `conversationId` while dropping `exchangeId`, `messages` and `userSettings` and validate passes. The runtime reads all four, so that flow ships an agent with no chat history and no user settings.
+
+Note the field is `latestExchangeId` inside `conversationContext`, not `exchangeId`.
+
+## Bindings Are Objects, Not `=js:` Strings
+
+Every expression binding in a `.flow` is the object form above. A bare `"=js:$vars.…"` string is a pre-1.3 file format that current files no longer use — Studio Web renders it as literal text rather than a binding, and nothing warns.
+
+This matters when using `node add`, which writes `--input` JSON through untouched:
+
+```bash
+# WRONG — lands in the file verbatim, renders as text
+uip maestro flow node add ChatFlow/ChatFlow.flow uipath.conversational.wait-for-message \
+  --input '{"conversationId":"=js:$vars.conversationTrigger1.output.conversationId"}'
+
+# RIGHT
+uip maestro flow node add ChatFlow/ChatFlow.flow uipath.conversational.wait-for-message \
+  --input '{"conversationId":{"type":"jsExpression","expression":"$vars.conversationTrigger1.output.conversationId","fieldType":"string"}}'
+```
+
+(`uip maestro flow node configure --detail` uses the `=js:` form for **connector** nodes — that is a different surface and does not apply here.)
+
+## Node JSON
+
+> **Which surface authors this node.** [inline-agent/impl.md § What NOT to Do](../inline-agent/impl.md#what-not-to-do) bars Flow CLI `node add` / `edge add` for inline **autonomous** agent graph edits. That rule does not cover `uipath.agent.conversational`: the CLI path below is the supported one for this node, `--source` is a documented `node add` flag for it, and the full recipe validates clean. Use `Edit` / `Write` when you prefer, but do not read the inline-agent prohibition as applying here.
+
+Editing the `.flow` directly carries the usual obligations — chiefly a `variables.nodes[]` entry for every data-producing node, which is what makes `$vars.<id>.output` resolve at all. See [editing-operations-json.md](../../editing-operations-json.md). `node add` writes those entries for you.
+
+### Conversation trigger
+
+Replace the default manual trigger — `flow init` scaffolds `core.trigger.manual`, and the conversation trigger is what makes the packaged flow conversational and exposed as a chat experience. Same two-step shape as [editing-operations-cli.md § Replace manual trigger with connector trigger](../../editing-operations-cli.md#replace-manual-trigger-with-connector-trigger), with the conversation trigger in place of a connector one.
+
+```bash
+uip maestro flow node remove ChatFlow/ChatFlow.flow start
+uip maestro flow node add ChatFlow/ChatFlow.flow core.trigger.conversation --position 256,144
+```
+
+### Wait for message
+
+```json
+{
+  "id": "waitForMessage1",
+  "type": "uipath.conversational.wait-for-message",
+  "inputs": {
+    "conversationId": { "type": "jsExpression", "expression": "$vars.conversationTrigger1.output.conversationId", "fieldType": "string" },
+    "from": "User"
+  }
+}
+```
+
+### The agent — inline
+
+`inputs.source` is the scaffolded UUID; `conversationalAgentSettings` is the five-key block above.
+
+```bash
+uip maestro flow node add ChatFlow/ChatFlow.flow uipath.agent.conversational \
+  --position 768,144 --source <ProjectId> --input '<the settings JSON>'
+```
+
+### The agent — in-solution or published
+
+Same settings block, different node type, and `isConversational` alongside it instead of `source`. The suffix is the solution resource key in-solution and the Orchestrator-assigned UUID when published, so read the exact `nodeType` off `registry get` either way:
+
+```json
+{
+  "id": "supportAgent1",
+  "type": "uipath.core.agent.<suffix from registry get>",
+  "typeVersion": "<version from registry get>",
+  "inputs": {
+    "isConversational": true,
+    "conversationalAgentSettings": { "...": "the five-key block above" }
+  }
+}
+```
+
+An in-solution agent needs its `definitions[]` entry fetched with `--local`; a published one comes from the pulled tenant registry.
+
+### Send message (for flow-composed messages)
+
+`conversationId`, `exchangeId`, `content`, `role` and `mimeType` are all required. `role` and `mimeType` each accept exactly one value, so write them as shown. `content` is normally a literal — the agent's own replies are streamed, not routed through this node.
+
+```json
+{
+  "id": "sendMessage1",
+  "type": "uipath.conversational.send-message",
+  "inputs": {
+    "conversationId": { "type": "jsExpression", "expression": "$vars.conversationTrigger1.output.conversationId", "fieldType": "string" },
+    "exchangeId":     { "type": "jsExpression", "expression": "$vars.waitForMessage1.output.conversationContext.latestExchangeId", "fieldType": "string" },
+    "content":        { "type": "literal", "expression": "Anything else I can help with?", "fieldType": "string" },
+    "role": "assistant",
+    "mimeType": "text/markdown"
+  }
+}
+```
+
+### Get conversation context
+
+Reads recent exchanges without waiting. Rarely needed, and constrained — see [planning.md § Get Conversation Context](planning.md#get-conversation-context).
+```json
+{
+  "id": "getConversationContext1",
+  "type": "uipath.conversational.get-conversation-context",
+  "inputs": {
+    "conversationId": { "type": "jsExpression", "expression": "$vars.conversationTrigger1.output.conversationId", "fieldType": "string" },
+    "exchangeLimit": 20
+  }
+}
+```
+
+## Structured Outputs
+
+In addition to responding to the chat, an **inline** conversational agent can also return named fields for a downstream node to route on. Published and in-solution agents cannot.
+
+Declare each field in two places or it yields nothing at run time:
+
+| Where | What |
+| --- | --- |
+| the node, in the `.flow` | `inputs.agentOutputVariables: [{ "id": "shouldHandoff", "type": "boolean", "description": "..." }]` |
+| the inline `agent.json` | the same field under `outputSchema.properties` |
+
+Bind it downstream as `$vars.<agentNodeId>.output.shouldHandoff`. Writing one side without the other passes `agent validate` and `flow validate` — nothing checks the pair.
+
+## Wire the Edges
+
+An **inline** agent leaves on `success`; an in-solution or published one leaves on `output`. The smallest loop:
+
+```bash
+uip maestro flow edge add ChatFlow/ChatFlow.flow conversationTrigger1 waitForMessage1
+uip maestro flow edge add ChatFlow/ChatFlow.flow waitForMessage1 conversationalAgent1
+uip maestro flow edge add ChatFlow/ChatFlow.flow conversationalAgent1 waitForMessage1 --source-port success
+```
+
+Omit `--source-port success` and the command fails with `Source port "output" not found on node "conversationalAgent1". Available source ports: escalation, context, tool, success`.
+
+## Validate
+
+```bash
+uip maestro flow validate ChatFlow/ChatFlow.flow
+```
+
+Unbound identifiers each report their own error, naming the node and field:
+
+```
+[nodes[waitForMessage1].inputs.conversationId]   [SCHEMA_ERROR] Conversation ID is required
+[nodes[sendMessage1].inputs.exchangeId]          [SCHEMA_ERROR] Exchange ID is required
+[nodes[sendMessage1].inputs.content]             [SCHEMA_ERROR] Content is required
+[nodes[conversationalAgent1].inputs.conversationalAgentSettings.conversationId]
+                                                 [CONVERSATIONAL_CONVERSATION_ID_REQUIRED] Conversation ID is required
+```
+
+A clean validate does **not** mean the bindings are right — see [planning.md § Output Variables](planning.md#output-variables).
+
+## Pack and Ship
+
+```bash
+uip maestro flow pack ChatFlow ./dist --version 1.0.0
+```
+
+Confirm the marker in the packaged `content/operate.json`:
+
+```json
+"runtimeOptions": { "isConversational": true }
+```
+
+The marker is the contract with the runtime chat channels: a headless SDK lists any deployed process carrying it, and every OOTB integration on that SDK (e.g. web-chat, iframe embedding, UiPath Assistant, Microsoft Teams, Slack) plus custom UIs pick it up automatically.
+
+Absent means the flow does not start on `core.trigger.conversation`, and it will not be listed as a Conversational Agent in the channels.
+
+## Debug — the CLI Hands Off
+
+A chat cannot be driven headlessly, so `flow debug` uploads the solution and stops:
+
+```bash
+uip maestro flow debug ChatFlow --open-in-browser
+```
+
+Returns `Code: FlowDebugStudioWebHandoff` with `Data.studioWebUrl` and `Data.handedOff: true`, and no debug session is started. `--timeout` has no effect on this path.
+
+Two chat UIs can drive the run — the CLI names both:
+
+- **Studio Web** — open `Data.studioWebUrl` (`--open-in-browser` does it for you) and chat from its panel
+- **UiPath Maestro VS Code extension** — open the flow and hit Debug
+
+If the solution's `.uipx` already carries a `SolutionId`, the upload overwrites that solution rather than creating a second one.
+
+## What NOT to Do
+
+- **Do not stop at `context` and `conversationId`** — see [§ The `conversationalAgentSettings` Wiring Rule](#the-conversationalagentsettings-wiring-rule).
+- **Do not invent output paths.** `waitForMessage1.output.exchangeId` and `conversationalAgent1.output.response` do not exist, and validate accepts both.
+- **Do not use `=js:` strings** for bindings in a `.flow`.
+- **Do not carry one flavor's agent port across.** Inline continues on `success`, in-solution and published on `output`.
+- **Do not add a send-message just to deliver the conversational agent's reply.** The conversational agent already streams it.
+- **Do not expect `flow debug` to run the conversation.** It hands off to Studio Web or the VS Code extension.
+- **Do not leave the manual trigger in place.** Without `core.trigger.conversation` the package is not marked conversational, and nothing errors.

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

@@ -0,0 +1,133 @@
+# Chat (Text-based Conversation) Nodes — Planning
+
+Build a conversational flow whose job is to model a **text-based chat**: a user types, the Flow responds through AI or deterministic answers, and waits for the next message or eventually terminates. For a chat that happens over a **phone call**, use [inline-voice-agent](../inline-voice-agent/planning.md) instead — same idea, different medium, different node types.
+
+The flow is **surface-agnostic**; one conversational flow is consumed from many channels. Once deployed, the common UiPath TypeScript SDK can list every conversational flow on the tenant, and every OOTB integration built on that SDK — e.g. web-chat, iframe embedding, UiPath Assistant, Microsoft Teams, Slack — plus any customer's custom UI is able to converse with the chat experience. Author for the conversation, not for a channel.
+
+## Node Types
+
+| Node type | Role |
+| --- | --- |
+| `core.trigger.conversation` | Starts the flow when a conversation is created. Emits the `conversationId` every other node is addressed by. |
+| `uipath.conversational.wait-for-message` | Pauses until the user sends a message (initiates an exchange). Returns the conversation context (which includes the recent exchanges in the chat history), intended for input into a conversational agent node. |
+| conversational agent node | Requires the user to initiate an exchange first. Given the conversation context, runs a single response turn, streaming its messages and tool-calls back to the chat. Which node type depends on where the agent lives — see below. |
+| `uipath.conversational.send-message` | Requires the user to initiate an exchange first. Sends a flow-composed message (e.g. a handoff notice, results/updates from other nodes) back to the chat. |
+| `uipath.conversational.get-conversation-context` | Immediately reads the conversation context without waiting for a user message. Rarely needed, and constrained — see [§ Get Conversation Context](#get-conversation-context). |
+
+### Pick the agent flavor before you build
+
+The trigger and message nodes are identical whichever you pick. Only the agent node changes — and **ask the user rather than defaulting**, because the answer decides the node type, the ports, and whether you scaffold anything at all:
+
+| Flavor | Node type | Where the agent lives | Choose it when |
+| --- | --- | --- | --- |
+| **Inline** | `uipath.agent.conversational` | A UUID subdirectory inside this flow project | The agent exists only as part of this conversational flow, or you need [structured outputs](impl.md#structured-outputs) to route on — only inline has them. You scaffold it with `agent init --inline-in-flow --conversational`. |
+| **In-solution** | `uipath.core.agent.{key}` | A sibling project in the same solution | The agent is its own project, versioned separately, maybe reused by other flows in the solution. Discover it with `registry list --local`. |
+| **Published** | `uipath.core.agent.<agentUuid>` | The tenant, already published | The user names an existing agent, or one is already deployed. Discover it with `registry search`. Nothing to scaffold. |
+
+`{key}` is the in-solution agent's solution resource key, the `key` in `resources/solution_folder/process/agent/<Project>.json`, and **not** `agent.json`'s `projectId`. A published agent's suffix is the Orchestrator-assigned UUID instead. Read either off `registry get`.
+
+**If the user names an existing agent, it is not inline.** Run `uip maestro flow registry search "<name>" --output json` (and `registry list --local` for solution siblings) before scaffolding anything — the same rule the [agent](../agent/planning.md) plugin states for autonomous agents.
+
+In-solution and published share one node type and one set of ports; inline differs on both (see [Ports](#ports)).
+
+Read each node's current inputs and version from the registry rather than assuming — these move between releases:
+
+```bash
+uip maestro flow registry get uipath.conversational.wait-for-message
+```
+
+## When to Use
+
+Use these nodes when the flow **is** the conversation: a support chat, an intake questionnaire, a triage bot. The flow's shape generally loops with wait-for-message, but can also have termination - once the flow ends, the conversation gracefully completes, with a UI change to the user that the conversation has completed.
+
+### Chat vs Voice vs Autonomous
+
+| Situation | Text-based conversation (`uipath.agent.conversational`) | Voice ([`uipath.agent.voice`](../inline-voice-agent/planning.md)) | Inline autonomous ([`uipath.agent.autonomous`](../inline-agent/planning.md)) |
+| --- | --- | --- | --- |
+| The user types and reads replies | Yes | No | No |
+| The user is on a phone call | No | Yes | No |
+| A reasoning step over flow data, nobody talking | No | No | Yes |
+| Reply reaches the user | Streamed by the agent | Spoken on the call | Only through send-message node with the agent's result (high latency) |
+
+### When NOT to Use
+- **The conversation is a phone call** — [inline-voice-agent](../inline-voice-agent/planning.md).
+- **A single pause for a human to review, approve, or fill in data** — See [hitl](../hitl/planning.md) for a form.
+
+## Critical Rules Any Conversational Flow Must Follow
+Combine the nodes, along with flow's other nodes and routing capabilities, to model conversational paths as needed. The **following rules hold for whatever shape you build:**
+
+- **Start with `core.trigger.conversation`.** The trigger alone sets `runtimeOptions.isConversational` in the packed `operate.json`, marking it as a chattable process.
+- **Immediately follow the conversation trigger with a wait-for-message node.** This is so the Flow can immediately handle user's first chat message.
+  - Related: the flow **cannot send a message "first"** and can only reply. The user must initiate an exchange before conversational agent and send-message nodes can respond, as those nodes require an exchange ID to reply to; this exchange ID is included in the conversation context outputted from a wait-for-message node.
+  - Every key in `conversationalAgentSettings` derives from a wait-for-message node's `conversationContext` — see [impl.md](impl.md#the-conversationalagentsettings-wiring-rule).
+- **Reach a wait node again to keep the conversation alive.** The flow's response to the latest exchange ends when either (1) arriving back at a wait-for-message node or (2) when the flow ends. Until either occurs, the user is not expected to send a message (chat UI blocks input, since it is the flow's turn in the exchange). When the flow ends, the chat UI will indicate to the user that the conversation has gracefully completed.
+- **The conversational agent node streams its own reply.** No send-message is needed for the agent to answer, since its message and tool-calls are streamed automatically to the chat and appended to the conversation history.
+- **Leave the conversational agent on the port its flavor exposes** — `success` for inline, `output` for in-solution and published. See [Ports](#ports).
+
+A simple flow that satisfies all the rules:
+
+```
+core.trigger.conversation → wait-for-message → conversational agent ──┐
+                                   ▲                                   │
+                                   └───────────────────────────────────┘
+```
+
+That is a starting point, not the only supported shape. Add whatever the conversational flow needs: additional agent and send-message nodes, a decision on the agent's outputs, handoffs, parallel branches to execute behind-the-scenes tasks, an escalation to [hitl](../hitl/planning.md), a connector or RPA call between turns, or no loop back at all when the conversation should end.
+
+### Get Conversation Context
+
+`get-conversation-context` is legal but usually redundant — wait-for-message already returns the context. It may be useful for cases when conversational agent and send-message nodes are chained together (to re-obtain the chat-history between them) or when needing the most up-to-date conversation-history without requiring the user to send a message. Note that you **cannot** immediately use `get-conversation-context` after the `core.trigger.conversation` and use the outputted conversation context as input for conversational agents and send-message nodes, since there is not yet an initiated exchange (see above critical rules).
+
+## Ports
+
+| Node type | Target | Source |
+| --- | --- | --- |
+| `core.trigger.conversation` | — | `output` |
+| `uipath.conversational.wait-for-message` | `input` | `output` |
+| `uipath.agent.conversational` (inline) | `input` | `success`, `escalation`, `context`, `tool` |
+| `uipath.core.agent.{key}` (in-solution) | `input` | `output` |
+| `uipath.core.agent.<agentUuid>` (published) | `input` | `output`, `error` |
+| `uipath.conversational.send-message` | `input` | `output` |
+| `uipath.conversational.get-conversation-context` | `input` | `output` |
+
+Only the inline agent breaks the pattern: `success`, and no `output` port. In-solution and published have `output` and no `success`. Both mistakes are caught — `edge add` lists the real ports, validate reports `Edge references undeclared source handle`. Note `output` is also a variable namespace (`$vars.<id>.output.…`) on every node, which is why the inline agent has one without having the port.
+
+## Output Variables
+
+| Node | Output |
+| --- | --- |
+| `core.trigger.conversation` | `output.conversationId` |
+| `uipath.conversational.wait-for-message` | `output.conversationContext` — an object holding `conversationId`, `latestExchangeId`, `messages`, `userSettings` |
+| `uipath.agent.conversational` | `output.uipath__agent_response_messages` — this turn's messages (role, contentParts, toolCalls). The reply is streamed, so there is no `output.response`. |
+
+There is **no `output.exchangeId`** on wait-for-message and **no `output.response`** on the agent. Binding either produces `undefined` at runtime, and `flow validate` does not catch it — invented `$vars` paths pass validation today, so read the real field names off `registry get` rather than trusting a clean validate.
+
+## Scaffolding Prerequisite
+
+The inline agent node points at an agent project directory that must exist first:
+
+```bash
+uip agent init "<FlowProjectName>" --inline-in-flow --conversational
+```
+
+The returned `ProjectId` is the UUID the node's `inputs.source` must carry. See [impl.md](impl.md) for the scaffold contents and the `agent.json` settings that matter.
+
+## Resources — tools, context, escalation
+
+The `tool`, `context` and `escalation` source ports behave exactly as they do on the inline autonomous node: discover the resource node type through the registry, add the node with `Edit`, wire the artifact edge from the agent's port, and author the matching `resource.json`. Do not re-derive that flow — [inline-agent/impl.md § Adding Resource Nodes](../inline-agent/impl.md#adding-resource-nodes) owns discovery, the one UUID that serves as both `inputs.source` and the sidecar directory, and the `refresh --bindings-target` step that propagates tool bindings into the parent flow.
+
+Three things differ from the autonomous node:
+
+- **There is no `memory` port.** The autonomous node has one; `uipath.agent.conversational` does not. An edge to it fails the same way any bad port does — `edge add` will not list it, and validate reports `Edge references undeclared source handle`.
+- **Guardrails ride as a top-level `guardrails` array in the inline agent's `agent.json`**, which `uip agent init --inline-in-flow --conversational` scaffolds for you. Which guardrails apply is flavor-specific — Studio Web's properties panel filters the catalog by conversational vs autonomous — so do not assume a guardrail available on an autonomous agent is offered here.
+- **Do not add `guardrails` to `inputSchema.properties`.** That requirement is autonomous-only, where it sits alongside the process arguments. A conversational agent's `inputSchema` stays `{"type": "object", "properties": {}}`; populating it breaks the shape the `uipath-agents` scaffold test asserts.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- `chat-agent: <description>` — one line per agent; omit for a scripted chat. Inline: Reuse the [inline-agent](../inline-agent/planning.md) annotations. In-solution or published: `<agent-name> in <folder-path>`.
+- `chat-agent-flavor: <agent-name> = inline | in-solution | published` — one per agent above; decides the node type (`uipath.agent.conversational` for inline, `uipath.core.agent.*` for the others — see the [flavor table](#pick-the-agent-flavor-before-you-build) for which suffix each takes) and on which port (`success` for inline, `output` for the others)
+- `chat-send-message: <purpose>` — one line per flow-authored message (loading messages, handoff notice, node output results); a scripted chat consists mostly of these
+- `chat-structured-output: <agent-name> = <fieldName>` — only when the flow branches on that conversational agent's reply; forces that conversational agent to inline flavor because in-solution and published conversational agents have no structured outputs
+- Tools, contexts, and escalations on any inline chat agent reuse the [inline-agent](../inline-agent/planning.md) annotations

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

@@ -518,7 +518,7 @@ Current CLIs report the same fault as `[SCHEMA_ERROR] System prompt is required`
 
 ## What NOT to Do
 
-- **Do not use Flow CLI `node add`, `edge add`, or `variable` commands for inline-agent graph edits** — inline-agent node, edge, variable, layout, and tool-resource node changes are non-carve-out structural `.flow` mutations and must be authored directly with `Edit` / `Write`.
+- **Do not use Flow CLI `node add`, `edge add`, or `variable` commands for inline-agent graph edits** — inline-agent node, edge, variable, layout, and tool-resource node changes are non-carve-out structural `.flow` mutations and must be authored directly with `Edit` / `Write`. This rule scopes to `uipath.agent.autonomous`. It does **not** cover the inline conversational agent (`uipath.agent.conversational`), whose documented recipe authors the node and its edges with `node add` / `edge add` — see [conversational-agent/impl.md § Node JSON](../conversational-agent/impl.md#node-json).
 - **Do not write `inputs.systemPrompt` / `inputs.userPrompt` on the inline-agent node** — full rule in § Wiring Flow Variables into Agent Prompts § Anti-patterns. Prompts live in `agent.json`.
 - **Do not put a `model` block on the inline-agent node instance** — the node inherits serviceType/version/context from `definitions[]`; the inline-agent source lives at `inputs.source`.
 - **Do not use `model.agentProjectId`, `inputs.agentProjectId`, or `model.source` on any inline-agent-related node instance** — both `uipath.agent.autonomous` and every attached resource node (`uipath.agent.resource.tool.*`, `uipath.agent.resource.escalation`, `uipath.agent.resource.context.*`) carry source identity at `inputs.source` and have no instance `model` block.

package/skills/uipath-maestro-flow/references/diagnose/CAPABILITY.md

@@ -35,6 +35,8 @@ Capability index for postmortem on a failed `flow debug` or deployed process run
 | Need | Read |
 | --- | --- |
 | Triage a failed flow run | [troubleshooting-guide.md](troubleshooting-guide.md) |
+| An in-solution chat agent shows as autonomous | The registry builds that node from the sibling project's `agent.json` and falls back to autonomous when it cannot read it. `--log-level debug` names the reason ("Unparseable agent.json" / "No readable agent.json"); nothing else reports it. See [conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#resolve-the-agent) |
+| A chat flow "hangs" or times out during debug | Not a fault. `flow debug` hands a `core.trigger.conversation` flow off rather than running it, and a flow parked on `wait-for-message` is waiting for a user message that no headless run will send. Drive it from a chat UI — Studio Web or the UiPath Maestro VS Code extension. See [conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#debug--the-cli-hands-off) |
 | Read the cause out of a faulted `flow debug` response | [troubleshooting-guide.md — Step 0](troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have) |
 | Find the error message and faulting element | [troubleshooting-guide.md — Step 2 Fetch incidents](troubleshooting-guide.md#step-2--fetch-incidents) |
 | See data state at failure time | [troubleshooting-guide.md — Step 3 Fetch runtime variable state](troubleshooting-guide.md#step-3--fetch-runtime-variable-state) |

package/skills/uipath-maestro-flow/references/operate/CAPABILITY.md

@@ -39,6 +39,7 @@ Capability index for the lifecycle of a flow as a deployed asset. Operate owns e
 | **Deploy a flow to Orchestrator** (only if explicitly requested) | [ship.md — Path 2](ship.md#path-2--orchestrator-deploy-explicit-only) + [/uipath:uipath-solution](/uipath:uipath-solution) |
 | **Sync solution resource declarations** | [ship.md — Pre-flight](ship.md#pre-flight) (the `uip solution resources refresh` step) |
 | **Debug a flow end-to-end** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) |
+| **Debug a chat flow** | `flow debug` cannot drive a conversation headlessly. On a flow starting with `core.trigger.conversation` it uploads, returns `Code: FlowDebugStudioWebHandoff` with `Data.studioWebUrl`, and starts no run. Chat from either Studio Web (open that URL; `--open-in-browser` does it for you) or the UiPath Maestro VS Code extension. `--timeout` does nothing here. See [author/plugins/conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#debug--the-cli-hands-off) |
 | **Pass input arguments to `flow debug`** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) (the `--inputs` flag) |
 | **Bind local files to file-typed inputs** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) and [run.md — Process run](run.md#process-run--trigger-a-deployed-process) (same `--attachment <variableId>=<localPath>` flag on both, repeatable; `--attachment` overrides `--inputs` on key collisions) |
 | **Trigger a deployed process** | [run.md — Process run](run.md#process-run--trigger-a-deployed-process) |

package/skills/uipath-maestro-flow/references/shared/node-output-wiring.md

@@ -34,6 +34,8 @@ Static values do not need `=js:`. For mixed strings, use `=js:` with JavaScript
 | Loop nodes (`core.logic.loop`) | `inputs.collection` | **YES** |
 | Subflow nodes (`core.subflow`) | `inputs.<inputId>.source` | **YES** |
 | Script nodes (`core.action.script`) | `inputs.script` body | **NO**; the body is already JS and reads `$vars.*` directly |
+| **Chat `conversationId`** (`uipath.conversational.*` nodes) | `inputs.conversationId` — a structured binding object to the trigger's only output, `$vars.<conversationTriggerId>.output.conversationId`. send-message also needs `exchangeId`, which is `conversationContext.latestExchangeId` on the wait node — there is no `output.exchangeId`. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [conversational-agent/impl.md § Node JSON](../author/plugins/conversational-agent/impl.md#node-json). |
+| **Chat `conversationalAgentSettings`** (`uipath.agent.conversational`, `uipath.core.agent.*` when conversational) | `inputs.conversationalAgentSettings` — five structured binding objects: `context` plus the `conversationId`, `exchangeId`, `messages` and `userSettings` derived from it. All five must be written when authoring from the CLI. | **NO** — the expression sits unprefixed inside each object's `expression` field. See [conversational-agent/impl.md § The `conversationalAgentSettings` Wiring Rule](../author/plugins/conversational-agent/impl.md#the-conversationalagentsettings-wiring-rule). |
 | **Voice `callContext`** (`uipath.agent.voice`, `uipath.conversational.voice.end-call`) | `inputs.callContext` — a structured binding object `{ "type": "jsExpression", "expression": "$vars.<originNodeId>.output.callContext", "fieldType": ... }`, never a bare string. `fieldType` is `"object"` on the voice agent and `"string"` on the end-call node. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [author/plugins/inline-voice-agent/impl.md § The `callContext` wiring rule](../author/plugins/inline-voice-agent/impl.md#the-callcontext-wiring-rule). |
 | **Inline-agent prompt** (`uipath.agent.autonomous` / `uipath.agent.voice` `agent.json` `messages[].content`) | Tokens use the flattened delivery key, never the flow expression: `{{input.<flowNodeId>__output__<field>}}`. The key is delivered by the node's `inputs.agentInputVariables[]` binding (`=$vars.<flowNodeId>.output.<field>`) and declared in `inputSchema.properties`. Mirror in `contentTokens[]` as `{ "type": "variable", "rawString": "input.<flowNodeId>__output__<field>" }` — `rawString` is brace-free with no added spaces, and `uip agent refresh` regenerates it, so never hand-author it. **Never a raw `{{ $vars.… }}`** (nothing rewrites agent.json prompt text — the model receives it literally) and never a bare `{{name}}`. | **NO** — `{{ ... }}` tokens, not `=js:`. See [author/plugins/inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](../author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). Encoding note: a read `agent.json` may use the flat `__` input keys or a newer nested (dotted-key) form — author flat, read both (see the impl.md encoding note). |
 
@@ -81,4 +83,4 @@ When a flow outputs literal `vars.X.output.Y`, `nodes.X.output.Y`, or another un
 1. Open the `.flow` file.
 2. Search for the token: `grep '"vars\.' <project>.flow` or `grep '"\$vars\.' <project>.flow`.
 3. In `bodyParameters`, `queryParameters`, `pathParameters`, end-node `source`, and other value fields, prepend `=js:` to each variable reference.
-4. Run `uip maestro flow validate` and re-debug.
+4. Run `uip maestro flow validate` and re-debug.

package/version-manifest.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 2,
-  "skillsVersion": "1.202.0-preview.710",
+  "skillsVersion": "1.202.0-preview.716",
   "targetCli": "^1.202.0"
 }