agentex-sdk 0.4.10__py3-none-any.whl → 0.4.12__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.12"  # x-release-please-version

agentex/lib/adk/_modules/acp.py

@@ -205,6 +205,8 @@ class ACPModule:
         self,
         task_id: str | None = None,
         task_name: str | None = None,
+        agent_id: str | None = None,
+        agent_name: str | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
         start_to_close_timeout: timedelta = timedelta(seconds=5),
@@ -212,11 +214,13 @@ class ACPModule:
         retry_policy: RetryPolicy = DEFAULT_RETRY_POLICY,
     ) -> Task:
         """
-        Cancel a task.
+        Cancel a task by sending cancel request to the agent that owns the task.
 
         Args:
-            task_id: The ID of the task to cancel.
-            task_name: The name of the task to cancel.
+            task_id: ID of the task to cancel.
+            task_name: Name of the task to cancel.
+            agent_id: ID of the agent that owns the task.
+            agent_name: Name of the agent that owns the task.
             trace_id: The trace ID for the task.
             parent_span_id: The parent span ID for the task.
             start_to_close_timeout: The start to close timeout for the task.
@@ -225,6 +229,10 @@ class ACPModule:
 
         Returns:
             The task entry.
+            
+        Raises:
+            ValueError: If neither agent_name nor agent_id is provided,
+                       or if neither task_name nor task_id is provided
         """
         if in_temporal_workflow():
             return await ActivityHelpers.execute_activity(
@@ -232,6 +240,8 @@ class ACPModule:
                 request=TaskCancelParams(
                     task_id=task_id,
                     task_name=task_name,
+                    agent_id=agent_id,
+                    agent_name=agent_name,
                     trace_id=trace_id,
                     parent_span_id=parent_span_id,
                 ),
@@ -244,6 +254,8 @@ class ACPModule:
             return await self._acp_service.task_cancel(
                 task_id=task_id,
                 task_name=task_name,
+                agent_id=agent_id,
+                agent_name=agent_name,
                 trace_id=trace_id,
                 parent_span_id=parent_span_id,
             )

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,10 @@ 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,
+        max_turns: int | None = None,
     ) -> SerializableRunResult | RunResult:
         """
         Run an agent without streaming or TaskMessage creation.
@@ -107,6 +112,10 @@ 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.
+            max_turns: Maximum number of turns the agent can take. Uses Runner's default if None.
 
         Returns:
             Union[SerializableRunResult, RunResult]: SerializableRunResult when in Temporal, RunResult otherwise.
@@ -126,6 +135,10 @@ 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,
+                max_turns=max_turns,
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT,
@@ -150,6 +163,10 @@ 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,
+                max_turns=max_turns,
             )
 
     async def run_agent_auto_send(
@@ -175,6 +192,10 @@ 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,
+        max_turns: int | None = None,
     ) -> SerializableRunResult | RunResult:
         """
         Run an agent with automatic TaskMessage creation.
@@ -197,6 +218,10 @@ 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.
+            max_turns: Maximum number of turns the agent can take. Uses Runner's default if None.
 
         Returns:
             Union[SerializableRunResult, RunResult]: SerializableRunResult when in Temporal, RunResult otherwise.
@@ -217,6 +242,10 @@ 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,
+                max_turns=max_turns,
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT_AUTO_SEND,
@@ -242,6 +271,10 @@ 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,
+                max_turns=max_turns,
             )
 
     async def run_agent_streamed(
@@ -263,6 +296,10 @@ 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,
+        max_turns: int | None = None,
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled but no TaskMessage creation.
@@ -289,6 +326,10 @@ 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.
+            max_turns: Maximum number of turns the agent can take. Uses Runner's default if None.
 
         Returns:
             RunResultStreaming: The result of the agent run with streaming.
@@ -318,6 +359,10 @@ 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,
+            max_turns=max_turns,
         )
 
     async def run_agent_streamed_auto_send(
@@ -344,6 +389,9 @@ class OpenAIModule:
             | ToolsToFinalOutputFunction
         ) = "run_llm_again",
         mcp_timeout_seconds: int | None = None,
