@uipath/maestro-builder-sdk 6.42.0 → 6.44.0

package/dist/nodes/process/flow/check.js

@@ -4,6 +4,19 @@ import { nearestName } from '../../../core/edit-distance.js';
 import { ownEntry } from '../../../core/own-entry.js';
 import { renamedFieldMessage } from '../../../core/process-resource.js';
 export const PROCESS_DIAGNOSTICS = {
+    AGENT_EMPTY_INPUT_FLOOR: { severity: 'warning', summary: 'an agent step that binds no inputs' },
+    AGENT_EMPTY_RETURNS: { severity: 'warning', summary: 'an agent step with returns: {}' },
+    AGENT_KEY_NOT_GUID: { severity: 'error', summary: 'an agent step whose key is not a GUID' },
+    AGENT_LOCAL_NO_PROJECT_ID: { severity: 'error', summary: 'an agent step in-solution, with no projectId' },
+    AGENT_LOCAL_PROJECT_ID_NOT_GUID: { severity: 'error', summary: 'an agent step in-solution, with a projectId that is not a GUID' },
+    AGENT_NAME_IS_PATH: { severity: 'error', summary: 'an agent step whose name looks like a folder path' },
+    AGENT_NO_FOLDER: { severity: 'error', summary: 'an agent step with no folderPath' },
+    AGENT_NO_KEY: { severity: 'error', summary: 'an agent step with no key' },
+    AGENT_NO_NAME: { severity: 'error', summary: 'an agent step with no name' },
+    AGENT_READ_NOT_OUTPUT: { severity: 'error', summary: 'an agent step read outside output' },
+    AGENT_READ_UNKNOWN_FIELD: { severity: 'error', summary: 'an agent step read of a field returns does not declare' },
+    AGENT_READ_WITHOUT_RETURNS: { severity: 'error', summary: 'an agent step field read with no returns' },
+    AGENT_READ_WRONG_CASE: { severity: 'error', summary: 'an agent step read of a declared field in the wrong case' },
     AGENTIC_EMPTY_RETURNS: { severity: 'warning', summary: 'an agentic process step with returns: {}' },
     AGENTIC_KEY_NOT_KEY: { severity: 'error', summary: 'an agentic process step whose key is not a GUID' },
     AGENTIC_LOCAL_FORM_UNVERIFIED: { severity: 'error', summary: 'an agentic process step in-solution, with a form other than flow' },
@@ -442,3 +455,146 @@ export function checkAgenticProcessRead({ node: name, field, rest, reader: step
         + `"${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set is undefined on `
         + `every rung and on the platform.`, nearest !== undefined ? `out('${name}', '${nearest}')` : undefined);
 }
+/**
+ * Check an `agent(...)` call — a published or in-solution agent (coded or
+ * low-code).
+ *
+ * WHAT THESE RULES CAN AND CANNOT SEE. Whether the agent exists, which kind it is,
+ * and what it returns all live on the tenant. So these cover what is decidable from
+ * the call — and two of them are the exact classes v1's own baseline on this family
+ * fails on, which is why they are errors rather than warnings:
+ *
+ *  - **A reference to nothing.** 5 of 16 `skill-flow-coded-agent` runs in the
+ *    06-29 → 07-20 window emitted an agent node whose `resourceKey` was a LOCAL
+ *    project id and whose `folderPath` was `""`, and faulted at job start with
+ *    `[170007] … HTTP 404 "The job's associated process could not be found"`. A
+ *    blank `name` or `folderPath` is that flow, caught before a tenant round trip.
+ *  - **The empty-input floor.** `inputs` is required by the type, so `{}` is the only
+ *    way to reach it, and it is worth saying what the platform then does — see
+ *    `AGENT_EMPTY_INPUT_FLOOR`.
+ *
+ * What no rule here can see: whether the agent's ANSWER is right. That is CP-3's
+ * ruling — a green live rung means a model responded with the declared shape — and
+ * the gate that does cover a flow FAKING an answer is an offline `replays:` seed
+ * asserting the exact unfixtured value, not a check.
+ */
+export function checkAgent(inputs, ctx) {
+    const step = ctx.step;
+    const at = (code, message, suggestion) => ctx.report(code, message, suggestion);
+    const blank = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+    const inSolution = inputs?.location === 'in-solution';
+    if (blank(inputs?.key) && !blank(inputs?.agent)) {
+        at('AGENT_NO_KEY', renamedFieldMessage('Agent', step, 'agent'), `key: ${JSON.stringify(inputs.agent)}`);
+    }
+    else if (blank(inputs?.key)) {
+        at('AGENT_NO_KEY', `Agent step "${step}" has no \`key\`. It is a GUID and becomes part of the node's `
+            + `type — without it there is no agent to start. For a published agent, find the Orchestrator `
+            + `release with \`uip or processes list --all-folders --limit 200\` (take the row's \`Key\`) or `
+            + `\`uip maestro flow registry search uipath.core.agent\`. For an in-solution agent, read `
+            + `\`resource.key\` from \`resources/solution_folder/process/agent/<project>.json\`.`, `key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa'`);
+    }
+    else if (!GUID_RE.test(String(inputs.key).trim())) {
+        at('AGENT_KEY_NOT_GUID', `Agent step "${step}"'s \`key\` is ${JSON.stringify(inputs.key)}, which is not a key. \`key\` is `
+            + `the GUID the tenant gives the published agent (it becomes the node type's suffix); the agent's NAME `
+            + `goes in \`name\` and its folder in \`folderPath\`. Passing a ProcessKey like `
+            + `"CountLetters.CodedAgent.agent.CountLetters" here is the common form of this — that string is the `
+            + `row's \`ProcessKey\`, not its \`Key\`.`, `key: '<guid>', name: ${JSON.stringify(inputs.key)}`);
+    }
+    if (blank(inputs?.name)) {
+        at('AGENT_NO_NAME', `Agent step "${step}" has no \`name\`. The runtime resolves the agent's release by name + folder, not `
+            + `by the key in the node type, so without it the job cannot start — deployed, that is `
+            + `\`[170007] … 404 The job's associated process could not be found\`.`, `name: 'CountLetters LowCode Agent'`);
+    }
+    if (!inSolution && blank(inputs?.folderPath)) {
+        at('AGENT_NO_FOLDER', `Agent step "${step}" has no \`folderPath\`. The runtime resolves the agent by listing ONE Orchestrator `
+            + `folder, so a blank folder resolves nothing — and an empty \`folderPath\` is the exact shape of v1's `
+            + `commonest live failure on this node type (5 of 16 runs, 06-29 → 07-20: `
+            + `\`[170007] … 404 The job's associated process could not be found\`). It is also what disambiguates `
+            + `two same-named agents: this tenant has \`CountLetters\` in both \`Shared\` and `
+            + `\`Shared/uipath-maestro-flow/CountLetters CodedAgent\`.`, `folderPath: 'Shared/uipath-maestro-flow/CountLetters LowCode'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        at('AGENT_LOCAL_NO_PROJECT_ID', `In-solution agent step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/agent/<project>.json\` after registering the sibling `
+            + `with \`uip solution projects add\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('AGENT_LOCAL_PROJECT_ID_NOT_GUID', `In-solution agent step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the registered sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
+    }
+    const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
+    if (name.includes('/')) {
+        at('AGENT_NAME_IS_PATH', `Agent step "${step}"'s \`name\` is ${JSON.stringify(name)}, which looks like a folder path. \`name\` is `
+            + `the agent's own name in Orchestrator; the path it lives in goes in \`folderPath\`. Together they form `
+            + `the resourceKey "<folderPath>.<name>", so swapping them points the job at nothing.`);
+    }
+    // The platform's SECOND place for rewriting an agent node's inputs behind the
+    // author's back (the first is the reserved-key class — see AGENTIC_RESERVED_INPUT).
+    // A warning rather than an error: an argument-less agent is legal, and the floor
+    // makes it work. What is not acceptable is that it happen silently.
+    if (inputs?.inputs && Object.keys(inputs.inputs).length === 0) {
+        at('AGENT_EMPTY_INPUT_FLOOR', `Agent step "${step}" binds no inputs. The platform does not send an empty body for an agent the way `
+            + `it does for the other job families — flow-v1's \`applyEmptyInputFloor\` seeds `
+            + `\`JobArguments: { input: "" }\` (or \`{}\` / \`[]\`, typed off the agent's declared \`input\` field), `
+            + `because the Python agent runner validates the body against a schema with a REQUIRED \`input\` field `
+            + `and rejects a bare \`{}\` with "Field required: input" — the pod then exits 0x33. So the deployed `
+            + `node carries an argument named \`input\` that you did not write, and which is not in the agent's own `
+            + `schema unless it happens to declare one. Locally the envelope passes straight through, so no rung `
+            + `sees the difference. Bind the agent's own arguments if it takes any.`);
+    }
+    if (inputs?.returns && Object.keys(inputs.returns).length === 0) {
+        at('AGENT_EMPTY_RETURNS', `Agent step "${step}" declares \`returns: {}\` — an empty contract, which emits no output schema at `
+            + `all and so reads exactly like omitting it. If the agent returns nothing, drop the key; if it `
+            + `returns something, name the fields (\`uip maestro flow registry get uipath.core.agent.`
+            + `${inputs.key}\` shows them under outputDefinition.output.schema.properties).`);
+    }
+}
+/**
+ * A read of a published agent's output: `out('<step>', '<field>')`.
+ *
+ * The three mistakes are api-workflow's and agentic-process's, plus a fourth this
+ * family owns: a read whose CASE differs from the declared field. That is worth its
+ * own message because for a while it was a live-only defect rather than a mistake —
+ * a poller that read the job through `uip agent run status` got a PascalCased
+ * envelope, so `output.Count` was right live and wrong offline while
+ * `output.count` was the reverse (flow-builder-sdk #122). Now the agent's own field
+ * names arrive verbatim and the wrong case is simply undefined; naming it as a CASE
+ * problem rather than an unknown field is the difference between a two-second fix and
+ * a re-read of the registry.
+ */
+export function checkAgentRead({ node: name, field, rest, reader: step }, spec, report) {
+    if (field === undefined)
+        return; // `out('call')` — the whole output object.
+    if (field === 'error')
+        return; // the error envelope every agent node declares.
+    if (field !== 'output') {
+        report('AGENT_READ_NOT_OUTPUT', `Agent "${name}" publishes the job's output arguments under "output", but `
+            + `"$vars.${name}.${field}" (read in "${step}") asks for "${field}", which is undefined at run time.`, `out('${name}', '<field>')`);
+        return;
+    }
+    const declared = Object.keys(spec.returns ?? {});
+    const wanted = (rest ?? '').replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return; // `$vars.<name>.output` — the whole object.
+    if (declared.length === 0) {
+        report('AGENT_READ_WITHOUT_RETURNS', `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of agent "${name}"'s result, but `
+            + `the step declares no \`returns\` — so the node carries no output schema and nothing can tell a real `
+            + `field from a typo. The agent's output fields live on the tenant; declare the ones you read. `
+            + `\`uip maestro flow registry get uipath.core.agent.${spec.key}\` shows them under `
+            + `outputDefinition.output.schema.properties.`, `returns: { ${wanted}: 'string' }`);
+        return;
+    }
+    if (declared.includes(wanted))
+        return;
+    const caseMatch = declared.find((d) => d.toLowerCase() === wanted.toLowerCase());
+    if (caseMatch) {
+        report('AGENT_READ_WRONG_CASE', `Agent "${name}" declares "${caseMatch}", not "${wanted}" (read as "$vars.${name}.output.${wanted}" `
+            + `in "${step}") — the same field, the wrong case. An agent answers with the field names its own `
+            + `definition declares, and a read is case-sensitive on every rung, so this is undefined everywhere.`, `out('${name}', '${caseMatch}')`);
+        return;
+    }
+    const nearest = nearestName(wanted, declared);
+    report('AGENT_READ_UNKNOWN_FIELD', `Agent "${name}" declares no output "${wanted}" (read as "$vars.${name}.output.${wanted}" in "${step}"). `
+        + `Its \`returns\` names: ${declared.join(', ')}. A read outside that set is undefined on every rung and `
+        + `on the platform.`, nearest ? `out('${name}', '${nearest}')` : undefined);
+}

package/dist/nodes/process/flow/factories.d.ts

@@ -1,10 +1,10 @@
 /**
- * The process factories — `rpaWorkflow()`, `apiWorkflow()`, `publishedFunction()`
- * and `agenticProcess()`. Moved from core/actions.ts in Phase 4 of
+ * The process factories — `rpaWorkflow()`, `apiWorkflow()`, `publishedFunction()`,
+ * `agenticProcess()` and `agent()`. Moved from core/actions.ts in Phase 4 of
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
  */
 import { type ActionSpec } from '../../../core/actions.js';
-import type { AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
+import type { AgentInputs, AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
 /**
  * Invoke a deployed RPA (robotic process automation) workflow — a classic
  * UI-automation process, published to Orchestrator, run by a robot.
@@ -156,3 +156,58 @@ export declare function publishedFunction(inputs: PublishedFunctionInputs): Acti
  * @returns An action spec to pass to `.step(name, …)`.
  */
 export declare function agenticProcess(inputs: AgenticProcessInputs): ActionSpec;
+/**
+ * Invoke an AGENT resource — either one published to Orchestrator or a sibling
+ * agent project registered in the same solution. Both start through
+ * `Orchestrator.StartAgentJob`.
+ *
+ * @remarks
+ * **Coded and low-code agents are the same node.** This one factory authors both.
+ * `registry get` on a coded agent and on a low-code one returns the same node type,
+ * the same service type, the same `sortOrder` and the same bindings shape; the
+ * only difference is the icon, which is what `flavour` sets. Which kind a resource
+ * is a property of what somebody published, not of the flow — so if a task asks for
+ * "a coded agent", what it is asking you to get right is the RESOURCE you point at.
+ *
+ * **What this factory cannot do, said plainly:** it does not create an agent. A
+ * published resource must already be deployed. An in-solution resource must first
+ * be scaffolded and registered with `uip solution projects add`; this factory then
+ * authors the local reference from the registered resource key and project id.
+ *
+ * The three identifiers are separate for `rpaWorkflow`'s reason: `agent` is the key
+ * the node's TYPE carries (`uipath.core.agent.<agent>`), while `name` +
+ * `folderPath` are what the runtime resolves the job by and together are the
+ * `resourceKey`, `"<folderPath>.<name>"`. `folderPath` earns its keep twice here —
+ * see {@link AgentInputs.folderPath} for the two-agents-called-CountLetters case.
+ *
+ * The step WAITS for the job and publishes its output arguments under `output`, so
+ * `out('<step>', '<field>')` reads a field `returns` declares — using the names the
+ * agent's own definition declares, case included.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * A green live rung here means **a model responded with the declared output shape**,
+ * not that the answer was right. A real Orchestrator job runs, the flow's input
+ * reaches it, and its answer reaches the flow's output — all four independently
+ * checkable (`ladder.sh job`). Whether the number it returned is the correct number
+ * is the model's business, and no rung asserts it. What CAN be asserted is that the
+ * flow did not fake it: the offline seeds assert the exact UNFIXTURED value, which a
+ * hardcoded answer cannot produce.
+ *
+ * @example
+ * **Start a published agent and read one declared output**
+ * ```ts
+ * .step('countLetters', agent({
+ *   key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa',
+ *   name: 'CountLetters LowCode Agent',
+ *   folderPath: 'Shared/uipath-maestro-flow/CountLetters LowCode',
+ *   inputs: { inputString: input('word') },
+ *   returns: { count: 'integer', inputString: 'string' },
+ * }))
+ * .return({ rs: out('countLetters', 'count') })
+ * ```
+ *
+ * @param inputs - The agent to start (`name`, `folderPath`, and `key` or
+ * `projectId`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function agent(inputs: AgentInputs): ActionSpec;

package/dist/nodes/process/flow/factories.js

@@ -1,6 +1,6 @@
 /**
- * The process factories — `rpaWorkflow()`, `apiWorkflow()`, `publishedFunction()`
- * and `agenticProcess()`. Moved from core/actions.ts in Phase 4 of
+ * The process factories — `rpaWorkflow()`, `apiWorkflow()`, `publishedFunction()`,
+ * `agenticProcess()` and `agent()`. Moved from core/actions.ts in Phase 4 of
  * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; the package entry re-exports them.
  */
 import { builtinActionSpec } from '../../../core/actions.js';
@@ -171,3 +171,60 @@ export function agenticProcess(inputs) {
     }
     return builtinActionSpec({ kind: 'agenticProcess', inputs });
 }
+/**
+ * Invoke an AGENT resource — either one published to Orchestrator or a sibling
+ * agent project registered in the same solution. Both start through
+ * `Orchestrator.StartAgentJob`.
+ *
+ * @remarks
+ * **Coded and low-code agents are the same node.** This one factory authors both.
+ * `registry get` on a coded agent and on a low-code one returns the same node type,
+ * the same service type, the same `sortOrder` and the same bindings shape; the
+ * only difference is the icon, which is what `flavour` sets. Which kind a resource
+ * is a property of what somebody published, not of the flow — so if a task asks for
+ * "a coded agent", what it is asking you to get right is the RESOURCE you point at.
+ *
+ * **What this factory cannot do, said plainly:** it does not create an agent. A
+ * published resource must already be deployed. An in-solution resource must first
+ * be scaffolded and registered with `uip solution projects add`; this factory then
+ * authors the local reference from the registered resource key and project id.
+ *
+ * The three identifiers are separate for `rpaWorkflow`'s reason: `agent` is the key
+ * the node's TYPE carries (`uipath.core.agent.<agent>`), while `name` +
+ * `folderPath` are what the runtime resolves the job by and together are the
+ * `resourceKey`, `"<folderPath>.<name>"`. `folderPath` earns its keep twice here —
+ * see {@link AgentInputs.folderPath} for the two-agents-called-CountLetters case.
+ *
+ * The step WAITS for the job and publishes its output arguments under `output`, so
+ * `out('<step>', '<field>')` reads a field `returns` declares — using the names the
+ * agent's own definition declares, case included.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * A green live rung here means **a model responded with the declared output shape**,
+ * not that the answer was right. A real Orchestrator job runs, the flow's input
+ * reaches it, and its answer reaches the flow's output — all four independently
+ * checkable (`ladder.sh job`). Whether the number it returned is the correct number
+ * is the model's business, and no rung asserts it. What CAN be asserted is that the
+ * flow did not fake it: the offline seeds assert the exact UNFIXTURED value, which a
+ * hardcoded answer cannot produce.
+ *
+ * @example
+ * **Start a published agent and read one declared output**
+ * ```ts
+ * .step('countLetters', agent({
+ *   key: '6a47dc5b-5fd4-461f-b97d-6c1817abcaaa',
+ *   name: 'CountLetters LowCode Agent',
+ *   folderPath: 'Shared/uipath-maestro-flow/CountLetters LowCode',
+ *   inputs: { inputString: input('word') },
+ *   returns: { count: 'integer', inputString: 'string' },
+ * }))
+ * .return({ rs: out('countLetters', 'count') })
+ * ```
+ *
+ * @param inputs - The agent to start (`name`, `folderPath`, and `key` or
+ * `projectId`), its `inputs`, and the fields you read back via `returns`.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function agent(inputs) {
+    return builtinActionSpec({ kind: 'agent', inputs });
+}

package/dist/nodes/process/flow/node-type.d.ts

@@ -1,6 +1,6 @@
 import { type ProcessResourceDef } from '../../../core/process-resource.js';
 import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
-import type { AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
+import type { AgentInputs, AgenticProcessInputs, ApiWorkflowInputs, PublishedFunctionInputs, RpaWorkflowInputs } from './spec.js';
 type ProcessSpec = {
     kind: 'rpaWorkflow';
     inputs: RpaWorkflowInputs;
@@ -13,6 +13,9 @@ type ProcessSpec = {
 } | {
     kind: 'agenticProcess';
     inputs: AgenticProcessInputs;
+} | {
+    kind: 'agent';
+    inputs: AgentInputs;
 };
 /**
  * The definition a process step's node is emitted against — what serialize

package/dist/nodes/process/flow/node-type.js

@@ -1,12 +1,14 @@
 /**
  * The process family's node types — one per published-resource kind this SDK
- * starts as a job: an RPA process, an API workflow, a published function, and an
- * agentic process in each of its three forms. Each type's name carries the
- * resource's key (`uipath.core.function.<key>`), so the type owns every name under
- * its prefix (`typeNamePrefix`) and supplies the definition it built, transcribed
- * from the platform's own synthesized one (per-tenant). Moved from serialize.ts /
- * check.ts / decompile.ts in Phase 4 of docs/NODE_TYPE_ARCHITECTURE_DESIGN.md;
- * serialized output, printed source, codes and messages unchanged.
+ * starts as a job: an RPA process, an API workflow, a published function, an
+ * agentic process in each of its three forms, and a published agent. Each type's
+ * name carries the resource's key (`uipath.core.function.<key>`), so the type owns
+ * every name under its prefix (`typeNamePrefix`) and supplies the definition it
+ * built, transcribed from the platform's own synthesized one (per-tenant).
+ * Moved from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; codes and messages unchanged, and
+ * printed source and serialized output unchanged except as the design doc's 4j
+ * and 4l entries list.
  */
 import { AGENTIC_PROCESS_FORMS } from '../../../core/agentic-process-forms.js';
 import { definitionHasErrorPort } from '../../../core/error-port.js';
@@ -14,7 +16,7 @@ import { Expr } from '../../../core/expr.js';
 import { ownEntry } from '../../../core/own-entry.js';
 import { resourceNodeSortOrder } from '../../../core/process-resource-sort-order.js';
 import { processResourceBindings, processResourceLocation } from '../../../core/process-resource.js';
-import { checkAgenticProcess, checkAgenticProcessRead, checkApiWorkflow, checkApiWorkflowRead, checkPublishedFunction, checkPublishedFunctionRead, checkRpaWorkflow, rpaWorkflowRead, } from './check.js';
+import { checkAgent, checkAgentRead, checkAgenticProcess, checkAgenticProcessRead, checkApiWorkflow, checkApiWorkflowRead, checkPublishedFunction, checkPublishedFunctionRead, checkRpaWorkflow, rpaWorkflowRead, } from './check.js';
 /** The RPA-workflow node type family. The process's release key is the suffix. */
 const RPA_WORKFLOW_PREFIX = 'uipath.core.rpa-workflow.';
 /**
@@ -453,6 +455,141 @@ function agenticProcessDef(spec) {
         debug: { runtime: 'bpmnEngine' },
     };
 }
+/** The published-agent node type family. The agent's release key is the suffix. */
+const AGENT_PREFIX = 'uipath.core.agent.';
+/**
+ * Build the definition for one published agent — coded or low-code, which are the
+ * SAME node.
+ *
+ * Unbundlable for rpa's, api-workflow's and agentic-process's reason: the node type
+ * carries a tenant's release key and the platform synthesizes the contract from
+ * whatever somebody published there. The constants below are transcribed from what
+ * the platform's oracles AGREE on, and this family is the first in the wave with
+ * BOTH a rich registry answer and a large deployed corpus, so the agreement is
+ * checkable rather than asserted:
+ *
+ *  - `uip maestro flow registry get uipath.core.agent.<key>` for ALL NINE agents on
+ *    the tenant (2026-07-29): `category: 'agent'`, `sortOrder: 505` (510 since flow-core's
+ *    renumber: the 54 runs from 09-01 below carry 510; `resourceNodeSortOrder`, #1045),
+ *    `supportsErrorHandling: true`, `version: '1.0.0'`, the `bpmn:ServiceTask` /
+ *    `Orchestrator.StartAgentJob` / `v2` model, `section: 'Published'`,
+ *    `resourceSubType: 'Agent'`, `orchestratorType: 'agent'`,
+ *    `debug.runtime: 'bpmnEngine'`, `runtimeConstraints.exclude: ['api-function']`,
+ *    and the `<bindings.name>` / `<bindings.folderPath>` context placeholders;
+ *  - **61 deployed, debug-green agent instances** across 61 dated
+ *    `skill-flow-{coded,lowcode}-agent` artifacts (05-18 → 07-29): `sortOrder: 505`
+ *    in 61/61, the `<folderPath>.<name>` resourceKey in 58/61 (the 3 exceptions are
+ *    the in-solution shape — a bare key and an EMPTY folderPath — which 404'd at
+ *    job start in those runs; that is the shape of `location: 'in-solution'`,
+ *    built by `processResourceLocation`, and it starts the job when the sibling is
+ *    in the solution: 54 v1 `skill-flow-coded-agent` runs, 09-01 → 10-08, carry
+ *    `isInSolution: true`, 45 score 1.0 and none of the other 9 fails on a
+ *    job-start 404, #1012), and the descriptor
+ *    ARRAY `bindings.values` in 59/61 (2 early runs used the object form);
+ *  - flow-v1's own generator, which is where those come from:
+ *    `node-manifest-builder.ts::createModel` hard-codes `bpmn:ServiceTask` for every
+ *    published-resource node and derives `orchestratorType` as
+ *    `resourceType.toLowerCase()`.
+ *
+ * `shared/sample-flows/agent.flow` is explicitly NOT an oracle here: dated
+ * 2026-05-12, it disagrees with both of the above in five places at once
+ * (`sortOrder: 530`, a bare-GUID resourceKey, an object-shaped `bindings.values`,
+ * and `=result.response` / `=result.Error` output sources). PR 11's rule — date a
+ * bundled sample before trusting the layer that copied it — and this is its second
+ * instance on that file.
+ *
+ * `outputs.output.source` is `=this`, which is what the definition declares. The
+ * corpus is split (`=result.response` 45, `=this` 14, both deploying green), and the
+ * split has a mechanical explanation: flow-v1's `applyOrchestratorActivityOutputs`
+ * APPENDS `{name:'output', source:'=this'}` when a node declares no `output`, so
+ * `=this` is what the platform writes for itself. We emit that one.
+ *
+ * The ONLY field that differs between a coded and a low-code agent is
+ * `display.icon` — which is why one factory serves both.
+ */
+function agentDef(spec) {
+    // One location slot with the other process resources: the in-solution
+    // model carries `projectId`, `projectName` AND `isInSolution: true`, as
+    // flow-core's `createModel` writes for every sibling-project resource.
+    const loc = processResourceLocation(spec);
+    const { inSolution, resourceKey } = loc;
+    const properties = {};
+    for (const [k, v] of Object.entries(spec.inputs)) {
+        properties[k] = { type: typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string' };
+    }
+    return {
+        nodeType: `${AGENT_PREFIX}${spec.key}`,
+        version: '1.0.0',
+        category: 'agent',
+        runtimeConstraints: { exclude: ['api-function'] },
+        description: loc.description,
+        tags: loc.tags,
+        sortOrder: resourceNodeSortOrder('agent'),
+        supportsErrorHandling: true,
+        display: {
+            label: spec.name,
+            icon: spec.flavour === 'coded' ? 'coded-agent' : 'autonomous-agent',
+        },
+        handleConfiguration: [
+            { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
+            { position: 'right', handles: [{ id: 'output', type: 'source', handleType: 'output' }] },
+        ],
+        ...loc.definitionExtras,
+        model: {
+            type: 'bpmn:ServiceTask',
+            serviceType: 'Orchestrator.StartAgentJob',
+            version: 'v2',
+            ...(inSolution ? {} : { section: 'Published' }),
+            bindings: {
+                resource: 'process',
+                resourceSubType: 'Agent',
+                resourceKey,
+                orchestratorType: 'agent',
+                values: [
+                    { name: 'name', propertyAttribute: 'name', default: spec.name },
+                    { name: 'folderPath', propertyAttribute: 'folderPath', default: loc.folderPath },
+                ],
+            },
+            ...loc.modelExtras,
+            context: [
+                { name: 'name', type: 'string', value: '<bindings.name>' },
+                { name: 'folderPath', type: 'string', value: '<bindings.folderPath>' },
+                { name: '_label', type: 'string', value: spec.name },
+            ],
+        },
+        inputDefinition: Object.keys(properties).length ? { type: 'object', properties } : {},
+        inputDefaults: inSolution
+            ? Object.fromEntries(Object.keys(properties).map((name) => [name, '']))
+            : {},
+        outputDefinition: {
+            output: {
+                type: 'object',
+                source: '=this',
+                var: 'output',
+                // The agent's output fields as the author declared them — the same shape
+                // `registry get` returns when it can reach the deployed agent (nested under
+                // `schema`, which is the spelling gen-tests reads). Without it a downstream
+                // read is unresolvable, rightly: nothing offline could tell a real field from a
+                // typo, and this is also what fixtures the node offline.
+                ...(spec.returns && Object.keys(spec.returns).length
+                    ? {
+                        schema: {
+                            type: 'object',
+                            properties: Object.fromEntries(Object.entries(spec.returns).map(([k, t]) => [k, { type: t }])),
+                        },
+                    }
+                    : {}),
+            },
+            error: {
+                type: 'object',
+                description: 'Error information if the node fails',
+                source: '=Error',
+                var: 'error',
+            },
+        },
+        debug: { runtime: 'bpmnEngine' },
+    };
+}
 /**
  * The definition a process step's node is emitted against — what serialize
  * supplies and what `errorPort` asks, so the two cannot disagree (#1040).
@@ -474,10 +611,15 @@ export function processDefinition(spec) {
                 key: s.key, name: s.name, folderPath: s.folderPath, location: s.location, projectId: s.projectId,
                 inputs: s.inputs ?? {}, returns: s.returns,
             });
+        case 'agent':
+            return agentDef({
+                key: s.key, name: s.name, folderPath: s.folderPath, location: s.location, projectId: s.projectId,
+                inputs: s.inputs ?? {}, returns: s.returns, flavour: s.flavour,
+            });
     }
 }
 /**
- * One emit path for the four process-resource kinds: they differ in the
+ * One emit path for the five process-resource kinds: they differ in the
  * definition they carry (node type, serviceType, subtype, the key's field name)
  * and in nothing else — the node body, the binding pair and the model-stripping
  * are identical, and the DATA paths that differ are all downstream in the engine.
@@ -518,6 +660,27 @@ function serializeProcess(spec, ctx) {
         ...(outputs !== undefined ? { outputs, replaceOutputs: true } : {}),
     };
 }
+/**
+ * Read back the expression template older SDK builds emitted on an in-solution
+ * `agent()` input (#1013): `{ type: 'literal', expression: '{{ <js> }}' }`.
+ * serialize now emits the platform's `{ type: 'jsExpression', expression }`
+ * instead, but `.flow` files written between 2026-08-10 and the fix still carry
+ * the template, and the runtime evaluates it (the agent receives the value, not
+ * the braces). So on an in-solution agent node a literal that is exactly one
+ * `{{ … }}` is that expression, and it decompiles to the reference it was
+ * written from rather than to a string. Anything else is returned unchanged.
+ */
+function legacyAgentTemplateInput(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return v;
+    const o = v;
+    if (o.type !== 'literal' || typeof o.expression !== 'string')
+        return v;
+    const m = /^\{\{\s*([\s\S]+?)\s*\}\}$/.exec(o.expression);
+    if (!m || m[1].includes('}}') || m[1].includes('{{'))
+        return v;
+    return { ...o, type: 'jsExpression', expression: m[1] };
+}
 /** A value as the author wrote it: an expression back to an Expr, a literal string as itself, any other JSON as is. */
 function lifted(raw, ctx) {
     const text = Array.isArray(raw) ? undefined : ctx.sourceText(raw);
@@ -554,7 +717,27 @@ function liftProcess(node, ctx, prefix, kind, form) {
     // author's map, so it comes back off here.
     const fireAndForget = ctx.plainValue(inputs.fireAndForget) === true;
     delete inputs.fireAndForget;
+    if (kind === 'agent' && (def?.model?.isInSolution === true || def?.model?.projectId !== undefined)) {
+        for (const [k, v] of Object.entries(inputs))
+            inputs[k] = legacyAgentTemplateInput(v);
+    }
     const schema = def?.outputDefinition?.output?.schema?.properties;
+    const returns = schema && Object.keys(schema).length > 0
+        ? Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, String(v?.type ?? 'string')]))
+        : undefined;
+    // The designer writes the process's output schema on the definition whether
+    // or not the step waits for it. `agenticProcess()` refuses `returns` beside
+    // `completion: 'fire-and-forget'` (a dispatch publishes no output, so nothing
+    // could read one), so the schema is not carried into source — said, not
+    // dropped silently (#1312). Merge keeps the original's definition row, so a
+    // no-edit round trip loses nothing in the file.
+    if (fireAndForget && returns !== undefined) {
+        const id = String(node.id ?? '');
+        ctx.lossy(`process step ${JSON.stringify(id)} is fire-and-forget, so the ${Object.keys(returns).length} output `
+            + `field(s) its definition declares (${Object.keys(returns).join(', ')}) are not written as \`returns\`: `
+            + `a fire-and-forget dispatch publishes no output, and agenticProcess() refuses the pair. Compile writes the `
+            + `definition without that schema. To read the process result, set completion: 'wait' and declare \`returns\`.`);
+    }
     const spec = {
         key,
         ...(name !== undefined ? { name } : {}),
@@ -562,8 +745,7 @@ function liftProcess(node, ctx, prefix, kind, form) {
         ...(!inSolution && folderPath !== undefined ? { folderPath } : {}),
         ...(inSolution && projectId !== undefined ? { projectId } : {}),
         ...(Object.keys(inputs).length ? { inputs: Object.fromEntries(Object.entries(inputs).map(([k, v]) => [k, lifted(v, ctx)])) } : {}),
-        ...(schema && Object.keys(schema).length > 0
-            ? { returns: Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, String(v?.type ?? 'string')])) } : {}),
+        ...(returns !== undefined && !fireAndForget ? { returns } : {}),
         ...(form !== undefined ? { form } : {}),
         ...(fireAndForget ? { completion: 'fire-and-forget' } : {}),
     };
@@ -605,6 +787,8 @@ function processOutput(spec) {
             return { kind: 'reader', read: (read, report) => checkPublishedFunctionRead(read, spec.inputs, report) };
         case 'agenticProcess':
             return { kind: 'reader', read: (read, report) => checkAgenticProcessRead(read, spec.inputs, report) };
+        case 'agent':
+            return { kind: 'reader', read: (read, report) => checkAgentRead(read, spec.inputs, report) };
     }
 }
 function processCheck(spec, ctx) {
@@ -613,13 +797,14 @@ function processCheck(spec, ctx) {
         case 'apiWorkflow': return checkApiWorkflow(spec.inputs, ctx);
         case 'publishedFunction': return checkPublishedFunction(spec.inputs, ctx);
         case 'agenticProcess': return checkAgenticProcess(spec.inputs, ctx);
+        case 'agent': return checkAgent(spec.inputs, ctx);
     }
 }
 function processType(kind, prefix, factory, form) {
     const impl = {
         kind, typeName: `${prefix}*`, version: '1.0.0', factory, definition: 'per-tenant',
         // The definition this SDK synthesizes is the one serialize emits, and every
-        // one of the four sets supportsErrorHandling; asking it keeps the two in step (#1040).
+        // one of the five sets supportsErrorHandling; asking it keeps the two in step (#1040).
         errorPort: (spec) => definitionHasErrorPort(processDefinition(spec)),
         serialize: (spec, ctx) => serializeProcess(spec, ctx),
         deserialize: (node, ctx) => liftProcess(node, ctx, prefix, kind, form),
@@ -649,4 +834,5 @@ export const processNodeTypes = [
     processType('agenticProcess', AGENTIC_PROCESS_FORMS.bpmn.prefix, 'agenticProcess'),
     processType('agenticProcess', AGENTIC_PROCESS_FORMS.flow.prefix, 'agenticProcess', 'flow'),
     processType('agenticProcess', AGENTIC_PROCESS_FORMS.case.prefix, 'agenticProcess', 'case'),
+    processType('agent', AGENT_PREFIX, 'agent'),
 ];