feat: add example for process tool http error handling (#707)

Author: andreitava-uip

CLAUDE.md

@@ -40,6 +40,7 @@ uv build
   - `tools/` — Structured tools: context, escalation, extraction, integration, process, MCP adapters, durable interrupts. All inherit from `BaseUiPathStructuredTool`.
   - `guardrails/` — Input/output validation within agent execution
   - `multimodal/` — Multimodal invoke support
+  - `exceptions/` — Structured error types (`AgentRuntimeError`, `AgentStartupError`) and helpers for agent error handling
   - `wrappers/` — Agent decorators and wrappers
 
 - **`chat/`** — LLM provider interfaces for OpenAI, Azure OpenAI, AWS Bedrock, Google Vertex AI. Uses **lazy imports** via `__getattr__` in `__init__.py` to keep CLI startup fast. Includes `hitl.py` with the `requires_approval` decorator for human-in-the-loop workflows. Factory pattern via `chat_model_factory.py`.
@@ -77,3 +78,5 @@ The package registers two entry points consumed by the `uipath` CLI:
 - **Linting**: Ruff with rules E, F, B, I. Line length 88. mypy with pydantic plugin for type checking.
 
 - **Bedrock/Vertex imports**: `bedrock.py` and `vertex.py` have per-file E402 ignores for conditional imports.
+
+- **Exception handling in `agent/`**: Use the error types and helpers from `agent/exceptions/`. Do not raise raw exceptions or invent new error types. New error codes may be defined.

pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "uipath-langchain"
-version = "0.8.27"
+version = "0.8.28"
 description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
     "uipath>=2.10.19, <2.11.0",
     "uipath-core>=0.5.2, <0.6.0",
-    "uipath-platform>=0.0.23, <0.1.0",
+    "uipath-platform>=0.0.27, <0.1.0",
     "uipath-runtime>=0.9.1, <0.10.0",
     "langgraph>=1.0.0, <2.0.0",
     "langchain-core>=1.2.11, <2.0.0",

src/uipath_langchain/agent/exceptions/__init__.py

@@ -4,10 +4,12 @@
     AgentStartupError,
     AgentStartupErrorCode,
 )
+from .helpers import raise_for_enriched
 
 __all__ = [
     "AgentStartupError",
     "AgentRuntimeError",
     "AgentStartupErrorCode",
     "AgentRuntimeErrorCode",
+    "raise_for_enriched",
 ]

src/uipath_langchain/agent/exceptions/helpers.py

@@ -0,0 +1,66 @@
+"""Helpers for raising structured errors from HTTP exceptions."""
+
+from collections import defaultdict
+
+from uipath.platform.errors import EnrichedException
+from uipath.runtime.errors import UiPathErrorCategory
+
+from .exceptions import AgentRuntimeError, AgentRuntimeErrorCode
+
+
+def raise_for_enriched(
+    e: EnrichedException,
+    known_errors: dict[tuple[int, str | None], tuple[str, UiPathErrorCategory]],
+    *,
+    title: str,
+    **context: str,
+) -> None:
+    """Raise AgentRuntimeError if the exception matches a known error pattern.
+
+    Matches on ``(status_code, error_code)`` pairs. Use ``None`` as error_code
+    to match any error with that status code. More specific matches (with
+    error_code) are tried first.
+
+    Each value is a ``(template, category)`` pair. Message templates can use
+    ``{keyword}`` placeholders filled from *context*, plus ``{message}`` for
+    the server's own error message.
+
+    Does nothing if no match is found — caller should re-raise the original.
+
+    Example::
+
+        try:
+            await client.processes.invoke_async(name=name, folder_path=folder)
+        except EnrichedException as e:
+            raise_for_enriched(
+                e,
+                {
+                    (404, "1002"): ("Process not found.", UiPathErrorCategory.DEPLOYMENT),
+                    (409, None): ("Conflict: {message}", UiPathErrorCategory.DEPLOYMENT),
+                },
+                title=f"Failed to execute tool '{tool_name}'",
+            )
+            raise
+    """
+    info = e.error_info
+    error_code = info.error_code if info else None
+    server_message = (info.message if info else None) or ""
+    context["message"] = server_message
+
+    # Try specific match first, then wildcard
+    entry = known_errors.get((e.status_code, error_code))
+    if entry is None:
+        entry = known_errors.get((e.status_code, None))
+    if entry is None:
+        return
+
+    template, category = entry
+    detail = template.format_map(defaultdict(lambda: "<unknown>", context))
+    raise AgentRuntimeError(
+        code=AgentRuntimeErrorCode.HTTP_ERROR,
+        title=title,
+        detail=detail,
+        category=category,
+        status=e.status_code,
+        should_wrap=False,
+    ) from e

