docs(uipath-maestro-flow): inline-agent prompt token + trigger-input wiring#1656
docs(uipath-maestro-flow): inline-agent prompt token + trigger-input wiring#1656jiyangzh wants to merge 2 commits into
Conversation
…er-input wiring
Inline-agent flows that reference flow data in the agent prompt were failing
two ways that `flow validate` does not catch, surfacing only at `flow debug`:
1. content/contentTokens schema thrash. `uip agent refresh` reconstructs
`content` from `contentTokens` and requires a byte-exact match. The docs
described the format but not the invariant, so the agent looped between
braces-in-content vs braces-in-rawString and used "text" instead of
"simpleText" — burning the turn to timeout. Add the explicit mirror
invariant (simpleText vs variable, braces only in content, brace-free
rawString, whitespace-exact reconstruction) with a worked decomposition and
the three validator-error strings it produces.
2. Undeclared trigger inputs. A `{{ $vars.start.output.<field> }}` token only
resolves if the field is declared as a trigger-associated `in` global
(direction:"in", triggerNodeId). Validate passes regardless; debug faults
with the literal token text reaching the LLM and empty JobArguments. Add the
prerequisite to the wiring section plus a symptom->fix Debug row.
Mirror the contentTokens guidance into the uipath-agents inline-in-flow
source-of-truth file so both entry points carry it.
jiyangzh
requested review from
a team,
AlexandruCGhimisi,
al3xanndru,
andreibalas-uipath and
andreitava-uip
as code owners
|
Claude finished @jiyangzh's task in 2m 17s —— View job PR Review: #1656SummaryDocuments two failure modes in inline-agent prompt wiring that Change-by-Change Review1.
|
| Area | Status | Notes |
|---|---|---|
| Frontmatter | OK | No frontmatter changes |
| E2E Tests | OK | Docs-only change to existing skill; no new CLI workflows introduced |
| Skill Body | OK | Additions are within the reference file, not SKILL.md |
| References & Assets | Medium | inline-in-flow.md restates invariant rules beyond bridge content |
| Repo Hygiene | OK | No secrets, no CODEOWNERS impact, scoped changes |
Issues for Manual Review
- Domain accuracy of validator error strings: The three error messages (
Expected type "simpleText" but got "text",Expected " $vars.X " but got " {{ $vars.X }} ",contentTokens has N entries but content requires 1) should be verified against the actualuip agent refreshoutput for the current CLI version. Docs claim these are the exact strings — if they're paraphrased rather than literal, an agent pattern-matching on them would fail to recognize the error. - "Two validator failures" vs three bullets (impl.md line 86): Minor wording inconsistency — verify intent.
Conclusion
Clean, high-value documentation fix addressing real agent failure modes found during eval. The impl.md changes are well-structured and follow existing conventions. One Medium finding on Reference Pointer Discipline in inline-in-flow.md where the invariant summary restates rules that belong only in the authoritative source — recommend trimming to bridge-only. Otherwise, approve.
The inline-agent docs taught a broken model — author inputSchema {}, put
{{ $vars… }} in agent.json prompts, and 'refresh derives inputSchema'.
Verified false: uip agent refresh has no derivation (passes agent.json
through as-is), the runtime resolves {{input.<key>}} not $vars, and an
empty inputSchema makes the agent receive the literal token at runtime
even when JobArguments delivers the value.
Corrected to the form proven through agent validate + flow validate +
flow debug (agent answered the real input, not the token):
- delivery: node inputs.agentInputVariables[] (binding =$vars.<trig>.output.<var>)
- contract: agent.json inputSchema.properties has a <trig>__output__<var> key (mandatory)
- resolution: agent.json messages[].content uses {{input.<trig>__output__<var>}}
- nothing auto-derives; verify at flow debug, not after refresh
Updates inline-in-flow.md + impl.md (directive, table, content/contentTokens
invariant, worked example, anti-patterns, troubleshooting).
1 participant
Why
Inline-agent flows that wire flow data into the agent prompt were failing two ways that
uip maestro flow validatedoes not catch — both surfaced only atflow debug. Found while running theskill-flow-devcon-billing-dispute-analysteval againstuip1.197.0.What
1.
content↔contentTokensmirror invariant (inline-agent/impl.md)uip agent refreshreconstructscontentfromcontentTokensand requires a byte-exact match. The docs described the format but not the invariant, so the agent looped between braces-in-contentvs braces-in-rawString, used"text"instead of"simpleText", and burned the whole turn to a timeout. Added:simpleTextvsvariable; braces only incontent; brace-freerawString; whitespace-exact reconstruction check)2. Trigger-input declaration prerequisite (
inline-agent/impl.md)A
{{ $vars.start.output.<field> }}token only resolves if the field is declared as a trigger-associatedinglobal (direction:"in",triggerNodeId). Validate passes regardless; debug faults with the literal token text reaching the LLM and emptyJobArguments. Added the prerequisite to the wiring section plus a symptom→fix Debug row, and the matchingout-global / End-node mapping note.3. Mirror into
uipath-agents(inline-in-flow.md)Strengthened the
contentTokensbullet in the source-of-truth file so both entry points carry the invariant.Scope
Docs only — no behavior/code. Coder-eval changes are intentionally excluded from this PR (still iterating on the grader).
Verification
The eval went ERROR (timeout) → SUCCESS after these two doc fixes landed; the agent built and ran the flow end-to-end with no schema thrash and resolved trigger inputs.