fix(uipath-agents): install the framework package before codedagent new and verify the scaffold

skills/uipath-agents/SKILL.md

@@ -13,16 +13,16 @@
 - Treat "build/create/scaffold/implement a UiPath agent" as the full One-Prompt Flow by default. Do not stop after file creation or local run unless the user explicitly says to stop there.
 - A normal completion point is after smoke eval and the mandatory Delivery fork question. A final build summary before that is premature unless run/eval is blocked or the user opted out.
 <!--skill-flavor:solution-verb-probe:start-->
 - **Probe the `solution` verb once per session before the first scaffold or deploy.** Run `uip solution init --help --output json`. Result `Success` → use `solution init` and `solution deploy run --parent-folder-path` / `--parent-folder-key` (post-rename, default). `unknown command` / non-zero exit → CLI predates the rename; substitute `uip solution new <Name>` and `--folder-path` / `--folder-key` (same arguments otherwise) wherever this skill calls those.
 <!--skill-flavor:solution-verb-probe:end-->
-- **Greenfield coded agents — scaffold with `uip codedagent new`, never hand-author the project.** Building a NEW coded agent from scratch: always create it with `uip codedagent new <name>`, then generate schemas with `uip codedagent init` — never hand-write `pyproject.toml` / `main.py` / `langgraph.json` / `entry-points.json` yourself, even for a trivial agent. Hand-authoring skips required project structure and produces invalid packages. (Existing or Studio Web local-workspace projects: do NOT run `uip codedagent new` — follow the project-state gating in [coded/quickstart.md](references/coded/quickstart.md).)
+- **Greenfield coded agents — scaffold with `uip codedagent new`, never hand-author the project.** Building a NEW coded agent from scratch: install the framework package in the active venv first, then always create the project with `uip codedagent new <name>` and generate schemas with `uip codedagent init` — never hand-write `pyproject.toml` / `main.py` / `langgraph.json` / `entry-points.json` yourself, even for a trivial agent. Hand-authoring skips required project structure and produces invalid packages. The installed framework package selects the scaffold (`uipath new` defaults to `--type auto`); after `new`, confirm `<framework>.json` exists — recovery is in [coded/lifecycle/setup.md](references/coded/lifecycle/setup.md) § Verify the Scaffold. (Existing or Studio Web local-workspace projects: do NOT run `uip codedagent new` — follow the project-state gating in [coded/quickstart.md](references/coded/quickstart.md).)
 - **Coded agents only — bindings are always derived from UiPath Python SDK calls and must never be hand-authored.** To derive them, always run the sync workflow in [coded/lifecycle/bindings-reference.md](references/coded/lifecycle/bindings-reference.md) — scan code, regenerate `bindings.json`. Without this, resources cannot be overridden per execution environment and will always default to the hardcoded values in the SDK calls. Derive bindings whenever you add, remove, or modify any UiPath SDK resource call — for instance `assets`, `queues`, `processes`, `buckets`, `indexes`, `connections`, `apps`, `MCP servers`, or `InvokeProcess|CreateTask|CreateEscalation(...)`.
 
 ## Project Type Detection
 
 Determine the agent mode before proceeding:
 
-1. **First — confirm this is an agent, not a Coded Function.** If `uipath.json` declares a `functions` map — a Python entrypoint (e.g. `"functions": {"main": "main.py:main"}`, sibling `pyproject.toml`) or a JS/TS one (e.g. `"functions": {"invoice": "functions/invoice.ts:default"}`, sibling `package.json`) — the project is a **Coded Function**, not an agent. Stop here and use the [`uipath-functions`](/uipath:uipath-functions) skill instead. Functions are deterministic, do not reason via LLM, and have a distinct lifecycle (`uip function new/pack/publish/run`; `init` is Python-only).
+1. **First — confirm this is an agent, not a Coded Function.** If `uipath.json` declares a `functions` map — a Python entrypoint (e.g. `"functions": {"main": "main.py:main"}`, sibling `pyproject.toml`) or a JS/TS one (e.g. `"functions": {"invoice": "functions/invoice.ts:default"}`, sibling `package.json`) — the project is a **Coded Function**, not an agent. Stop here and use the [`uipath-functions`](/uipath:uipath-functions) skill instead. Functions are deterministic, do not reason via LLM, and have a distinct lifecycle (`uip function new/pack/publish/run`; `init` is Python-only). Exception: a `functions` map you produced yourself moments ago by running `uip codedagent new` without the framework package installed is a mis-scaffold, not a Coded Function — re-scaffold per [coded/lifecycle/setup.md](references/coded/lifecycle/setup.md) § Verify the Scaffold instead of handing off.
 2. **Check for existing agent project files** in the working directory:
    - `pyproject.toml` + `.py` files + a framework dep (`uipath-langchain`, `uipath-llamaindex`, or `uipath-openai-agents`) → **Coded**. The framework package already declares `uipath` as a dependency, so an explicit `uipath` entry is not required.
    - `agent.json` with `"type": "lowCode"` + `project.uiproj`, AND no `pyproject.toml` → **Low-code**