src/uipath_langchain/agent/tools/process_tool.py

@@ -10,10 +10,13 @@
 from uipath.eval.mocks import mockable
 from uipath.platform import UiPath
 from uipath.platform.common import WaitJobRaw
+from uipath.platform.errors import EnrichedException
 from uipath.platform.orchestrator import JobState
+from uipath.runtime.errors import UiPathErrorCategory
 
 from uipath_langchain._utils import get_execution_folder_path
 from uipath_langchain._utils.durable_interrupt import durable_interrupt
+from uipath_langchain.agent.exceptions import raise_for_enriched
 from uipath_langchain.agent.react.job_attachments import get_job_attachments
 from uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
 from uipath_langchain.agent.react.types import AgentGraphState
@@ -27,6 +30,21 @@
 
 from .utils import sanitize_tool_name
 
+_START_JOBS_ERRORS: dict[tuple[int, str | None], tuple[str, UiPathErrorCategory]] = {
+    (404, "1002"): (
+        "Could not find process for tool '{tool}'. Please check if the process is deployed in the configured folder.",
+        UiPathErrorCategory.DEPLOYMENT,
+    ),
+    (400, "1100"): (
+        "Could not find folder for tool '{tool}'. Please check if the folder exists and is accessible by the robot.",
+        UiPathErrorCategory.DEPLOYMENT,
+    ),
+    (409, None): (
+        "Cannot start process for tool '{tool}': {message}",
+        UiPathErrorCategory.DEPLOYMENT,
+    ),
+}
+
 
 def create_process_tool(resource: AgentProcessToolResourceConfig) -> StructuredTool:
     """Uses interrupt() to suspend graph execution until process completes (handled by runtime)."""
@@ -61,14 +79,23 @@ async def invoke_process(**_tool_kwargs: Any):
             @durable_interrupt
             async def start_job():
                 client = UiPath()
