feat: add connections retrieve payload

Author: cristipufu

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.1.17"
+version = "2.1.18"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"

samples/event-trigger/.python-version

@@ -0,0 +1 @@
+3.13

samples/event-trigger/README.md

@@ -0,0 +1,128 @@
+# UiPath Coded Agents with Event Triggers
+
+This guide explains how to create Python-based UiPath Coded Agents that respond to event triggers, enabling seamless event-driven agents.
+
+## Overview
+
+UiPath Coded Agents allow you to write automation logic directly in Python while leveraging UiPath's event trigger system. This project demonstrates how to create agents that handle external events from systems like Gmail, Slack, and other connectors.
+
+## How to Set Up UiPath Coded Agents with Event Triggers
+
+### Step 1: Install UiPath Python SDK
+
+1. Open it with your prefered editor
+2. In terminal run:
+```bash
+uv init
+uv add uipath
+uv run uipath new event-agent
+uv run uipath init
+```
+
+### Step 2: Create Your Coded Agent
+
+Create a Python file with your agent logic using the UiPath SDK:
+
+```python
+from dataclasses import dataclass
+from uipath.models import EventArguments
+from uipath import UiPath
+import logging
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class EchoOut:
+    message: dict
+
+# use EventArguments when called by UiPath EventTriggers
+def main(input: EventArguments) -> EchoOut:
+    sdk = UiPath()
+
+    # get the event payload, this will be different from event to event
+    payload = sdk.connections.retrieve_event_payload(input)
+
+    logger.info(f"Received payload: {payload}")
+
+    return EchoOut(payload)
+```
+
+Run `uipath init` again to update the input arguments.
+
+### Step 3: Understanding the Event Flow
+
+When an event trigger fires, UiPath will:
+1. Pass event data through `EventArguments`
+2. Your agent retrieves the full payload using `sdk.connections.retrieve_event_payload(input)`
+3. Process the payload based on your business logic
+4. Return structured output
+
+### Step 4: Publish Your Coded Agent and setup Event Trigger
+
+#### 4.1: Build and Publish
+1. Use `uipath pack` and `uipath publish` to create and publish the package
+2. Create an Orchestrator Automation from the published process
+
+#### 4.2: Access Event Triggers
+1. Log into UiPath Orchestrator
+2. Navigate to **Automations** → **Processes**
+3. Click on your coded workflow process
+
+#### 4.3: Create Event Trigger
+1. Go to the **Triggers** tab
+2. Click **Add Trigger** → **Event Trigger**
+
+#### 4.4: Configure Event Trigger Settings
+1. **Name**: Descriptive name (e.g., "Gmail Event Handler")
+2. **Event Source**: Select connector type:
+   - `uipath-google-gmailcustom` for Gmail
+   - `uipath-slack` for Slack
+   - `uipath-microsoft-outlookcustom` for Outlook
+   - Custom connectors
+3. **Event Type**: Choose specific event:
+   - `EMAIL_RECEIVED` for emails
+   - `MESSAGE_RECEIVED` for chat messages
+   - Custom event types
+4. **Filters**: Optional event filtering criteria
+
+#### 4.5: Map Event to Input Arguments
+The event data will automatically be passed to your `EventArguments` parameter.
+
+#### 4.6: Enable the Trigger
+1. Review configuration
+2. Click **Create** to save
+3. Ensure trigger status is **Enabled**
+
+### Step 5: Test Your Setup
+
+#### 5.1: Trigger Test Events
+- Send test email (Gmail triggers)
+- Post message in Slack (Slack triggers)
+- Perform action matching your event source
+
+#### 5.2: Monitor Execution
+1. Check **Monitoring** → **Jobs** in Orchestrator
+2. View job details and execution logs
+3. Verify your coded agent processed the event correctly
+
+#### 5.3: Debug with Logs
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+def main(input: EventArguments) -> EchoOut:
+    sdk = UiPath()
+    
+    # payload will be a json (dict) specific to your event
+    payload = sdk.connections.retrieve_event_payload(input)
+    logger.info(f"Successfully retrieved payload: {type(payload)}")
+    logger.debug(f"Payload details: {payload}")
+    
+    # Your processing logic here
+    result = process_event(payload)
+    
+    logger.info(f"Event processed successfully: {result}")
+    return EchoOut(result)
+```

samples/event-trigger/main.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from uipath.models import EventArguments
+from uipath import UiPath
+from uipath.tracing import traced
+import logging
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class EchoOut:
+    message: dict
+
+@traced()
+def handle_slack_event(payload: dict[str, any]) -> EchoOut:
+    """Handle Slack message events"""
+    message = payload['event']['text'] if 'event' in payload and 'text' in payload['event'] else "No message"
+    user = payload['event']['user'] if 'event' in payload and 'user' in payload['event'] else "Unknown user"
+
+    logger.info(f"Slack message from {user}: {message}")
+
+
+# use InputTriggerEventArgs when called by UiPath EventTriggers
+@traced()
+def main(input: EventArguments) -> EchoOut:
+    sdk = UiPath()
+
+    # get the event payload, this will be different from event to event
+    payload = sdk.connections.retrieve_event_payload(input)
+
+    handle_slack_event(payload)
+
+    logger.info(f"Received payload: {payload}")
+
+    return EchoOut(payload)

samples/event-trigger/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "event-agent"
+version = "0.0.5"
+description = "event-agent"
+authors = [{ name = "John Doe", email = "john.doe@myemail.com" }]
+dependencies = [
+    "uipath>=2.1.18",
+]
+requires-python = ">=3.10"

src/uipath/_cli/_runtime/_runtime.py

@@ -11,6 +11,7 @@
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic import BaseModel
 
 from uipath.tracing import LlmOpsHttpExporter
 
@@ -162,9 +163,11 @@ async def _execute_python_script(self, script_path: str, input_data: Any) -> Any
                 input_param = params[0]
                 input_type = input_param.annotation
 
-                # Case 2: Class or dataclass parameter
+                # Case 2: Class, dataclass, or Pydantic model parameter
                 if input_type != inspect.Parameter.empty and (
-                    is_dataclass(input_type) or hasattr(input_type, "__annotations__")
+                    is_dataclass(input_type)
+                    or self._is_pydantic_model(input_type)
+                    or hasattr(input_type, "__annotations__")
                 ):
                     try:
                         valid_type = cast(Type[Any], input_type)
@@ -216,7 +219,16 @@ async def _execute_python_script(self, script_path: str, input_data: Any) -> Any
         )
 
     def _convert_to_class(self, data: Dict[str, Any], cls: Type[T]) -> T:
-        """Convert a dictionary to either a dataclass or regular class instance."""
+        """Convert a dictionary to either a dataclass, Pydantic model, or regular class instance."""
+        # Handle Pydantic models
+        try:
+            if inspect.isclass(cls) and issubclass(cls, BaseModel):
+                return cast(T, cls.model_validate(data))
+        except TypeError:
+            # issubclass can raise TypeError if cls is not a class
+            pass
+
+        # Handle dataclasses
         if is_dataclass(cls):
             field_types = get_type_hints(cls)
             converted_data = {}
@@ -227,13 +239,17 @@ def _convert_to_class(self, data: Dict[str, Any], cls: Type[T]) -> T:
 
                 value = data[field_name]
                 if (
-                    is_dataclass(field_type) or hasattr(field_type, "__annotations__")
+                    is_dataclass(field_type)
+                    or self._is_pydantic_model(field_type)
+                    or hasattr(field_type, "__annotations__")
                 ) and isinstance(value, dict):
                     typed_field = cast(Type[Any], field_type)
                     value = self._convert_to_class(value, typed_field)
                 converted_data[field_name] = value
 
             return cast(T, cls(**converted_data))
+
+        # Handle regular classes
         else:
             sig = inspect.signature(cls.__init__)
             params = sig.parameters
@@ -254,6 +270,7 @@ def _convert_to_class(self, data: Dict[str, Any], cls: Type[T]) -> T:
 
                     if (
                         is_dataclass(param_type)
+                        or self._is_pydantic_model(param_type)
                         or hasattr(param_type, "__annotations__")
                     ) and isinstance(value, dict):
                         typed_param = cast(Type[Any], param_type)
@@ -265,22 +282,41 @@ def _convert_to_class(self, data: Dict[str, Any], cls: Type[T]) -> T:
 
             return cls(**init_args)
 
+    def _is_pydantic_model(self, cls: Type[Any]) -> bool:
+        """Safely check if a class is a Pydantic model."""
+        try:
+            return inspect.isclass(cls) and issubclass(cls, BaseModel)
+        except TypeError:
+            # issubclass can raise TypeError if cls is not a class
+            return False
+
     def _convert_from_class(self, obj: Any) -> Dict[str, Any]:
-        """Convert a class instance (dataclass or regular) to a dictionary."""
+        """Convert a class instance (dataclass, Pydantic model, or regular) to a dictionary."""
         if obj is None:
             return {}
 
-        if is_dataclass(obj):
+        # Handle Pydantic models
+        if isinstance(obj, BaseModel):
+            return obj.model_dump()
+
+        # Handle dataclasses
+        elif is_dataclass(obj):
             # Make sure obj is an instance, not a class
             if isinstance(obj, type):
                 return {}
             return asdict(obj)
+
+        # Handle regular classes
         elif hasattr(obj, "__dict__"):
             result = {}
             for key, value in obj.__dict__.items():
                 # Skip private attributes
                 if not key.startswith("_"):
-                    if hasattr(value, "__dict__") or is_dataclass(value):
+                    if (
+                        isinstance(value, BaseModel)
+                        or hasattr(value, "__dict__")
+                        or is_dataclass(value)
+                    ):
                         result[key] = self._convert_from_class(value)
                     else:
                         result[key] = value

src/uipath/_cli/_utils/_input_args.py

@@ -14,6 +14,8 @@
     get_type_hints,
 )
 
+from pydantic import BaseModel
+
 SchemaType = Literal["object", "integer", "double", "string", "boolean", "array"]
 
 TYPE_MAP: Dict[str, SchemaType] = {
@@ -50,7 +52,30 @@ def get_type_schema(type_hint: Any) -> Dict[str, Any]:
         return {"type": "object"}
 
     if inspect.isclass(type_hint):
-        if is_dataclass(type_hint):
+        # Handle Pydantic models
+        if issubclass(type_hint, BaseModel):
+            properties = {}
+            required = []
+
+            # Get the model fields
+            model_fields = type_hint.model_fields
+
+            for field_name, field_info in model_fields.items():
+                # Use alias if defined, otherwise use field name
+                schema_field_name = field_info.alias if field_info.alias else field_name
+
+                # Get the field type schema
+                field_schema = get_type_schema(field_info.annotation)
+                properties[schema_field_name] = field_schema
+
+                # Check if field is required using Pydantic's built-in method
+                if field_info.is_required():
+                    required.append(schema_field_name)
+
+            return {"type": "object", "properties": properties, "required": required}
+
+        # Handle dataclasses
+        elif is_dataclass(type_hint):
             properties = {}
             required = []
 
@@ -61,6 +86,8 @@ def get_type_schema(type_hint: Any) -> Dict[str, Any]:
                     required.append(field.name)
 
             return {"type": "object", "properties": properties, "required": required}
+
+        # Handle regular classes with annotations
         elif hasattr(type_hint, "__annotations__"):
             properties = {}
             required = []