fix(uipath-maestro-flow): fix inline agent prompt wiring contract

[rockymadden]

Fix inline-agent prompt-wiring contract

The uipath-maestro-flow skill (and one mirror reference in uipath-agents) documents an agent input bridge for wiring flow data into inline-agent prompts: agentInputVariables[] on the flow node ↔ inputSchema.properties.<id> ↔ {{input.<id>}} token ↔ contentTokens[].rawString: "input.<id>".

That contract is wrong. Studio Web's canvas does not resolve input.* against the agent's inputSchema when rendering prompt tokens — it rewrites {{input.<id>}} to {{ $vars.<id> }} against flow scope, then fails its own lint with:

Prompt references "$vars.<id>" but that variable is not available in this scope. Fix or remove the reference before publishing.

The correct contract — verified end-to-end against uip agent validate --inline-in-flow and a published flow in Studio Web — is to reference upstream flow nodes directly in agent.json messages[].content, with no bridge:

"content": "From {{ $vars.emailReceived1.output.from }}\nSubject: {{ $vars.emailReceived1.output.subject }}",
"contentTokens": [
  { "type": "simpleText", "rawString": "From " },
  { "type": "variable",   "rawString": " $vars.emailReceived1.output.from " },
  { "type": "simpleText", "rawString": "\nSubject: " },
  { "type": "variable",   "rawString": " $vars.emailReceived1.output.subject " }
]

Plus a previously-undocumented constraint: contentTokens[].rawString for variable tokens must include leading and trailing spaces to match the spaced-brace {{ <expr> }} form in content. Without them, uip agent validate fails with:

messages[N].contentTokens[M].rawString: Expected " $vars.X " but got "$vars.X"

Changes

File	Change
skills/uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md	Rewrote the Wiring Flow Variables into Agent Prompts section: replaced the four-place bridge with the direct {{ $vars.<flowNodeId>.output[.<field>] }} form. Updated the worked example (email-trigger) to use empty agentInputVariables: [] and inputSchema.properties: {}. Rewrote the When the source field name is unknown subsection. Inverted the anti-patterns list (the old "Never write {{ $vars.X }} directly" rule was backwards; now the bans are {{input.X}}, bare {{plainName}}, omitted rawString spaces, and populated agentInputVariables[] / inputSchema.properties for prompt-data wiring). Updated the JSON Structure note on inputs.agentInputVariables. Replaced the literal-{{X}} Debug row with three precise rows covering scope-lint, rawString spacing, and literal-text symptoms — each citing the exact empirical error string.
skills/uipath-maestro-flow/references/shared/node-output-wiring.md	Fixed the inline-agent row in the =js: field reference table to teach {{ $vars.<flowNodeId>.output[.<field>] }} + spaced rawString instead of the bridge form.
skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md	Updated the inputSchema.properties and messages/contentTokens bullets in Step 3: Create agent.json to describe the canvas-form contract (no {{input.X}} slot declarations; one simpleText token per literal segment and one variable token per {{ ... }} reference).

Verification

End-to-end empirical confirmation against alpha.uipath.com / popoc / DefaultTenant:

• Built a flow with an upstream HTTP node → Script node → inline-agent → Slack node.
• First attempt used the old four-place bridge as documented — uip agent validate passed, but Studio Web showed Prompt references "$vars.hnHits" but that variable is not available in this scope.
• Switched the prompt to {{ $vars.extractHits1.output.hnHits }} with empty agentInputVariables: [] / inputSchema.properties: {} — uip agent validate first failed on unspaced rawString, then passed once leading/trailing spaces were added inside rawString. Studio Web accepted the flow.
• Grepped the entire skills repo for stale {{input.<id>}} / "four-place" / "input bridge" references — all remaining matches are either anti-pattern citations (warning against the bad form) or unrelated JSON skeletons with agentInputVariables: [].

What this PR does NOT change

• The flow-node JSON skeletons under JSON Structure and Adding / Editing continue to show agentInputVariables: [] — that's correct under the new contract and unchanged.
• No claims are made about non-prompt typed-schema uses of agentInputVariables[] or inputSchema.properties.<id>. The new docs constrain themselves to prompt-only flow-data references, which is what was verified.
• uip agent migrate --inline-in-flow and uip solution upload behavior is unchanged — only the authoring contract is corrected.

[github-actions]

Claude finished @rockymadden's task in 1m 50s —— View job

---

Summary

