agentex-sdk 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

agentex/lib/cli/handlers/agent_handlers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from typing import NamedTuple
 from pathlib import Path
 
 from rich.console import Console
@@ -8,7 +9,7 @@ from python_on_whales import DockerException, docker
 from agentex.lib.cli.debug import DebugConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.cli.handlers.run_handlers import RunError, run_agent as _run_agent
-from agentex.lib.sdk.config.agent_manifest import AgentManifest
+from agentex.lib.sdk.config.agent_manifest import AgentManifest, BuildContextManager
 
 logger = make_logger(__name__)
 console = Console()
@@ -18,6 +19,17 @@ class DockerBuildError(Exception):
     """An error occurred during docker build"""
 
 
+class CloudBuildContext(NamedTuple):
+    """Contains the prepared build context for cloud builds."""
+
+    archive_bytes: bytes
+    dockerfile_path: str
+    agent_name: str
+    tag: str
+    image_name: str
+    build_context_size_kb: float
+
+
 def build_agent(
     manifest_path: str,
     registry_url: str,
@@ -42,9 +54,7 @@ def build_agent(
         The image URL
     """
     agent_manifest = AgentManifest.from_yaml(file_path=manifest_path)
-    build_context_root = (
-        Path(manifest_path).parent / agent_manifest.build.context.root
-    ).resolve()
+    build_context_root = (Path(manifest_path).parent / agent_manifest.build.context.root).resolve()
 
     repository_name = repository_name or agent_manifest.agent.name
 
@@ -85,9 +95,7 @@ def build_agent(
                         key, value = arg.split("=", 1)
                         docker_build_args[key] = value
                     else:
-                        logger.warning(
-                            f"Invalid build arg format: {arg}. Expected KEY=VALUE"
-                        )
+                        logger.warning(f"Invalid build arg format: {arg}. Expected KEY=VALUE")
 
                 if docker_build_args:
                     docker_build_kwargs["build_args"] = docker_build_args
@@ -100,9 +108,7 @@ def build_agent(
             if push:
                 # Build and push in one step for multi-platform builds
                 logger.info("Building and pushing image...")
-                docker_build_kwargs["push"] = (
-                    True  # Push directly after build for multi-platform
-                )
+                docker_build_kwargs["push"] = True  # Push directly after build for multi-platform
                 docker.buildx.build(**docker_build_kwargs)
 
                 logger.info(f"Successfully built and pushed {image_name}")
@@ -146,11 +152,11 @@ def run_agent(manifest_path: str, debug_config: "DebugConfig | None" = None):
         shutting_down = True
         logger.info(f"Received signal {signum}, shutting down...")
         raise KeyboardInterrupt()
-    
+
     # Set up signal handling for the main thread
     signal.signal(signal.SIGINT, signal_handler)
     signal.signal(signal.SIGTERM, signal_handler)
-    
+
     try:
         asyncio.run(_run_agent(manifest_path, debug_config))
     except KeyboardInterrupt:
@@ -158,3 +164,115 @@ def run_agent(manifest_path: str, debug_config: "DebugConfig | None" = None):
         sys.exit(0)
     except RunError as e:
         raise RuntimeError(str(e)) from e
+
+
+def parse_build_args(build_args: list[str] | None) -> dict[str, str]:
+    """Parse build arguments from KEY=VALUE format to a dictionary.
+
+    Args:
+        build_args: List of build arguments in KEY=VALUE format
+
+    Returns:
+        Dictionary mapping keys to values
+    """
+    result: dict[str, str] = {}
+    if not build_args:
+        return result
+
+    for arg in build_args:
+        if "=" in arg:
+            key, value = arg.split("=", 1)
+            result[key] = value
+        else:
+            logger.warning(f"Invalid build arg format: {arg}. Expected KEY=VALUE")
+
+    return result
+
+
+def prepare_cloud_build_context(
+    manifest_path: str,
+    tag: str | None = None,
+    build_args: list[str] | None = None,
+) -> CloudBuildContext:
+    """Prepare the build context for cloud-based container builds.
+
+    Reads the manifest, prepares the build context by copying files according to
+    the include_paths and dockerignore, then creates a compressed tar.gz archive
+    ready for upload to a cloud build service.
+
+    Args:
+        manifest_path: Path to the agent manifest file
+        tag: Image tag override (if None, reads from manifest's deployment.image.tag)
+        build_args: List of build arguments in KEY=VALUE format
+
+    Returns:
+        CloudBuildContext containing the archive bytes, dockerfile path, and metadata
+    """
+    agent_manifest = AgentManifest.from_yaml(file_path=manifest_path)
+    build_context_root = (Path(manifest_path).parent / agent_manifest.build.context.root).resolve()
+
+    agent_name = agent_manifest.agent.name
+    dockerfile_path = agent_manifest.build.context.dockerfile
+
+    # Validate that the Dockerfile exists
+    full_dockerfile_path = build_context_root / dockerfile_path
+    if not full_dockerfile_path.exists():
+        raise FileNotFoundError(
+            f"Dockerfile not found at: {full_dockerfile_path}\n"
+            f"Check that 'build.context.dockerfile' in your manifest points to an existing file."
+        )
+    if not full_dockerfile_path.is_file():
+        raise ValueError(
+            f"Dockerfile path is not a file: {full_dockerfile_path}\n"
+            f"'build.context.dockerfile' must point to a file, not a directory."
+        )
+
+    # Get tag and repository from manifest if not provided
+    if tag is None:
+        if agent_manifest.deployment and agent_manifest.deployment.image:
+            tag = agent_manifest.deployment.image.tag
+        else:
+            tag = "latest"
+
+    # Get repository name from manifest (just the repo name, not the full registry URL)
+    if agent_manifest.deployment and agent_manifest.deployment.image:
+        repository = agent_manifest.deployment.image.repository
+        if repository:
+            # Extract just the repo name (last part after any slashes)
+            image_name = repository.split("/")[-1]
+        else:
+            image_name = "<repository>"
+    else:
+        image_name = "<repository>"
+
+    logger.info(f"Agent: {agent_name}")
+    logger.info(f"Image name: {image_name}")
+    logger.info(f"Build context root: {build_context_root}")
+    logger.info(f"Dockerfile: {dockerfile_path}")
+    logger.info(f"Tag: {tag}")
+
+    if agent_manifest.build.context.include_paths:
+        logger.info(f"Include paths: {agent_manifest.build.context.include_paths}")
+
+    parsed_build_args = parse_build_args(build_args)
+    if parsed_build_args:
+        logger.info(f"Build args: {list(parsed_build_args.keys())}")
+
+    logger.info("Preparing build context...")
+
+    with agent_manifest.context_manager(build_context_root) as build_context:
+        # Compress the prepared context using the static zipped method
+        with BuildContextManager.zipped(root_path=build_context.path) as archive_buffer:
+            archive_bytes = archive_buffer.read()
+
+        build_context_size_kb = len(archive_bytes) / 1024
+        logger.info(f"Build context size: {build_context_size_kb:.1f} KB")
+
+        return CloudBuildContext(
+            archive_bytes=archive_bytes,
+            dockerfile_path=build_context.dockerfile_path,
+            agent_name=agent_name,
+            tag=tag,
+            image_name=image_name,
+            build_context_size_kb=build_context_size_kb,
+        )

agentex/lib/cli/templates/sync-openai-agents/.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/sync-openai-agents/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 \
+    nodejs \
+    npm \ 
+    && 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
+
+# Set environment variables
+ENV PYTHONPATH=/app
+
+# Run the agent using uvicorn
+CMD ["uvicorn", "project.acp:acp", "--host", "0.0.0.0", "--port", "8000"] 

agentex/lib/cli/templates/sync-openai-agents/Dockerfile.j2

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

agentex/lib/cli/templates/sync-openai-agents/README.md.j2

@@ -0,0 +1,313 @@
+# {{ 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
+├── dev.ipynb                # Development notebook for testing
+{% 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. Test Your Agent with the Development Notebook
+Use the included `dev.ipynb` Jupyter notebook to test your agent interactively:
+
+```bash
+# Start Jupyter notebook (make sure you have jupyter installed)
+jupyter notebook dev.ipynb
+
+# Or use VS Code to open the notebook directly
+code dev.ipynb
+```
+
+The notebook includes:
+- **Setup**: Connect to your local AgentEx backend
+- **Non-streaming tests**: Send messages and get complete responses
+- **Streaming tests**: Test real-time streaming responses
+- **Task management**: Optional task creation and management
+
+The notebook automatically uses your agent name (`{{ agent_name }}`) and provides examples for both streaming and non-streaming message handling.
+
+### 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
+
+# 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 %}
+
+### 4. 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! 🚀⚡