@uipath/maestro-builder-sdk 6.42.0 → 6.43.0

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

@@ -0,0 +1,134 @@
+/**
+ * The agents family's factories — `createOutgoingCall()`, `endCall()`,
+ * `voiceAgent()`, `conversationalAgent()` and `inlineAgent()`. 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 { ConversationalAgentInputs, CreateOutgoingCallInputs, EndCallInputs, InlineAgentInputs, VoiceAgentInputs } from './spec.js';
+/**
+ * Place an outgoing phone call
+ * (`uipath.conversational.voice.create-outgoing-call`) and get back the
+ * `callContext` every other voice step is keyed by.
+ *
+ * ```ts
+ * .step('dial', createOutgoingCall({ from: '+15550001111', to: input('customerPhone') }))
+ * .step('talk', voiceAgent({
+ *   systemPrompt: 'Confirm the delivery window, then thank them.',
+ *   callContext: out('dial', 'callContext'),
+ * }))
+ * ```
+ *
+ * @param inputs - The provisioned `from` number and the `to` number to dial.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function createOutgoingCall(inputs: CreateOutgoingCallInputs): ActionSpec;
+/**
+ * Hang up (`uipath.conversational.voice.end-call`). Reads
+ * `out('<step>', 'ended')`.
+ *
+ * @param inputs - The `callContext` of the call to end.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function endCall(inputs: EndCallInputs): ActionSpec;
+/**
+ * Put a VOICE agent on a live call (`uipath.agent.voice`) — it speaks and
+ * listens for one turn, then the flow continues.
+ *
+ * ```ts
+ * .trigger(voiceTrigger())
+ * .step('greet', voiceAgent({
+ *   systemPrompt: 'Greet {{input.customerName}} and find out why they called.',
+ *   inputs: { customerName: input('customerName') },
+ *   callContext: out('start', 'callContext'),
+ *   voice: { model: 'gemini-3.1-flash-live-preview', persona: 'Kore' },
+ * }))
+ * ```
+ *
+ * Like `inlineAgent`, compile emits the node PLUS a stable
+ * `<source>/agent.json` sidecar. Unlike it, the turn's content comes from the
+ * call rather than from a user-prompt argument. Flow context can still be
+ * supplied through `inputs` and referenced from the system prompt. There are no
+ * declared `returns`: read the turn back as
+ * `out('<step>', 'uipath__agent_response_messages')`.
+ *
+ * @param inputs - The instructions, the call to join, and how the agent sounds.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function voiceAgent(inputs: VoiceAgentInputs): ActionSpec;
+/**
+ * A CONVERSATIONAL agent (`uipath.agent.conversational`) — it answers one turn
+ * of a live chat, reading the transcript rather than flow arguments.
+ *
+ * ```ts
+ * .trigger(conversationTrigger())
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * .step('reply', conversationalAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt: 'You are a support agent. Be brief.',
+ *   settings: { context: out('listen', 'conversationContext') },
+ * }))
+ * ```
+ *
+ * The reply is `out('<step>', 'uipath__agent_response_messages')` — the
+ * platform's own field name. Like `inlineAgent`, compile emits the node plus a
+ * stable `<source>/agent.json` sidecar.
+ *
+ * `sendMessage` is the alternative when the flow (not a model) decides what to
+ * say; this factory is for when the model does.
+ *
+ * @param inputs - The model, the instructions, and how the turn is bound.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export declare function conversationalAgent(inputs: ConversationalAgentInputs): ActionSpec;
+/**
+ * Declare an INLINE AUTONOMOUS AGENT — an agent defined inside this flow's own
+ * project rather than published to Orchestrator (`uipath.agent.autonomous`,
+ * `Orchestrator.StartInlineAgentJob`).
+ *
+ * @remarks
+ * **Two artifacts, not one.** The node carries the prompts and the variable
+ * descriptors, and it points at a directory — `source` — where the platform expects
+ * the agent's own configuration (flow-v1 emits `entryPoint: <source>/agent.json`).
+ * So `compile` writes `<source>/agent.json` beside the `.flow`, built from the same
+ * fields. Nothing to assemble by hand; `source` defaults to a uuid derived from the
+ * flow id and step name so a recompile is not a diff.
+ *
+ * **How this differs from `agent()`.** That one references something already
+ * published and started as an Orchestrator job; this one IS the definition, and the
+ * platform runs it inside the flow's own debug/publish context. The practical
+ * consequences: there is no folder, no release key and no binding pair here — and
+ * no `uip` verb that starts one headlessly either.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * Weaker than `agent()`'s, and in a specific way. `Orchestrator.StartInlineAgentJob`
+ * is Studio-Web-debug-only, so there is no Orchestrator job to point at and no
+ * headless verb that starts one. No local runner currently calls a model for this
+ * node either — an offline run asserts the WIRING and the declared `returns` shape,
+ * never that a model answered. Two differences would remain for any runner that did
+ * call one: knowledge grounding (a context handle) is a cloud-side index an offline
+ * path does not have, so the call would be ungrounded; and the node's `model` would
+ * have to be substituted for one reachable headlessly. Answer quality stays on the
+ * offline `expect` seeds; real behaviour needs a Studio Web debug run.
+ *
+ * @example
+ * **Classify an email with an agent defined inline**
+ * ```ts
+ * .step('triage', inlineAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt:
+ *     'You are a support triage assistant. Classify the email into exactly one ' +
+ *     'category and one priority. Return a result conforming to the output schema. ' +
+ *     'category: billing | technical | account. priority: low | normal | high.',
+ *   userPrompt: 'Classify this email:\n{{input.body}}',
+ *   inputs: { body: input('body') },
+ *   returns: { category: 'string', priority: 'string' },
+ * }))
+ * .return({ category: out('triage', 'category') })
+ * ```
+ *
+ * @param inputs - The agent defined in this project: its `model`,
+ * `systemPrompt`, `userPrompt`, and the `returns` fields it must produce.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export declare function inlineAgent(inputs: InlineAgentInputs): ActionSpec;

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

@@ -0,0 +1,143 @@
+/**
+ * The agents family's factories — `createOutgoingCall()`, `endCall()`,
+ * `voiceAgent()`, `conversationalAgent()` and `inlineAgent()`. 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';
+/**
+ * Place an outgoing phone call
+ * (`uipath.conversational.voice.create-outgoing-call`) and get back the
+ * `callContext` every other voice step is keyed by.
+ *
+ * ```ts
+ * .step('dial', createOutgoingCall({ from: '+15550001111', to: input('customerPhone') }))
+ * .step('talk', voiceAgent({
+ *   systemPrompt: 'Confirm the delivery window, then thank them.',
+ *   callContext: out('dial', 'callContext'),
+ * }))
+ * ```
+ *
+ * @param inputs - The provisioned `from` number and the `to` number to dial.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function createOutgoingCall(inputs) {
+    return builtinActionSpec({ kind: 'createOutgoingCall', inputs });
+}
+/**
+ * Hang up (`uipath.conversational.voice.end-call`). Reads
+ * `out('<step>', 'ended')`.
+ *
+ * @param inputs - The `callContext` of the call to end.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function endCall(inputs) {
+    return builtinActionSpec({ kind: 'endCall', inputs });
+}
+/**
+ * Put a VOICE agent on a live call (`uipath.agent.voice`) — it speaks and
+ * listens for one turn, then the flow continues.
+ *
+ * ```ts
+ * .trigger(voiceTrigger())
+ * .step('greet', voiceAgent({
+ *   systemPrompt: 'Greet {{input.customerName}} and find out why they called.',
+ *   inputs: { customerName: input('customerName') },
+ *   callContext: out('start', 'callContext'),
+ *   voice: { model: 'gemini-3.1-flash-live-preview', persona: 'Kore' },
+ * }))
+ * ```
+ *
+ * Like `inlineAgent`, compile emits the node PLUS a stable
+ * `<source>/agent.json` sidecar. Unlike it, the turn's content comes from the
+ * call rather than from a user-prompt argument. Flow context can still be
+ * supplied through `inputs` and referenced from the system prompt. There are no
+ * declared `returns`: read the turn back as
+ * `out('<step>', 'uipath__agent_response_messages')`.
+ *
+ * @param inputs - The instructions, the call to join, and how the agent sounds.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function voiceAgent(inputs) {
+    return builtinActionSpec({ kind: 'voiceAgent', inputs });
+}
+/**
+ * A CONVERSATIONAL agent (`uipath.agent.conversational`) — it answers one turn
+ * of a live chat, reading the transcript rather than flow arguments.
+ *
+ * ```ts
+ * .trigger(conversationTrigger())
+ * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
+ * .step('reply', conversationalAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt: 'You are a support agent. Be brief.',
+ *   settings: { context: out('listen', 'conversationContext') },
+ * }))
+ * ```
+ *
+ * The reply is `out('<step>', 'uipath__agent_response_messages')` — the
+ * platform's own field name. Like `inlineAgent`, compile emits the node plus a
+ * stable `<source>/agent.json` sidecar.
+ *
+ * `sendMessage` is the alternative when the flow (not a model) decides what to
+ * say; this factory is for when the model does.
+ *
+ * @param inputs - The model, the instructions, and how the turn is bound.
+ * @returns An action spec to pass to `.step(...)`.
+ */
+export function conversationalAgent(inputs) {
+    return builtinActionSpec({ kind: 'conversationalAgent', inputs });
+}
+/**
+ * Declare an INLINE AUTONOMOUS AGENT — an agent defined inside this flow's own
+ * project rather than published to Orchestrator (`uipath.agent.autonomous`,
+ * `Orchestrator.StartInlineAgentJob`).
+ *
+ * @remarks
+ * **Two artifacts, not one.** The node carries the prompts and the variable
+ * descriptors, and it points at a directory — `source` — where the platform expects
+ * the agent's own configuration (flow-v1 emits `entryPoint: <source>/agent.json`).
+ * So `compile` writes `<source>/agent.json` beside the `.flow`, built from the same
+ * fields. Nothing to assemble by hand; `source` defaults to a uuid derived from the
+ * flow id and step name so a recompile is not a diff.
+ *
+ * **How this differs from `agent()`.** That one references something already
+ * published and started as an Orchestrator job; this one IS the definition, and the
+ * platform runs it inside the flow's own debug/publish context. The practical
+ * consequences: there is no folder, no release key and no binding pair here — and
+ * no `uip` verb that starts one headlessly either.
+ *
+ * ── the live bar, stated ─────────────────────────────────────────────────────────
+ * Weaker than `agent()`'s, and in a specific way. `Orchestrator.StartInlineAgentJob`
+ * is Studio-Web-debug-only, so there is no Orchestrator job to point at and no
+ * headless verb that starts one. No local runner currently calls a model for this
+ * node either — an offline run asserts the WIRING and the declared `returns` shape,
+ * never that a model answered. Two differences would remain for any runner that did
+ * call one: knowledge grounding (a context handle) is a cloud-side index an offline
+ * path does not have, so the call would be ungrounded; and the node's `model` would
+ * have to be substituted for one reachable headlessly. Answer quality stays on the
+ * offline `expect` seeds; real behaviour needs a Studio Web debug run.
+ *
+ * @example
+ * **Classify an email with an agent defined inline**
+ * ```ts
+ * .step('triage', inlineAgent({
+ *   model: 'gpt-5.4',
+ *   systemPrompt:
+ *     'You are a support triage assistant. Classify the email into exactly one ' +
+ *     'category and one priority. Return a result conforming to the output schema. ' +
+ *     'category: billing | technical | account. priority: low | normal | high.',
+ *   userPrompt: 'Classify this email:\n{{input.body}}',
+ *   inputs: { body: input('body') },
+ *   returns: { category: 'string', priority: 'string' },
+ * }))
+ * .return({ category: out('triage', 'category') })
+ * ```
+ *
+ * @param inputs - The agent defined in this project: its `model`,
+ * `systemPrompt`, `userPrompt`, and the `returns` fields it must produce.
+ * @returns An action spec to pass to `.step(name, …)`.
+ */
+export function inlineAgent(inputs) {
+    return builtinActionSpec({ kind: 'inlineAgent', inputs });
+}

