agentex-sdk 0.1.0a6__py3-none-any.whl

agentex/lib/cli/templates/temporal/Dockerfile.j2

@@ -0,0 +1,48 @@
+# syntax=docker/dockerfile:1.3
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.6.4 /uv /uvx /bin/
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    htop \
+    vim \
+    curl \
+    tar \
+    python3-dev \
+    postgresql-client \
+    build-essential \
+    libpq-dev \
+    gcc \
+    cmake \
+    netcat-openbsd \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install tctl (Temporal CLI)
+RUN curl -L https://github.com/temporalio/tctl/releases/download/v1.18.1/tctl_1.18.1_linux_arm64.tar.gz -o /tmp/tctl.tar.gz && \
+    tar -xzf /tmp/tctl.tar.gz -C /usr/local/bin && \
+    chmod +x /usr/local/bin/tctl && \
+    rm /tmp/tctl.tar.gz
+
+RUN uv pip install --system --upgrade pip setuptools wheel
+
+ENV UV_HTTP_TIMEOUT=1000
+
+# Copy just the requirements file to optimize caching
+COPY {{ project_path_from_build_root }}/requirements.txt /app/{{ project_path_from_build_root }}/requirements.txt
+
+WORKDIR /app/{{ project_path_from_build_root }}
+
+# Install the required Python packages
+RUN uv pip install --system -r requirements.txt
+
+# Copy the project code
+COPY {{ project_path_from_build_root }}/project /app/{{ project_path_from_build_root }}/project
+
+WORKDIR /app/{{ project_path_from_build_root }}/project
+
+# Run the ACP server using uvicorn
+CMD ["uvicorn", "acp:acp", "--host", "0.0.0.0", "--port", "8000"]
+
+# When we deploy the worker, we will replace the CMD with the following
+# CMD ["python", "-m", "run_worker"] 

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

@@ -0,0 +1,316 @@
+# {{ agent_name }} - AgentEx Temporal Agent Template
+
+This is a starter template for building asynchronous agents with the AgentEx framework and Temporal. It provides a basic implementation of the Agent 2 Client Protocol (ACP) with Temporal workflow support to help you get started quickly.
+
+## What You'll Learn
+
+- **Tasks**: A task is a grouping mechanism for related messages. Think of it as a conversation thread or a session.
+- **Messages**: Messages are communication objects within a task. They can contain text, data, or instructions.
+- **ACP Events**: The agent responds to four main events:
+  - `task_received`: When a new task is created
+  - `task_message_received`: When a message is sent within a task
+  - `task_approved`: When a task is approved
+  - `task_canceled`: When a task is canceled
+- **Temporal Workflows**: Long-running processes that can handle complex state management and async operations
+
+## Running the Agent
+
+1. Run the agent locally:
+```bash
+agentex agents run --manifest manifest.yaml
+```
+
+The agent will start on port 8000 and print messages whenever it receives any of the ACP events.
+
+## What's Inside
+
+This template:
+- Sets up a basic ACP server with Temporal integration
+- Handles each of the required ACP events
+- Provides a foundation for building complex async agents
+- Includes Temporal workflow and activity definitions
+
+## Next Steps
+
+For more advanced agent development, check out the AgentEx tutorials:
+
+- **Tutorials 00-08**: Learn about building synchronous agents with ACP
+- **Tutorials 09-10**: Learn how to use Temporal to power asynchronous agents
+  - Tutorial 09: Basic Temporal workflow setup
+  - Tutorial 10: Advanced Temporal patterns and best practices
+
+These tutorials will help you understand:
+- How to handle long-running tasks
+- Implementing state machines
+- Managing complex workflows
+- Best practices for async agent development
+
+## The Manifest File
+
+The `manifest.yaml` file is your agent's configuration file. It defines:
+- How your agent should be built and packaged
+- What files are included in your agent's Docker image
+- Your agent's name and description
+- Local development settings (like the port your agent runs on)
+- Temporal worker configuration
+
+This file is essential for both local development and deployment of your agent.
+
+## Project Structure
+
+```
+{{ project_name }}/
+├── project/                  # Your agent's code
+│   ├── __init__.py
+│   ├── acp.py               # ACP server and event handlers
+│   ├── workflow.py          # Temporal workflow definitions
+│   ├── activities.py        # Temporal activity definitions
+│   └── run_worker.py        # Temporal worker setup
+├── Dockerfile               # Container definition
+├── manifest.yaml            # Deployment config
+{% if use_uv %}
+└── pyproject.toml          # Dependencies (uv)
+{% else %}
+└── requirements.txt         # Dependencies (pip)
+{% endif %}
+```
+
+## Development
+
+### 1. Customize Event Handlers
+- Modify the handlers in `acp.py` to implement your agent's logic
+- Add your own tools and capabilities
+- Implement custom state management
+
+### 2. Develop Temporal Workflows
+- Edit `workflow.py` to define your agent's async workflow logic
+- Modify `activities.py` to add custom activities
+- Use `run_worker.py` to configure the Temporal worker
+
+### 3. Manage Dependencies
+
+{% if use_uv %}
+You chose **uv** for package management. Here's how to work with dependencies:
+
+```bash
+# Add new dependencies
+agentex uv add requests openai anthropic
+
+# Add Temporal-specific dependencies (already included)
+agentex uv add temporalio
+
+# Install/sync dependencies
+agentex uv sync
+
+# Run commands with uv
+uv run agentex agents run --manifest manifest.yaml
+```
+
+**Benefits of uv:**
+- Faster dependency resolution and installation
+- Better dependency isolation
+- Modern Python packaging standards
+
+{% else %}
+You chose **pip** for package management. Here's how to work with dependencies:
+
+```bash
+# Probably create a conda env for your agent.
+# Optionally add agentex-sdk editable installation
+
+# Edit requirements.txt manually to add dependencies
+echo "requests" >> requirements.txt
+echo "openai" >> requirements.txt
+
+# Temporal dependencies are already included
+# temporalio is already in requirements.txt
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+**Benefits of pip:**
+- Familiar workflow for most Python developers
+- Simple requirements.txt management
+- Wide compatibility
+{% endif %}
+
+### 4. Configure Credentials
+- Add any required credentials to your manifest.yaml
+- For local development, create a `.env` file in the project directory
+- Use `load_dotenv()` only in development mode:
+
+```python
+import os
+from dotenv import load_dotenv
+
+if os.environ.get("ENVIRONMENT") == "development":
+    load_dotenv()
+```
+
+## Local Development
+
+### 1. Start the Agentex Backend
+```bash
+# Navigate to the backend directory
+cd agentex
+
+# Start all services using Docker Compose
+make dev
+
+# Optional: In a separate terminal, use lazydocker for a better UI (everything should say "healthy")
+lzd
+```
+
+### 2. Setup Your Agent's requirements/pyproject.toml
+```bash
+agentex uv sync [--group editable-apy]
+source .venv/bin/activate
+
+# OR
+conda create -n {{ project_name }} python=3.12
+conda activate {{ project_name }}
+pip install -r requirements.txt
+```
+### 3. Run Your Agent
+```bash
+# From this directory
+export ENVIRONMENT=development && [uv run] agentex agents run --manifest manifest.yaml
+```
+4. **Interact with your agent**
+
+Option 0: CLI (deprecated - to be replaced once a new CLI is implemented - please use the web UI for now!)
+```bash
+# Submit a task via CLI
+agentex tasks submit --agent {{ agent_name }} --task "Your task here"
+```
+
+Option 1: Web UI
+```bash
+# Start the local web interface
+cd agentex-web
+make dev
+
+# Then open http://localhost:3000 in your browser to chat with your agent
+```
+
+## Development Tips
+
+### Environment Variables
+- Set environment variables in project/.env for any required credentials
+- Or configure them in the manifest.yaml under the `env` section
+- The `.env` file is automatically loaded in development mode
+
+### Local Testing
+- Use `export ENVIRONMENT=development` before running your agent
+- This enables local service discovery and debugging features
+- Your agent will automatically connect to locally running services
+
+### Temporal-Specific Tips
+- Monitor workflows in the Temporal Web UI at http://localhost:8080
+- Use the Temporal CLI for advanced workflow management
+- Check workflow logs for debugging async operations
+
+### Debugging
+- Check agent logs in the terminal where you ran the agent
+- Use the web UI to inspect task history and responses
+- Monitor backend services with `lzd` (LazyDocker)
+- Use Temporal Web UI for workflow debugging
+
+### To build the agent Docker image locally (normally not necessary):
+
+1. Build the agent image:
+```bash
+agentex agents build --manifest manifest.yaml
+```
+
+## Advanced Features
+
+### Temporal Workflows
+Extend your agent with sophisticated async workflows:
+
+```python
+# In project/workflow.py
+@workflow.defn
+class MyWorkflow(BaseWorkflow):
+    async def complex_operation(self):
+        # Multi-step async operations
+        # Error handling and retries
+        # State management
+        pass
+```
+
+### Custom Activities
+Add custom activities for external operations:
+
+```python
+# In project/activities.py
+@activity.defn
+async def call_external_api(data):
+    # HTTP requests, database operations, etc.
+    pass
+```
+
+### Integration with External Services
+{% if use_uv %}
+```bash
+# Add service clients
+agentex uv add httpx requests-oauthlib
+
+# Add AI/ML libraries
+agentex uv add openai anthropic transformers
+
+# Add database clients
+agentex uv add asyncpg redis
+```
+{% else %}
+```bash
+# Add to requirements.txt
+echo "httpx" >> requirements.txt
+echo "openai" >> requirements.txt
+echo "asyncpg" >> requirements.txt
+pip install -r requirements.txt
+```
+{% endif %}
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Agent not appearing in web UI**
+   - Check if agent is running on port 8000
+   - Verify `ENVIRONMENT=development` is set
+   - Check agent logs for errors
+
+2. **Temporal workflow issues**
+   - Check Temporal Web UI at http://localhost:8080
+   - Verify Temporal server is running in backend services
+   - Check workflow logs for specific errors
+
+3. **Dependency issues**
+{% if use_uv %}
+   - Run `agentex uv sync` to ensure all dependencies are installed
+   - Verify temporalio is properly installed
+{% else %}
+   - Run `pip install -r requirements.txt`
+   - Check if all dependencies are correctly listed in requirements.txt
+   - Verify temporalio is installed correctly
+{% endif %}
+
+4. **Port conflicts**
+   - Check if another service is using port 8000
+   - Use `lsof -i :8000` to find conflicting processes
+
+### Temporal-Specific Troubleshooting
+
+1. **Workflow not starting**
+   - Check if Temporal server is running (`docker ps`)
+   - Verify task queue configuration in `run_worker.py`
+   - Check workflow registration in the worker
+
+2. **Activity failures**
+   - Check activity logs in the console
+   - Verify activity registration
+   - Check for timeout issues
+
+Happy building with Temporal! 🚀⚡

agentex/lib/cli/templates/temporal/deploy/example.yaml.j2

@@ -0,0 +1,55 @@
+# Example Override Configuration
+# =============================
+# This file shows how to override deployment settings from the global defaults in manifest.yaml.
+# You can create multiple override files for different environments (e.g., staging.yaml, prod.yaml, dev.yaml)
+# Only specify values that differ from the global defaults in manifest.yaml
+
+# Override image tag
+# image:
+#   tag: "v1.2.3"
+
+# Override replica count
+# replicaCount: 2
+
+# Environment-specific environment variables
+# env:
+#   - name: LOG_LEVEL
+#     value: "DEBUG"
+#   - name: ENVIRONMENT
+#     value: "staging"
+
+# Override resource requirements
+# resources:
+#   requests:
+#     cpu: "250m"
+#     memory: "512Mi"
+#   limits:
+#     cpu: "500m"
+#     memory: "1Gi"
+
+# Advanced: Additional helm chart value overrides
+# Use this for any helm chart values not covered by the simple options above
+# additional_overrides:
+#   autoscaling:
+#     enabled: true
+#     minReplicas: 2
+#     maxReplicas: 10
+#     targetCPUUtilizationPercentage: 70
+#   
+#   service:
+#     type: LoadBalancer
+#   
+#   ingress:
+#     enabled: true
+#     annotations:
+#       kubernetes.io/ingress.class: "nginx"
+#     hosts:
+#       - host: {{ agent_name }}.example.com
+#         paths:
+#           - path: /
+#             pathType: Prefix
+
+# To use this configuration:
+# 1. Copy this file to a new file (e.g., staging.yaml, prod.yaml)
+# 2. Uncomment and modify the values you want to override
+# 3. Deploy with: agentex agents deploy --cluster your-cluster --namespace your-namespace --override-file staging.yaml 

agentex/lib/cli/templates/temporal/manifest.yaml.j2

@@ -0,0 +1,137 @@
+# 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 agentic
+  acp_type: agentic
+
+  # 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: Credentials mapping
+  # Maps Kubernetes secrets to environment variables
+  # Common credentials include:
+  # credentials:
+  #   - 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:
+    - name: my-registry-secret  # Update with your image pull secret name
+
+  # Global deployment settings that apply to all clusters
+  # These can be overridden using --override-file with custom configuration files
+  global:
+    agent:
+      name: "{{ agent_name }}"
+      description: "{{ description }}"
+    
+    # Default replica count
+    replicaCount: 1
+    
+    # Default resource requirements
+    resources:
+      requests:
+        cpu: "500m"
+        memory: "1Gi"
+      limits:
+        cpu: "1000m"
+        memory: "2Gi" 

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

@@ -0,0 +1,30 @@
+import os
+from agentex.lib.sdk.fastacp.fastacp import FastACP
+from agentex.lib.types.fastacp import TemporalACPConfig
+
+
+# Create the ACP server
+acp = FastACP.create(
+    acp_type="agentic",
+    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")
+    )
+)
+
+
+# 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/project/run_worker.py.j2

@@ -0,0 +1,33 @@
+import asyncio
+import os
+
+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.environment_variables import EnvironmentVariables
+
+from workflow import {{ workflow_class }}
+
+
+environment_variables = EnvironmentVariables.refresh()
+
+logger = make_logger(__name__)
+
+
+async def main():
+    task_queue_name = environment_variables.WORKFLOW_TASK_QUEUE
+    if task_queue_name is None:
+        raise ValueError("WORKFLOW_TASK_QUEUE is not set")
+
+    # Create a worker with automatic tracing
+    worker = AgentexWorker(
+        task_queue=task_queue_name,
+    )
+
+    await worker.run(
+        activities=get_all_activities(),
+        workflow={{ workflow_class }},
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

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

@@ -0,0 +1,66 @@
+import json
+
+from temporalio import workflow
+
+from agentex.lib import adk
+from agentex.lib.types.acp import CreateTaskParams, SendEventParams
+from agentex.lib.core.temporal.workflows.workflow import BaseWorkflow
+from agentex.lib.core.temporal.types.workflow import SignalName
+from agentex.lib.utils.logging import make_logger
+from agentex.types.task_message import TextContent
+from agentex.lib.environment_variables import EnvironmentVariables
+
+environment_variables = EnvironmentVariables.refresh()
+
+if environment_variables.WORKFLOW_NAME is None:
+    raise ValueError("Environment variable WORKFLOW_NAME is not set")
+
+if environment_variables.AGENT_NAME is None:
+    raise ValueError("Environment variable AGENT_NAME is not set")
+
+logger = make_logger(__name__)
+
+@workflow.defn(name=environment_variables.WORKFLOW_NAME)
+class {{ workflow_class }}(BaseWorkflow):
+    """
+    Minimal async workflow template for AgentEx Temporal agents.
+    """
+    def __init__(self):
+        super().__init__(display_name=environment_variables.AGENT_NAME)
+        self._complete_task = False
+
+    @workflow.signal(name=SignalName.RECEIVE_EVENT)
+    async def on_task_event_send(self, params: SendEventParams) -> None:
+        logger.info(f"Received task message instruction: {params}")
+            
+        # 2. Echo back the client's message to show it in the UI. This is not done by default so the agent developer has full control over what is shown to the user.
+        await adk.messages.create(task_id=params.task.id, content=params.event.content)
+
+        # 3. Send a simple response message.
+        # In future tutorials, this is where we'll add more sophisticated response logic.
+        await adk.messages.create(
+            task_id=params.task.id,
+            content=TextContent(
+                author="agent",
+                content=f"Hello! I've received your message. I can't respond right now, but in future tutorials we'll see how you can get me to intelligently respond to your message.",
+            ),
+        )
+
+    @workflow.run
+    async def on_task_create(self, params: CreateTaskParams) -> str:
+        logger.info(f"Received task create params: {params}")
+
+        # 1. Acknowledge that the task has been created.
+        await adk.messages.create(
+            task_id=params.task.id,
+            content=TextContent(
+                author="agent",
+                content=f"Hello! I've received your task. Normally you can do some state initialization here, or just pass and do nothing until you get your first event. For now I'm just acknowledging that I've received a task with the following params:\n\n{json.dumps(params.params, indent=2)}.\n\nYou should only see this message once, when the task is created. All subsequent events will be handled by the `on_task_event_send` handler.",
+            ),
+        )
+
+        await workflow.wait_condition(
+            lambda: self._complete_task,
+            timeout=None, # Set a timeout if you want to prevent the task from running indefinitely. Generally this is not needed. Temporal can run hundreds of millions of workflows in parallel and more. Only do this if you have a specific reason to do so.
+        )
+        return "Task completed"