@uipath/skills 1.195.0

package/skills/uipath-agents/references/coded/quickstart.md

@@ -0,0 +1,333 @@
+# UiPath Coded Agents — Quickstart
+
+For initial project scaffolding, follow [lifecycle/setup.md](lifecycle/setup.md) — it covers preflight, framework selection, starting points, and the workflow.
+
+## Project State Detection (run once, before step 1)
+
+Inspect the working directory and its ancestors. Compute the variables below — every later step branches on them. Re-running the flow is safe: each step is gated on these signals and skips itself when its work is already done.
+
+| Variable | How to detect | Used by |
+|---|---|---|
+| `project_state` | `local-workspace` if any ancestor contains `.sw-path-marker` or `.local/folder.lock` (Studio Web–specific markers — `*.uipx` alone does NOT qualify). Else `existing-coded` if cwd has `pyproject.toml` with `uipath` dep + a `<framework>.json`. Else `greenfield`. | Steps 1, 2, 3, 8, 9 |
+| `framework` | Read from existing `<framework>.json` (`langgraph.json` / `llama_index.json` / `openai_agents.json` / `uipath.json` with `functions`). `none` if absent. | Step 1 |
+| `has_venv` | `.venv/` exists in cwd | Step 2 |
+| `has_entry_points` | `entry-points.json` exists | Steps 2, 6 |
+| `has_bindings` | `bindings.json` exists | Step 4 |
+| `has_smoke_set` | `evaluations/eval-sets/smoke-test.json` exists | Step 7 |
+| `has_evaluators` | any `evaluations/evaluators/*.json` exists | Step 7 |
+| `has_project_id` | `.env` contains `UIPATH_PROJECT_ID=<guid>` | Step 8 |
+
+When `project_state == local-workspace`, also read [lifecycle/local-workspace.md](lifecycle/local-workspace.md) for files-owned-by-Studio-Web and anti-patterns. The lifecycle itself is the One-Prompt Flow below — Local Workspace differs at step 8 (auto-sync replaces options A and B; the user is asked only C or Skip) and at step 9 (deploy options remain available, but Studio Web's publish-from-UI button is the most common path).
+
+**State signals are recomputed implicitly by reading the filesystem at the step that consumes them.** Steps that mutate state (Setup creates `.venv`; Build/Run can rerun `init` and update `entry-points.json`; Evaluate creates `evaluations/`; Delivery may write `UIPATH_PROJECT_ID` to `.env`) update the underlying files; later steps read fresh values, not the initial table. Treat the table above as a snapshot at flow start, not a frozen contract.
+
+## CLI Conventions
+
+| Command family | Accepts `--output json` |
+|---|---|
+| `uip login`, `uip login status`, `uip login tenant list`, `uip login tenant set`, `uip logout` | yes |
+| `uip codedagent setup` | yes |
+| `uip codedagent new`, `init`, `run`, `dev`, `eval`, `deploy`, `push`, `pull`, `invoke` | no (forwarded to the Python CLI) |
+
+Use `uip codedagent <cmd>`, not `uv run uipath <cmd>`. The wrapper injects session credentials (`UIPATH_URL`, `UIPATH_ACCESS_TOKEN`, org/tenant identifiers) from your `uip login` session into the Python subprocess; `uv run uipath` skips that injection.
+
+## Critical Rules
+
+- **NEVER add a `[build-system]` section to `pyproject.toml`**. No `hatchling`, no `setuptools`, no build backend. UiPath agents do not use a build system. Only include `[project]`, `[dependency-groups]`, and `[tool.*]` sections.
+- **Always create a smoke evaluation set.** Every agent must include `evaluations/eval-sets/smoke-test.json` with 2-3 test cases covering the primary happy path (not exhaustive error-case coverage — the smoke set exists to catch regressions, not to fully validate behavior). Create it in the Evaluate step, not during Build.
+- **Select a framework before writing any code.** If the prompt clearly implies a framework (e.g., mentions tools, RAG, multi-step orchestration, or a specific SDK), pick the best match. If the prompt is ambiguous, ask the user to choose from: Coded Function, LangGraph, LlamaIndex, or OpenAI Agents.
+- **Correct SDK import: `from uipath.platform import UiPath`** — not `from uipath import UiPath` (that path does not exist and will cause `ImportError`). Always instantiate `UiPath()` inside functions/nodes, never at module level.
+- **Refresh the CLI's Python executable path after venv changes.** If `uip codedagent` reports that the UiPath CLI/Python executable is not recognized, or any error indicates a stale `uipathExePath`, activate the project venv and run `uip codedagent setup --force`. This rewrites the CLI configuration to point at the current `.venv` executable.
+- **Auth check is one-shot.** Run `uip login status --output json` once, at step 5. If the user supplied environment + organization + tenant or explicitly asked to connect to a specific tenant, run the matching one-shot `uip login --organization "<ORG>" --tenant "<TENANT>" --output json` after the status check, even if another session is already logged in. Otherwise, the wrapper auto-refreshes tokens on subsequent cloud calls (no `uip login refresh` exists); re-auth only on a real `401`.
+- **Use `uip codedagent run` from non-interactive shells.** `uip codedagent dev` auto-appends `--interactive`.
+- **Runtime captures only the last node's delta as output.** `Annotated[list, operator.add]` reducers accumulate inside the graph but vanish from `--output-file` JSON and eval trajectories. Carry aggregate fields forward in each node's return (`{"items": [*state.get("items", []), x]}`) — see [frameworks/langgraph-integration.md](frameworks/langgraph-integration.md) § Runtime Output Quirk.
+- **Verify the JSON, not the streamed display.** After `uip codedagent run --output-file out.json`, inspect `out.json` — the streamed view shows per-node deltas; the JSON is the runtime's actual final result. Mismatches expose the runtime quirk above.
+- **Use `uip codedagent deploy` for packaging/publishing.** `uip codedagent pack` and `uip codedagent publish` are filtered by the wrapper.
+- **NEVER run `uip login` without `--tenant`.** The interactive tenant picker does not work from Claude's Bash tool. Use the one-shot form `uip login --organization "<ORG>" --tenant "<TENANT>"`, mapping staging/alpha to `--authority` (see [../authentication.md](../authentication.md)).
+- **Auth MUST be an interactive question only when needed and values are missing.** If the session check fails and the user did not provide all of environment / organization / tenant, your ENTIRE response must be a single direct question. Do NOT wrap it in bullet points, "Next Steps" headers, or status summaries. Just ask and stop:
+
+  > What is your UiPath **environment** (cloud/staging/alpha), **organization name**, and **tenant name**?
+- **In a flow, coded agents are referenced via the [`agent`](../../../uipath-maestro-flow/references/plugins/agent/) plugin** — node type `uipath.core.agent.{key}`, `Orchestrator.StartAgentJob`. See [flow-integration.md](flow-integration.md) for the three patterns: in-solution sibling folder, Orchestrator-published, tool resource.
+
+## Lifecycle Stages
+
+Each stage has a reference file with detailed instructions. Read **only** the relevant reference when you reach that stage — do not preload.
+
+| Stage | Reference | CLI Commands |
+|-------|-----------|-------------|
+| **Auth** | [../authentication.md](../authentication.md) | `uip login` |
+| **Setup** | [lifecycle/setup.md](lifecycle/setup.md) | `uv venv --python 3.13`, `source .venv/bin/activate`, `uip codedagent setup --force`, `uip codedagent new <name>`, `uv add <framework-package>`, `uv add uipath-dev --dev`, `uv sync`, `uip codedagent init` |
+| **Build** | [lifecycle/build.md](lifecycle/build.md) | Code agent logic with framework patterns |
+| **Bindings** | [lifecycle/bindings-reference.md](lifecycle/bindings-reference.md) | Sync resource overrides in `bindings.json` |
+| **Run** | [lifecycle/running-agents.md](lifecycle/running-agents.md) | `uip codedagent run` |
+| **Evaluate** | [lifecycle/evaluate.md](lifecycle/evaluate.md) | `uip codedagent eval` |
+| **Deploy** | [lifecycle/deployment.md](lifecycle/deployment.md) | `uip codedagent deploy`, `uip codedagent invoke` |
+| **Sync** | [lifecycle/file-sync.md](lifecycle/file-sync.md) | `uip codedagent push`, `uip codedagent pull` |
+| **Flow Integration** | [flow-integration.md](flow-integration.md) | Inline, published node, or tool resource in Flow |
+
+## Build Scenarios
+
+Two top-level build paths. Pick one before starting — the lifecycle and publish mechanism differ.
+
+- **Scenario 1 — Standalone Coded Agent** — the agent is its own tenant resource, published via `uip codedagent deploy`. Use when the agent runs on its own, is called from multiple flows, or needs independent versioning.
+- **Scenario 2 — In-Solution Coded Agent in a Flow** — the agent lives as a **sibling folder** to a flow project, registered into the solution via `uip solution project add`. The flow references it as an in-solution `uipath.core.agent.<resourceKey>` node, where `<resourceKey>` is the local UUID minted by `uip solution project add` and discoverable via `uip maestro flow registry list --local`. Use when the agent is tightly coupled to one flow.
+
+## Quick Start: Scenario 1 — Standalone Coded Agent
+
+When the user asks to create and deploy an agent end-to-end, follow these steps in order. Skip stages that are already done.
+
+**IMPORTANT: Do NOT stop between steps to ask "would you like me to continue?" or list next steps. Execute the entire flow automatically.** Pause only when (a) you hit an **architectural fork** — a step with multiple valid implementations (framework choice, HITL pattern, evaluator type, deploy target, conversational vs not, etc.) — or (b) you need data only the user has (credentials, project ID). At a fork, apply **infer-or-ask**: if the prompt or context names the choice, infer it and continue; otherwise output ONLY the choice question as your entire response, then STOP and wait. For missing data, output ONLY the data request. After getting the answer, resume immediately. Forks for each step are documented in that step's referenced file — read the reference when you reach the step; do not guess.
+
+Steps 8 and 9 are mandatory stops **for greenfield**: always ask, even if the user only said "build". Use `AskUserQuestion` (or platform equivalent); fall back to plain text only when no UI tool exists. They are **automatically resolved** for `local-workspace` (auto-sync) and for `existing-coded` with `has_project_id == true` (push) — see steps 8 and 9 for the branch logic.
+
+1. **Framework** — **Skip if `framework != none`** (already chosen — verify the right `<framework>.json` is present and continue). Else select per the [Framework Selection](#framework-selection) section below.
+2. **Setup** — Idempotent by `project_state` and `has_venv`:
+   - `local-workspace` → Studio Web already scaffolded `pyproject.toml` / `<framework>.json` / `entry-points.json` / `bindings.json`. Run **only** the venv prep block when `has_venv == false`:
+
+     ```bash
+     uv venv --python 3.13
+     source .venv/bin/activate                 # Windows: .venv\Scripts\activate
+     uv sync
+     uip codedagent setup --force
+     ```
+
+     If `has_venv == true`, just `source .venv/bin/activate` and continue. Do **not** run `uip codedagent new`. Re-run `init` only when schemas change — see step 6 for the full rule.
+   - `existing-coded` → `source .venv/bin/activate`. If `has_venv == false`, run `uv venv --python 3.13 && source .venv/bin/activate && uv sync`. Then `uip codedagent setup --force` (idempotent — refreshes `uipathExePath`). Skip `uip codedagent new`. Run `uip codedagent init` only if `has_entry_points == false` or schemas changed.
+   - `greenfield` → Full Workflow in [lifecycle/setup.md](lifecycle/setup.md). Infer the project name from the user's prompt or the current directory.
+
+   **Do NOT authenticate yet** — auth happens after build (step 5).
+
+   **Exception — Integration Service / SaaS-connector agents:** if the agent calls IS connector activities (`sdk.connections.invoke_activity`), you cannot author its `body_fields` / `ActivityMetadata` without `uip is resources describe` output, which is auth-gated. For these agents, do the step-5 auth one-shot **and** IS discovery (per [capabilities/integration-service.md](capabilities/integration-service.md) § Discovery) NOW, before Build, then resume at Build with the discovered metadata in hand. Non-IS agents keep the default order (auth after build).
+3. **Build** — Implement agent logic using the selected framework's patterns. **For `local-workspace`: skip only the scaffold-cleanup sub-step below** — Studio Web supplied a clean shell, so the module-level-client checks aren't needed. Logic edits in `main.py` proceed normally. For `greenfield` / `existing-coded`, after scaffolding and before running `uip codedagent init`, inspect the generated code and clean up scaffold hazards:
+   - No module-level `UiPathChat`, `UiPathAzureChatOpenAI`, `UiPath`, or other auth-dependent clients.
+   - Instantiate LLM/SDK clients inside graph nodes/functions only.
+   - Ensure importing `main.py` works without UiPath auth.
+
+   See [lifecycle/build.md](lifecycle/build.md) § Additional Instructions for the detailed Build-stage rules. After implementing, re-run `uip codedagent init` to update schemas from the actual code.
+4. **Bindings** — Sync `bindings.json` with the code using [lifecycle/bindings-reference.md](lifecycle/bindings-reference.md).
+5. **Auth (one-shot)** — Run `uip login status --output json` once. If the user supplied environment + organization + tenant, immediately run the matching one-shot login command from [../authentication.md](../authentication.md), using both `--organization` and `--tenant` in the same `uip login` command. Do this even when `Status: Logged in`, because the existing session may be for a different tenant. If no credentials were supplied and `Status: Logged in`, trust the wrapper for the rest of the run (it auto-refreshes tokens). Otherwise ask for credentials — output ONLY this question as your entire response:
+
+> What is your UiPath **environment** (cloud/staging/alpha), **organization name**, and **tenant name**?
+
+Then STOP and wait. On reply, run the matching one-shot login from [../authentication.md](../authentication.md) (maps environment → `--authority`). Never run `uip login` without `--tenant`.
+6. **Run** — Re-run `uip codedagent init` first whenever any of these changed since the last init, **or** when `has_entry_points == false`:
+   - `Input`/`Output`/`State` Pydantic models or TypedDicts — any field added, removed, renamed, or retyped counts (the class name being the same does not).
+   - The entry function's signature (parameters or return type annotation).
+   - `<framework>.json` (`langgraph.json` / `llama_index.json` / `openai_agents.json` / `uipath.json` `functions`).
+
+   Skip init only when the edit is purely inside node bodies / helpers (logic, prompts, business rules) and leaves every schema and the entry signature byte-identical. Then test locally with `uip codedagent run <ENTRYPOINT> '<input>'` (use the entrypoint name from `entry-points.json`, e.g., `main`).
+7. **Evaluate** — Run `uip codedagent eval <ENTRYPOINT> evaluations/eval-sets/smoke-test.json --no-report`. Idempotent by `has_evaluators` / `has_smoke_set`: create the missing one(s) only — **never overwrite an existing evaluator config or smoke set**, the user may have tuned them.
+
+   **Note:** `uipath-llm-judge-trajectory-similarity` requires emitted trace spans to populate `AgentRunHistory`. Plain `StateGraph` agents without explicit OpenTelemetry tracing produce empty history → all cases score 0.0 even on successful runs. If the smoke set scores 0.0, verify the agent actually executed (via local `uip codedagent run`) before treating it as a logic failure; consider an output-only evaluator for non-conversational graphs.
+
+   **If `has_evaluators == false`**, create `evaluations/evaluators/llm-judge-trajectory.json`. If the default `model` below is not available in the user's tenant, call `sdk.agenthub.get_available_llm_models()` and substitute a `model_name` from the returned list.
+
+   ```json
+   {
+     "version": "1.0",
+     "id": "LLMJudgeTrajectoryEvaluator",
+     "evaluatorTypeId": "uipath-llm-judge-trajectory-similarity",
+     "evaluatorConfig": {
+       "name": "LLMJudgeTrajectoryEvaluator",
+       "model": "gpt-4o-mini-2024-07-18",
+       "defaultEvaluationCriteria": {
+         "expectedAgentBehavior": "Agent should process the input and return a response."
+       }
+     }
+   }
+   ```
+
+   **If `has_smoke_set == false`**, create `evaluations/eval-sets/smoke-test.json` with 2-3 test cases based on the agent's input schema (version is string `"1.0"`, top-level `id`/`name` required, test cases in `evaluations` array):
+   ```json
+   {
+     "version": "1.0",
+     "id": "smoke-test",
+     "name": "Smoke Test",
+     "evaluatorRefs": ["LLMJudgeTrajectoryEvaluator"],
+     "evaluations": [
+       {
+         "id": "test-1",
+         "name": "Basic test",
+         "inputs": {"field": "value"},
+         "evaluationCriterias": {
+           "LLMJudgeTrajectoryEvaluator": {
+             "expectedAgentBehavior": "Agent should process the input and return a response."
+           }
+         }
+       }
+     ]
+   }
+   ```
+
+   **Finally**, run `uip codedagent eval <ENTRYPOINT> evaluations/eval-sets/smoke-test.json --no-report` (use the entrypoint name from `entry-points.json`).
+8. **Delivery target.** Single branch point. **Evaluate branches in order — Local Workspace projects also have `UIPATH_PROJECT_ID` set in `.env`, so the `local-workspace` check MUST come before the `has_project_id` check, or Local Workspace will incorrectly fall into the push branch:**
+
+   - **(1) `project_state == local-workspace`** → Studio Web auto-syncs saves to the remote SW project, so options A and B (manual push / solution upload) are skipped — they would be redundant or break sync identity. The user may still want a local dev console. Stop and ask via `AskUserQuestion` (header `"Delivery"`, `multiSelect: false`):
+
+     **Question:** *Studio Web is auto-syncing this workspace. Do you want a local dev console too?*
+
+     | # | Label (≤5 words) | Description |
+     |---|---|---|
+     | C | Local dev web server | I start `uip codedagent dev` (default `http://localhost:8080`) so you can interact with the agent in the browser. Studio Web continues to auto-sync. |
+     | — | Skip — continue to deploy | No console; proceed to step 9. |
+
+     On reply:
+     - **C** → run `uip codedagent dev` in the background; surface the URL. Prereq: `uipath-dev` (added during scaffold). **STOP — do NOT proceed to step 9.** Local dev is a terminal choice.
+     - **Skip** → continue to step 9.
+
+     Do **not** run `uip codedagent push` for this branch (that's recovery only — see [lifecycle/local-workspace.md](lifecycle/local-workspace.md) § Studio-Web-Auto-Sync). Do **not** present options A or B.
+   - **(2) `has_project_id == true` (cloud workspace, project ID already set)** → Run `uip codedagent push` to upload local edits, then continue to step 9. No fork question — the delivery choice was made in a prior session.
+   - **(3) Else (greenfield / cloud workspace not yet wired)** → Stop and ask via `AskUserQuestion` (header `"Delivery"`, `multiSelect: false`).
+
+     **Question:** *How do you want to use the agent next?*
+
+     | # | Label (≤5 words) | Description |
+     |---|---|---|
+     | A | Studio Web — you set it up | You open Studio Web, create a Coded Agent project inside a solution, paste the project ID. I'll write `UIPATH_PROJECT_ID` to `.env` and run `uip codedagent push`. |
+     | B | Studio Web — I package & upload | I run `uip solution init`, import the agent, strip `.venv`, and run `uip solution upload`. No Studio Web setup needed from you. |
+     | C | Local dev web server | I start `uip codedagent dev` (default `http://localhost:8080`) so you can interact with the agent in the browser. Nothing is published. |
+     | — | Skip — I'm done | Stop here. The agent is built and evaluated. |
+
+     On reply:
+     - **A** → wait for the project ID, write `UIPATH_PROJECT_ID=<id>` to `.env`, then run `uip codedagent push`.
+     - **B** → run the local-solution flow. `uip solution init "<SOLUTION_NAME>"` creates `<cwd>/<SOLUTION_NAME>/<SOLUTION_NAME>.uipx` (sibling, not ancestor). `uip solution upload` archives verbatim and does NOT honor `packOptions.directoriesExcluded` — strip `.venv` from the imported copy or upload fails with `code 20001: solution archive is corrupt`. From the parent directory of the agent:
+
+       ```bash
+       uip solution init "<SOLUTION_NAME>"
+       cd "<SOLUTION_NAME>"
+       uip solution project import --source "../<AGENT_PROJECT_DIR>" --output json
+       rm -rf "<AGENT_PROJECT_DIR>/.venv" "<AGENT_PROJECT_DIR>/__pycache__" \
+              "<AGENT_PROJECT_DIR>/__uipath" "<AGENT_PROJECT_DIR>/eval-results.json"
+       uip solution upload . --output json
+       ```
+     - **C** → run `uip codedagent dev` in the background; surface the URL (default `http://localhost:8080`). Prereq: `uipath-dev` (added during scaffold). **STOP — do NOT proceed to step 9.** Local dev is a terminal choice.
+     - **Skip** → continue to step 9.
+
+9. **Deploy.** Reachable from any `project_state` after option **Skip** at step 8 (greenfield or local-workspace), after the auto-push in branch (2), or after options **A** / **B** in greenfield. After option **C** at step 8, the run ends — do not ask. Stop and ask via `AskUserQuestion` (header `"Deploy target"`, `multiSelect: false`).
+
+   **Question:** *Do you want to deploy the agent? If yes, which target?*
+
+   | # | Label (≤5 words) | Description |
+   |---|---|---|
+   | A | Personal workspace | Run `uip codedagent deploy --my-workspace`. |
+   | B | Tenant feed | Run `uip codedagent deploy --tenant`. |
+   | C | Specific folder | Ask for the folder name, then run `uip codedagent deploy --folder "<Name>"`. |
+   | — | Skip deployment | Stop here. |
+
+   On reply, run `uip codedagent deploy <target-flag>`. If re-deploying, bump the patch version in `pyproject.toml` first.
+
+   > **For `project_state == local-workspace`:** the user can still choose A/B/C to publish a package via `uip codedagent deploy` — that targets package feeds (personal workspace / tenant / folder) **outside** the Studio Web project lifecycle. It is a separate distribution path from Studio Web's own publish-from-UI button, which remains available in the SW browser. Skip deployment is the most common answer here, since Studio Web's publish UI typically covers the user's intent.
+
+10. **Continue to flow wiring if the prompt asked for it.** If the original request also describes wiring the agent into a Maestro Flow (phrases like *"use that agent in a flow"*, *"build a flow that calls it"*, *"hand off to maestro flow"*, *"wire the agent in as a node"*), deploy is not the final step. Do the hand-off **with a tool call, not narration** — invoke the `Skill` tool with `skill: uipath-maestro-flow` directly; do NOT emit a text-only "now switching to the flow skill" message in place of the invocation.
+
+    For a Published coded agent, the flow project lives in its OWN directory, NOT as a sibling of the coded agent. After loading the `uipath-maestro-flow` skill, refresh the registry (`uip maestro flow registry pull --force`) so the just-deployed agent is discoverable, then author the flow per the `uipath-maestro-flow` skill's workflow. Done when the requested `.flow` file exists and `uip maestro flow validate` passes on it.
+
+Read the relevant reference file at each step — do not guess.
+
+## Quick Start: Scenario 2 — In-Solution Coded Agent in a Flow
+
+Use when the coded agent is tightly coupled to one flow and lives as a sibling folder inside the same solution. The agent is wired to the flow via `--local` registry discovery — no separate Orchestrator deployment for the agent, no separate skill hand-off. **`uipath-agents` owns this scenario end-to-end** — solution scaffolding, flow scaffolding, agent build, registration, and flow wiring all happen here. Do not invoke `uipath-maestro-flow` as a separate skill; run the maestro-flow CLI commands directly from this workflow.
+
+Execute the following in order, end-to-end, in one pass — do not pause for confirmation between steps.
+
+1. **Scaffold the solution.** From the working directory:
+
+   ```bash
+   uip solution init "<SolutionName>" --output json
+   ```
+
+   Creates `<SolutionName>/<SolutionName>.uipx`. All subsequent project paths are relative to the solution root.
+
+2. **Scaffold the flow project inside the solution** (the layout is always double-nested `<Solution>/<Flow>/<Flow>.flow`):
+
+   ```bash
+   cd "<SolutionName>"
+   uip maestro flow init "<FlowName>" --output json
+   ```
+
+   This auto-registers the flow as a project in the solution.
+
+3. **Scaffold the coded agent as a sibling folder.** From the solution root (still inside `<SolutionName>/`):
+
+   ```bash
+   uv venv --python 3.13
+   source .venv/bin/activate        # .venv\Scripts\activate on Windows
+   uv add <framework-package>       # e.g. uipath-langchain for LangGraph
+   uv add uipath-dev --dev
+   uv sync
+   uip codedagent setup --force
+   uip codedagent new "<AgentName>"
+   ```
+
+   Result: `<SolutionName>/<AgentName>/` sibling to `<SolutionName>/<FlowName>/`.
+
+4. **Implement the agent's `main.py`** with lazy LLM initialization (LLM clients inside graph nodes only — never at module top level), then regenerate entry-points / bindings:
+
+   ```bash
+   cd "<AgentName>"
+   uip codedagent init
+   ```
+
+   Refer to [frameworks/](frameworks/) for the chosen framework's patterns. Verify locally with `uip codedagent run <entrypoint> '<input>'`.
+
+5. **Register the agent in the solution.** This step mints the `resource.key` UUID the flow node will reference:
+
+   ```bash
+   cd ..
+   uip solution project add "<AgentName>" "<SolutionName>.uipx" --output json
+   ```
+
+   After this command, `resources/solution_folder/process/agent/<AgentName>.json` holds the `resource.key`. Read that file (or the `--output json` response) to capture the UUID — it is what the flow node's `type` (`uipath.core.agent.<resourceKey>`) and `model.bindings.resourceKey` will reference.
+
+6. **Discover the agent's flow-side definition** (no `uip login` required for `--local`):
+
+   ```bash
+   cd "<FlowName>"
+   uip maestro flow registry list --local --output json
+   uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json
+   ```
+
+   The second command's `Data.Node` object is what gets pasted verbatim into the flow's top-level `definitions[]` array.
+
+7. **Wire the agent node into the `.flow` file.** Edit `<FlowName>.flow` directly:
+   - Add a `uipath.core.agent.<resourceKey>` node to `nodes[]` with `inputs.detail` matching the agent's input schema and `model.section: "In this solution"`.
+   - Add the definition from step 6 to `definitions[]`.
+   - Add a top-level `bindings[]` entry for the agent (no duplicates per `(resourceKey, propertyAttribute)`).
+   - Add edges from upstream nodes to the agent's input port and from its output port downstream.
+
+   See [embedding-in-flows.md](embedding-in-flows.md) for the directory layout and [flow-integration.md § Pattern 1](flow-integration.md#pattern-1-in-solution-coded-agent) for the JSON shape.
+
+8. **Validate and format:**
+
+   ```bash
+   uip maestro flow validate "<FlowName>.flow" --output json
+   uip maestro flow format "<FlowName>.flow" --output json
+   ```
+
+   Resolve any validation errors before declaring the scenario complete. Done when both commands return success and the flow file contains the wired agent node.
+
+## Framework Selection
+
+Infer the framework from the user's prompt when possible. If ambiguous, ask them to choose:
+
+1. **Coded Function** — Plain Python with `Input`/`Output` models. No LLM. Best for deterministic logic.
+2. **LangGraph** — StateGraph with conditional routing, tool use, interrupts. Best for complex LLM agents.
+3. **LlamaIndex** — Workflow with events and RAG support. Best for knowledge retrieval.
+4. **OpenAI Agents** — Lightweight agent with tools and handoffs. Best for simple LLM agents; lacks HITL, process invocation, and state persistence.
+
+**Inference hints:** mentions of tools/tool calling, multi-step, or orchestration → LangGraph. RAG or knowledge retrieval → LlamaIndex. Simple handoffs or lightweight LLM → OpenAI Agents. No LLM needed → Coded Function. Summarize / research / synthesize over PDF or TXT (incl. bucket files, attachments) → not a framework choice — see [capabilities/deeprag/planning.md](capabilities/deeprag/planning.md). Per-row CSV extraction → see [capabilities/batch-transform/planning.md](capabilities/batch-transform/planning.md). When in doubt, ask.
+
+**Always tell the user which framework you selected and why** before proceeding to build. Example: "I'll use **LangGraph** for this agent since it involves tool calling and multi-step orchestration."
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Project authors cannot be empty` | Missing `authors` in `pyproject.toml` | Add `authors = [{ name = "Your Name" }]` to `[project]` section |
+| `Version already exists` on deploy | Same version already published | Bump patch version in `pyproject.toml` before re-deploying |
+| `Your local version is behind...Aborted!` | Push needs interactive confirmation | Use `uip codedagent push --overwrite` to force push |
+
+## Resources
+
+- **UiPath Python SDK**: https://uipath.github.io/uipath-python/
+- **UiPath Evaluations**: https://uipath.github.io/uipath-python/eval/

package/skills/uipath-agents/references/coded-vs-lowcode-guide.md

@@ -0,0 +1,115 @@
+# Coded vs Low-Code Agent Selection Guide
+
+Reference for comparing **coded** (Python) and **low-code** (agent.json) agents. Use this when the user needs help deciding which mode to choose.
+
+## Capability Matrix
+
+| Capability | Low-code | Coded |
+|---|:---:|:---:|
+| Build without writing Python | ✅ | ❌ |
+| Call UiPath processes / API workflows as tools | ✅ | ✅ |
+| Use Integration Service connectors | ✅ | ✅ |
+| RAG over Context Grounding index | ✅ | ✅ |
+| Use third-party Python libraries | ❌ | ✅ |
+| Custom LLM state machine (LangGraph StateGraph) | ❌ | ✅ |
+| Human-in-the-loop | ✅ escalation | ✅ `interrupt()` |
+| Complex conditional HITL resume logic | ❌ | ✅ |
+| Studio Web Agent Builder canvas | ✅ | Optional |
+| `@mockable` for evaluation isolation | ❌ | ✅ |
+| Full runtime control over LLM prompts | ❌ | ✅ |
+| Multi-model / multi-framework strategies | ❌ | ✅ |
+| Fastest path to first working agent | ✅ | ❌ |
+| Embed inline in a flow project | ✅ | ❌ |
+| Embed as sibling project in same solution | ✅ | ✅ |
+| Invoke as published agent node in a flow | ✅ | ✅ |
+| Use as tool resource for another agent in a flow | ✅ | ✅ |
+| Solution-level deployment with resource provisioning | ✅ | ❌ |
+
+## Key Differences
+
+| Aspect | Coded | Low-code |
+|--------|-------|----------|
+| Language | Python | Declarative JSON (`agent.json`) |
+| CLI | `uip codedagent` | `uip agent` + `uip solution` |
+| Project marker | `pyproject.toml` + `.py` files | `agent.json` + `project.uiproj` |
+| Frameworks | LangGraph, LlamaIndex, OpenAI Agents, Coded Function | None (prompt + tools config) |
+| Deployment | `uip codedagent deploy` | `uip solution pack/publish/deploy` |
+| Local testing | `uip codedagent run` | Studio Web only |
+| Evaluations | `uip codedagent eval` (13 evaluator types) | Not available |
+| Flow integration | Inline, published node, tool resource (3 patterns) | Inline, published, solution, external, tool resource (5 patterns) |
+| Solution support | Standalone projects | Full solution lifecycle |
+| Custom code | Full Python | None |
+| Sync | `uip codedagent push/pull` | `uip solution upload` |
+
+## Solution-Level Mixing
+
+A UiPath solution can contain **both** coded and low-code agent projects. Each project is independently one mode or the other — there is no hybrid within a single project.
+
+### Pattern 1: Low-code orchestrator calling coded agent as tool
+
+The low-code agent adds the coded agent as an **external tool** in its `resources[]` array:
+
+```jsonc
+{
+  "$resourceType": "tool",
+  "type": "agent",
+  "location": "external",
+  "properties": {
+    "processName": "MyCodedAgent",
+    "folderPath": "Shared/CodedAgents"
+  }
+}
+```
+
+The coded agent must be deployed to Orchestrator first via `uip codedagent deploy`.
+
+### Pattern 2: Coded agent invoking low-code agent via SDK
+
+The coded agent calls the deployed low-code agent as an Orchestrator process:
+
+```python
+sdk = UiPath()
+result = await sdk.processes.invoke(
+    name="MySolution.agent.MyLowCodeAgent",
+    folder_path="Shared/MySolution",
+    input_arguments={"userInput": "Hello"}
+)
+```
+
+The low-code agent must be deployed via `uip solution deploy` first.
+
+### Pattern 3: Mixed solution
+
+A solution contains both project types, deployed together:
+
+```
+MySolution/
+├── LowCodeAgent/      ← agent.json (low-code)
+├── CodedAgent/        ← pyproject.toml + .py (coded)
+├── resources/
+└── MySolution.uipx
+```
+
+Each agent type uses its own CLI and lifecycle. The solution's `uip solution deploy` handles both.
+
+## Interop Mechanisms
+
+| From | To | Mechanism |
+|------|----|-----------|
+| Low-code | Coded (deployed) | Agent tool resource with `location: "external"` in `agent.json` |
+| Coded | Low-code (deployed) | `sdk.processes.invoke()` targeting the deployed agent process |
+| Low-code | Low-code (same solution) | Agent tool resource with `location: "solution"` in `agent.json` |
+| Low-code | Low-code (different solution) | Agent tool resource with `location: "external"` in `agent.json` |
+| Coded | Coded | `workflows.*` or `sdk.processes.invoke()` |
+| Flow | Coded (deployed) | Published agent node (`uipath.core.agent.{key}`) in the flow |
+| Flow | Low-code (deployed) | Published agent node (`uipath.core.agent.{key}`) in the flow |
+| Flow (inline low-code agent) | Coded (deployed) | Tool resource (`uipath.agent.resource.tool.agent`) wired to the agent |
+
+### Flow Integration Details
+
+- **Low-code agents** support 5 Flow patterns: inline embedding, published node, solution-level, external, and tool resource
+- **Coded agents** support 3 Flow patterns: in-solution sibling project (`uipath.core.agent.<resourceKey>` with `section: "In this solution"`), published node (`uipath.core.agent.<resourceKey>` via `uip codedagent deploy`), and tool resource
+- **Low-code inline embedding**: `uip agent init --inline-in-flow` creates a `<projectId-uuid>` subdirectory inside the flow project
+- **Coded solution-level embedding**: The coded agent lives as a sibling folder to the flow project; `uip solution project add` mints the `resource.key` that the flow's `uipath.core.agent.<resourceKey>` node references, discoverable via `uip maestro flow registry list --local` (see [coded/embedding-in-flows.md](coded/embedding-in-flows.md))
+- Node types differ by pattern: inline low-code uses `uipath.agent.autonomous`; every other case (published low-code, in-solution coded, published coded) uses `uipath.core.agent.{key}`
+- For coded agent Flow integration details, see [coded/flow-integration.md](coded/flow-integration.md)

package/skills/uipath-agents/references/context-grounding-patterns.md

@@ -0,0 +1,52 @@
+# Context Grounding Patterns — When to Use What
+
+Shared decision logic for picking the right context-grounding mode and surface.
+
+## BatchTransform vs DeepRAG — Pick by File Type
+
+| Input file | Mode |
+|---|---|
+| `.csv` | **BatchTransform** |
+| `.pdf` / `.txt` | **DeepRAG** |
+
+Hard rule: BatchTransform accepts CSV only; DeepRAG accepts PDF or TXT only. No subjective tiebreaker.
+
+## The Three Modes
+
+| Mode | Input | What it does | Best for |
+|---|---|---|---|
+| **BatchTransform (BT)** | CSV | Iterate every row of the CSV (CSV is the datasource — hosted in a context-grounding index purely so the runtime can iterate), apply the same prompt to each row, optionally augment with a per-row web search, write augmented rows (original columns + new LLM-filled columns) to an Orchestrator bucket attachment. | Bulk extraction, per-row classification, address-match validation, vendor enrichment, sales-order triage. One row in, one row out. |
+| **DeepRAG** | PDF / TXT | Iterative research-and-synthesis pass over an ephemeral index built from runtime attachments. Returns a single grounded narrative with citations (optional bounding-box anchors). Handles large files and produces longer / denser output than `analyze-attachments`. | Summarize / research / synthesize across one or more runtime documents — especially when the file is large or the answer needs citations. One question, one answer. Prefer over `analyze-attachments` (lower page limits, one-shot synthesis). |
+| **Index search** (semantic / structured) | Pre-built index | Query a stable, pre-built context-grounding index. Returns ranked snippets. | Stable knowledge bases (policies, manuals, FAQs) — corpus does not change per run. |
+
+## Decision Matrix
+
+Route by file type first, signal second:
+
+| File type | User signal | Mode | Where to go |
+|---|---|---|---|
+| `.csv` | "add columns" / "classify every row" / "enrich vendor addresses" / "MCC categorization" / "1000 rows of structured output" | **BatchTransform** | Coded: [coded/capabilities/batch-transform/planning.md](coded/capabilities/batch-transform/planning.md). Low-code: [lowcode/capabilities/built-in-tools/batch-transform/planning.md](lowcode/capabilities/built-in-tools/batch-transform/planning.md). |
+| `.pdf` / `.txt` | "summarize" / "research across these docs" / "one narrative answer" | **DeepRAG** | Coded: [coded/capabilities/deeprag/planning.md](coded/capabilities/deeprag/planning.md). Low-code: [lowcode/capabilities/built-in-tools/deeprag/planning.md](lowcode/capabilities/built-in-tools/deeprag/planning.md). |
+| pre-built index, no file upload | "search the policy KB" / "look up X in our docs" | **Index search** | `sdk.context_grounding.unified_search_async` or low-code Context tool — see [coded/capabilities/context-grounding.md](coded/capabilities/context-grounding.md). |
+
+## Surface Selection
+
+Once the mode is picked, route by execution surface:
+
+| Surface signal | BatchTransform | DeepRAG |
+|---|---|---|
+| Project has `pyproject.toml` + `langgraph.json`, or user wants Python | [coded/capabilities/batch-transform/planning.md](coded/capabilities/batch-transform/planning.md) | [coded/capabilities/deeprag/planning.md](coded/capabilities/deeprag/planning.md) |
+| Project has `agent.json` with `"type": "lowCode"`, or user is building in Studio Web Agent Builder | [lowcode/capabilities/built-in-tools/batch-transform/planning.md](lowcode/capabilities/built-in-tools/batch-transform/planning.md) | [lowcode/capabilities/built-in-tools/deeprag/planning.md](lowcode/capabilities/built-in-tools/deeprag/planning.md) |
+
+Both surfaces hit the same backend per mode. The difference is **how** the agent invokes the mode, not what the mode does.
+
+## Cross-Surface Invariants
+
+These hold regardless of mode or surface:
+
+1. **The hosted file is a datasource for iteration (BT) or grounding (DR), not the other way around.** BatchTransform iterates rows from a CSV-backed context-grounding index; DeepRAG synthesizes across a PDF/TXT-backed index. Per-row external grounding for BT comes from `enable_web_search_grounding`, not the index.
+2. **`prompt` is required.** Empty → `400 "The Prompt field is required."` BatchTransform additionally requires `output_columns` (each with `name` + `description`).
+3. **Output destination differs by mode.** BatchTransform produces an augmented CSV server-side. Coded resume: the runtime downloads it to the local `destination_path` you supplied. Low-code: it is delivered as an Orchestrator bucket attachment for downstream consumers. DeepRAG returns content (`text` + optional `citations`) inline on the resume value.
+4. **Folder context is required.** Explicit folder key/path or env var. Missing → `400 "A folder is required for this action."`
+5. **Permissions live on the folder.** Coded: the invoking user's role must grant the index permission. Low-code: the agent's runtime identity must have it in the folder where the agent is published. `403 "User is missing required index permissions."` → switch folders (personal workspace is the safe default for self-serve).
+6. **Async / event-driven.** Both modes are long-running. Coded agents use plain `interrupt()` with the matching `Create*` / `Wait*` resume-trigger models from `uipath.platform.common`; low-code agents get this for free via the runtime.