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

[vldcmp-uipath]

Why

UiPath/uipath-python#1886 (with UiPath/uipath-langchain-python#1069) gives uipath new an explicit --type auto|agent|function. The default is auto, which keeps the existing behavior: the framework package installed in the active venv selects the agent template, and with none installed the result is a Coded Function scaffold (uipath.json with a functions map, no <framework>.json). --type agent turns the missing-package case into an error and resolves the framework from the installed integration; --type function forces a function.

So uip codedagent new <name> stays flag-free in the skills. What the skills got wrong is the ordering and the missing check: the quickstart Setup row ran uv add <framework-package> after new, so auto found no framework and produced a function scaffold, and nothing told the agent to look. Running the unmodified skill against builds of the two Python PRs, every LangGraph task hit the function scaffold first and recovered by improvising (one hand-wrote langgraph.json, two dug through uipath new --help).

What changed

uipath-agents

• SKILL.md: the greenfield rule says to install the framework package first, scaffold with a bare uip codedagent new <name>, and confirm <framework>.json exists; the Coded Function detection rule excludes a functions map the agent itself just produced without the package installed (mis-scaffold, not a function).
• references/coded/lifecycle/setup.md: Framework Selection explains --type auto, that exactly one framework package must be installed before new, and names the explicit --type overrides once without using them; new Verify the Scaffold section with four outcomes: <framework>.json present → continue; functions map without it → package missing, install it, delete the three generated files, re-run new; The '<package>' package is required to scaffold a '<framework>' agent → same cause, reported by a CLI that forwards --type agent (UiPath/cli#4126), nothing generated, install and re-run; Multiple agent frameworks are installed → keep one. Matching troubleshooting rows. The Coded Function section names it as the auto fallback when no framework package is installed.
• references/coded/quickstart.md: new Critical Rule (install first, verify after); Setup stage row moves the framework install before new and uses uv pip install; Scenario 2 gains the verification note.
• references/coded/frameworks/{langgraph,llamaindex,openai-agents}-integration.md: prerequisite note says the installed package selects the template and links to setup.md § Verify the Scaffold for recovery.
• references/coded/embedding-in-flows.md: framework install comment fixed (uipath-langchain, not uipath); verification note; the "simple stub" alternative is the auto fallback with only uipath installed. lifecycle/build.md: check <framework>.json before cleaning main.py.

No changes to uipath-functions, preview/uipath-maestro-flow, or task YAMLs. The uip\s+codedagent\s+new patterns are untouched.

Validation

• npm run skills:validate (default + studioweb), npm run skills:check-links (6719 links), hooks/validate-skill-descriptions.sh: clean.
• Probes against wheels built from the current heads of the two Python PRs (uipath 2.14.14, uipath-langchain 0.17.6): with uipath-langchain installed, uipath new and uipath new --type agent both write langgraph.json; --type function writes the function scaffold; with no framework package, uipath new writes the function scaffold and uipath new --type agent (also through uip codedagent) stops with The 'uipath-langchain' package is required to scaffold a 'langchain' agent, nothing written — the two recovery paths documented in § Verify the Scaffold.
• coder-eval run of tasks/uipath-agents/coded/conversational_agent_langgraph (claude-code / claude-sonnet-5, experiments/default.yaml, agent venv on the PR-head wheels) against an earlier revision of this branch: SUCCESS 1.0, 37 visible / 38 SDK turns, 206 s, versus main at 45 / 46 turns, 599 s (main recovered through a --help detour and a re-scaffold; smoke.yaml caps max_turns at 40, so main's 46 would be cut off). That revision passed explicit flags; the current one relies on the package being installed first, which is the same happy path, but it has not been re-run.

Notes

• The skills send no new option, so they work unchanged on older uipath cores, on today's uip (verbatim forwarding, auto), and on a uip that appends --type agent (UiPath/cli#4126): in both CLI cases the installed framework package selects the template.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VqfFdgnQFGJ8EPGXn6HC82

[github-actions]

Claude finished @vldcmp-uipath's task in 2m 44s —— View job

---

PR Review: fix(uipath-agents): require --type agent for codedagent new scaffolds

• Gather context and read review criteria
• Read full diff and all changed files
• Verify relative links in changed markdown files
• Check for cross-skill references, secrets, consistency
• Post review findings

---

Summary

Upstream CLI changes (uipath-python#1886, uipath-langchain-python#1069) make uipath new default to --type function, so uip codedagent new <name> without --type agent --agent-framework <framework> now produces a Coded Function scaffold instead of an agent scaffold. This PR updates 13 files across uipath-agents, uipath-functions, and preview/uipath-maestro-flow to require the new flags, add a "Verify the Scaffold" recovery section, and document fallback for older CLIs that don't support --type.

Change-by-Change Review

1. skills/uipath-agents/SKILL.md

OK

Two targeted edits: the greenfield scaffold rule now includes the full --type agent --agent-framework invocation, and the Coded Function detection rule (item 1) adds an exception for self-produced function scaffolds (mis-scaffold recovery rather than handing off to uipath-functions). Both are correct and well-scoped. The recovery pointer to setup.md § Verify the Scaffold avoids duplicating the steps inline.

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

OK

The most substantial change. The "Framework Selection" paragraph and table now include the <AGENT_FRAMEWORK> column. New "Verify the Scaffold" section (3 numbered items) is clear, prescriptive, and covers the three outcomes: success, function scaffold, old CLI. Two new troubleshooting rows match. The "Coded Function Agents" section clarifies the default. The <framework>.json note in the Generated Files table is accurate.

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

OK

New Critical Rule for --type agent with compact recovery + pointer to setup.md. Setup stage row in the Lifecycle table reordered to match the correct sequence (uv pip install before setup). Scenario 2 scaffold block and verification note updated consistently.

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

OK

Scaffold command updated. Prerequisite blockquote rewritten with both-flags requirement, recovery steps, and old-CLI fallback.

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

OK

Same pattern as langgraph — scaffold command + prerequisite blockquote updated.

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

OK

Same pattern as langgraph — scaffold command + prerequisite blockquote updated.

7. skills/uipath-agents/references/coded/frameworks/agent-patterns.md

OK

One-line update to the scaffold pointer — flags added to the bullet text.

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

OK

"Clean generated scaffold code" rule now gates on <framework>.json existence check before proceeding to main.py inspection. Correct ordering.

9. skills/uipath-agents/references/coded/lifecycle/evaluations/creating-evaluations.md

OK

One-line update: "create an agent first using uip codedagent new <name> --type agent --agent-framework <framework>". Minimal, correct.

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

OK

Scaffold block updated with flags. New verification sentence after the block. The Coded Function alternative paragraph is rewritten to clarify that omitting --type agent intentionally produces a function scaffold. Comment change (e.g. uipath for Coded Function → e.g. uipath-langchain for LangGraph) is correct.

11. skills/uipath-functions/SKILL.md

OK

Rule 6 rewritten: uip function new -l py now produces a function scaffold by default; the old framework-hijack behavior is documented as an older-package edge case with the existing reshape recovery preserved. Quick Start comment updated.

12. skills/uipath-functions/references/python/workflow-guide.md

OK

Step 1 prose updated to match the new default behavior — function scaffold is expected, agent scaffold is the older-package exception. Recovery instructions unchanged.

13. preview/skills/uipath-maestro-flow/references/agent.md

OK

Sibling-agent scaffold command in the bash block gains --type agent --agent-framework <agent-framework> with a trailing comment listing valid values. Minimal, correct.

What's Missing

Medium — Recovery instructions duplicated across framework files. The full "delete files and re-run with flags / old-CLI fallback" recovery is now repeated nearly verbatim in langgraph-integration.md:16, llamaindex-integration.md:16, openai-agents-integration.md:20, quickstart.md:37, and is authoritative in setup.md:49-55. This is 5 copies of the same multi-sentence recovery procedure. Per the repo's Reference Pointer Discipline, each framework file's prerequisite blockquote could instead state the two requirements (package + flags) and point to setup.md § Verify the Scaffold for recovery — one bridging sentence + link, matching what SKILL.md and build.md already do. Not blocking, but worth a follow-up to reduce drift surface.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes; existing frontmatter valid
E2E Tests	OK	No test changes needed — existing command_pattern: 'uip\s+codedagent\s+new' regexes match with appended flags; PR description includes a passing coder-eval run showing 3× speedup (206s vs 599s)
Skill Body	OK	Rules, detection, and scaffold commands all updated consistently
References & Assets	OK	All relative links verified — every target file exists. No broken links
Repo Hygiene	OK	No secrets, no personal paths, no cross-skill imports. Changes scoped to the three affected skills. No new skill folders, so no CODEOWNERS / skills.sh.json / skill-status.json edits needed

Issues for Manual Review

• Upstream availability: The PR notes that PyPI's uipath 2.14.13 and uipath-langchain 0.17.5 (shipped 2026-09-09) do not yet include the --type flag. The skill's No such option '--type' fallback (item 3 in "Verify the Scaffold") handles this, but reviewers should confirm the fallback path is actually tested in CI once the flag ships.
• uipath-llamaindex / uipath-openai-agents companion PRs: The PR description notes these packages don't have companion PRs yet. The flags are safe today (legacy middleware still claims the scaffold), but the --agent-framework llamaindex and --agent-framework openai-agents values should be verified against those packages once they update.

Conclusion

Clean, well-scoped PR that correctly addresses a real scaffold regression. All 13 files are internally consistent, the old-CLI fallback is documented, links resolve, and existing test patterns still match. The one Medium observation (recovery prose duplication across framework files) is non-blocking and could be addressed in a follow-up. Approve.