Skip to content

docs(maestro-flow): Extract document result.output is typed in the SDK (merge after the SDK release that ships builder-sdk#2050) - #4741

Open
tmatup wants to merge 2 commits into
mainfrom
docs/flow-sdk-1987-extract-output
Open

tmatup wants to merge 2 commits into
mainfrom
docs/flow-sdk-1987-extract-output

Conversation

@tmatup

@tmatup tmatup commented Nov 15, 2026

Copy link
Copy Markdown
Member

Merge after the SDK release that ships UiPath/builder-sdk#2050.

Short version: the SDK's Extract document node (dynamicExtract()) now embeds the current processed-document output and checks reads of it. This drops the skill paragraph that said a result.output read warns "until the SDK catches up".

What changes for the agent (references/document-pipeline.md, Schema and outputs):

  • Before: a factory-built flow embeds the older ExtractionResult shape, so a result.output read validates with an EXPRESSION_DIAGNOSTIC warning.
  • After: read a value with out('extract', 'result.output.<field>'). check refuses a key the document does not have (EXTRACT_READ_UNKNOWN_FIELD), ExtractionResult included, and names the spelling to use.

Example:

.return({ total: out('extract', 'result.output.invoiceTotal') })   // passes
// $vars.extract.output.ExtractionResult -> EXTRACT_READ_UNKNOWN_FIELD

Retires the skill text in UiPath/builder-sdk#1987 (document-pipeline.md:83-88). No flavor markers or overrides are touched; no flavor overrides this file.

Not verified: no eval run. This is a wording change that is only true once the SDK release is out.

🤖 Generated with Claude Code
Co-Authored-By: Claude

…output

Merge after the SDK release that ships UiPath/builder-sdk#2050.

That PR makes dynamicExtract() embed the processed-document output (values
at result.output) and adds EXTRACT_READ_UNKNOWN_FIELD. So the paragraph that
said a result.output read warns "until the SDK catches up" now says how to
read a value, and that check refuses ExtractionResult.

Example: out('extract', 'result.output.invoiceTotal') passes;
$vars.extract.output.ExtractionResult is refused.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @tmatup's task in 44s —— View job


Summary

Swaps the document-pipeline.md § Schema and outputs paragraph that said a factory-built flow's result.output read warns "until the SDK catches up". The new text says to read with out('extract', 'result.output.<field>') and that check refuses unknown keys with EXTRACT_READ_UNKNOWN_FIELD. Merge it only after the SDK release that ships builder-sdk#2050.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/document-pipeline.md:83-86 — OK

  • The new wording is shorter and prescriptive.
  • It keeps the ExtractionResult → ixp.md disambiguation, and that link resolves.
  • Using check as a bare verb matches the rest of the skill (diagnose.md, parallel-merge.md, agent.md).

2. skills/uipath-maestro-flow/references/document-pipeline.md:24 — Medium (not touched by the PR)

The opening example in the same file still has the caveat this PR retires:

.step('total', script({ code: 'return $vars.extract.output.result.output;' })) // warns until the SDK typing catches up

After this PR merges, line 24 says the read warns and line 83 says it is typed and checked. An agent that reads the top first gets the old story. Drop the trailing comment. Optionally, also change the example to the read the new prose recommends, e.g. .return({ total: out('extract', 'result.output.invoiceTotal') }), which is the example in the PR body.

Fix this →

What's Missing

  • The stale // warns until the SDK typing catches up comment at document-pipeline.md:24 (above). I searched the rest of the skill and the studioweb flavor overrides for other "catches up" or older-shape wording and found nothing else. The studioweb flavor has no override for document-pipeline.md, so it inherits this change unchanged.

Area Ratings

Area Status Notes
Frontmatter OK Not touched
E2E Tests OK Wording-only change; no task covers this read
Skill Body OK Not touched
References & Assets Issue Stale comment at line 24
Repo Hygiene OK Scoped to one file; no secrets or paths

Issues for Manual Review

  • I can't check SDK behaviour from here. Someone should confirm against the builder-sdk#2050 release that:
    • check emits EXTRACT_READ_UNKNOWN_FIELD with that exact code;
    • it names the correct spelling;
    • it also covers $vars.<step>.output.* reads inside script code, not only out().
  • The merge gate depends on that SDK release; the PR description already says so.

Conclusion

The paragraph rewrite is correct. Request one small change: remove the matching stale comment on line 24 so the file doesn't contradict itself, then merge once the SDK release is out.

…omment

Addresses the review on this PR: the opening example still said the
result.output read warns, which contradicts the Schema and outputs section.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup

tmatup commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

Fixed in the latest commit: line 24 drops the stale // warns until the SDK typing catches up comment. I kept the script read of result.output, since it is valid and passes the new check. No other 'catches up' wording is left in the skill.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant