@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/core/actions.js

@@ -145,199 +145,6 @@ export function builtinTriggerSpec(spec) {
 export function ixpExtract(inputs) {
     return builtinActionSpec({ kind: 'ixpExtract', inputs });
 }
-/**
- * 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 });
-}
-/**
- * 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 });
-}
-/**
- * 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 });
-}
 export function connector(a, b, c, d) {
     if (typeof a === 'string') {
         const opts = (d ?? {});

package/dist/core/agent-sidecar.d.ts

@@ -0,0 +1,186 @@
+/** One agent's declared inputs as the platform sees them — see {@link agentInputPlan}. */
+export interface AgentInputPlan {
+    byName: Map<string, AgentInputBinding>;
+    refs: Array<{
+        flatName: string;
+        binding: string;
+    }>;
+}
+/**
+ * What one declared agent input turns into on the platform.
+ *
+ *  - `ref` — a single source reference. It gets a JobArgument named `flatName`,
+ *    so it gets a descriptor entry, an `inputSchema` key and a prompt token.
+ *  - `literal` — a constant. There is NO JobArgument for one: v1 prunes a literal
+ *    binding as un-re-derivable (`deriveAgentInputVariables`'s doc block,
+ *    `:477-481`), so an `{{input.x}}` token for it would never substitute. The
+ *    value is INLINED into the agent.json prompt instead.
+ *  - `expression` — a computed expression spanning zero or several references.
+ *    No single JobArgument can exist, so there is no honest name to emit, and
+ *    the author's placeholder has nothing to point at — `check`'s
+ *    `INLINE_AGENT_COMPOSITE_INPUT` says so and names the fix (compute it in a
+ *    script step first).
+ */
+export type AgentInputBinding = {
+    kind: 'ref';
+    flatName: string;
+    binding: string;
+} | {
+    kind: 'literal';
+    text: string;
+} | {
+    kind: 'expression';
+    binding: string;
+};
+/**
+ * The platform-facing plan for one inline agent's declared inputs.
+ *
+ * Built once and used by all three agent-facing sites (the node's
+ * `agentInputVariables`, the sidecar's `inputSchema`, and both prompts), so they
+ * cannot drift apart.
+ *
+ * `refs` is DEDUPED BY FLAT NAME and keeps author order. Two logical names bound
+ * to the same reference are one JobArgument on the platform (v1 dedupes on a
+ * seen-set, `:490-522`), so emitting two descriptors would claim an argument that
+ * will not exist.
+ */
+export declare function agentInputPlan(inputs: Record<string, unknown>, render: (value: unknown) => unknown): AgentInputPlan;
+/**
+ * The `agent.json` sidecar for a text CONVERSATIONAL agent.
+ *
+ * The inline agent's shape minus the argument plumbing: the turn arrives as the
+ * conversation transcript, so there is no `inputSchema` keyed by flat names and
+ * no `outputSchema` (the definition declares
+ * `uipath__agent_response_messages`). `metadata.isConversational` is what tells
+ * the platform's own storage layer which kind of agent this is.
+ */
+export declare function conversationalAgentJson(spec: {
+    model: string;
+    systemPrompt: string;
+    temperature?: number;
+    maxTokenPerResponse?: number;
+    maxIterations?: number;
+    guardrails?: unknown[];
+    source: string;
+    name: string;
+}): any;
+/**
+ * The `agent.json` sidecar for a VOICE agent.
+ *
+ * The text agent's shape with voice-specific settings. The turn arrives as
+ * audio, while optional flow context is delivered through `inputSchema` and
+ * `{{input.…}}` system-prompt placeholders. There is no `outputSchema` (the
+ * definition declares what comes back), and `settings.voice` carries the
+ * audio configuration in the storage layer's own `StoredVoiceSettings` shape
+ * (`model` / `maxTokens` / `temperature` / `persona`) — with the platform's
+ * catalog defaults filled in, because its own writer treats a partial voice
+ * block as incomplete.
+ */
+export declare function voiceAgentJson(spec: {
+    systemPrompt: string;
+    plan: AgentInputPlan;
+    voice?: {
+        model?: string;
+        persona?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+    maxIterations?: number;
+    source: string;
+    name: string;
+}): any;
+/**
+ * The `agent.json` an inline agent's `source` directory must hold.
+ *
+ * The node is only half of an inline agent. flow-v1's `handleInlineAgentJob` emits
+ * `entryPoint: "<source>/agent.json"` into the BPMN context, and the runtime
+ * resolves the agent's real configuration — model settings, the message list, the
+ * input/output schemas — from that file relative to the project. A `.flow` with an
+ * inline-agent node and no such file references a definition that is not there.
+ *
+ * Shape transcribed from deployed agents under `runs/` (e.g. the four DevCon
+ * billing agents, `type: 'lowCode'`), which is also what
+ * `uip agent init --inline-in-flow` scaffolds. The `version` is
+ * {@link AGENT_DEFINITION_VERSION}, not the `1.1.0` those older agents carry. `contentTokens` mirrors `content` as
+ * one `simpleText` run: the designer uses those tokens to render a prompt with
+ * inline variable chips, and a single run is the faithful encoding of a plain
+ * string.
+ */
+export declare function inlineAgentJson(spec: {
+    model: string;
+    systemPrompt: string;
+    userPrompt: string;
+    /**
+     * The platform-facing plan for `inputs` — see {@link agentInputPlan}. The
+     * sidecar speaks FLAT NAMES throughout (schema keys, prompt text, tokens);
+     * the author's logical names never appear in this file.
+     */
+    plan: AgentInputPlan;
+    returns: Record<string, string>;
+    temperature?: number;
+    maxTokenPerResponse?: number;
+    maxIterations?: number;
+    /** Harness mode; the sidecar's `settings.mode` (`'standard'` when omitted). */
+    mode?: string;
+    /** Guardrail array, stored verbatim as the sidecar's own `guardrails`. */
+    guardrails?: unknown[];
+    /** The agent's own directory uuid — its `projectId`/`id`, and the node's `inputs.source`. */
+    source: string;
+    /** The agent's display name (the step's label). */
+    name: string;
+}): any;
+/** Which writer produced an `agent.json`: the inline, conversational or voice agent's. */
+export type AgentSidecarDialect = 'inline' | 'conversational' | 'voice';
+/**
+ * The agent configuration a SHELL agent node keeps in its sidecar, read from
+ * `<source>/agent.json` in the node's own input names: the prompts, the model,
+ * the run settings (`temperature`, `maxTokenPerResponse`, `maxIterations`,
+ * `mode`), the `guardrails` and (voice) the `voice` settings. Empty when the
+ * node carries prompts itself (an embedded node, e.g. a `.flow` saved by Studio
+ * Web with the self-contained flag on), or when no sidecar can be read.
+ *
+ * A run setting equal to the default a sidecar writer fills in (`temperature`
+ * 0, `maxTokens` 16384, `mode` `'standard'`) is not recovered: recompiling
+ * without it writes the same sidecar, and recovering it would add an argument
+ * the author never wrote to every agent. `mode: 'standard'` is the exception on
+ * a 1.3 node, where naming it is what selected that definition. The same goes
+ * for the inline agent's `maxIterations` 25: the SDK omits it when unset, but
+ * Studio Web always writes it (its `getDefaultAgentContent()` default), so
+ * every Studio Web-saved agent would otherwise decompile with `maxIterations: 25`.
+ */
+export declare function agentSidecarInputs(o: {
+    /** The node's id, for the warnings. */
+    nodeId: string;
+    /** The node's own `inputs`. */
+    inputs: Record<string, unknown>;
+    /** The node's `inputs.source`, unwrapped from its envelope. */
+    source: string | undefined;
+    /** Which writer produced the sidecar. */
+    dialect: AgentSidecarDialect;
+    /** A file beside the `.flow`, by its path relative to it; undefined when it is not there. */
+    read: ((path: string) => string | undefined) | undefined;
+    warn(message: string): void;
+}): Record<string, unknown>;
+/**
+ * Where an agent schema property points to declare "this is a FILE":
+ * `{ $ref: JOB_ATTACHMENT_REF }`, with {@link jobAttachmentDefinition} under the
+ * same schema's `definitions['job-attachment']`.
+ */
+export declare const JOB_ATTACHMENT_REF = "#/definitions/job-attachment";
+/**
+ * The canonical `job-attachment` definition an agent schema's file field
+ * `$ref`s into — the uipath-agents skill's `agent-definition.md` § File
+ * Attachments ("Schema is fixed — copy verbatim"), and the same block the
+ * platform's own analyze-attachments tool contract carries.
+ *
+ * It tells the agent runtime that an input is an Orchestrator attachment, so a
+ * file tool (Analyze Files) can resolve the attachment's `ID`.
+ *
+ * A function, not a shared object: each schema gets its own copy, so an edit
+ * to one emitted file cannot reach another.
+ *
+ * (The case serializer keeps its own copy in `case/entry-points.ts`: that one
+ * mirrors the platform's `entry-points.json` packager byte for byte, and its
+ * `MimeType` description differs.)
+ */
+export declare function jobAttachmentDefinition(): Record<string, unknown>;