package/dist/nodes/agent/flow/family.d.ts

@@ -0,0 +1,3 @@
+/** The agents node family, as flow-node-registry.ts lists it: the inline, conversational and voice agents and the voice call steps. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const agentFlowFamily: FlowNodeFamily;

package/dist/nodes/agent/flow/family.js

@@ -0,0 +1,8 @@
+import { AGENT_DIAGNOSTICS } from './check.js';
+import { agentNodeTypes } from './node-type.js';
+export const agentFlowFamily = {
+    id: 'agent',
+    title: 'Agents',
+    types: agentNodeTypes,
+    diagnostics: AGENT_DIAGNOSTICS,
+};

package/dist/nodes/agent/flow/index.d.ts

@@ -0,0 +1,3 @@
+/** The agents family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/agent/flow/index.js

@@ -0,0 +1,3 @@
+/** The agents family's public surface, which the package entry re-exports. */
+export * from './spec.js';
+export * from './factories.js';

package/dist/nodes/agent/flow/inline-agent-lift.d.ts

@@ -0,0 +1,44 @@
+import { Expr } from '../../../core/expr.js';
+import type { FlowDeserializeContext, FlowPrintContext } from '../../../flow-node-type.js';
+/** The part of a `.flow` node the lift reads. */
+interface FlowNode {
+    id: string;
+    type: string;
+    typeVersion?: string;
+    display?: {
+        label?: unknown;
+    };
+    inputs?: Record<string, unknown>;
+}
+/** Where the agent's own `inputs` go in the option list: the printer writes them, as expressions. */
+declare const INPUT_ROWS: unique symbol;
+/** The lifted agent: its options in factory order, as source, and its input rows. */
+export interface LiftedInlineAgent {
+    kind: 'inlineAgent';
+    inputs: {
+        inputRows: Array<[string, Expr]>;
+        options: Array<[string, string | undefined | typeof INPUT_ROWS]>;
+    };
+}
+/**
+ * An AGENT and its attached resources — the inline autonomous agent, the
+ * conversational agent, and the voice agent.
+ *
+ * The cluster is a node plus artifact nodes on its `tool` / `context` /
+ * `escalation` / `memory` handles, so this walks those edges and recovers each
+ * resource as an argument rather than as a step (see {@link ARTIFACT_PORTS}).
+ *
+ * **The author's input NAMES are not recoverable, and that is by design.** The
+ * platform does not send an agent the names you declared: it keys each argument
+ * by the reference PATH, `__`-joined (`$vars.prep.output` → `prep__output`), and
+ * only those flat names survive in the emitted file. Recovery therefore uses
+ * them for both the `inputs` keys and the `{{input.…}}` placeholders — the same
+ * arguments reach the model, spelled the platform's way. (Node ids are
+ * preserved exactly; only these logical names change.)
+ */
+export declare function liftInlineAgent(node: FlowNode, ctx: FlowDeserializeContext): LiftedInlineAgent;
+export declare function printInlineAgent(spec: LiftedInlineAgent, ctx: FlowPrintContext): {
+    factory: string;
+    options: (readonly [string, string | undefined])[];
+};
+export {};