-                job = await client.processes.invoke_async(
-                    name=process_name,
-                    input_arguments=input_arguments,
-                    folder_path=folder_path,
-                    attachments=attachments,
-                    parent_span_id=parent_span_id,
-                    parent_operation_id=parent_operation_id,
-                )
+                try:
+                    job = await client.processes.invoke_async(
+                        name=process_name,
+                        input_arguments=input_arguments,
+                        folder_path=folder_path,
+                        attachments=attachments,
+                        parent_span_id=parent_span_id,
+                        parent_operation_id=parent_operation_id,
+                    )
+                except EnrichedException as e:
+                    raise_for_enriched(
+                        e,
+                        _START_JOBS_ERRORS,
+                        title=f"Failed to execute tool '{resource.name}'",
+                        tool=resource.name,
+                    )
+                    raise
 
                 if job.key:
                     bts_key = (

tests/agent/test_exception_helpers.py

@@ -0,0 +1,140 @@
+"""Tests for raise_for_enriched helper."""
+
+import json
+
+import httpx
+import pytest
+from uipath.platform.errors import EnrichedException
+from uipath.runtime.errors import UiPathErrorCategory
+
+from uipath_langchain.agent.exceptions import AgentRuntimeError, AgentRuntimeErrorCode
+from uipath_langchain.agent.exceptions.helpers import raise_for_enriched
+
+
+def _make_enriched(
+    status: int,
+    body: dict[str, object] | None = None,
+    url: str = "https://cloud.uipath.com/org/tenant/orchestrator_/api/v1",
+) -> EnrichedException:
+    content = json.dumps(body).encode() if body else b""
+    request = httpx.Request("POST", url)
+    response = httpx.Response(
+        status_code=status,
+        request=request,
+        headers={"content-type": "application/json"},
+        content=content,
+    )
+    http_err = httpx.HTTPStatusError("error", request=request, response=response)
+    enriched = EnrichedException(http_err)
+    enriched.__cause__ = http_err
+    return enriched
+
+
+_KNOWN_ERRORS: dict[tuple[int, str | None], tuple[str, UiPathErrorCategory]] = {
+    (404, "1002"): (
+        "Could not find process for tool '{tool}'.",
+        UiPathErrorCategory.USER,
+    ),
+    (400, "1100"): (
+        "Folder not found for tool '{tool}'.",
+        UiPathErrorCategory.USER,
+    ),
+    (409, None): (
+        "Cannot start tool '{tool}': {message}",
+        UiPathErrorCategory.DEPLOYMENT,
+    ),
+}
+
+_TITLE = "Failed to execute tool 'MyProcess'"
+
+
+class TestMatching:
+    def test_exact_match(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002", "message": "Not found"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="MyProcess")
+        assert exc_info.value.error_info.category == UiPathErrorCategory.USER
+        assert "MyProcess" in exc_info.value.error_info.detail
+
+    def test_wildcard_match(self) -> None:
+        err = _make_enriched(409, {"message": "Already running"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="MyTool")
+        assert "Already running" in exc_info.value.error_info.detail
+        assert "MyTool" in exc_info.value.error_info.detail
+
+    def test_specific_beats_wildcard(self) -> None:
+        errors: dict[tuple[int, str | None], tuple[str, UiPathErrorCategory]] = {
+            (404, "1002"): ("specific: {tool}", UiPathErrorCategory.DEPLOYMENT),
+            (404, None): ("wildcard: {tool}", UiPathErrorCategory.SYSTEM),
+        }
+        err = _make_enriched(404, {"errorCode": "1002"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, errors, title=_TITLE, tool="T")
+        assert exc_info.value.error_info.detail == "specific: T"
+        assert exc_info.value.error_info.category == UiPathErrorCategory.DEPLOYMENT
+
+    def test_no_match_does_nothing(self) -> None:
+        err = _make_enriched(500, {"message": "Server error"})
+        raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+
+    def test_unknown_error_code_does_nothing(self) -> None:
+        err = _make_enriched(404, {"errorCode": "9999"})
+        raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+
+
+class TestTitleAndDetail:
+    def test_title_is_fixed(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002", "message": "Not found"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert exc_info.value.error_info.title == _TITLE
+
+    def test_detail_uses_template(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002", "message": "Not found"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="InvoiceBot")
+        assert (
+            exc_info.value.error_info.detail
+            == "Could not find process for tool 'InvoiceBot'."
+        )
+
+    def test_message_placeholder(self) -> None:
+        err = _make_enriched(409, {"message": "Job conflict"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert "Job conflict" in exc_info.value.error_info.detail
+
+    def test_empty_message_when_no_error_info(self) -> None:
+        err = _make_enriched(409, body=None)
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert "Cannot start tool 'T': " in exc_info.value.error_info.detail
+
+    def test_missing_context_renders_as_unknown(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE)
+        assert "<unknown>" in exc_info.value.error_info.detail
+
+
+class TestErrorProperties:
+    def test_error_code(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert exc_info.value.error_info.code == AgentRuntimeError.full_code(
+            AgentRuntimeErrorCode.HTTP_ERROR
+        )
+
+    def test_status_code_preserved(self) -> None:
+        err = _make_enriched(400, {"errorCode": "1100"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert exc_info.value.error_info.status == 400
+
+    def test_original_exception_chained(self) -> None:
+        err = _make_enriched(404, {"errorCode": "1002"})
+        with pytest.raises(AgentRuntimeError) as exc_info:
+            raise_for_enriched(err, _KNOWN_ERRORS, title=_TITLE, tool="T")
+        assert exc_info.value.__cause__ is err