+        input_guardrails: list[InputGuardrail] | None = None,
+        output_guardrails: list[OutputGuardrail] | None = None,
+        max_turns: int | None = None,
     ) -> SerializableRunResultStreaming | RunResultStreaming:
         """
         Run an agent with streaming enabled and automatic TaskMessage creation.
@@ -364,9 +412,12 @@ 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.
+            max_turns: Maximum number of turns the agent can take. Uses Runner's default if None.
 
         Returns:
             Union[SerializableRunResultStreaming, RunResultStreaming]: SerializableRunResultStreaming when in Temporal, RunResultStreaming otherwise.
@@ -388,6 +439,9 @@ 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,
+                max_turns=max_turns
             )
             return await ActivityHelpers.execute_activity(
                 activity_name=OpenAIActivityName.RUN_AGENT_STREAMED_AUTO_SEND,
@@ -414,4 +468,7 @@ 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,
+                max_turns=max_turns,
             )

agentex/lib/cli/handlers/deploy_handlers.py

@@ -229,9 +229,12 @@ def merge_deployment_configs(
                 all_env_vars[EnvVarKeys.AUTH_PRINCIPAL_B64.value] = encoded_principal
             else:
                 raise DeploymentError(f"Auth principal unable to be encoded for agent_env_config: {agent_env_config}")
-                
+        
+        logger.info(f"Defined agent helm overrides: {agent_env_config.helm_overrides}")
+        logger.info(f"Before-merge helm values: {helm_values}")
         if agent_env_config.helm_overrides:
             _deep_merge(helm_values, agent_env_config.helm_overrides)
+        logger.info(f"After-merge helm values: {helm_values}")
 
     # Set final environment variables
     # Environment variable precedence: manifest -> environments.yaml -> secrets (highest)

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/environments.yaml.j2

@@ -52,7 +52,7 @@ environments:
         limits:
           cpu: "1000m"
           memory: "2Gi"
-      temporal:
+      temporal-worker:
         enabled: true
         replicaCount: 2
         resources:

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/acp/acp.py

@@ -180,9 +180,19 @@ class ACPService:
         self,
         task_id: str | None = None,
         task_name: str | None = None,
+        agent_id: str | None = None,
+        agent_name: str | None = None,
         trace_id: str | None = None,
         parent_span_id: str | None = None,
-    ) -> Task:
+    ) -> Task:        
+        # Require agent identification
+        if not agent_name and not agent_id:
+            raise ValueError("Either agent_name or agent_id must be provided to identify the agent that owns the task")
+            
+        # Require task identification
+        if not task_name and not task_id:
+            raise ValueError("Either task_name or task_id must be provided to identify the task to cancel")
+        
         trace = self._tracer.trace(trace_id=trace_id)
         async with trace.span(
             parent_id=parent_span_id,
@@ -190,27 +200,32 @@ class ACPService:
             input={
                 "task_id": task_id,
                 "task_name": task_name,
+                "agent_id": agent_id,
+                "agent_name": agent_name,
             },
         ) as span:
             heartbeat_if_in_workflow("task cancel")
+            
+            # Build params for the agent (task identification)
+            params = {}
+            if task_id:
+                params["task_id"] = task_id
             if task_name:
+                params["task_name"] = task_name
+            
+            # Send cancel request to the correct agent
+            if agent_name:
                 json_rpc_response = await self._agentex_client.agents.rpc_by_name(
-                    agent_name=task_name,
+                    agent_name=agent_name,
                     method="task/cancel",
-                    params={
-                        "task_name": task_name,
-                    },
+                    params=params,
                 )
-            elif task_id:
+            else:  # agent_id is provided (validated above)
                 json_rpc_response = await self._agentex_client.agents.rpc(
-                    agent_id=task_id,
+                    agent_id=agent_id,
                     method="task/cancel",
-                    params={
-                        "task_id": task_id,
-                    },
+                    params=params,
                 )
-            else:
-                raise ValueError("Either task_name or task_id must be provided")
 
             task_entry = Task.model_validate(json_rpc_response.result)
             if span: