fix: process tool folder fallback when UIPATH_FOLDER_PATH is unset

[mjnovice]

Problem

Agent evaluations that invoke an RPA/process tool fail with:

Failed to execute tool '<tool>'
Could not find process for tool '<tool>'. Please check if the process is deployed in the configured folder.
Code: AGENT_RUNTIME.HTTP_ERROR

even though the process is deployed. On staging this is ~900 exceptions/3 days across 6 tenants, 100% correlated with eval runs on the serverless LangGraph path; the same tools succeed in normal agent runs.

Root cause

create_process_tool resolves the tool's folder exclusively from the UIPATH_FOLDER_PATH env var. Eval serverless job environments expose UIPATH_FOLDER_KEY but not UIPATH_FOLDER_PATH (job log: ConfigurationManager(... folder_key='ecbc94dd-...', folder_path=None)), so processes.invoke_async was called with folder_path=None and no folder_key. header_folder(None, None) returns {}, StartJobs goes out with no folder header, and Orchestrator returns 404 (error 1002) — surfaced as the misleading "process not deployed" message.

Fix

Resolve the folder with a three-step fallback, passing exactly one of path/key to invoke_async (header_folder rejects both):

1. UIPATH_FOLDER_PATH env (current behavior, unchanged)
2. the resource's design-time folderPath (previously ignored)
3. UIPATH_FOLDER_KEY env — fixes the eval serverless scenario

Also exposes the resolved folder_key in tool span metadata so this failure mode is visible in telemetry (the folder_path: null spans were the main diagnostic clue).

Covers process, agent, flow, and function tools (all built via create_process_tool).

Telemetry (staging App Insights)

Failure volume by tool (~916 hits / 3 days, 100% eval runs):

exceptions
| where timestamp > ago(3d)
| where type == "uipath_langchain.agent.exceptions.exceptions.AgentRuntimeError"
| where outerMessage has "Could not find process for tool"
| extend Tool = extract(@"Could not find process for tool '([^']+)'", 1, outerMessage)
| summarize Failures = count(), Operations = dcount(operation_Id),
    FirstSeen = min(timestamp), LastSeen = max(timestamp) by Tool
| order by Failures desc

The smoking gun — failing process-tool spans carry folder_path: null and correlate with StartJobs 404s (no folder header sent):

dependencies
| where timestamp > ago(3d)
| where name endswith "StartJobs" and resultCode == "404"
| join kind=inner (
    dependencies
    | where timestamp > ago(3d)
    | where tostring(customDimensions.metadata) has '"tool_type": "process"'
        and tostring(customDimensions.metadata) has '"folder_path": null'
    ) on operation_Id
| project timestamp, operation_Id, name, resultCode,
    metadata = customDimensions1.metadata,
    hierarchy = customDimensions1.["uipath.reference_hierarchy"]

Failing ops show uipath.reference_hierarchy = [agent, langgraph] (serverless eval path); succeeding runs of the same tools show [agent] (direct path) with StartJobs 201. Verification after rollout: the first query should trend to zero for eval-sourced operations, and process-tool spans should show a populated folder_key.

Testing

• New TestProcessToolFolderResolution suite: resource-path fallback, folder-key fallback, path-over-key precedence, metadata exposure
• Full repo suite green: 2192 passed; ruff check/format clean

Follow-up (not in this PR)

context_tool.py, escalation_recipient.py, and escalation_tool.py share the same env-path-only resolution and likely need the same fallback.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for resolving an execution folder key from the environment (for contexts that don’t provide a folder path) and wires it through process invocation + tool metadata.

Changes:

• Resolve folder context via UIPATH_FOLDER_PATH → resource folder_path → UIPATH_FOLDER_KEY.
• Pass folder_key into processes.invoke_async and expose it in tool metadata.
• Add tests covering folder path/key resolution and invocation arguments.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/agent/tools/test_process_tool.py	Adds coverage for folder path/key resolution and validates invoke_async receives expected folder context.
src/uipath_langchain/agent/tools/process_tool.py	Implements folder context resolution and forwards folder_key to invoke_async; includes in metadata.
src/uipath_langchain/_utils/_environment.py	Introduces get_execution_folder_key() reading UIPATH_FOLDER_KEY.
src/uipath_langchain/_utils/init.py	Re-exports get_execution_folder_key via package init and __all__.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud