agentex-sdk 0.7.1__py3-none-any.whl → 0.7.2__py3-none-any.whl

agentex/lib/cli/templates/temporal-openai-agents/dev.ipynb.j2

@@ -0,0 +1,126 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36834357",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from agentex import Agentex\n",
+    "\n",
+    "client = Agentex(base_url=\"http://localhost:5003\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d1c309d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "AGENT_NAME = \"{{ agent_name }}\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f6e6ef0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# (REQUIRED) Create a new task. For Async agents, you must create a task for messages to be associated with.\n",
+    "import uuid\n",
+    "\n",
+    "rpc_response = client.agents.create_task(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    params={\n",
+    "        \"name\": f\"{str(uuid.uuid4())[:8]}-task\",\n",
+    "        \"params\": {}\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "task = rpc_response.result\n",
+    "print(task)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b03b0d37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Send an event to the agent\n",
+    "\n",
+    "# The response is expected to be a list of TaskMessage objects, which is a union of the following types:\n",
+    "# - TextContent: A message with just text content   \n",
+    "# - DataContent: A message with JSON-serializable data content\n",
+    "# - ToolRequestContent: A message with a tool request, which contains a JSON-serializable request to call a tool\n",
+    "# - ToolResponseContent: A message with a tool response, which contains response object from a tool call in its content\n",
+    "\n",
+    "# When processing the message/send response, if you are expecting more than TextContent, such as DataContent, ToolRequestContent, or ToolResponseContent, you can process them as well\n",
+    "\n",
+    "rpc_response = client.agents.send_event(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    params={\n",
+    "        \"content\": {\"type\": \"text\", \"author\": \"user\", \"content\": \"Hello what can you do?\"},\n",
+    "        \"task_id\": task.id,\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "event = rpc_response.result\n",
+    "print(event)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a6927cc0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Subscribe to the async task messages produced by the agent\n",
+    "from agentex.lib.utils.dev_tools import subscribe_to_async_task_messages\n",
+    "\n",
+    "task_messages = subscribe_to_async_task_messages(\n",
+    "    client=client,\n",
+    "    task=task, \n",
+    "    only_after_timestamp=event.created_at, \n",
+    "    print_messages=True,\n",
+    "    rich_print=True,\n",
+    "    timeout=5,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4864e354",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

agentex/lib/cli/templates/temporal-openai-agents/environments.yaml.j2

@@ -0,0 +1,64 @@
+# Agent Environment Configuration
+# ------------------------------
+# This file defines environment-specific settings for your agent.
+# This DIFFERS from the manifest.yaml file in that it is used to program things that are ONLY per environment.
+
+# ********** EXAMPLE **********
+# schema_version: "v1" # This is used to validate the file structure and is not used by the agentex CLI
+# environments:
+#   dev:
+#     auth:
+#       principal:
+#         user_id: "1234567890"
+#         user_name: "John Doe"
+#         user_email: "john.doe@example.com"
+#         user_role: "admin"
+#       user_permissions: "read, write, delete"
+#     helm_overrides: # This is used to override the global helm values.yaml file in the agentex-agent helm charts
+#       replicas: 3
+#       resources:
+#         requests:
+#           cpu: "1000m"
+#           memory: "2Gi"
+#         limits:
+#           cpu: "2000m"
+#           memory: "4Gi"
+#       env:
+#         - name: LOG_LEVEL
+#           value: "DEBUG"
+#         - name: ENVIRONMENT
+#           value: "staging"
+#
+#     kubernetes: 
+#       # OPTIONAL - Otherwise it will be derived from separately. However, this can be used to override the derived
+#       #   namespace and deploy it with in the same namespace that already exists for a separate agent.
+#       namespace: "team-{{agent_name}}"
+# ********** END EXAMPLE **********
+
+schema_version: "v1" # This is used to validate the file structure and is not used by the agentex CLI
+environments:
+  dev:
+    auth:
+      principal:
+        user_id: # TODO: Fill in
+        account_id: # TODO: Fill in
+    helm_overrides: 
+      # This is used to override the global helm values.yaml file in the agentex-agent helm charts
+      replicaCount: 2
+      resources:
+        requests:
+          cpu: "500m"
+          memory: "1Gi"
+        limits:
+          cpu: "1000m"
+          memory: "2Gi"
+      temporal-worker:
+        enabled: true
+        replicaCount: 2
+        resources:
+          requests:
+            cpu: "500m"
+            memory: "1Gi"
+          limits:
+            cpu: "1000m"
+            memory: "2Gi"

agentex/lib/cli/templates/temporal-openai-agents/manifest.yaml.j2

@@ -0,0 +1,140 @@
+# Agent Manifest Configuration
+# ---------------------------
+# This file defines how your agent should be built and deployed.
+
+# Build Configuration
+# ------------------
+# The build config defines what gets packaged into your agent's Docker image.
+# This same configuration is used whether building locally or remotely.
+#
+# When building:
+# 1. All files from include_paths are collected into a build context
+# 2. The context is filtered by dockerignore rules
+# 3. The Dockerfile uses this context to build your agent's image
+# 4. The image is pushed to a registry and used to run your agent
+build:
+  context:
+    # Root directory for the build context
+    root: ../  # Keep this as the default root
+
+    # Paths to include in the Docker build context
+    # Must include:
+    # - Your agent's directory (your custom agent code)
+    # These paths are collected and sent to the Docker daemon for building
+    include_paths:
+      - {{ project_path_from_build_root }}
+
+    # Path to your agent's Dockerfile
+    # This defines how your agent's image is built from the context
+    # Relative to the root directory
+    dockerfile: {{ project_path_from_build_root }}/Dockerfile
+
+    # Path to your agent's .dockerignore
+    # Filters unnecessary files from the build context
+    # Helps keep build context small and builds fast
+    dockerignore: {{ project_path_from_build_root }}/.dockerignore
+
+
+# Local Development Configuration
+# -----------------------------
+# Only used when running the agent locally
+local_development:
+  agent:
+    port: 8000  # Port where your local ACP server is running
+    host_address: host.docker.internal  # Host address for Docker networking (host.docker.internal for Docker, localhost for direct) 
+
+  # File paths for local development (relative to this manifest.yaml)
+  paths:
+    # Path to ACP server file
+    # Examples:
+    #   project/acp.py          (standard)
+    #   src/server.py           (custom structure)
+    #   ../shared/acp.py        (shared across projects)
+    #   /absolute/path/acp.py   (absolute path)
+    acp: project/acp.py
+    
+    # Path to temporal worker file
+    # Examples:
+    #   project/run_worker.py   (standard)
+    #   workers/temporal.py     (custom structure)
+    #   ../shared/worker.py     (shared across projects)
+    worker: project/run_worker.py
+
+
+# Agent Configuration
+# -----------------
+agent:
+  # Type of agent - either sync or async
+  acp_type: async
+
+  # Unique name for your agent
+  # Used for task routing and monitoring
+  name: {{ agent_name }}
+
+  # Description of what your agent does
+  # Helps with documentation and discovery
+  description: {{ description }}
+
+  # Temporal workflow configuration
+  # This enables your agent to run as a Temporal workflow for long-running tasks
+  temporal:
+    enabled: true
+    workflows:
+      # Name of the workflow class
+      # Must match the @workflow.defn name in your workflow.py
+      - name: {{ workflow_name }}
+
+        # Queue name for task distribution
+        # Used by Temporal to route tasks to your agent
+        # Convention: <agent_name>_task_queue
+        queue_name: {{ queue_name }}
+
+    # Optional: Health check port for temporal worker
+    # Defaults to 80 if not specified
+    # health_check_port: 80
+
+  # Optional: Credentials mapping
+  # Maps Kubernetes secrets to environment variables
+  # Common credentials include:
+  credentials:
+    - env_var_name: REDIS_URL
+      secret_name: redis-url-secret
+      secret_key: url
+  #   - env_var_name: OPENAI_API_KEY
+  #     secret_name: openai-api-key
+  #     secret_key: api-key
+  
+  # Optional: Set Environment variables for running your agent locally as well 
+  # as for deployment later on
+  env: {}
+  #   OPENAI_API_KEY: "<YOUR_OPENAI_API_KEY_HERE>"
+  #   OPENAI_BASE_URL: "<YOUR_OPENAI_BASE_URL_HERE>"
+  #   OPENAI_ORG_ID: "<YOUR_OPENAI_ORG_ID_HERE>"
+
+
+# Deployment Configuration
+# -----------------------
+# Configuration for deploying your agent to Kubernetes clusters
+deployment:
+  # Container image configuration
+  image:
+    repository: "" # Update with your container registry
+    tag: "latest"  # Default tag, should be versioned in production
+
+  imagePullSecrets: [] # Update with your image pull secret name
+    # - name: my-registry-secret
+
+  # Global deployment settings that apply to all clusters
+  # These can be overridden in cluster-specific environments (environments.yaml)
+  global:
+    # Default replica count
+    replicaCount: 1
+    
+    # Default resource requirements
+    resources:
+      requests:
+        cpu: "500m"
+        memory: "1Gi"
+      limits:
+        cpu: "1000m"
+        memory: "2Gi" 

agentex/lib/cli/templates/temporal-openai-agents/project/acp.py.j2

@@ -0,0 +1,80 @@
+import os
+import sys
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin, ModelActivityParameters
+from datetime import timedelta
+from agentex.lib.core.temporal.plugins.openai_agents.interceptors.context_interceptor import ContextInterceptor
+from agentex.lib.core.temporal.plugins.openai_agents.models.temporal_streaming_model import (
+    TemporalStreamingModelProvider,
+)
+
+# === DEBUG SETUP (AgentEx CLI Debug Support) ===
+if os.getenv("AGENTEX_DEBUG_ENABLED") == "true":
+    try:
+        import debugpy
+        from agentex.lib.utils.logging import make_logger
+
+        logger = make_logger(__name__)
+        debug_port = int(os.getenv("AGENTEX_DEBUG_PORT", "5679"))
+        debug_type = os.getenv("AGENTEX_DEBUG_TYPE", "acp")
+        wait_for_attach = os.getenv("AGENTEX_DEBUG_WAIT_FOR_ATTACH", "false").lower() == "true"
+
+        # Configure debugpy
+        debugpy.configure(subProcess=False)
+        debugpy.listen(debug_port)
+
+        logger.info(f"[{debug_type.upper()}] Debug server listening on port {debug_port}")
+
+        if wait_for_attach:
+            logger.info(f"[{debug_type.upper()}] Waiting for debugger to attach...")
+            debugpy.wait_for_client()
+            logger.info(f"[{debug_type.upper()}] Debugger attached!")
+        else:
+            logger.info(f"[{debug_type.upper()}] Ready for debugger attachment")
+
+    except ImportError:
+        print("debugpy not available. Install with: pip install debugpy")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Debug setup failed: {e}")
+        sys.exit(1)
+# === END DEBUG SETUP ===
+
+from agentex.lib.sdk.fastacp.fastacp import FastACP
+from agentex.lib.types.fastacp import TemporalACPConfig
+
+context_interceptor = ContextInterceptor()
+streaming_model_provider = TemporalStreamingModelProvider()
+
+
+# Create the ACP server
+acp = FastACP.create(
+    acp_type="async",
+    config=TemporalACPConfig(
+        # When deployed to the cluster, the Temporal address will automatically be set to the cluster address
+        # For local development, we set the address manually to talk to the local Temporal service set up via docker compose
+        type="temporal",
+        temporal_address=os.getenv("TEMPORAL_ADDRESS", "localhost:7233"),
+        plugins=[OpenAIAgentsPlugin(
+            model_params=ModelActivityParameters(
+                start_to_close_timeout=timedelta(days=1)
+            ),
+            model_provider=streaming_model_provider
+        )],
+        interceptors=[context_interceptor]
+    )
+)
+
+
+# Notice that we don't need to register any handlers when we use type="temporal"
+# If you look at the code in agentex.sdk.fastacp.impl.temporal_acp
+# You can see that these handlers are automatically registered when the ACP is created
+
+# @acp.on_task_create
+# This will be handled by the method in your workflow that is decorated with @workflow.run
+
+# @acp.on_task_event_send
+# This will be handled by the method in your workflow that is decorated with @workflow.signal(name=SignalName.RECEIVE_MESSAGE)
+
+# @acp.on_task_cancel
+# This does not need to be handled by your workflow.
+# It is automatically handled by the temporal client which cancels the workflow directly

agentex/lib/cli/templates/temporal-openai-agents/project/activities.py.j2

@@ -0,0 +1,116 @@
+"""
+Temporal Activities for OpenAI Agents SDK
+==========================================
+
+WHAT ARE ACTIVITIES?
+--------------------
+Activities are functions that perform non-deterministic operations - things that
+might have different results each time they run, such as:
+- API calls (weather services, databases, external services)
+- File I/O operations
+- Current time/date lookups
+- Random number generation
+- Any operation with side effects
+
+Temporal workflows must be deterministic (same input = same output every time).
+Activities let you safely perform non-deterministic work while Temporal handles
+retries, timeouts, and failure recovery automatically.
+
+
+HOW TO ADD NEW ACTIVITIES:
+--------------------------
+Adding a new activity requires 3 steps:
+
+1. DEFINE the activity in this file with the @activity.defn decorator:
+
+    @activity.defn
+    async def my_new_activity(param: str) -> str:
+        # Your non-deterministic logic here
+        return result
+
+2. REGISTER it in run_worker.py by adding to the activities list:
+
+    from project.activities import get_weather, my_new_activity
+
+    all_activities = get_all_activities() + [
+        stream_lifecycle_content,
+        get_weather,
+        my_new_activity,  # Add your new activity here
+    ]
+
+3. ADD it as a tool to your OpenAI agent in workflow.py:
+
+    from project.activities import get_weather, my_new_activity
+
+    agent = Agent(
+        name="...",
+        tools=[
+            openai_agents.workflow.activity_as_tool(
+                get_weather,
+                start_to_close_timeout=timedelta(minutes=5),
+            ),
+            openai_agents.workflow.activity_as_tool(
+                my_new_activity,  # Add your new activity as a tool
+                start_to_close_timeout=timedelta(minutes=5),
+            ),
+        ],
+    )
+
+
+RUNNING ACTIVITIES OUTSIDE OPENAI AGENT SDK:
+--------------------------------------------
+You can also call activities directly from your workflow without going through
+the OpenAI agent. This is useful for setup/teardown operations or when you need
+to run an activity before the agent starts:
+
+    from temporalio import workflow
+    from datetime import timedelta
+
+    # Inside your workflow method:
+    result = await workflow.execute_activity(
+        get_weather,
+        start_to_close_timeout=timedelta(minutes=5),
+    )
+
+For activities with parameters:
+
+    result = await workflow.execute_activity(
+        my_activity_with_params,
+        "param_value",  # positional args
+        start_to_close_timeout=timedelta(minutes=5),
+    )
+
+
+TEMPORAL DASHBOARD:
+-------------------
+Monitor your workflows and activities in real-time at:
+
+    http://localhost:8080
+
+The dashboard shows:
+- Running and completed workflows
+- Activity execution history
+- Retries and failures
+- Workflow state and signals
+"""
+
+from temporalio import activity
+
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+
+@activity.defn
+async def get_weather() -> str:
+    """
+    Get the current weather.
+
+    This is a dummy activity that returns a hardcoded string for demo purposes.
+    Replace this with a real weather API call in your implementation.
+
+    Returns:
+        A string describing the current weather conditions.
+    """
+    logger.info("get_weather activity called")
+    return "Sunny, 72°F"

agentex/lib/cli/templates/temporal-openai-agents/project/run_worker.py.j2

@@ -0,0 +1,56 @@
+import asyncio
+
+from agentex.lib.core.temporal.activities import get_all_activities
+from agentex.lib.core.temporal.workers.worker import AgentexWorker
+from agentex.lib.utils.logging import make_logger
+from agentex.lib.utils.debug import setup_debug_if_enabled
+from agentex.lib.environment_variables import EnvironmentVariables
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin, ModelActivityParameters
+from datetime import timedelta
+from agentex.lib.core.temporal.plugins.openai_agents.interceptors.context_interceptor import ContextInterceptor
+from agentex.lib.core.temporal.plugins.openai_agents.hooks.activities import stream_lifecycle_content
+from agentex.lib.core.temporal.plugins.openai_agents.models.temporal_streaming_model import (
+    TemporalStreamingModelProvider,
+)
+from project.workflow import {{ workflow_class }}
+from project.activities import get_weather
+
+environment_variables = EnvironmentVariables.refresh()
+
+logger = make_logger(__name__)
+
+
+async def main():
+    # Setup debug mode if enabled
+    setup_debug_if_enabled()
+
+    task_queue_name = environment_variables.WORKFLOW_TASK_QUEUE
+    if task_queue_name is None:
+        raise ValueError("WORKFLOW_TASK_QUEUE is not set")
+
+    # Register all activities here
+    # When you add new activities in activities.py, add them to this list
+    all_activities = get_all_activities() + [stream_lifecycle_content, get_weather]
+
+    context_interceptor = ContextInterceptor()
+    streaming_model_provider = TemporalStreamingModelProvider()
+
+    # Create a worker with automatic tracing
+    worker = AgentexWorker(
+        task_queue=task_queue_name,
+        plugins=[OpenAIAgentsPlugin(
+            model_params=ModelActivityParameters(
+                start_to_close_timeout=timedelta(days=1)
+            ),
+            model_provider=streaming_model_provider
+        )],
+        interceptors=[context_interceptor],
+    )
+
+    await worker.run(
+        activities=all_activities,
+        workflow={{ workflow_class }},
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main())