Skip to content

docs(uipath-maestro-flow): prepare an external agent the library lacks (merge after the SDK release that ships builder-sdk#2051) - #4742

Open
tmatup wants to merge 2 commits into
mainfrom
docs/flow-external-agent-prepare
Open

tmatup wants to merge 2 commits into
mainfrom
docs/flow-external-agent-prepare

Conversation

@tmatup

@tmatup tmatup commented Nov 15, 2026

Copy link
Copy Markdown
Member

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

Short version

An external agent or automation that the connector library lacks no longer pushes the flow out of the SDK loop. Before, references/external-agent.md sent the agent to nodes create + configure --detail JSON by hand and told it to drop the flow's SDK source. Now it runs uip maestro registry prepare <key> --action <op> and authors the step with connector(...), like any library operation.

Example (Salesforce Agentforce, not in the library):

uip maestro registry prepare uipath-salesforce-agent --action execute-salesforce-agent
import { ExecuteSalesforceAgent } from './.flow-sdk/connectors-local/uipath-salesforce-agent.ts';
.step('ask', connector(ExecuteSalesforceAgent, { message: { text: input('question') }, agent_id: '<agent id>' },
  { connection: 'agent', folder: 'shared' }))

What changed

  • references/external-agent.md: the external-agent-cli block now covers prepare, the import, required inputs, the agent_id lookup, and the execution type (compile writes inputs.detail.executionType, as nodes configure does).
  • SKILL.md: the node-type row says to prepare the operation instead of using the CLI.
  • The Studio Web override of the block is unchanged.

Why it waits for the release

prepare + connector() works on current SDK releases. builder-sdk#2051 adds the execution type to the compiled node. Without it, a sync agent runs under the registry's async service type. That PR also verified the whole path on alpha (prepare, compile, flow validate: Valid).

Checks

npm run skills:validate OK (default and studioweb). scripts/check-skill-links.mjs: all links and anchors resolve. git diff --check clean.

Refs UiPath/builder-sdk#1988

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

…s, then author it with connector()

Short version: an external agent or automation the connector library lacks
no longer pushes the flow out of the SDK loop. `uip maestro registry prepare
<key> --action <op>` builds its entry from the tenant's node and the object's
request fields, and `connector(...)` authors it. This replaces the
`nodes create` + `configure --detail` fallback in external-agent.md.

Merge after the SDK release that ships UiPath/builder-sdk#1988's PR: that
release writes the agent's execution type on the compiled node.

🤖 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 49s —— View job


Summary

Swaps the "not in the library" path in references/external-agent.md from hand-built CLI work (nodes create + configure --detail, no SDK source) to uip maestro registry prepare <key> --action <op> plus connector(...). The SKILL.md router row changes to match. The Studio Web override of external-agent-cli is unchanged, which is right because it replaces the whole block.

Change-by-Change Review

1. references/external-agent.md:28: import path doesn't match the skill's layout

Severity: High

The example imports from './.flow-sdk/connectors-local/uipath-salesforce-agent.ts'. The source lives inside .flow-sdk/ (SKILL.md:27), and SKILL.md:64 says prepared modules import as ./connectors-local/<key>.ts. bindings.md:28 and connector-params.md:170 say the same thing, relative to the source. An agent that copies this line gets a module that doesn't resolve, because the path would point at .flow-sdk/.flow-sdk/connectors-local/…. The PR body's example has the same path.

Fix: use import { ExecuteSalesforceAgent } from './connectors-local/uipath-salesforce-agent.ts';

Fix this →

2. references/external-agent.md:30 vs :35: the example contradicts the next bullet

Severity: Medium

The example hard-codes agent_id: '<agent id>'. Two bullets later, the doc says agent_id is a picker lookup and tells the agent to "author lookup(...) rather than pasting one". Agents copy code blocks more readily than they follow prose, so the example will win, and the id ends up pasted, which is the pattern connector-params.md § Resolving connection-scoped reference values forbids.

Fix: write the example the way the bullet says, for example agent_id: lookup(ExecuteSalesforceAgent, 'agent_id').by('<field>', '<value>'), using the searchable name prepare prints.

Fix this →

3. references/external-agent.md:33-36: the bullets

Severity: OK

The dotted-field note, the execution-type explanation and the uip update fallback are each specific to this node type and don't restate connector-params.md. The lookup bullet links to the anchor instead of copying it, and the anchor #resolving-connection-scoped-reference-values exists.

Low: the placeholders <agent id> and <operation> don't follow the repo's <UPPER_SNAKE_CASE> style. <operation> was already there before this PR.

4. SKILL.md:217: router row

Severity: OK

It matches the new reference. registry prepare is named consistently with SKILL.md:71 and CLI-LOOP.md:127.

What's Missing

  • No test covers the not-in-the-library path (Medium). No task in tests/tasks/uipath-maestro-flow/ exercises an external-agent connector that the library lacks. The only one nearby is inline_agent/inline_external_agent_tool, which tests something else. The PR changes the workflow from CLI node editing to SDK source plus prepare, so consider a smoke task that checks the agent runs registry prepare … --action and imports from connectors-local/ (for example with command_executed and file_contains).
  • Merge gate isn't enforced in the repo. Holding the merge until the builder-sdk#2051 release relies on the PR title alone. The new text calls the execution type a fact ("Compile writes that as inputs.detail.executionType"), which is only true on that release. Consider naming the minimum SDK version, as d077519 did with "SDK 6.108.0+", so agents on an older SDK know why a sync agent runs async.

Area Ratings

Area Status Notes
Frontmatter OK Unchanged
E2E Tests Issue No task covers the external-agent prepare path
Skill Body OK Router row is consistent
References & Assets Issue Wrong import path; example contradicts the lookup rule
Repo Hygiene OK Scoped to one skill; flavor block boundaries intact; no secrets or personal paths

Issues for Manual Review

  • Whether prepare actually works for a Curated agent operation that isn't in the library. The old text implied it didn't, which is why it fell back to the CLI. The PR says this was verified on alpha via builder-sdk#2051.
  • Whether uipath-salesforce-agent and execute-salesforce-agent are the real connector key and action names.
  • Whether the "If prepare warns … run uip update" fallback matches what the CLI prints.

Conclusion

Request changes. Fix the import path in #1 and the example in #2 before merging. Once those are fixed, the approach is sound: it keeps the flow in the SDK loop and drops the "no SDK source" restriction. Merge only after the SDK release that ships builder-sdk#2051, as the title says.

…ow-sdk/, and author agent_id as a lookup

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

tmatup commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

Addressed the Claude review in the latest commit:

  1. Import path (High): fixed. The source lives in .flow-sdk/, so the example now imports ./connectors-local/uipath-salesforce-agent.ts, and the text says so.
  2. agent_id pasted (Medium): fixed. The example now authors lookup(ExecuteSalesforceAgent, 'agent_id').byDeveloperName('<agent name>'), and the bullet says to record it with the --resolve agent_id:DeveloperName=<agent name> that prepare prints. I checked this form against a prepared Execute Salesforce Agent overlay: flow check gives LOOKUP_UNRESOLVED with exactly that --resolve command, the normal lookup loop.
  3. Bullets: no change.

🤖 Generated with Claude Code

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