glaip-sdk 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

glaip_sdk/client/agents.py

@@ -34,7 +34,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_AGENT_VERSION,
     DEFAULT_MODEL,
 )
-from glaip_sdk.exceptions import NotFoundError
+from glaip_sdk.exceptions import NotFoundError, ValidationError
 from glaip_sdk.models import Agent
 from glaip_sdk.payload_schemas.agent import list_server_only_fields
 from glaip_sdk.utils.agent_config import normalize_agent_config_for_import
@@ -97,9 +97,7 @@ def _merge_override_maps(
         for key, value in source.items():
             if value is None:
                 continue
-            merged[key] = (
-                _normalise_sequence(value) if key in _MERGED_SEQUENCE_FIELDS else value
-            )
+            merged[key] = _normalise_sequence(value) if key in _MERGED_SEQUENCE_FIELDS else value
     return merged
 
 
@@ -134,9 +132,7 @@ def _prepare_agent_metadata(value: Any) -> dict[str, Any]:
     return prepared
 
 
-def _load_agent_file_payload(
-    file_path: Path, *, model_override: str | None
-) -> dict[str, Any]:
+def _load_agent_file_payload(file_path: Path, *, model_override: str | None) -> dict[str, Any]:
     """Load agent configuration from disk and normalise legacy fields."""
     if not file_path.exists():
         raise FileNotFoundError(f"Agent configuration file not found: {file_path}")
@@ -168,9 +164,7 @@ def _prepare_import_payload(
     raw_definition = load_resource_from_file(file_path)
     original_refs = _extract_original_refs(raw_definition)
 
-    base_payload = _load_agent_file_payload(
-        file_path, model_override=overrides_dict.get("model")
-    )
+    base_payload = _load_agent_file_payload(file_path, model_override=overrides_dict.get("model"))
 
     cli_args = _build_cli_args(overrides_dict)
 
@@ -223,11 +217,7 @@ def _build_cli_args(overrides_dict: dict) -> dict[str, Any]:
 
 def _build_additional_args(overrides_dict: dict, cli_args: dict) -> dict[str, Any]:
     """Build additional args not already in CLI args."""
-    return {
-        key: value
-        for key, value in overrides_dict.items()
-        if value is not None and key not in cli_args
-    }
+    return {key: value for key, value in overrides_dict.items() if value is not None and key not in cli_args}
 
 
 def _remove_model_fields_if_needed(merged: dict, overrides_dict: dict) -> None:
@@ -278,9 +268,7 @@ class AgentClient(BaseClient):
         """
         if query is not None and kwargs:
             # Both query object and individual parameters provided
-            raise ValueError(
-                "Provide either `query` or individual filter arguments, not both."
-            )
+            raise ValueError("Provide either `query` or individual filter arguments, not both.")
 
         if query is None:
             # Create query from individual parameters for backward compatibility
@@ -339,7 +327,19 @@ class AgentClient(BaseClient):
 
     def get_agent_by_id(self, agent_id: str) -> Agent:
         """Get agent by ID."""
-        data = self._request("GET", f"/agents/{agent_id}")
+        try:
+            data = self._request("GET", f"/agents/{agent_id}")
+        except ValidationError as exc:
+            if exc.status_code == 422:
+                message = f"Agent '{agent_id}' not found"
+                raise NotFoundError(
+                    message,
+                    status_code=404,
+                    error_type=exc.error_type,
+                    payload=exc.payload,
+                    request_id=exc.request_id,
+                ) from exc
+            raise
 
         if isinstance(data, str):
             # Some backends may respond with plain text for missing agents.
@@ -372,9 +372,7 @@ class AgentClient(BaseClient):
             self._renderer_manager = manager
         return manager
 
-    def _create_renderer(
-        self, renderer: RichStreamRenderer | str | None, **kwargs: Any
-    ) -> RichStreamRenderer:
+    def _create_renderer(self, renderer: RichStreamRenderer | str | None, **kwargs: Any) -> RichStreamRenderer:
         manager = self._get_renderer_manager()
         verbose = kwargs.get("verbose", False)
         if isinstance(renderer, RichStreamRenderer) or hasattr(renderer, "on_start"):
@@ -506,9 +504,7 @@ class AgentClient(BaseClient):
             return entry_id
 
         if entry_name:
-            resolved, success = self._resolve_resource_by_name(
-                find_by_name, entry_name, singular, plural
-            )
+            resolved, success = self._resolve_resource_by_name(find_by_name, entry_name, singular, plural)
             return resolved if success else entry_name
 
         raise ValueError(f"{singular} references must include a valid ID or name.")
@@ -523,9 +519,7 @@ class AgentClient(BaseClient):
         return str(entry)
 
     @staticmethod
-    def _validate_resource_id(
-        fetch_by_id: Callable[[str], Any], candidate_id: str | None
-    ) -> str | None:
+    def _validate_resource_id(fetch_by_id: Callable[[str], Any], candidate_id: str | None) -> str | None:
         if not candidate_id:
             return None
         try:
@@ -547,21 +541,13 @@ class AgentClient(BaseClient):
             return entry_name, False
 
         if not matches:
-            raise ValueError(
-                f"{singular} '{entry_name}' not found in current workspace."
-            )
+            raise ValueError(f"{singular} '{entry_name}' not found in current workspace.")
         if len(matches) > 1:
-            exact = [
-                m
-                for m in matches
-                if getattr(m, "name", "").lower() == entry_name.lower()
-            ]
+            exact = [m for m in matches if getattr(m, "name", "").lower() == entry_name.lower()]
             if len(exact) == 1:
                 matches = exact
             else:
-                raise ValueError(
-                    f"Multiple {plural} named '{entry_name}'. Please disambiguate."
-                )
+                raise ValueError(f"Multiple {plural} named '{entry_name}'. Please disambiguate.")
         return str(matches[0].id), True
 
     def _resolve_tool_ids(
@@ -610,9 +596,7 @@ class AgentClient(BaseClient):
 
     def _create_agent_from_payload(self, payload: Mapping[str, Any]) -> "Agent":
         """Create an agent using a fully prepared payload mapping."""
-        known, extras = _split_known_and_extra(
-            payload, AgentCreateRequest.__dataclass_fields__
-        )
+        known, extras = _split_known_and_extra(payload, AgentCreateRequest.__dataclass_fields__)
 
         name = known.pop("name", None)
         instruction = known.pop("instruction", None)
@@ -721,9 +705,7 @@ class AgentClient(BaseClient):
         overrides = _merge_override_maps(base_overrides, kwargs)
 
         if file is not None:
-            payload = _prepare_import_payload(
-                Path(file).expanduser(), overrides, drop_model_fields=True
-            )
+            payload = _prepare_import_payload(Path(file).expanduser(), overrides, drop_model_fields=True)
             if overrides.get("model") is None:
                 payload.pop("model", None)
         else:
@@ -746,9 +728,7 @@ class AgentClient(BaseClient):
         payload: Mapping[str, Any],
     ) -> "Agent":
         """Update an agent using a prepared payload mapping."""
-        known, extras = _split_known_and_extra(
-            payload, AgentUpdateRequest.__dataclass_fields__
-        )
+        known, extras = _split_known_and_extra(payload, AgentUpdateRequest.__dataclass_fields__)
         _normalise_sequence_fields(known)
 
         tool_refs = extras.pop("_tool_refs", None)
@@ -818,9 +798,7 @@ class AgentClient(BaseClient):
         overrides = _merge_override_maps(base_overrides, kwargs)
 
         if file is not None:
-            payload = _prepare_import_payload(
-                Path(file).expanduser(), overrides, drop_model_fields=True
-            )
+            payload = _prepare_import_payload(Path(file).expanduser(), overrides, drop_model_fields=True)
         else:
             payload = overrides
 
@@ -882,9 +860,7 @@ class AgentClient(BaseClient):
                 payload["tty"] = True
             return payload, None, None, headers, None
 
-    def _get_timeout_values(
-        self, timeout: float | None, **kwargs: Any
-    ) -> tuple[float, float]:
+    def _get_timeout_values(self, timeout: float | None, **kwargs: Any) -> tuple[float, float]:
         """Get request timeout and execution timeout values.
 
         Args:
@@ -1009,9 +985,7 @@ class AgentClient(BaseClient):
             headers = {"Accept": SSE_CONTENT_TYPE}
             return payload, None, None, headers
 
-    def _create_async_client_config(
-        self, timeout: float | None, headers: dict | None
-    ) -> dict:
+    def _create_async_client_config(self, timeout: float | None, headers: dict | None) -> dict:
         """Create async client configuration with proper headers and timeout."""
         config = self._build_async_client(timeout or self.timeout)
         if headers:
@@ -1040,9 +1014,7 @@ class AgentClient(BaseClient):
         ) as stream_response:
             stream_response.raise_for_status()
 
-            async for event in aiter_sse_events(
-                stream_response, timeout_seconds, agent_name
-            ):
+            async for event in aiter_sse_events(stream_response, timeout_seconds, agent_name):
                 try:
                     chunk = json.loads(event["data"])
                     yield chunk
@@ -1077,9 +1049,7 @@ class AgentClient(BaseClient):
             Exception: For other unexpected errors
         """
         # Prepare request data
-        payload, data_payload, files_payload, headers = self._prepare_request_data(
-            message, files, **kwargs
-        )
+        payload, data_payload, files_payload, headers = self._prepare_request_data(message, files, **kwargs)
 
         # Create async client configuration
         async_client_config = self._create_async_client_config(timeout, headers)

glaip_sdk/client/base.py

@@ -7,6 +7,7 @@ Authors:
 
 import logging
 import os
+from collections.abc import Iterable, Mapping
 from typing import Any, NoReturn, Union
 
 import httpx
@@ -151,12 +152,7 @@ class BaseClient:
     def timeout(self, value: float) -> None:
         """Set timeout and rebuild client."""
         self._timeout = value
-        if (
-            hasattr(self, "http_client")
-            and self.http_client
-            and not self._session_scoped
-            and not self._parent_client
-        ):
+        if hasattr(self, "http_client") and self.http_client and not self._session_scoped and not self._parent_client:
             self.http_client.close()
             self.http_client = self._build_client(value)
 
@@ -246,18 +242,14 @@ class BaseClient:
             client_log.debug(f"Response status: {response.status_code}")
             return response
         except httpx.ConnectError as e:
-            client_log.warning(
-                f"Connection error on {method} {endpoint}, retrying once: {e}"
-            )
+            client_log.warning(f"Connection error on {method} {endpoint}, retrying once: {e}")
             try:
                 response = self.http_client.request(method, endpoint, **kwargs)
-                client_log.debug(
-                    f"Retry successful, response status: {response.status_code}"
-                )
+                client_log.debug(f"Retry successful, response status: {response.status_code}")
                 return response
             except httpx.ConnectError:
                 client_log.error(f"Retry failed for {method} {endpoint}: {e}")
-                raise e
+                raise
 
     def _request(self, method: str, endpoint: str, **kwargs) -> Any:
         """Make HTTP request with error handling and unwrap success envelopes."""
@@ -298,7 +290,7 @@ class BaseClient:
                 return parsed.get("data", parsed) if unwrap else parsed
             else:
                 error_type = parsed.get("error", "UnknownError")
-                message = parsed.get("message", DEFAULT_ERROR_MESSAGE)
+                message = self._format_error_dict({key: value for key, value in parsed.items() if key != "success"})
                 self._raise_api_error(
                     400,
                     message,
@@ -341,12 +333,58 @@ class BaseClient:
                 return validation_message
             return f"Validation error: {parsed}"
 
+        formatted_details = None
+        if "details" in parsed:
+            formatted_details = self._format_error_details(parsed["details"])
+
         message = parsed.get("message")
         if message:
+            if formatted_details:
+                return f"{message}\n{formatted_details}"
             return message
 
+        if formatted_details:
+            return formatted_details
+
         return str(parsed) if parsed else DEFAULT_ERROR_MESSAGE
 
+    def _format_error_details(self, details: Any) -> str | None:
+        """Render generic error details into a human-readable string."""
+        if details is None:
+            return None
+
+        if isinstance(details, dict):
+            return self._format_detail_mapping(details)
+
+        if isinstance(details, (list, tuple, set)):
+            return self._format_detail_iterable(details)
+
+        return f"Details: {details}"
+
+    @staticmethod
+    def _format_detail_mapping(details: Mapping[str, Any]) -> str | None:
+        """Format details provided as a mapping."""
+        entries = [f"  {key}: {value}" for key, value in details.items()]
+        if not entries:
+            return None
+        return "Details:\n" + "\n".join(entries)
+
+    @staticmethod
+    def _format_detail_iterable(details: Iterable[Any]) -> str | None:
+        """Format details provided as an iterable collection."""
+        entries: list[str] = []
+        for item in details:
+            if isinstance(item, Mapping):
+                inner = ", ".join(f"{k}={v}" for k, v in item.items())
+                entries.append(f"  - {inner if inner else '{}'}")
+            else:
+                entries.append(f"  - {item}")
+
+        if not entries:
+            return None
+
+        return "Details:\n" + "\n".join(entries)
+
     def _format_validation_errors(self, errors: list[Any]) -> str | None:
         """Render validation errors into a human-readable string."""
         entries: list[str] = []
@@ -365,6 +403,22 @@ class BaseClient:
 
         return "Validation errors:\n" + "\n".join(entries)
 
+    @staticmethod
+    def _is_no_content_response(response: httpx.Response) -> bool:
+        """Return True when the response contains no content."""
+        return response.status_code == 204
+
+    @staticmethod
+    def _is_success_status(response: httpx.Response) -> bool:
+        """Return True for successful HTTP status codes."""
+        return 200 <= response.status_code < 300
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Raise an API error for non-success responses."""
+        error_message = self._get_error_message(response)
+        parsed_content = self._parse_response_content(response)
+        self._raise_api_error(response.status_code, error_message, payload=parsed_content)
+
     def _handle_response(
         self,
         response: httpx.Response,
@@ -373,24 +427,17 @@ class BaseClient:
     ) -> Any:
         """Handle HTTP response with proper error handling."""
         # Handle no-content success before general error handling
-        if response.status_code == 204:
+        if self._is_no_content_response(response):
             return None
 
-        # Handle error status codes
-        if not (200 <= response.status_code < 300):
-            error_message = self._get_error_message(response)
-            # Try to parse response content for payload
-            parsed_content = self._parse_response_content(response)
-            self._raise_api_error(
-                response.status_code, error_message, payload=parsed_content
-            )
-            return None  # Won't be reached but helps with type checking
-
-        parsed = self._parse_response_content(response)
-        if parsed is None:
-            return None
+        if self._is_success_status(response):
+            parsed = self._parse_response_content(response)
+            if parsed is None:
+                return None
+            return self._handle_success_response(parsed, unwrap=unwrap)
 
-        return self._handle_success_response(parsed, unwrap=unwrap)
+        self._handle_error_response(response)
+        return None
 
     def _raise_api_error(
         self,
@@ -435,12 +482,7 @@ class BaseClient:
 
     def close(self) -> None:
         """Close the HTTP client."""
-        if (
-            hasattr(self, "http_client")
-            and self.http_client
-            and not self._session_scoped
-            and not self._parent_client
-        ):
+        if hasattr(self, "http_client") and self.http_client and not self._session_scoped and not self._parent_client:
             self.http_client.close()
 
     def __enter__(self) -> "BaseClient":

glaip_sdk/client/mcps.py

@@ -179,9 +179,7 @@ class MCPClient(BaseClient):
         update_data = {
             "name": name if name is not None else current_mcp.name,
             "type": DEFAULT_MCP_TYPE,  # Required by backend, MCPs are always server type
-            "transport": kwargs.get(
-                "transport", getattr(current_mcp, "transport", DEFAULT_MCP_TRANSPORT)
-            ),
+            "transport": kwargs.get("transport", getattr(current_mcp, "transport", DEFAULT_MCP_TRANSPORT)),
         }
 
         # Handle description with proper None handling

glaip_sdk/client/run_rendering.py

@@ -43,9 +43,7 @@ def _update_state_transcript(state: Any, text_value: str) -> bool:
 
     updated = False
 
-    if hasattr(state, "final_text") and not _has_visible_text(
-        getattr(state, "final_text", "")
-    ):
+    if hasattr(state, "final_text") and not _has_visible_text(getattr(state, "final_text", "")):
         try:
             state.final_text = text_value
             updated = True
@@ -66,11 +64,9 @@ def _update_renderer_transcript(renderer: Any, text_value: str) -> None:
     if _update_state_transcript(state, text_value):
         return
 
-    if hasattr(renderer, "final_text") and not _has_visible_text(
-        getattr(renderer, "final_text", "")
-    ):
+    if hasattr(renderer, "final_text") and not _has_visible_text(getattr(renderer, "final_text", "")):
         try:
-            setattr(renderer, "final_text", text_value)
+            renderer.final_text = text_value
         except Exception:
             pass
 
@@ -220,9 +216,7 @@ class AgentRunRenderingManager:
         meta: dict[str, Any],
         renderer: RichStreamRenderer,
     ) -> None:
-        req_id = stream_response.headers.get(
-            "x-request-id"
-        ) or stream_response.headers.get("x-run-id")
+        req_id = stream_response.headers.get("x-request-id") or stream_response.headers.get("x-run-id")
         if req_id:
             meta["run_id"] = req_id
             renderer.on_start(meta)
@@ -318,9 +312,7 @@ class AgentRunRenderingManager:
             meta["run_id"] = ev["run_id"]
             renderer.on_start(meta)
 
-    def _ensure_renderer_final_content(
-        self, renderer: RichStreamRenderer, text: str
-    ) -> None:
+    def _ensure_renderer_final_content(self, renderer: RichStreamRenderer, text: str) -> None:
         """Populate renderer state with final output when the stream omits it."""
         if not text:
             return
@@ -351,7 +343,7 @@ class AgentRunRenderingManager:
         if hasattr(renderer, "state") and hasattr(renderer.state, "buffer"):
             buffer_values = renderer.state.buffer
         elif hasattr(renderer, "buffer"):
-            buffer_values = getattr(renderer, "buffer")
+            buffer_values = renderer.buffer
 
         if buffer_values is not None:
             try:

glaip_sdk/client/tools.py

@@ -96,9 +96,7 @@ class ToolClient(BaseClient):
         """
         return os.path.splitext(os.path.basename(file_path))[0]
 
-    def _prepare_upload_data(
-        self, name: str, framework: str, description: str | None = None, **kwargs
-    ) -> dict:
+    def _prepare_upload_data(self, name: str, framework: str, description: str | None = None, **kwargs) -> dict:
         """Prepare upload data dictionary.
 
         Args:
@@ -217,29 +215,21 @@ class ToolClient(BaseClient):
         elif hasattr(current_tool, "description") and current_tool.description:
             update_data["description"] = current_tool.description
 
-    def _handle_tags_update(
-        self, update_data: dict[str, Any], kwargs: dict[str, Any], current_tool: Tool
-    ) -> None:
+    def _handle_tags_update(self, update_data: dict[str, Any], kwargs: dict[str, Any], current_tool: Tool) -> None:
         """Handle tags field in update payload."""
         if kwargs.get("tags"):
             if isinstance(kwargs["tags"], list):
-                update_data["tags"] = ",".join(
-                    str(tag).strip() for tag in kwargs["tags"]
-                )
+                update_data["tags"] = ",".join(str(tag).strip() for tag in kwargs["tags"])
             else:
                 update_data["tags"] = str(kwargs["tags"])
         elif hasattr(current_tool, "tags") and current_tool.tags:
             # Preserve existing tags if present
             if isinstance(current_tool.tags, list):
-                update_data["tags"] = ",".join(
-                    str(tag).strip() for tag in current_tool.tags
-                )
+                update_data["tags"] = ",".join(str(tag).strip() for tag in current_tool.tags)
             else:
                 update_data["tags"] = str(current_tool.tags)
 
-    def _handle_additional_kwargs(
-        self, update_data: dict[str, Any], kwargs: dict[str, Any]
-    ) -> None:
+    def _handle_additional_kwargs(self, update_data: dict[str, Any], kwargs: dict[str, Any]) -> None:
         """Handle additional kwargs in update payload."""
         excluded_keys = {
             "tags",
@@ -290,12 +280,8 @@ class ToolClient(BaseClient):
         update_data = {
             "name": name if name is not None else current_tool.name,
             "type": current_type,
-            "framework": kwargs.get(
-                "framework", getattr(current_tool, "framework", DEFAULT_TOOL_FRAMEWORK)
-            ),
-            "version": kwargs.get(
-                "version", getattr(current_tool, "version", DEFAULT_TOOL_VERSION)
-            ),
+            "framework": kwargs.get("framework", getattr(current_tool, "framework", DEFAULT_TOOL_FRAMEWORK)),
+            "version": kwargs.get("version", getattr(current_tool, "version", DEFAULT_TOOL_VERSION)),
         }
 
         # Handle description update
@@ -355,9 +341,7 @@ class ToolClient(BaseClient):
 
         try:
             # Prepare upload data
-            upload_data = self._prepare_upload_data(
-                name=name, framework=framework, description=description, **kwargs
-            )
+            upload_data = self._prepare_upload_data(name=name, framework=framework, description=description, **kwargs)
 
             # Upload file
             return self._upload_tool_file(temp_file_path, upload_data)

glaip_sdk/client/validators.py

@@ -39,9 +39,7 @@ class ResourceValidator:
         if len(found_tools) == 1:
             return str(found_tools[0].id)
         elif len(found_tools) > 1:
-            raise AmbiguousResourceError(
-                f"Multiple tools found with name '{tool_name}': {[t.id for t in found_tools]}"
-            )
+            raise AmbiguousResourceError(f"Multiple tools found with name '{tool_name}': {[t.id for t in found_tools]}")
         else:
             raise NotFoundError(f"Tool not found: {tool_name}")
 
@@ -51,9 +49,7 @@ class ResourceValidator:
         if len(found_tools) == 1:
             return str(found_tools[0].id)
         elif len(found_tools) > 1:
-            raise AmbiguousResourceError(
-                f"Multiple tools found with name '{tool.name}': {[t.id for t in found_tools]}"
-            )
+            raise AmbiguousResourceError(f"Multiple tools found with name '{tool.name}': {[t.id for t in found_tools]}")
         else:
             raise NotFoundError(f"Tool not found: {tool.name}")
 
@@ -73,9 +69,7 @@ class ResourceValidator:
         elif hasattr(tool, "name") and tool.name is not None:
             return self._resolve_tool_by_name_attribute(tool, client)
         else:
-            raise ValidationError(
-                f"Invalid tool reference: {tool} - must have 'id' or 'name' attribute"
-            )
+            raise ValidationError(f"Invalid tool reference: {tool} - must have 'id' or 'name' attribute")
 
     def _process_single_tool(self, tool: str | Tool, client: Any) -> str:
         """Process a single tool reference and return its ID."""
@@ -99,22 +93,14 @@ class ResourceValidator:
             try:
                 tool_id = cls()._process_single_tool(tool, client)
                 tool_ids.append(tool_id)
-            except (AmbiguousResourceError, NotFoundError) as e:
+            except (AmbiguousResourceError, NotFoundError) as err:
                 # Determine the tool name for the error message
-                tool_name = (
-                    tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
-                )
-                raise ValidationError(
-                    f"Failed to resolve tool name '{tool_name}' to ID: {e}"
-                )
-            except Exception as e:
+                tool_name = tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
+                raise ValidationError(f"Failed to resolve tool name '{tool_name}' to ID: {err}") from err
+            except Exception as err:
                 # For other exceptions, wrap them appropriately
-                tool_name = (
-                    tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
-                )
-                raise ValidationError(
-                    f"Failed to resolve tool name '{tool_name}' to ID: {e}"
-                )
+                tool_name = tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
+                raise ValidationError(f"Failed to resolve tool name '{tool_name}' to ID: {err}") from err
 
         return tool_ids
 
@@ -158,9 +144,7 @@ class ResourceValidator:
         elif hasattr(agent, "name") and agent.name is not None:
             return self._resolve_agent_by_name_attribute(agent, client)
         else:
-            raise ValidationError(
-                f"Invalid agent reference: {agent} - must have 'id' or 'name' attribute"
-            )
+            raise ValidationError(f"Invalid agent reference: {agent} - must have 'id' or 'name' attribute")
 
     def _process_single_agent(self, agent: str | Any, client: Any) -> str:
         """Process a single agent reference and return its ID."""
@@ -184,26 +168,14 @@ class ResourceValidator:
             try:
                 agent_id = cls()._process_single_agent(agent, client)
                 agent_ids.append(agent_id)
-            except (AmbiguousResourceError, NotFoundError) as e:
+            except (AmbiguousResourceError, NotFoundError) as err:
                 # Determine the agent name for the error message
-                agent_name = (
-                    agent
-                    if isinstance(agent, str)
-                    else getattr(agent, "name", str(agent))
-                )
-                raise ValidationError(
-                    f"Failed to resolve agent name '{agent_name}' to ID: {e}"
-                )
-            except Exception as e:
+                agent_name = agent if isinstance(agent, str) else getattr(agent, "name", str(agent))
+                raise ValidationError(f"Failed to resolve agent name '{agent_name}' to ID: {err}") from err
+            except Exception as err:
                 # For other exceptions, wrap them appropriately
-                agent_name = (
-                    agent
-                    if isinstance(agent, str)
-                    else getattr(agent, "name", str(agent))
-                )
-                raise ValidationError(
-                    f"Failed to resolve agent name '{agent_name}' to ID: {e}"
-                )
+                agent_name = agent if isinstance(agent, str) else getattr(agent, "name", str(agent))
+                raise ValidationError(f"Failed to resolve agent name '{agent_name}' to ID: {err}") from err
 
         return agent_ids
 
@@ -213,8 +185,8 @@ class ResourceValidator:
         for tool_id in tool_ids:
             try:
                 client.get_tool_by_id(tool_id)
-            except NotFoundError:
-                raise ValidationError(f"Tool not found: {tool_id}")
+            except NotFoundError as err:
+                raise ValidationError(f"Tool not found: {tool_id}") from err
 
     @classmethod
     def validate_agents_exist(cls, agent_ids: list[str], client: Any) -> None:
@@ -222,5 +194,5 @@ class ResourceValidator:
         for agent_id in agent_ids:
             try:
                 client.get_agent_by_id(agent_id)
-            except NotFoundError:
-                raise ValidationError(f"Agent not found: {agent_id}")
+            except NotFoundError as err:
+                raise ValidationError(f"Agent not found: {agent_id}") from err