fix(agents,maestro-flow): coded-agent resource file is under process/function/

[dmetzgar]

Four references tell an authoring agent to read the minted resource.key from resources/solution_folder/process/agent/<project>.json. That file is not written for a coded agent.

Why

uip solution projects add infers project type from the manifest it finds — project.uiproj, project.json, or uipath.json — and has no flag to override it. A coded agent scaffolded by uip codedagent new has only uipath.json, which is indistinguishable from a Function project's. So the resource lands at process/function/<project>.json with spec.type: "Function", and uip solution projects list reports Type: Function.

Observed on CLI 1.203.0-dev.8669. A coder-eval run spent 18 turns and 167s trying to make the documented path appear — removing and re-adding the project, hand-editing uipath.json, deleting and regenerating the resource files. It never appeared. The run finished by inventing a GUID, which uip maestro flow validate accepted, because validate does not check that a well-formed key resolves on the tenant.

What changed

Each of the four sites now:

• names uip maestro flow registry list --local as the source to read the key from, rather than one of two equal options;
• globs for the resource file (process/*/<project>.json) instead of hard-coding a directory, so the guidance survives the classification being fixed;
• states that Type: Function on a coded agent is that classification and not a scaffolding mistake, so it isn't "corrected" before wiring the Flow;
• says never to substitute a hand-written GUID, and why validate won't catch one.

uip codedagent run in the troubleshooting table is also qualified: it executes the graph, so it needs UIPATH_ACCESS_TOKEN and LLM-gateway reach, and where those are absent its import and virtualenv errors are environment rather than project defects. uip codedagent review is named as the offline rung.

Scope

Low-code agent projects are deliberately untouched. They carry agent.json plus project.uiproj, so the classification is plausibly correct there and process/agent/ may well be right. I did not verify that, so I left all of references/lowcode/ alone — it still says process/agent/ in several places, correctly as far as I know.

Follow-up

The underlying CLI behaviour looks like a defect: the classifier could read uipath.json's agents vs functions map rather than keying on the filename. Worth filing against the CLI; this change makes the guidance true in the meantime, and the glob means it stays true afterwards.

Checks run

• check-skill-verbs.py — uipath-maestro-flow 38 findings / 0 blocking; uipath-agents 73 / 0 blocking
• .maintenance/check-links.sh — 972 checked, 0 broken
• .maintenance/check-anchors.sh — 323 checked, 1 bad, pre-existing and unrelated: references/diagnose/troubleshooting-guide.md → ../shared/cli-conventions.md#7-use-uip_log_levelinfo-for-debug-runs. Left alone rather than mixed into a guidance-correctness PR.

Phase 0 of UiPath/flow-builder-sdk docs/SKILLS_PROMOTION_PLAN.md. The preview tree carries the same two wrong claims plus a "do not search for a published release" instruction; that side is fixed upstream in flow-builder-sdk and arrives here via the nightly Maestro SDK preview sync.

🤖 Generated with Claude Code

[github-actions]

Claude finished @dmetzgar's task in 2m 34s —— View job

---

PR Review: fix(agents,maestro-flow): coded-agent resource path

• Read review criteria and project conventions
• Analyze the full diff
• Read each changed file in full for surrounding context
• Check relative links, cross-skill references, secrets
• Post review findings

---

Summary

Corrects four documentation sites across uipath-agents and uipath-maestro-flow that told agents to look for coded-agent resource files under process/agent/ when they actually land at process/function/ due to CLI classification behavior. Changes each site to glob with process/*/, explain the classification, warn against hand-written GUIDs, and qualify uip codedagent run in troubleshooting. Well-scoped and well-motivated.

Change-by-Change Review

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

Severity: OK

Three edits — intro paragraph, tree diagram, and step 4 after projects add. All three now show the glob pattern (process/*/<name>.json), explain the function/ classification, and use ls to find the file. The tree diagram correctly updates to process/function/. Internally consistent. Flavor markers preserved.

2. skills/uipath-agents/references/coded/flow-integration.md

Severity: OK

Pattern 1 paragraph and the Debug table row both updated. The debug row now includes the validate silent-pass warning about hand-written GUIDs — good addition directly at the troubleshooting site where an agent would encounter this.

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

Severity: OK

Step 5 post-projects add text updated. Adds the explanation that Type: Function in uip solution projects list is the classification, not a mistake. This is a valuable addition — it directly prevents the 18-turn failure mode described in the PR body.

4. skills/uipath-maestro-flow/references/author/plugins/agent/impl.md

Severity: OK

Two sites updated — the "In this solution" bullet and the definitions[] authoring instructions — plus the Debug table. Both now point to registry list --local as the authoritative source and glob for the resource file. The uip codedagent run vs uip codedagent review qualification in the Debug table is a useful addition.

Pre-existing: file lacks a trailing newline. Not introduced by this PR.

What's Missing

• Test files still hard-code process/agent/.

  • tests/tasks/uipath-agents/coded/coded_in_flow_e2e/coded_in_flow_e2e.yaml:93 — file_exists criterion checks GreeterSol/resources/solution_folder/process/agent/InputProcessor.json which, per this PR's own analysis, will never exist for a coded agent. This test will fail against the actual CLI behavior.
  • tests/tasks/uipath-agents/coded/coded_in_flow_e2e/check_coded_in_flow_e2e.py:34 — hard-codes CODED_RESOURCE = SOL / "resources" / "solution_folder" / "process" / "agent" / "InputProcessor.json". Same issue.
  • tests/tasks/uipath-agents/coded/coded_in_flow_published/check_coded_in_flow_published.py:109 — globs resources/solution_folder/process/agent/*.json to assert Pattern 1 absence; should also check process/function/.
  • tests/tasks/uipath-maestro-flow/conversational/check_conversational_flow.py:408 — _resource_key_projects() only globs process/agent/ to discover resource keys, missing process/function/.

  These are functional correctness issues in the test harness — the same bug this PR fixes in the docs. Updating them is out of scope for a guidance-correctness PR (the PR description explains this well), but they should be tracked as a follow-up. Severity: Medium (flagging for awareness, not blocking).

• conversational-agent/planning.md:27 in uipath-maestro-flow still says resources/solution_folder/process/agent/<Project>.json. This is arguably in-scope since it's in the same skill (uipath-maestro-flow) and makes the same incorrect claim about coded agents. However, the PR author may have intentionally left it because it's about in-solution agents generically (including low-code), not just coded agents. Worth considering.

• uipath-solution skill — references/scenarios/intra-solution-references.md references process/agent/ in its tree and prose (lines 19-20, 42). If that file covers coded agents too, it has the same issue. Likely out of scope (different skill), but worth noting for the follow-up.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	Issue	Existing tests hard-code the old process/agent/ path — see What's Missing. Not introduced by this PR but now inconsistent with the updated guidance.
Skill Body	OK	No SKILL.md changes
References & Assets	OK	All four changed references are correct, internally consistent, and well-written
Repo Hygiene	OK	No secrets, no broken links, no cross-skill structural dependencies, changes scoped to the two affected skills

Issues for Manual Review

• CLI behavior verification: The PR states this was observed on CLI 1.203.0-dev.8669. Worth confirming the process/function/ classification still holds on the current stable CLI release — if it's been fixed upstream, the glob guidance is still correct (resilient) but the "today under function/" qualifications would need updating.
• Low-code agent classification: The PR intentionally leaves process/agent/ in all low-code references. Worth confirming low-code agents with agent.json + project.uiproj do indeed land under process/agent/ as expected — if they also land under function/, the lowcode references have the same bug.

Conclusion

Clean, well-scoped fix. All four documentation sites are updated consistently — the glob pattern, the classification explanation, and the GUID warning are present at every site. The PR description is unusually thorough and clearly documents what was and wasn't changed, and why. No issues in the changed files themselves.

The main gap is the test files that still hard-code the old path, but those are pre-existing and explicitly out of scope. I'd suggest tracking them as a follow-up issue. Approve.

[dmetzgar]

Closing this — it is the wrong fix, and it conflicts with better work.

Superseded on 2 of the 4 files. #3165 already changes coded/embedding-in-flows.md and coded/quickstart.md, and it fixes the cause rather than the symptom: uipath new --type auto picks the template from whichever framework package is installed in the active venv, and the skills had the framework install running after new, so auto produced a Coded Function scaffold. That PR is validated with probes against wheels from the two Python PRs plus a coder-eval run. It should land instead of this.

My causal claim here was also wrong. I said a coded agent's uipath.json is indistinguishable from a Function project's. The eval artifacts show the scaffolded manifest carried "functions": {} and "agents": {} — both empty, because uip codedagent init failed on a missing dependency before it registered the entry point. So the Type: Function result came from a specific classifier fallback, not from inherent ambiguity, and documenting the folder it happens to produce is a bandage over a CLI gap.

The two things in here that were real are independent of folder names and are not covered by #3165:

• uip maestro flow validate accepts a well-formed resource key that resolves to nothing on the tenant, so a fabricated GUID fails at run time rather than author time. The run that motivated this scored 1.000 on exactly that.
• uip codedagent run executes the graph and needs UIPATH_ACCESS_TOKEN plus LLM-gateway reach; where those are absent, its import and virtualenv errors are environment rather than project defects. uip codedagent review is the offline rung.

Both live in uipath-maestro-flow's plugins/agent/impl.md, which #3165 does not touch. I will reopen those as a smaller PR against that file alone.