This PR rewrites the inline-agent prompt-wiring contract from a four-place "agent input bridge" pattern (agentInputVariables[] binding → inputSchema.properties.<id> slot → {{input.<id>}} token → contentTokens mirror) to a direct {{ $vars.<flowNodeId>.output[.<field>] }} pattern where prompts reference upstream flow nodes directly. The change touches three files across two skills — uipath-agents (one reference) and uipath-maestro-flow (one reference + one shared doc), updating explanatory text, worked examples, anti-patterns, and debug tables to reflect the new contract.

Change-by-Change Review

1. skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md

Severity: OK

Two lines changed (lines 74–75). The old inputSchema / agentInputVariables instructions replaced with the new direct $vars pattern. The contentTokens explanation updated from type: "simpleText" to show the type: "variable" / type: "simpleText" parallel list pattern.

The cross-skill link to uipath-maestro-flow's impl.md (line 74) pre-dates this PR and resolves correctly. The anchor #wiring-flow-variables-into-agent-prompts matches the heading in impl.md.

Clean.

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

Severity: OK

This is the core of the PR. The "Wiring Flow Variables into Agent Prompts" section is rewritten:

• Table (lines 51–56): Reordered to lead with agent.json fields (what the agent actually writes first) and demote agentInputVariables / inputSchema.properties to empty-value rows. Clear and logical.
• Worked example (lines 62–108): The flow node excerpt now shows "agentInputVariables": [] (line 72), inputSchema.properties is now {} (lines 83–84), and the prompt uses {{ $vars.emailReceived1.output.from }} form (lines 94–101). Example is internally consistent — content string tokens match contentTokens entries one-for-one.
• Unknown field names section (lines 110–116): Simplified from 4 steps to 3 — no longer needs "pick slot ids" since there's no input bridge. Clean simplification.
• Anti-patterns (lines 119–125): All six patterns updated to forbid the old {{input.<id>}} form and mandate the new {{ $vars.X }} form. No ambiguity.
• Notes bullet (line 336): The agentInputVariables explanation now clarifies it's [] for the common case and only populated for "non-prompt typed-schema uses." Good nuance.
• Debug table (lines 387–389): Three new rows replacing the old single row, covering the most common error messages. Each has a specific cause/fix. These are actionable.

Clean.

3. skills/uipath-maestro-flow/references/shared/node-output-wiring.md

Severity: OK

Single row updated in the "Where the Rule Applies" table (line 74). The inline-agent prompt row now documents the {{ $vars.X }} direct pattern instead of the old {{input.<id>}} bridge pattern. The description is detailed but appropriately so for a table cell that serves as a quick reference. The link to the impl.md section resolves correctly.

One minor note: the old text referenced a "four-place contract", now removed — the new text is self-consistent and doesn't reference that phrase.

Clean.

What's Missing

Nothing identified. The change is well-scoped to the prompt-wiring contract across the three files that document it. All three files are internally consistent with each other after the change.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes — existing skills only
E2E Tests	OK	Documentation-only change to prompt-wiring contract; no new CLI workflows or commands introduced. Existing test tasks in tests/tasks/uipath-maestro-flow/ are not affected (they test flow operations, not agent.json authoring).
Skill Body	OK	No SKILL.md changes
References & Assets	OK	All three changed files are consistent with each other. Relative links resolve. Cross-skill link pre-dates this PR.
Repo Hygiene	OK	No secrets, no binary files, changes scoped to the two affected skills, no CODEOWNERS change needed (existing skill paths)

Issues for Manual Review

• Domain accuracy: The core claim — that inline-agent prompts use {{ $vars.<flowNodeId>.output[.<field>] }} directly instead of an agentInputVariables[] binding bridge — is a product behavior assertion. Verify against the actual canvas/runtime behavior that agentInputVariables: [] is correct for prompt-data references and that rawString with leading/trailing spaces is the expected format.

Conclusion

Clean PR. The three files consistently document the new direct-reference contract, the worked example is internally consistent, anti-patterns and debug tables are updated, and no issues were found with structure, links, or repo hygiene. Approve.

---

[tmatup]

I wonder if we should tighten up the rule in agent validate and flow validate accordingly so the first attempt will fail earlier instead of later when StudioWeb rejected it.

[rockymadden]

I wonder if we should tighten up the rule in agent validate and flow validate accordingly so the first attempt will fail earlier instead of later when StudioWeb rejected it.

Sounds fantastic to me.