agentex-sdk 0.4.10__py3-none-any.whl → 0.4.11__py3-none-any.whl

agentex/_utils/_transform.py

@@ -16,18 +16,20 @@ from ._utils import (
     lru_cache,
     is_mapping,
     is_iterable,
+    is_sequence,
 )
 from .._files import is_base64_file_input
+from ._compat import get_origin, is_typeddict
 from ._typing import (
     is_list_type,
     is_union_type,
     extract_type_arg,
     is_iterable_type,
     is_required_type,
+    is_sequence_type,
     is_annotated_type,
     strip_annotated_type,
 )
-from .._compat import get_origin, model_dump, is_typeddict
 
 _T = TypeVar("_T")
 
@@ -167,6 +169,8 @@ def _transform_recursive(
 
             Defaults to the same value as the `annotation` argument.
     """
+    from .._compat import model_dump
+
     if inner_type is None:
         inner_type = annotation
 
@@ -184,6 +188,8 @@ def _transform_recursive(
         (is_list_type(stripped_type) and is_list(data))
         # Iterable[T]
         or (is_iterable_type(stripped_type) and is_iterable(data) and not isinstance(data, str))
+        # Sequence[T]
+        or (is_sequence_type(stripped_type) and is_sequence(data) and not isinstance(data, str))
     ):
         # dicts are technically iterable, but it is an iterable on the keys of the dict and is not usually
         # intended as an iterable, so we don't transform it.
@@ -329,6 +335,8 @@ async def _async_transform_recursive(
 
             Defaults to the same value as the `annotation` argument.
     """
+    from .._compat import model_dump
+
     if inner_type is None:
         inner_type = annotation
 
@@ -346,6 +354,8 @@ async def _async_transform_recursive(
         (is_list_type(stripped_type) and is_list(data))
         # Iterable[T]
         or (is_iterable_type(stripped_type) and is_iterable(data) and not isinstance(data, str))
+        # Sequence[T]
+        or (is_sequence_type(stripped_type) and is_sequence(data) and not isinstance(data, str))
     ):
         # dicts are technically iterable, but it is an iterable on the keys of the dict and is not usually
         # intended as an iterable, so we don't transform it.

agentex/_utils/_typing.py

@@ -15,7 +15,7 @@ from typing_extensions import (
 
 from ._utils import lru_cache
 from .._types import InheritsGeneric
-from .._compat import is_union as _is_union
+from ._compat import is_union as _is_union
 
 
 def is_annotated_type(typ: type) -> bool:
@@ -26,6 +26,11 @@ def is_list_type(typ: type) -> bool:
     return (get_origin(typ) or typ) == list
 
 
+def is_sequence_type(typ: type) -> bool:
+    origin = get_origin(typ) or typ
+    return origin == typing_extensions.Sequence or origin == typing.Sequence or origin == _c_abc.Sequence
+
+
 def is_iterable_type(typ: type) -> bool:
     """If the given type is `typing.Iterable[T]`"""
     origin = get_origin(typ) or typ

agentex/_utils/_utils.py

@@ -22,7 +22,6 @@ from typing_extensions import TypeGuard
 import sniffio
 
 from .._types import NotGiven, FileTypes, NotGivenOr, HeadersLike
-from .._compat import parse_date as parse_date, parse_datetime as parse_datetime
 
 _T = TypeVar("_T")
 _TupleT = TypeVar("_TupleT", bound=Tuple[object, ...])

agentex/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "agentex"
-__version__ = "0.4.10"  # x-release-please-version
+__version__ = "0.4.11"  # x-release-please-version

agentex/lib/adk/providers/_modules/openai.py

@@ -4,6 +4,7 @@ from typing import Any, Literal
 from agentex.lib.adk.utils._modules.client import create_async_agentex_client
 from agents import Agent, RunResult, RunResultStreaming
 from agents.agent import StopAtTools, ToolsToFinalOutputFunction
+from agents.guardrail import InputGuardrail, OutputGuardrail
 from agents.agent_output import AgentOutputSchemaBase
 from agents.model_settings import ModelSettings
 from agents.tool import Tool
@@ -84,6 +85,9 @@ class OpenAIModule:
             | StopAtTools
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
+        mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> SerializableRunResult | RunResult:
         """
         Run an agent without streaming or TaskMessage creation.
@@ -107,6 +111,9 @@ class OpenAIModule:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
+            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on initial user input.
+            output_guardrails: Optional list of output guardrails to run on final agent output.
 
         Returns:
             Union[SerializableRunResult, RunResult]: SerializableRunResult when in Temporal, RunResult otherwise.
@@ -126,6 +133,9 @@ class OpenAIModule:
                 tools=tools,
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
+                mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT,
@@ -150,6 +160,9 @@ class OpenAIModule:
                 tools=tools,
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
+                mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )
 
     async def run_agent_auto_send(
@@ -175,6 +188,9 @@ class OpenAIModule:
             | StopAtTools
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
+        mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> SerializableRunResult | RunResult:
         """
         Run an agent with automatic TaskMessage creation.
@@ -197,6 +213,9 @@ class OpenAIModule:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
+            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on initial user input.
+            output_guardrails: Optional list of output guardrails to run on final agent output.
 
         Returns:
             Union[SerializableRunResult, RunResult]: SerializableRunResult when in Temporal, RunResult otherwise.
@@ -217,6 +236,9 @@ class OpenAIModule:
                 tools=tools,
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
+                mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT_AUTO_SEND,
@@ -242,6 +264,9 @@ class OpenAIModule:
                 tools=tools,
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
+                mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )
 
     async def run_agent_streamed(
@@ -263,6 +288,9 @@ class OpenAIModule:
             | StopAtTools
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
+        mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled but no TaskMessage creation.
@@ -289,6 +317,9 @@ class OpenAIModule:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
+            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on initial user input.
+            output_guardrails: Optional list of output guardrails to run on final agent output.
 
         Returns:
             RunResultStreaming: The result of the agent run with streaming.
@@ -318,6 +349,9 @@ class OpenAIModule:
             tools=tools,
             output_type=output_type,
             tool_use_behavior=tool_use_behavior,
+            mcp_timeout_seconds=mcp_timeout_seconds,
+            input_guardrails=input_guardrails,
+            output_guardrails=output_guardrails,
         )
 
     async def run_agent_streamed_auto_send(
@@ -344,6 +378,8 @@ class OpenAIModule:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> SerializableRunResultStreaming | RunResultStreaming:
         """
         Run an agent with streaming enabled and automatic TaskMessage creation.
@@ -364,6 +400,8 @@ class OpenAIModule:
             model: Optional model to use.
             model_settings: Optional model settings.
             tools: Optional list of tools.
+            input_guardrails: Optional list of input guardrails to run on initial user input.
+            output_guardrails: Optional list of output guardrails to run on final agent output.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
             mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
@@ -388,6 +426,8 @@ class OpenAIModule:
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
                 mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT_STREAMED_AUTO_SEND,
@@ -414,4 +454,6 @@ class OpenAIModule:
                 output_type=output_type,
                 tool_use_behavior=tool_use_behavior,
                 mcp_timeout_seconds=mcp_timeout_seconds,
+                input_guardrails=input_guardrails,
+                output_guardrails=output_guardrails,
             )

agentex/lib/cli/templates/temporal/README.md.j2

@@ -262,14 +262,30 @@ class MyWorkflow(BaseWorkflow):
 ```
 
 ### Custom Activities
-Add custom activities for external operations:
+Add custom activities for external operations. **Important**: Always specify appropriate timeouts (recommended: 10 minutes):
 
 ```python
 # In project/activities.py
-@activity.defn
+from datetime import timedelta
+from temporalio import activity
+from temporalio.common import RetryPolicy
+
+@activity.defn(name="call_external_api")
 async def call_external_api(data):
     # HTTP requests, database operations, etc.
     pass
+
+# In your workflow, call it with a timeout:
+result = await workflow.execute_activity(
+    "call_external_api",
+    data,
+    start_to_close_timeout=timedelta(minutes=10),  # Recommended: 10 minute timeout
+    heartbeat_timeout=timedelta(minutes=1),         # Optional: heartbeat monitoring
+    retry_policy=RetryPolicy(maximum_attempts=3)    # Optional: retry policy
+)
+
+# Don't forget to register your custom activities in run_worker.py:
+# all_activities = get_all_activities() + [your_custom_activity_function]
 ```
 
 ### Integration with External Services

agentex/lib/cli/templates/temporal/project/activities.py.j2

@@ -0,0 +1,77 @@
+"""
+Custom Temporal Activities Template
+====================================
+This file is for defining custom Temporal activities that can be executed
+by your workflow. Activities are used for:
+- External API calls
+- Database operations  
+- File I/O operations
+- Heavy computations
+- Any non-deterministic operations
+
+IMPORTANT: All activities should have appropriate timeouts!
+Default recommendation: start_to_close_timeout=timedelta(minutes=10)
+"""
+
+from datetime import timedelta
+from typing import Any, Dict
+
+from pydantic import BaseModel
+from temporalio import activity
+from temporalio.common import RetryPolicy
+
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+
+# Example activity parameter models
+class ExampleActivityParams(BaseModel):
+    """Parameters for the example activity"""
+    data: Dict[str, Any]
+    task_id: str
+
+
+# Example custom activity
+@activity.defn(name="example_custom_activity")
+async def example_custom_activity(params: ExampleActivityParams) -> Dict[str, Any]:
+    """
+    Example custom activity that demonstrates best practices.
+    
+    When calling this activity from your workflow, use:
+    ```python
+    result = await workflow.execute_activity(
+        "example_custom_activity",
+        ExampleActivityParams(data={"key": "value"}, task_id=task_id),
+        start_to_close_timeout=timedelta(minutes=10),  # Recommended: 10 minute timeout
+        heartbeat_timeout=timedelta(minutes=1),         # Optional: heartbeat every minute
+        retry_policy=RetryPolicy(maximum_attempts=3)    # Optional: retry up to 3 times
+    )
+    ```
+    """
+    logger.info(f"Processing activity for task {params.task_id} with data: {params.data}")
+    
+    # Your activity logic here
+    # This could be:
+    # - API calls
+    # - Database operations
+    # - File processing
+    # - ML model inference
+    # - etc.
+    
+    result = {
+        "status": "success",
+        "processed_data": params.data,
+        "task_id": params.task_id
+    }
+    
+    return result
+
+
+# Add more custom activities below as needed
+# Remember to:
+# 1. Use appropriate timeouts (default: 10 minutes)
+# 2. Define clear parameter models with Pydantic
+# 3. Handle errors appropriately
+# 4. Use logging for debugging
+# 5. Keep activities focused on a single responsibility

agentex/lib/cli/templates/temporal/project/run_worker.py.j2

@@ -22,13 +22,15 @@ async def main():
     if task_queue_name is None:
         raise ValueError("WORKFLOW_TASK_QUEUE is not set")
 
+    all_activities = get_all_activities() + []  # add your own activities here
+    
     # Create a worker with automatic tracing
     worker = AgentexWorker(
         task_queue=task_queue_name,
     )
 
     await worker.run(
-        activities=get_all_activities(),
+        activities=all_activities,
         workflow={{ workflow_class }},
     )
 

agentex/lib/core/services/adk/providers/openai.py

@@ -5,13 +5,14 @@ from typing import Any, Literal
 
 from agents import Agent, Runner, RunResult, RunResultStreaming
 from agents.agent import StopAtTools, ToolsToFinalOutputFunction
+from agents.guardrail import InputGuardrail, OutputGuardrail
+from agents.exceptions import InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered
 from agents.mcp import MCPServerStdio
 from mcp import StdioServerParameters
 from openai.types.responses import (
     ResponseCompletedEvent,
     ResponseFunctionToolCall,
     ResponseOutputItemDoneEvent,
-    ResponseReasoningSummaryPartDoneEvent,
     ResponseTextDeltaEvent,
     ResponseReasoningSummaryTextDeltaEvent,
     ResponseReasoningSummaryTextDoneEvent,
@@ -104,6 +105,8 @@ class OpenAIService:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> RunResult:
         """
         Run an agent without streaming or TaskMessage creation.
@@ -122,8 +125,12 @@ class OpenAIService:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
-            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
-
+            mcp_timeout_seconds: Optional param to set the timeout threshold 
+                for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on 
+                initial user input.
+            output_guardrails: Optional list of output guardrails to run on 
+                final agent output.
         Returns:
             SerializableRunResult: The result of the agent run.
         """
@@ -174,6 +181,10 @@ class OpenAIService:
                     agent_kwargs["model_settings"] = (
                         model_settings.to_oai_model_settings()
                     )
+                if input_guardrails is not None:
+                    agent_kwargs["input_guardrails"] = input_guardrails
+                if output_guardrails is not None:
+                    agent_kwargs["output_guardrails"] = output_guardrails
 
                 agent = Agent(**agent_kwargs)
 
@@ -214,6 +225,8 @@ class OpenAIService:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> RunResult:
         """
         Run an agent with automatic TaskMessage creation.
@@ -234,7 +247,8 @@ class OpenAIService:
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
             mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
-
+            input_guardrails: Optional list of input guardrails to run on initial user input.
+            output_guardrails: Optional list of output guardrails to run on final agent output.
         Returns:
             SerializableRunResult: The result of the agent run.
         """
@@ -290,6 +304,10 @@ class OpenAIService:
                     agent_kwargs["model_settings"] = (
                         model_settings.to_oai_model_settings()
                     )
+                if input_guardrails is not None:
+                    agent_kwargs["input_guardrails"] = input_guardrails
+                if output_guardrails is not None:
+                    agent_kwargs["output_guardrails"] = output_guardrails
 
                 agent = Agent(**agent_kwargs)
 
@@ -402,6 +420,8 @@ class OpenAIService:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled but no TaskMessage creation.
@@ -420,8 +440,12 @@ class OpenAIService:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
-            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
-
+            mcp_timeout_seconds: Optional param to set the timeout threshold 
+                for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on 
+                initial user input.
+            output_guardrails: Optional list of output guardrails to run on 
+                final agent output.
         Returns:
             RunResultStreaming: The result of the agent run with streaming.
         """
@@ -471,6 +495,10 @@ class OpenAIService:
                     agent_kwargs["model_settings"] = (
                         model_settings.to_oai_model_settings()
                     )
+                if input_guardrails is not None:
+                    agent_kwargs["input_guardrails"] = input_guardrails
+                if output_guardrails is not None:
+                    agent_kwargs["output_guardrails"] = output_guardrails
 
                 agent = Agent(**agent_kwargs)
 
@@ -511,6 +539,8 @@ class OpenAIService:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled and automatic TaskMessage creation.
@@ -530,7 +560,12 @@ class OpenAIService:
             tools: Optional list of tools.
             output_type: Optional output type.
             tool_use_behavior: Optional tool use behavior.
-            mcp_timeout_seconds: Optional param to set the timeout threshold for the MCP servers. Defaults to 5 seconds.
+            mcp_timeout_seconds: Optional param to set the timeout threshold 
+                for the MCP servers. Defaults to 5 seconds.
+            input_guardrails: Optional list of input guardrails to run on 
+                initial user input.
+            output_guardrails: Optional list of output guardrails to run on 
+                final agent output.
 
         Returns:
             RunResultStreaming: The result of the agent run with streaming.
@@ -589,6 +624,10 @@ class OpenAIService:
                     agent_kwargs["model_settings"] = (
                         model_settings.to_oai_model_settings()
                     )
+                if input_guardrails is not None:
+                    agent_kwargs["input_guardrails"] = input_guardrails
+                if output_guardrails is not None:
+                    agent_kwargs["output_guardrails"] = output_guardrails
 
                 agent = Agent(**agent_kwargs)
 
@@ -829,6 +868,86 @@ class OpenAIService:
                                         await streaming_context.close()
                                         unclosed_item_ids.discard(item_id)
 
+                except InputGuardrailTripwireTriggered as e:
+                    # Handle guardrail trigger by sending a rejection message
+                    rejection_message = "I'm sorry, but I cannot process this request due to a guardrail. Please try a different question."
+                    
+                    # Try to extract rejection message from the guardrail result
+                    if hasattr(e, 'guardrail_result') and hasattr(e.guardrail_result, 'output'):
+                        output_info = getattr(e.guardrail_result.output, 'output_info', {})
+                        if isinstance(output_info, dict) and 'rejection_message' in output_info:
+                            rejection_message = output_info['rejection_message']
+                        elif hasattr(e.guardrail_result, 'guardrail'):
+                            # Fall back to using guardrail name if no custom message
+                            triggered_guardrail_name = getattr(e.guardrail_result.guardrail, 'name', None)
+                            if triggered_guardrail_name:
+                                rejection_message = f"I'm sorry, but I cannot process this request. The '{triggered_guardrail_name}' guardrail was triggered."
+                    
+                    # Create and send the rejection message as a TaskMessage
+                    async with (
+                        self.streaming_service.streaming_task_message_context(
+                            task_id=task_id,
+                            initial_content=TextContent(
+                                author="agent",
+                                content=rejection_message,
+                            ),
+                        ) as streaming_context
+                    ):
+                        # Send the full message
+                        await streaming_context.stream_update(
+                            update=StreamTaskMessageFull(
+                                parent_task_message=streaming_context.task_message,
+                                content=TextContent(
+                                    author="agent",
+                                    content=rejection_message,
+                                ),
+                                type="full",
+                            ),
+                        )
+                    
+                    # Re-raise to let the activity handle it
+                    raise
+                
+                except OutputGuardrailTripwireTriggered as e:
+                    # Handle output guardrail trigger by sending a rejection message
+                    rejection_message = "I'm sorry, but I cannot provide this response due to a guardrail. Please try a different question."
+                    
+                    # Try to extract rejection message from the guardrail result
+                    if hasattr(e, 'guardrail_result') and hasattr(e.guardrail_result, 'output'):
+                        output_info = getattr(e.guardrail_result.output, 'output_info', {})
+                        if isinstance(output_info, dict) and 'rejection_message' in output_info:
+                            rejection_message = output_info['rejection_message']
+                        elif hasattr(e.guardrail_result, 'guardrail'):
+                            # Fall back to using guardrail name if no custom message
+                            triggered_guardrail_name = getattr(e.guardrail_result.guardrail, 'name', None)
+                            if triggered_guardrail_name:
+                                rejection_message = f"I'm sorry, but I cannot provide this response. The '{triggered_guardrail_name}' guardrail was triggered."
+                    
+                    # Create and send the rejection message as a TaskMessage
+                    async with (
+                        self.streaming_service.streaming_task_message_context(
+                            task_id=task_id,
+                            initial_content=TextContent(
+                                author="agent",
+                                content=rejection_message,
+                            ),
+                        ) as streaming_context
+                    ):
+                        # Send the full message
+                        await streaming_context.stream_update(
+                            update=StreamTaskMessageFull(
+                                parent_task_message=streaming_context.task_message,
+                                content=TextContent(
+                                    author="agent",
+                                    content=rejection_message,
+                                ),
+                                type="full",
+                            ),
+                        )
+                    
+                    # Re-raise to let the activity handle it
+                    raise
+
                 finally:
                     # Cleanup: ensure all streaming contexts for this session are properly finished
                     # Create a copy to avoid modifying set during iteration