skills/uipath-agents/references/coded/embedding-in-flows.md

@@ -56,15 +56,21 @@ If the solution and flow project don't yet exist, run `uip solution init "<Solut
    cd <CodedAgentProject>
    uv venv --python 3.13
    source .venv/bin/activate       # .venv/Scripts/activate on Windows
-   uv pip install <FRAMEWORK_PACKAGE>   # e.g. uipath for Coded Function
+   uv pip install <FRAMEWORK_PACKAGE>   # e.g. uipath-langchain for LangGraph
    uip codedagent setup --force
    uip codedagent new <agent-name>
    uv sync
    ```
 
+   Confirm `<framework>.json` exists before continuing — a `uipath.json` `functions` map without it is a function scaffold (see [lifecycle/setup.md](lifecycle/setup.md) § Verify the Scaffold).
+
    For a simple stub with no LLM call, use the Coded Function framework
-   (`uipath` package). This avoids downloading the full LangGraph or
-   LlamaIndex stack and keeps the setup fast.
+   (`uipath` package only): `uv pip install uipath`, then
+   `uip codedagent new <agent-name> --type function`. If that fails with
+   `No such option '--type'`, the venv's `uipath` predates the option — re-run
+   without the flag, which produces the same function scaffold while no
+   framework package is installed. This avoids downloading the full LangGraph
+   or LlamaIndex stack and keeps the setup fast.
 
 2. Implement `main.py`. Use lazy LLM initialization (create clients inside functions, never at module level).
 

skills/uipath-agents/references/coded/frameworks/langgraph-integration.md

@@ -13,7 +13,7 @@ uip codedagent new my-agent
 
 This generates `main.py` (with a StateGraph template), `langgraph.json`, and `pyproject.toml`. Then modify `main.py` to implement your actual agent logic.
 
-> **Prerequisite:** `uipath-langchain` must be installed for the LangGraph template to be used. If you get a base template instead, install `uipath-langchain` first.
+> **Prerequisite:** `uipath-langchain` must be installed in the active venv before `new` — `uipath new` defaults to `--type auto` and picks the LangGraph template from the installed package. Confirm `langgraph.json` exists after `new`; if `uipath.json` with a `functions` map appeared instead, the package was missing — recover per [../lifecycle/setup.md](../lifecycle/setup.md) § Verify the Scaffold.
 
 ## Project Structure
 

skills/uipath-agents/references/coded/frameworks/llamaindex-integration.md

@@ -13,7 +13,7 @@ uip codedagent new my-agent
 
 This generates `main.py` (with a Workflow template), `llama_index.json`, and `pyproject.toml`. Then modify `main.py` to implement your actual agent logic.
 
-> **Prerequisite:** `uipath-llamaindex` must be installed for the LlamaIndex template to be used.
+> **Prerequisite:** `uipath-llamaindex` must be installed in the active venv before `new` — `uipath new` defaults to `--type auto` and picks the LlamaIndex template from the installed package. Confirm `llama_index.json` exists after `new`; if `uipath.json` with a `functions` map appeared instead, the package was missing — recover per [../lifecycle/setup.md](../lifecycle/setup.md) § Verify the Scaffold.
 
 ## Project Structure
 

skills/uipath-agents/references/coded/frameworks/openai-agents-integration.md

@@ -17,7 +17,7 @@ uip codedagent new my-agent
 
 This generates `main.py` (with an Agent + tool template), `openai_agents.json`, `AGENTS.md`, and `pyproject.toml`. Then modify `main.py` to implement your actual agent logic.
 
-> **Prerequisite:** `uipath-openai-agents` must be installed for the OpenAI Agents template to be used.
+> **Prerequisite:** `uipath-openai-agents` must be installed in the active venv before `new` — `uipath new` defaults to `--type auto` and picks the OpenAI Agents template from the installed package. Confirm `openai_agents.json` exists after `new`; if `uipath.json` with a `functions` map appeared instead, the package was missing — recover per [../lifecycle/setup.md](../lifecycle/setup.md) § Verify the Scaffold.
 
 ## Project Structure
 

skills/uipath-agents/references/coded/lifecycle/build.md

@@ -48,7 +48,7 @@ Load capability references **only if the task requires them** — do not preload
 - **Select a framework before writing any code.** Infer from the prompt if possible (tools/orchestration → LangGraph, RAG → LlamaIndex, simple LLM → OpenAI Agents, no LLM → Coded Function). If ambiguous, ask the user to choose.
 - **Structured input contract → not OpenAI Agents.** OpenAI Agents always require a `messages` input field and cannot express an input contract without it (see `../frameworks/openai-agents-integration.md` § Input). When the user needs a strict typed/structured input (e.g. a single named field, no `messages`), choose LangGraph (custom `StateGraph` with arbitrary input state) instead. Do NOT silently fall back to a Coded Function to satisfy the input shape — a Coded Function produces `ProjectType: Function`, not a coded agent, so it does not fulfill a request for an agent.
 - **Read ONLY the single framework reference** for the selected framework before writing code. Do NOT read other framework references or capability references unless the task explicitly requires that capability.
-- **Clean generated scaffold code before schema init.** After `uip codedagent new` and before running `uip codedagent init`, inspect `main.py` and remove 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.
+- **Clean generated scaffold code before schema init.** After `uip codedagent new` and before running `uip codedagent init`, first confirm `<framework>.json` exists (a `uipath.json` `functions` map with no `<framework>.json` is a function scaffold — re-scaffold per [setup.md](setup.md) § Verify the Scaffold), then inspect `main.py` and remove 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.
 - **NEVER instantiate LLM clients or SDK clients at module level.** `uip codedagent init` imports your Python file to introspect schemas — module-level `UiPathAzureChatOpenAI()`, `UiPathChat()`, `UiPathChatOpenAI()`, or `UiPath()` will fail because auth may not have happened yet. Always create these instances inside functions or graph nodes, never at the top level of the module.
 - **Correct SDK import: `from uipath.platform import UiPath`** — not `from uipath import UiPath` (that does not exist). Instantiate inside functions only: `sdk = UiPath()`.
 - LangGraph agents get tracing automatically — no `@traced()` needed on graph nodes.

skills/uipath-agents/references/coded/lifecycle/setup.md

@@ -10,11 +10,13 @@ which uip > /dev/null 2>&1 || echo "install uip: npm install -g @uipath/cli"
 
 ## Framework Selection
 
-Pick the framework before starting. The package installed in the Workflow determines which scaffold `uip codedagent new` produces.
+Pick the framework before starting: the package installed in the active venv selects the agent template, and there is no flag for naming it. Install exactly one `<FRAMEWORK_PACKAGE>` before `new`, not after — with several installed, `new` fails and names them.
+
+`uip codedagent new` asks `uipath new` for an agent scaffold (`--type agent`) whenever the installed `uipath` accepts that option, so a missing framework package fails with an error naming what to install. An older `uip` or `uipath` leaves the choice to `uipath new`'s `--type auto` default, which silently produces a Coded Function scaffold (`uipath.json` with a `functions` map, no `<framework>.json`) instead. § Verify the Scaffold covers both symptoms.
 
 | Agent Type | `<FRAMEWORK_PACKAGE>` | Framework config | Guide |
 |---|---|---|---|
-| LangGraph | `"uipath-langchain"` | `langgraph.json` | [langgraph-integration.md](../frameworks/langgraph-integration.md) |
+| LangGraph | `uipath-langchain` | `langgraph.json` | [langgraph-integration.md](../frameworks/langgraph-integration.md) |
 | LlamaIndex | `uipath-llamaindex` | `llama_index.json` | [llamaindex-integration.md](../frameworks/llamaindex-integration.md) |
 | OpenAI Agents | `uipath-openai-agents` | `openai_agents.json` | [openai-agents-integration.md](../frameworks/openai-agents-integration.md) |
 
@@ -36,6 +38,7 @@ source .venv/bin/activate                    # Windows: .venv\Scripts\activate
 uv pip install <FRAMEWORK_PACKAGE>
 uip codedagent setup --force
 uip codedagent new <PROJECT_NAME>
+# verify: <framework>.json must exist — see § Verify the Scaffold
 uv add uipath-dev --dev                      # required by `uip codedagent dev` (local dev web server)
 uv sync
 uip codedagent init
@@ -45,9 +48,18 @@ uip codedagent init
 
 **What `uip codedagent setup` does:** locates a Python that has `uipath` installed and caches its path, so later commands (`init`/`run`/`eval`/`pack`) can invoke the Python SDK. It searches PATH (`python3.x`, `python3`, `python`) and uses your `.venv` only when activated. So when using uv, always `uv sync` then activate the venv before the `setup` command.
 
+## Verify the Scaffold
+
+After `uip codedagent new`, check the directory before running anything else:
+
+1. `<framework>.json` present (`langgraph.json` / `llama_index.json` / `openai_agents.json`) → agent scaffold. Continue.
+2. `uipath.json` with a `functions` map and no `<framework>.json` → function scaffold: `<FRAMEWORK_PACKAGE>` was not installed in the active venv when `new` ran, on a `uip` or `uipath` old enough that `--type auto` made the choice. Fix: `uv pip install <FRAMEWORK_PACKAGE>`, confirm `uip codedagent setup --force` reports the same venv, delete `main.py`, `pyproject.toml`, `uipath.json`, then re-run `uip codedagent new <PROJECT_NAME>`. Do not hand-write `<framework>.json` on top of the function scaffold, and do not hand off to `uipath-functions` — the project was never meant to be a function.
+3. `No agent framework integration is installed` (or `The '<FRAMEWORK_PACKAGE>' package is required to scaffold a '<framework>' agent`) → same cause as 2, reported by a CLI that forwards `--type agent` instead of falling back to a function scaffold. Nothing was generated. Fix: `uv pip install <FRAMEWORK_PACKAGE>`, then re-run `uip codedagent new <PROJECT_NAME>`.
+4. `Multiple agent frameworks are installed` → keep exactly one framework package in the venv (`uv pip uninstall` the others), then re-run `new`.
+
 ## Coded Function Agents
 
-`uipath.json` carries the entrypoint mapping:
+Ask for one explicitly: `uip codedagent new <PROJECT_NAME> --type function`. Only the `uipath` package is needed. If that fails with `No such option '--type'`, the venv's `uipath` predates the option — re-run without the flag and, with no framework package installed, the same project is what you get. `uipath.json` carries the entrypoint mapping:
 
 ```json
 {
@@ -65,7 +77,7 @@ Edit the scaffolded `main.py`'s `Input` / `Output` models and `async def main` t
 |---|---|
 | `pyproject.toml` | Project metadata and dependencies |
 | `main.py` | Agent entrypoint |
-| `<framework>.json` | Framework config (LangGraph / LlamaIndex / OpenAI Agents) |
+| `<framework>.json` | Framework config (LangGraph / LlamaIndex / OpenAI Agents) — agent scaffolds only; absent means a function scaffold, see § Verify the Scaffold |
 | `uipath.json` | Runtime options, pack options, `functions` map |
 | `entry-points.json` | Input / output schemas from Pydantic models |
 | `bindings.json` | Runtime bindings |
@@ -124,4 +136,7 @@ When the agent project is registered in a solution and uploaded via `uip solutio
 | `Project authors cannot be empty` | Missing `authors` in `pyproject.toml` | Add `authors = [{ name = "Your Name" }]` to `[project]` |
 | `NameError` during `init` | Framework not installed when `init` imports `main.py` | Run `uv sync` before `uip codedagent init` |
 | `No entrypoints found in uipath.json` | Framework config or package missing | Verify `uv pip install` succeeded, then re-run `uip codedagent init` |
+| `new` produced `uipath.json` with a `functions` map and no `<framework>.json` | Framework package not installed in the active venv when `new` ran | See § Verify the Scaffold — install the package, delete the three generated files, re-run `new` |
+| `No agent framework integration is installed` or `The '<FRAMEWORK_PACKAGE>' package is required to scaffold a '<framework>' agent` from `new` | Same cause; the CLI forwarded `--type agent`, so nothing was generated | `uv pip install <FRAMEWORK_PACKAGE>`, re-run `new` |
+| `Multiple agent frameworks are installed` from `new` | More than one framework package in the venv | Keep one framework package, re-run `new` |
 | `ModuleNotFoundError` for a package you just installed, even after activating `.venv` | A shell `python` alias points at a different interpreter (uv-managed, system, etc.) | Use `.venv/bin/python` directly for sanity checks, or `unalias python` for the session |