agentex-sdk 0.1.0a6__py3-none-any.whl

agentex/lib/cli/templates/sync/Dockerfile-uv.j2

@@ -0,0 +1,42 @@
+# 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/*
+
+RUN uv pip install --system --upgrade pip setuptools wheel
+
+ENV UV_HTTP_TIMEOUT=1000
+
+# Copy just the pyproject.toml file to optimize caching
+COPY {{ project_path_from_build_root }}/pyproject.toml /app/{{ project_path_from_build_root }}/pyproject.toml
+
+WORKDIR /app/{{ project_path_from_build_root }}
+
+# Install the required Python packages using uv
+RUN uv pip install --system .
+
+# 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
+
+# Set environment variables
+ENV PYTHONPATH=/app
+
+# Run the agent using uvicorn
+CMD ["uvicorn", "acp:acp", "--host", "0.0.0.0", "--port", "8000"] 

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

@@ -0,0 +1,42 @@
+# 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/*
+
+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
+
+# Set environment variables
+ENV PYTHONPATH=/app
+
+# Run the agent using uvicorn
+CMD ["uvicorn", "acp:acp", "--host", "0.0.0.0", "--port", "8000"]

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

@@ -0,0 +1,293 @@
+# {{ agent_name }} - AgentEx Sync ACP Template
+
+This is a starter template for building synchronous agents with the AgentEx framework. It provides a basic implementation of the Agent 2 Client Protocol (ACP) with immediate response capabilities 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.
+- **Sync ACP**: Synchronous Agent Communication Protocol that requires immediate responses
+- **Message Handling**: How to process and respond to messages in real-time
+
+## Running the Agent
+
+1. Run the agent locally:
+```bash
+agentex agents run --manifest manifest.yaml
+```
+
+The agent will start on port 8000 and respond immediately to any messages it receives.
+
+## What's Inside
+
+This template:
+- Sets up a basic sync ACP server
+- Handles incoming messages with immediate responses
+- Provides a foundation for building real-time agents
+- Can include streaming support for long responses
+
+## 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)
+
+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
+├── Dockerfile               # Container definition
+├── manifest.yaml            # Deployment config
+{% if use_uv %}
+└── pyproject.toml          # Dependencies (uv)
+{% else %}
+└── requirements.txt         # Dependencies (pip)
+{% endif %}
+```
+
+## Development
+
+### 1. Customize Message Handlers
+- Modify the handlers in `acp.py` to implement your agent's logic
+- Add your own tools and capabilities
+- Implement custom response generation
+
+### 2. 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
+
+# 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
+# Edit requirements.txt manually to add dependencies
+echo "requests" >> requirements.txt
+echo "openai" >> 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 %}
+
+### 3. Configure Credentials
+Options:
+1. Add any required credentials to your manifest.yaml via the `env` section
+2. Export them in your shell: `export OPENAI_API_KEY=...`
+3. For local development, create a `.env.local` file in the project directory
+
+## 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
+```
+
+### 3. Run Your Agent
+```bash
+# From this directory
+export ENVIRONMENT=development && agentex agents run --manifest manifest.yaml
+```
+
+### 4. Interact with Your Agent
+
+**Option 1: Web UI (Recommended)**
+```bash
+# Start the local web interface
+cd agentex-web
+make dev
+
+# Then open http://localhost:3000 in your browser to chat with your agent
+```
+
+**Option 2: CLI (Deprecated)**
+```bash
+# Submit a task via CLI
+agentex tasks submit --agent {{ agent_name }} --task "Your task here"
+```
+
+## 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
+
+### Sync ACP Considerations
+- Responses must be immediate (no long-running operations)
+- Use streaming for longer responses
+- Keep processing lightweight and fast
+- Consider caching for frequently accessed data
+
+### 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)
+- Test response times and optimize for speed
+
+### To build the agent Docker image locally (normally not necessary):
+
+1. Build the agent image:
+```bash
+agentex agents build --manifest manifest.yaml
+```
+{% if use_uv %}
+```bash
+# Build with uv
+agentex agents build --manifest manifest.yaml --push
+```
+{% else %}
+```bash
+# Build with pip
+agentex agents build --manifest manifest.yaml --push
+```
+{% endif %}
+
+
+## Advanced Features
+
+### Streaming Responses
+Handle long responses with streaming:
+
+```python
+# In project/acp.py
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    # For streaming responses
+    async def stream_response():
+        for chunk in generate_response_chunks():
+            yield TaskMessageUpdate(
+                content=chunk,
+                is_complete=False
+            )
+        yield TaskMessageUpdate(
+            content="",
+            is_complete=True
+        )
+    
+    return stream_response()
+```
+
+### Custom Response Logic
+Add sophisticated response generation:
+
+```python
+# In project/acp.py
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    # Analyze input
+    user_message = params.content.content
+    
+    # Generate response
+    response = await generate_intelligent_response(user_message)
+    
+    return TextContent(
+        author=MessageAuthor.AGENT,
+        content=response
+    )
+```
+
+### 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 fast processing libraries
+agentex uv add numpy pandas
+```
+{% else %}
+```bash
+# Add to requirements.txt
+echo "httpx" >> requirements.txt
+echo "openai" >> requirements.txt
+echo "numpy" >> 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. **Slow response times**
+   - Profile your message handling code
+   - Consider caching expensive operations
+   - Optimize database queries and API calls
+
+3. **Dependency issues**
+{% if use_uv %}
+   - Run `agentex uv sync` to ensure all dependencies are installed
+{% else %}
+   - Run `pip install -r requirements.txt`
+   - Check if all dependencies are correctly listed in requirements.txt
+{% endif %}
+
+4. **Port conflicts**
+   - Check if another service is using port 8000
+   - Use `lsof -i :8000` to find conflicting processes
+
+Happy building with Sync ACP! 🚀⚡

