@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,309 @@
+# 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. Imported standalone conversational agents (published or in-solution) do not support structured output fields.
+
+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.
+
+### Prompting: what goes where
+
+The prompts that drive the agent's chat replies and structured output differ:
+
+| Generated | Driven by |
+| --- | --- |
+| the chat reply | the system prompt **only** |
+| the structured outputs | the system prompt **plus** each field's `description` |
+
+So split the instructions by destination — *what to say* and *response instructions* in the system prompt, *how to fill the field* in that field's `description` (write the same description in both `agentOutputVariables[]` and `outputSchema.properties`):
+
+| Where | Example |
+| --- | --- |
+| system prompt | "Thank the user when they would like to end the conversation." |
+| `endConversation` (boolean) `description` | "Set to true when the user intends to end the conversation." |
+
+**Do not name the output field and how to set it in the system prompt.** An instruction like "set `endConversation` to `true` when the user says goodbye" in the system prompt may make the LLM emit the structured value to the chat or look for a tool to set the output variables.
+
+## 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