# Inline Agent in a Flow Walkthrough for embedding a low-code autonomous agent directly inside a flow project. The agent lives as a UUID-named subdirectory inside the flow project and is published with the parent flow. Flow authoring itself is the responsibility of the `uipath-maestro-flow` skill — this file covers only the inline-agent side (creating the agent subdirectory, configuring it, and the shape of the `uipath.agent.autonomous` flow node that references it). ## When to Use - Agent is tightly coupled to this specific flow - No need for separate versioning, evaluation, or reuse across flows - Fastest to set up — no separate agent project required ## Standalone vs Inline | Aspect | Standalone | Inline | |--------|-----------|--------| | Location | Own project in solution | Subdirectory inside flow project, named by projectId (UUID) | | Files | agent.json, entry-points.json, project.uiproj, flow-layout.json, evals/ | agent.json, flow-layout.json (`{}`), evals/eval-sets/ (empty), features/, resources/ | | Lifecycle | Independent publish | Published with parent flow | | Best for | Agent runs on its own or is referenced externally | Agent is a step within a flow | ## Inline Agent Directory Structure An inline agent lives in a subdirectory named after its `projectId` (a UUID). It contains `agent.json`, an empty `flow-layout.json`, and empty scaffold directories: ``` / ├── .flow ├── project.uiproj # Flow's project file ├── / # Inline agent subdirectory (UUID as folder name) ← inputs.source points here │ ├── agent.json # Agent definition (same schema as standalone — see ../../agent-definition.md) │ ├── flow-layout.json # Empty: {} │ ├── evals/ │ │ └── eval-sets/ # Empty (no evaluators for inline agents) │ ├── features/ # Empty │ └── resources/ # Agent resources (tools, contexts, escalations) └── ... ``` ### Key differences from standalone agent - **Folder name** is the agent's `projectId` UUID, not a human-readable name - **`flow-layout.json`** is an empty JSON object `{}` - **No `entry-points.json`** — the flow handles entry points - **No `project.uiproj`** — governed by the parent flow project - **`evals/`** contains only the `eval-sets/` subdirectory (empty) — no evaluators - Has a root-level `guardrails: []` field - No `metadata.targetRuntime` ## Creating an Inline Agent ### Option A: CLI command (recommended) ```bash uip agent init "" --inline-in-flow --output json ``` This generates a UUID for the `projectId`, creates the subdirectory `//`, and scaffolds `agent.json`, `flow-layout.json`, and empty directories. > The scaffold sets `settings.model: "gpt-4o-2024-11-20"` (stale) and empty prompts. **Override the model** (`uip agent model list` → [model-selection-guide.md](../../model-selection-guide.md)) and write robust prompts ([prompting/agent-prompting-guide.md](../../prompting/agent-prompting-guide.md)) before validating. ### Option B: Manual creation #### Step 1: Start with an existing flow project The flow project must already exist. #### Step 2: Generate a UUID and create the agent subdirectory Generate a unique UUID (e.g., `5029c8a8-799b-426a-803f-c4ec75255439`). Create a directory with that UUID as the name inside the flow project. #### Step 3: Create agent.json Same schema as a standalone agent (see [../../agent-definition.md](../../agent-definition.md)), with these conventions: - `projectId` matches the folder name UUID - `inputSchema.properties`: one `__output__` key per flow input — **mandatory**. See [§ Wiring Flow Inputs Into an Inline Agent](#wiring-flow-inputs-into-an-inline-agent-required). - `messages[].content`: reference inputs as `{{input.__output__}}` (the `input.` form). Then run `uip agent refresh` to regenerate `contentTokens` from `content` — don't hand-author them. See [§ Wiring Flow Inputs Into an Inline Agent](#wiring-flow-inputs-into-an-inline-agent-required). - `guardrails: []` at root level — can be populated with guardrail objects. See [../guardrails/guardrails.md](../guardrails/guardrails.md) - No `metadata.targetRuntime` field Example: ```json { "version": "1.1.0", "settings": { "model": "anthropic.claude-sonnet-4-6", "maxTokens": 16384, "temperature": 0, "engine": "basic-v2", "maxIterations": 25, "mode": "standard" }, "inputSchema": { "type": "object", "properties": {} }, "outputSchema": { "type": "object", "properties": { "content": { "type": "string", "description": "Output content" } } }, "metadata": { "storageVersion": "50.0.0", "isConversational": false, "showProjectCreationExperience": false }, "type": "lowCode", "guardrails": [], "messages": [ { "role": "system", "content": "", "contentTokens": [] }, { "role": "user", "content": "", "contentTokens": [] } ], "projectId": "5029c8a8-799b-426a-803f-c4ec75255439" } ``` #### Step 4: Create flow-layout.json ```json {} ``` #### Step 5: Create empty directories ``` evals/eval-sets/ features/ resources/ ``` ## Wiring Flow Inputs Into an Inline Agent (required) **The CLI does not derive the input wiring** — you author it; `refresh` only regenerates `contentTokens` from `content` (it does not fill `inputSchema` or `agentInputVariables`). `flow validate` *does* catch a prompt↔schema mismatch (a `{{input.K}}` that's malformed or names a key not in `inputSchema`), but **not** a missing/wrong node `agentInputVariables` binding — that delivery gap surfaces only at `flow debug`. This skill authors the **`agent.json` side** (flatten rule: `$vars..output.` → `__output__`): - `inputSchema.properties` — one `__output__` key per input (mandatory; binds the delivered `JobArguments` into the agent's `input`). Empty schema → the agent sees the literal `input.` token even when the value arrived. - `messages[].content` — reference each input as `{{input.__output__}}` (the `input.` form, **not** `$vars`), plus a real system prompt. `content` is the source of truth; run `uip agent refresh` to generate the matching `contentTokens` from it (don't hand-author them). ```json "inputSchema": { "properties": { "start__output__disputeSummary": { "type": "string", "description": "Bound from $vars.start.output.disputeSummary" } } }, "messages": [{ "role": "user", "content": "Write a billing resolution email for this dispute:\n{{input.start__output__disputeSummary}}" }] ``` The **flow side** — the trigger global and the node `agentInputVariables[]` binding (the only thing the converter turns into `JobArguments`) — is authored through the `uipath-maestro-flow` skill (Critical Rule 15). The full four-piece contract, the converter behavior, and the `content`↔`contentTokens` invariant + validator errors all live there: [inline-agent prompt-wiring guide § Wiring Flow Variables into Agent Prompts](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). ## Refresh and Validate Inline Agent ```bash uip agent refresh "/" --inline-in-flow --output json uip agent validate "/" --inline-in-flow --output json ``` `--inline-in-flow` skips the `entry-points.json` / `project.uiproj` checks. In inline mode `refresh` regenerates `messages[].contentTokens` (from `content`) and `bindings_v2.json` — **not** `entry-points.json` (standalone only). `validate` is read-only (it flags `contentTokens` drift but doesn't repair it — fix by re-running `refresh`). **Verify at `flow debug`, not after refresh:** `refresh` never fills `inputSchema` — it is non-empty only because you authored it (`DerivedFiles: 0` is normal and does **not** mean input is missing). The end-to-end check (run `uip maestro flow debug` and confirm the agent resolves the input rather than echoing the literal `input.` token) is owned by the `uipath-maestro-flow` skill — see its [inline-agent guide § Debug](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#debug). For inline agents with external capabilities (tools, contexts, memory spaces, or escalations), pass `--bindings-target` to **`refresh`** after all flow graph edits: ```bash uip agent refresh "/" --inline-in-flow \ --bindings-target "/bindings_v2.json" --output json ``` `--bindings-target` propagates the inline agent's bindings (process, connection, index, memorySpace, app, etc.) into the flow project's `bindings_v2.json`. This is required for `uip solution resources refresh` to discover the bindings and create solution-level resource files. Never hand-edit `bindings_v2.json`. > **Ordering constraint:** run the final `uip agent refresh --inline-in-flow --bindings-target …` after all flow graph edits are complete. The `uipath-maestro-flow` skill owns direct `.flow` authoring for the inline-agent node, capability-resource nodes, and edges; refresh last so the generated bindings land in the flow project's `bindings_v2.json` before `uip solution resources refresh`. See the [Walkthrough](#walkthrough--end-to-end) for the correct sequence. ## Flow Wiring After creating the inline agent, the flow needs a `uipath.agent.autonomous` node whose `inputs.source` is the inline agent's `projectId` UUID, plus edges connecting it to the rest of the flow. **Hand off to the `uipath-maestro-flow` skill for the actual node and edge authoring.** Per Critical Rule 15, this skill does not invoke flow operations directly. Tell the user: > The inline agent has been scaffolded at `//`. To wire it into the flow, use the `uipath-maestro-flow` skill — pass it `projectId = ` so it can add a `uipath.agent.autonomous` node with `inputs.source = ` and connect the input/success edges via direct `.flow` authoring. **After all flow graph edits are complete**, run `uip agent refresh --inline-in-flow`, then `uip agent validate --inline-in-flow`; for inline agents with external capabilities, include `--bindings-target /bindings_v2.json` on the refresh call. The node JSON shape that the flow skill must produce is documented in § Flow Node Structure below — keep it as a reference, not as a CLI walkthrough. ## Inline-in-Flow Resource Paths Inline-agent resources — `tool`, `context`, `escalation` — share one path convention. Memory spaces are features, not `resources/` files; add them with `uip agent memory add ... --path /` and see [../memory/memory.md](../memory/memory.md). **Path:** `//resources//resource.json` `` is a fresh UUID. It MUST match (a) the resource node's `inputs.source` in the flow and (b) the `id` field inside `resource.json`. The resource directory name is the UUID — never the human-readable resource name. Human-readable folder names are the standalone-agent convention; inline agents always use UUIDs. Resource body shape is identical to the standalone-agent docs — only the folder name differs: - Tools (`process` / `agent` / `api` / `processOrchestration`): [../process/process.md](../process/process.md) § Subtypes and § Tool resource.json Shape. Discovery is identical (`uip solution resources list` + `uip solution resources get`); subtype is selected by the `type` field. - Context index: [../context/index.md](../context/index.md) § Agent-Level Resource Shape. - Escalation: [../escalation/escalation.md](../escalation/escalation.md) § Agent-Level Resource. ### Tool-specific notes - **`location`**: Follows the same rule as standalone agents — set `"solution"` when the row from `uip solution resources list` has `Source: "Local"`, set `"external"` when `Source: "Remote"`. See [../process/process.md](../process/process.md) and [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Rule 12. - **`properties.folderPath`**: Must be the **literal folder path from discovery** (e.g., `"Shared/Sales"`) — do **not** leave it empty. An empty `folderPath` prevents `uip solution resources refresh` from resolving the tool at runtime. - **`inputSchema.properties`**: Must include `"guardrails": { "type": "array" }` alongside the tool arguments — the runtime expects it. - **All fields from the template in [../process/process.md](../process/process.md) are required** — especially `$resourceType: "tool"`, `guardrail`, `properties.processName`, `properties.exampleCalls`, `isEnabled`, and `argumentProperties`. A `resource.json` missing `$resourceType` will not be recognized by `uip agent validate` (the tool reports `"resources": 0`); `uip agent refresh` will then write an empty `bindings_v2.json`. ## Flow Node Structure ### Node type | Node type | Description | |-----------|-------------| | `uipath.agent.autonomous` | Autonomous reasoning agent embedded in the flow | ### `.flow` node JSON ```jsonc { "id": "autonomousAgent1", "type": "uipath.agent.autonomous", "typeVersion": "1.0", "display": { "label": "Autonomous Agent" }, "inputs": { "source": "", // UUID linking to the inline agent directory "agentInputVariables": [], "agentOutputVariables": [ { "id": "content", "type": "string" } ] }, "outputs": { "output": { "type": "object", "description": "Agent response", "source": "=result.response", "var": "output" }, "error": { "type": "object", "description": "Error information if the node fails", "source": "=Error", "var": "error" } } } ``` **Critical fields:** - `inputs.source` — The inline agent's `projectId` UUID. Must match the subdirectory name and `agent.json.projectId` inside the flow project. The definition still declares `model.source: true`, but flow-core hoists that identity field onto `inputs.source` for the `uipath.agent.autonomous` node instance. - `inputs.systemPrompt` / `inputs.userPrompt` — **do not write these keys.** A prompt string on the node makes the flow converter drop every `agentInputVariables[]` entry the prompt text does not reference. Empty strings fail `uip maestro flow validate`. The canonical prompts live in `agent.json.messages[]`. Validator behavior and the older-CLI fallback: [inline-agent guide § Refresh and Validate](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#refresh-and-validate). - `definitions[]` — The `uipath.agent.autonomous` definition copied from the flow registry supplies `model.serviceType: "Orchestrator.StartInlineAgentJob"`, BPMN type, version, and context. Do not copy those fields into the node instance. - No node instance `model` block — the inline-agent source lives at `inputs.source`. Resource nodes use the same `inputs.source` pattern as the autonomous agent — no instance `model` block. The `type` follows the per-kind patterns in § Resource nodes below — `uipath.agent.resource.tool.{process|agent|api|processorchestration}.`, where `` is the resource's release-key GUID returned by `uip solution resources list`: ```jsonc { "id": "agentTool1", "type": "uipath.agent.resource.tool..", "typeVersion": "", "display": { "label": "" }, "inputs": { "source": "" } } ``` The definition declares `model.source: true`; flow-core hoists that identity field onto the node instance as `inputs.source` (same hoisting rule as `uipath.agent.autonomous`). The same shape applies to `uipath.agent.resource.escalation.*` and `uipath.agent.resource.context.*` nodes. ### Handles | Handle | Position | Allowed connections | |--------|----------|---------------------| | `escalation` | top | `uipath.agent.resource.escalation.*` | | `context` | bottom | `uipath.agent.resource.context.*` | | `tool` | bottom | `uipath.agent.resource.tool.*` | | `input` | left | Previous flow node | | `success` | right | Next flow node | | `error` | right | Error handler (when enabled) | ### Resource nodes (tools, contexts, escalations) Resources are separate canvas nodes wired to the agent via artifact handle edges: ```jsonc // Edge connecting tool to agent: // sourceNodeId: "autonomousAgent1", sourcePort: "tool" // targetNodeId: "agentTool1", targetPort: "input" ``` | Resource type | Node type pattern | |--------------|-------------------| | RPA process | `uipath.agent.resource.tool.process.` | | Agent-as-tool | `uipath.agent.resource.tool.agent.` | | API workflow | `uipath.agent.resource.tool.api.` | | Process Orchestration | `uipath.agent.resource.tool.processorchestration.` | | Built-in tool | `uipath.agent.resource.tool.builtin.` | | IS connector | `uipath.agent.resource.tool.connector` | | Semantic index | `uipath.agent.resource.context.index..` | | Escalation | `uipath.agent.resource.escalation.` (e.g. `.coded-action-app`; discover with `uip maestro flow registry search "escalation"`) | | Memory space | `uipath.agent.resource.memory.*` canvas node, backed by `features//feature.json` from `uip agent memory` | `` is the resource's release-key GUID from `uip solution resources list` (the row's `Key` field). The four process-tool kinds share the same registry-discovery flow and the same `resource.json` shape — only the prefix in front of `` and the `type` field in `resource.json` differ. See [../process/process.md](../process/process.md) § Subtypes. ## Walkthrough — End-to-End ```bash # 1. Ensure solution and flow project exist # (use uipath-maestro-flow skill to create them, or start from existing) # 2. Scaffold the inline agent inside the flow project uip agent init "" --inline-in-flow --output json # Returns the generated projectId (UUID) and path # 3. Edit the agent.json inside // # - Set system prompt in messages[0].content + rebuild contentTokens # - Set model in settings.model # - Configure outputSchema if needed # 4. Add tools to //resources/ (optional) # See § Inline-in-Flow Resource Paths above for the exact format # 5. Hand off to the uipath-maestro-flow skill to add the # uipath.agent.autonomous node (inputs.source = ), # tool resource nodes, and wire all edges (input/success/tool). # Do NOT run uip maestro flow commands from this skill — # Critical Rule 15. # 6. Refresh — regenerates entry-points.json and bindings_v2.json, # and (with --bindings-target) propagates capability bindings into the flow # project's bindings_v2.json so resource refresh can discover them. # MUST run AFTER flow graph edits (step 5). uip agent refresh "/" --inline-in-flow \ --bindings-target "/bindings_v2.json" --output json # 7. Validate the inline agent (read-only check). uip agent validate "/" --inline-in-flow --output json # 8. Refresh solution resources and upload uip solution resources refresh --output json ``` ## What Happens at Pack Time `flow-workbench` extracts inline agents during `uip solution upload` / `uip solution pack`: 1. Reads the inline agent directory referenced by `inputs.source` UUID 2. Collects connected resource nodes via artifact handles 3. Packages the `AgentDefinition` from the inline agent's `agent.json` 4. Writes into package: ``` content/ ├── process.bpmn ├── operate.json # contentType: "Flow" ├── entry-points.json # type: "processorchestration" ├── bindings_v2.json └── agents/ └── / ├── agent.json # Extracted AgentDefinition └── .agent-builder/ ├── agent.json # Execution model └── bindings.json ``` ## Node Type Quick Reference ``` uipath.agent.autonomous ← Inline agent node uipath.agent.resource.tool.process. ← Tool: RPA process uipath.agent.resource.tool.agent. ← Tool: agent uipath.agent.resource.tool.api. ← Tool: API workflow uipath.agent.resource.tool.processorchestration. ← Tool: process orchestration uipath.agent.resource.tool.connector ← Tool: IS connector uipath.agent.resource.tool.builtin. ← Tool: built-in uipath.agent.resource.context.index.. ← Context: semantic index uipath.agent.resource.escalation. ← Escalation: HITL (e.g. .coded-action-app) uipath.agent.resource.memory.* ← Memory space canvas node; feature file lives under features/ ``` ## BPMN Execution Engine Notes - **Inline agents**: `ServiceTask` with `serviceType: "Orchestrator.StartInlineAgentJob"`. The agent definition is read from the inline agent directory (`inputs.source` UUID) and executed in-process. The execution is asynchronous. The flow pauses at the agent node and resumes when the agent job completes. ## Gotchas See [../../critical-rules/autonomous-critical-rules.md](../../critical-rules/autonomous-critical-rules.md) Critical Rule 1. The skill explicitly defers flow authoring to `uipath-maestro-flow` — it does not invoke that skill automatically ([../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Critical Rule 15). **Capability bindings must be propagated to the flow project's `bindings_v2.json`.** Only project-level bindings are scanned by `uip solution resources refresh`. Pass `--bindings-target /bindings_v2.json` to `uip agent refresh --inline-in-flow` — refresh is the command that writes the bindings. Without project-level propagation, Studio Web debug can fail because no solution-level resource file is created for the external capability. Run the final `uip agent refresh --inline-in-flow --bindings-target …` as the **last step** before `uip solution resources refresh`, after all flow graph edits are complete. See the [Walkthrough](#walkthrough--end-to-end) for the correct sequence. ## References - [../../agent-definition.md](../../agent-definition.md) — agent.json schema (same as standalone, with the inline-specific differences listed above) - [../../critical-rules/autonomous-critical-rules.md](../../critical-rules/autonomous-critical-rules.md) Critical Rule 1