agentex/lib/cli/templates/sync/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/sync/manifest.yaml.j2

@@ -0,0 +1,116 @@
+# 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
+
+
+# Agent Configuration
+# -----------------
+agent:
+  acp_type: sync
+  # 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
+  # Set enabled: true to use Temporal workflows for long-running tasks
+  temporal:
+    enabled: false
+
+  # 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
+
+  # Global deployment settings that apply to all clusters
+  # These can be overridden in cluster-specific files (deploy/*.yaml)
+  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/sync/project/acp.py.j2

@@ -0,0 +1,26 @@
+from typing import AsyncGenerator, Union
+from agentex.lib.sdk.fastacp.fastacp import FastACP
+from agentex.lib.types.acp import SendMessageParams
+
+from agentex.lib.types.task_message_updates import TaskMessageUpdate
+from agentex.types.task_message_content import TaskMessageContent
+from agentex.types.text_content import TextContent
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+
+# Create an ACP server
+acp = FastACP.create(
+    acp_type="sync",
+)
+
+@acp.on_message_send
+async def handle_message_send(
+    params: SendMessageParams
+) -> TaskMessageContent | list[TaskMessageContent] | AsyncGenerator[TaskMessageUpdate, None]:
+    """Default message handler with streaming support"""
+    return TextContent(
+        author="agent",
+        content=f"Hello! I've received your message. Here's a generic response, but in future tutorials we'll see how you can get me to intelligently respond to your message. This is what I heard you say: {params.content.content}",
+    )

agentex/lib/cli/templates/sync/pyproject.toml.j2

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ description }}"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "agentex-sdk",
+    "scale-gp",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "black",
+    "isort",
+    "flake8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["project"]
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+
+[tool.isort]
+profile = "black"
+line_length = 88

agentex/lib/cli/templates/sync/requirements.txt.j2

@@ -0,0 +1,5 @@
+# Install agentex-sdk from local path
+agentex-sdk
+
+# Scale GenAI Platform Python SDK
+scale-gp

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

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Environments
+.env**
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Git
+.git
+.gitignore
+
+# Misc
+.DS_Store 

agentex/lib/cli/templates/temporal/Dockerfile-uv.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 pyproject.toml file to optimize caching
+COPY {{ project_path_from_build_root }}/pyproject.toml /app/{{ project_path_from_build_root }}/pyproject.toml
+
+WORKDIR /app/{{ project_path_from_build_root }}
+
+# Install the required Python packages using uv
+RUN uv pip install --system .
+
+# 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"]