agentex-sdk 0.6.7__tar.gz → 0.7.0__tar.gz

{agentex_sdk-0.6.7 → agentex_sdk-0.7.0}/.gitignore

@@ -16,4 +16,7 @@ Brewfile.lock.json
 
 .DS_Store
 
-examples/**/uv.lock
+examples/**/uv.lock
+
+# Claude workspace directories
+.claude-workspace/

agentex_sdk-0.7.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.0"
+}

{agentex_sdk-0.6.7 → agentex_sdk-0.7.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.7.0 (2025-12-09)
+
+Full Changelog: [v0.6.7...v0.7.0](https://github.com/scaleapi/scale-agentex-python/compare/v0.6.7...v0.7.0)
+
+### Features
+
+* **api:** add messages/paginated endpoint ([3e03aff](https://github.com/scaleapi/scale-agentex-python/commit/3e03aff8490e0556cb05052d385156eda8f28107))
+* **api:** add messages/paginated to stainless config ([2473ded](https://github.com/scaleapi/scale-agentex-python/commit/2473ded39274bcd0a16d7314667fcf7f55e829c2))
+* **api:** api update ([f6eccdf](https://github.com/scaleapi/scale-agentex-python/commit/f6eccdf975eaef9b257ef3f20f087f2f2f9b3665))
+* **api:** api update ([41067fb](https://github.com/scaleapi/scale-agentex-python/commit/41067fb79725787e0ceb20dcf16029998bcbca24))
+* **api:** api update ([cdc9c63](https://github.com/scaleapi/scale-agentex-python/commit/cdc9c636be6f26e84772d1d1ef9d47cddcd9dabc))
+* **api:** api update ([413d9c8](https://github.com/scaleapi/scale-agentex-python/commit/413d9c806d918d7c5da3d0249c0f11d4b9f0894e))
+* **api:** api update ([1b4bf7d](https://github.com/scaleapi/scale-agentex-python/commit/1b4bf7d3a11306a50ec0eb9c20764c585d0e98e4))
+* **api:** manual updates ([131e836](https://github.com/scaleapi/scale-agentex-python/commit/131e836b5bda8248f847b00308b6711a1ee84ee0))
+
+
+### Bug Fixes
+
+* ensure streams are always closed ([7bb9db8](https://github.com/scaleapi/scale-agentex-python/commit/7bb9db851a213d261e585cd2f156046f05cf85db))
+* **types:** allow pyright to infer TypedDict types within SequenceNotStr ([9cfc9d6](https://github.com/scaleapi/scale-agentex-python/commit/9cfc9d66579a11f3eaf248bafbfddb422e878a58))
+
+
+### Chores
+
+* add missing docstrings ([81f1fa9](https://github.com/scaleapi/scale-agentex-python/commit/81f1fa9b3c440d893b8ea8f773ab2592eb333d65))
+* **deps:** mypy 1.18.1 has a regression, pin to 1.17 ([e20aaa4](https://github.com/scaleapi/scale-agentex-python/commit/e20aaa495384f547dd18c8d31496f70b4a37e0dd))
+* **docs:** use environment variables for authentication in code snippets ([a30f6ae](https://github.com/scaleapi/scale-agentex-python/commit/a30f6aebca8de5be72eb7bcf7a3b3ccea28479bc))
+* update lockfile ([a3a2e4f](https://github.com/scaleapi/scale-agentex-python/commit/a3a2e4fbcf6e6e4bcbadab50c6b9236e4514dae2))
+
 ## 0.6.7 (2025-11-19)
 
 Full Changelog: [v0.6.6...v0.6.7](https://github.com/scaleapi/scale-agentex-python/compare/v0.6.6...v0.6.7)

{agentex_sdk-0.6.7 → agentex_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.6.7
+Version: 0.7.0
 Summary: The official Python library for the agentex API
 Project-URL: Homepage, https://github.com/scaleapi/scale-agentex-python
 Project-URL: Repository, https://github.com/scaleapi/scale-agentex-python
@@ -20,7 +20,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: <4,>=3.12
 Requires-Dist: aiohttp<4,>=3.10.10
+Requires-Dist: anthropic>=0.40.0
 Requires-Dist: anyio<5,>=3.5.0
+Requires-Dist: claude-agent-sdk>=0.1.0
 Requires-Dist: cloudpickle>=3.1.1
 Requires-Dist: datadog>=0.52.1
 Requires-Dist: ddtrace>=3.13.0
@@ -178,6 +180,7 @@ pip install agentex-sdk[aiohttp]
 Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:
 
 ```python
+import os
 import asyncio
 from agentex import DefaultAioHttpClient
 from agentex import AsyncAgentex
@@ -185,7 +188,7 @@ from agentex import AsyncAgentex
 
 async def main() -> None:
     async with AsyncAgentex(
-        api_key="My API Key",
+        api_key=os.environ.get("AGENTEX_SDK_API_KEY"),  # This is the default and can be omitted
         http_client=DefaultAioHttpClient(),
     ) as client:
         tasks = await client.tasks.list()

{agentex_sdk-0.6.7 → agentex_sdk-0.7.0}/README.md

@@ -113,6 +113,7 @@ pip install agentex-sdk[aiohttp]
 Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:
 
 ```python
+import os
 import asyncio
 from agentex import DefaultAioHttpClient
 from agentex import AsyncAgentex
@@ -120,7 +121,7 @@ from agentex import AsyncAgentex
 
 async def main() -> None:
     async with AsyncAgentex(
-        api_key="My API Key",
+        api_key=os.environ.get("AGENTEX_SDK_API_KEY"),  # This is the default and can be omitted
         http_client=DefaultAioHttpClient(),
     ) as client:
         tasks = await client.tasks.list()

{agentex_sdk-0.6.7 → agentex_sdk-0.7.0}/examples/tutorials/00_sync/000_hello_acp/project/acp.py

@@ -21,7 +21,9 @@ async def handle_message_send(
 ) -> Union[TaskMessageContent, AsyncGenerator[TaskMessageUpdate, None]]:
     """Default message handler with streaming support"""
     # Extract content safely from the message
+
     message_text = ""
+    print(message_text, message_text)
     if hasattr(params.content, "content"):
         content_val = getattr(params.content, "content", "")
         if isinstance(content_val, str):

agentex_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/.dockerignore

@@ -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_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/.gitignore

@@ -0,0 +1,5 @@
+# Local environment variables (contains secrets)
+.env.local
+
+# Workspace directory (created at runtime)
+workspace/

agentex_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/Dockerfile

@@ -0,0 +1,53 @@
+# 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/**
+
+# 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 pyproject.toml and README.md to install dependencies
+COPY 090_claude_agents_sdk_mvp/pyproject.toml /app/090_claude_agents_sdk_mvp/pyproject.toml
+COPY 090_claude_agents_sdk_mvp/README.md /app/090_claude_agents_sdk_mvp/README.md
+
+WORKDIR /app/090_claude_agents_sdk_mvp
+
+# Copy the project code
+COPY 090_claude_agents_sdk_mvp/project /app/090_claude_agents_sdk_mvp/project
+
+# Install the required Python packages from pyproject.toml
+RUN uv pip install --system .
+
+WORKDIR /app/090_claude_agents_sdk_mvp
+
+
+ENV PYTHONPATH=/app
+# Run the ACP server using uvicorn
+CMD ["uvicorn", "project.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_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/README.md

@@ -0,0 +1,338 @@
+# Claude Agents SDK Integration with AgentEx
+
+Integration of Claude Agents SDK with AgentEx's Temporal-based orchestration platform. Claude agents run in durable workflows with real-time streaming to the AgentEx UI.
+
+> ⚠️ **Note**: This integration is designed for local agent development and single-worker deployments. For distributed multi-worker Kubernetes deployments, additional infrastructure is required (see [Deployment Considerations](#deployment-considerations) below).
+
+## Features
+
+- **Durable Execution** - Workflows survive restarts via Temporal's event sourcing (single-worker)
+- **Session Resume** - Conversation context maintained across turns via `session_id`
+- **Workspace Isolation** - Each task gets dedicated directory for file operations
+- **Real-time Streaming** - Text and tool calls stream to UI via Redis
+- **Tool Execution** - Read, Write, Edit, Bash, Grep, Glob with visibility in UI
+- **Subagents** - Specialized agents (code-reviewer, file-organizer) with nested tracing
+- **Cost Tracking** - Token usage and API costs logged per turn
+- **Automatic Retries** - Temporal policies handle transient failures
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────┐
+│  Temporal Workflow              │
+│  - Stores session_id in state   │
+│  - Tracks turn number           │
+│  - Sets _task_id, _trace_id     │
+└────────────┬────────────────────┘
+             │ execute_activity
+             ↓
+┌─────────────────────────────────┐
+│  run_claude_agent_activity      │
+│  - Reads context from ContextVar│
+│  - Configures Claude SDK        │
+│  - Processes messages via hooks │
+│  - Returns session_id           │
+└────────────┬────────────────────┘
+             │ ClaudeSDKClient
+             ↓
+┌─────────────────────────────────┐
+│  Claude SDK                     │
+│  - Maintains session            │
+│  - Calls Anthropic API          │
+│  - Executes tools in workspace  │
+│  - Triggers hooks               │
+└─────────────────────────────────┘
+```
+
+### Context Threading
+
+The integration reuses AgentEx's `ContextInterceptor` pattern (originally built for OpenAI):
+
+1. **Workflow** stores `_task_id`, `_trace_id`, `_parent_span_id` as instance variables
+2. **ContextInterceptor (outbound)** reads these from workflow instance, injects into activity headers
+3. **ContextInterceptor (inbound)** extracts from headers, sets `ContextVar` values
+4. **Activity** reads `ContextVar` to get task_id for streaming
+
+This enables real-time streaming without breaking Temporal's determinism requirements.
+
+### Session Management
+
+Claude SDK sessions are preserved across turns:
+
+1. **First turn**: Claude SDK creates session, returns `session_id` in `SystemMessage`
+2. **Message handler** extracts `session_id` from messages
+3. **Activity** returns `session_id` to workflow
+4. **Workflow** stores in `StateModel.claude_session_id` (Temporal checkpoints this)
+5. **Next turn**: Pass `resume=session_id` to `ClaudeAgentOptions`
+6. **Claude SDK** resumes session with full conversation history
+
+### Tool Streaming via Hooks
+
+Tool lifecycle events are handled by Claude SDK hooks:
+
+**PreToolUse Hook**:
+- Called before tool execution
+- Streams `ToolRequestContent` to UI → shows "Using tool: Write"
+- Creates nested span for Task tool (subagents)
+
+**PostToolUse Hook**:
+- Called after tool execution
+- Streams `ToolResponseContent` to UI → shows "Used tool: Write"
+- Closes subagent spans with results
+
+### Subagent Execution
+
+Subagents are defined as `AgentDefinition` objects passed to Claude SDK:
+
+```python
+agents={
+    'code-reviewer': AgentDefinition(
+        description='Expert code review specialist...',
+        prompt='You are a code reviewer...',
+        tools=['Read', 'Grep', 'Glob'],  # Read-only
+        model='sonnet',
+    )
+}
+```
+
+When Claude uses the Task tool, the SDK routes to the appropriate subagent based on description matching. Subagent execution is tracked via nested tracing spans.
+
+## Code Structure
+
+```
+claude_agents/
+├── __init__.py                 # Public exports
+├── activities.py               # Temporal activities
+│   ├── create_workspace_directory
+│   └── run_claude_agent_activity
+├── message_handler.py          # Message processing
+│   └── ClaudeMessageHandler
+│       ├── Streams text blocks
+│       ├── Extracts session_id
+│       └── Extracts usage/cost
+└── hooks/
+    └── hooks.py                # Claude SDK hooks
+        └── TemporalStreamingHooks
+            ├── pre_tool_use
+            └── post_tool_use
+```
+
+## Deployment Considerations
+
+This integration works well for local development and single-worker deployments. For distributed multi-worker production deployments, consider the following:
+
+### ⚠️ Session Persistence (Multi-Worker)
+
+**Current behavior**: Claude SDK sessions are tied to the worker process.
+
+- **Local dev**: ✅ Works - session persists within single worker
+- **K8s multi-pod**: ⚠️ Session ID stored in Temporal state, but session itself lives in Claude CLI process
+- **Impact**: If task moves to different pod, session becomes invalid
+- **Infrastructure needed**: Session persistence layer or sticky routing to same pod
+
+### ⚠️ Workspace Storage (Multi-Worker)
+
+**Current behavior**: Workspaces are local directories (`./workspace/{task_id}`).
+
+- **Local dev**: ✅ Works - single worker accesses all files
+- **K8s multi-pod**: ⚠️ Each pod has isolated filesystem
+- **Impact**: Files created by one pod are invisible to other pods
+- **Infrastructure needed**: Shared storage (NFS, EFS, GCS Fuse) via `CLAUDE_WORKSPACE_ROOT` env var
+
+**Solution for production**:
+```bash
+# Mount shared filesystem (NFS, EFS, etc.) to all pods
+export CLAUDE_WORKSPACE_ROOT=/mnt/shared/workspaces
+
+# All workers will now share workspace access
+```
+
+### ℹ️ Filesystem-Based Configuration
+
+**Current approach**: Agents and configuration are defined programmatically in code.
+
+- **Not used**: `.claude/agents/`, `.claude/skills/`, `CLAUDE.md` files
+- **Why**: Aligns with AgentEx's code-as-configuration philosophy
+- **Trade-off**: More explicit and version-controlled, but can't leverage existing Claude configs
+- **To enable**: Would need to add `setting_sources=["project"]` to `ClaudeAgentOptions`
+
+**Current approach** (programmatic config in workflow.py):
+```python
+subagents = {
+    'code-reviewer': AgentDefinition(
+        description='...',
+        prompt='...',
+        tools=['Read', 'Grep', 'Glob'],
+        model='sonnet',
+    ),
+}
+```
+
+---
+
+**Summary**: The integration is production-ready for **single-worker deployments**. Multi-worker deployments require additional infrastructure for session persistence and workspace sharing.
+
+## Quick Start
+
+### Prerequisites
+
+- Temporal server (localhost:7233)
+- Redis (localhost:6379)
+- Anthropic API key
+
+### Run
+
+```bash
+# Install
+rye sync --all-features
+
+# Configure
+export ANTHROPIC_API_KEY="your-key"
+export REDIS_URL="redis://localhost:6379"
+export TEMPORAL_ADDRESS="localhost:7233"
+
+# Run from repository root
+uv run agentex agents run --manifest examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/manifest.yaml
+```
+
+## Example Interactions
+
+### Context Preservation
+
+```
+User: "Your name is Jose"
+Claude: "Nice to meet you! I'm Jose..."
+
+User: "What name did I assign to you?"
+Claude: "You asked me to go by Jose!"  ← Remembers context
+```
+
+### Tool Usage
+
+```
+User: "Create a hello.c file with Hello World"
+Claude: *streams response*
+[Tool card appears: "Using tool: Write"]
+[Tool card updates: "Used tool: Write"]
+"Done! I've created hello.c..."
+```
+
+### Subagents
+
+```
+User: "Review the code quality in hello.c"
+Claude: *delegates to code-reviewer*
+[Tool card: "Using tool: Task" with subagent_type: "code-reviewer"]
+[Traces view shows: "Subagent: code-reviewer" nested under turn]
+```
+
+## Behind the Scenes
+
+### Message Flow
+
+When a user sends a message:
+
+1. **Signal received** (`on_task_event_send`) - Workflow increments turn, echoes message
+2. **Span created** - Tracing span wraps turn, stores `parent_span_id` for interceptor
+3. **Activity called** - Workflow passes prompt, workspace, session_id, subagent defs
+4. **Context threaded** - Interceptor injects task_id/trace_id into activity headers
+5. **Activity starts** - Reads context from ContextVar, creates hooks
+6. **Claude executes** - SDK uses hooks to stream tools, message_handler streams text
+7. **Results returned** - Activity returns session_id, usage, cost
+8. **State updated** - Workflow stores session_id for next turn
+
+### Streaming Pipeline
+
+**Text streaming**:
+```
+Claude SDK → TextBlock → ClaudeMessageHandler._handle_text_block()
+→ TextDelta → adk.streaming.stream_update()
+→ Redis XADD → AgentEx UI
+```
+
+**Tool streaming**:
+```
+Claude SDK → PreToolUse hook → ToolRequestContent
+→ adk.streaming (via hook) → Redis → UI ("Using tool...")
+
+Tool executes...
+
+Claude SDK → PostToolUse hook → ToolResponseContent
+→ adk.streaming (via hook) → Redis → UI ("Used tool...")
+```
+
+### Subagent Tracing
+
+When Task tool is detected in PreToolUse hook:
+
+```python
+# Create nested span
+span_ctx = adk.tracing.span(
+    trace_id=trace_id,
+    parent_id=parent_span_id,
+    name=f"Subagent: {subagent_type}",
+    input=tool_input,
+)
+span = await span_ctx.__aenter__()
+
+# Store for PostToolUse to close
+self.subagent_spans[tool_use_id] = (span_ctx, span)
+```
+
+In PostToolUse hook, the span is closed with results, creating a complete nested trace.
+
+## Key Implementation Details
+
+### Temporal Determinism
+
+- **File I/O in activities**: `create_workspace_directory` is an activity (not workflow code)
+- **Message iteration completes**: Use `receive_response()` (not `receive_messages()`)
+- **State is serializable**: `StateModel` uses Pydantic BaseModel
+
+### AgentDefinition Serialization
+
+Temporal serializes activity arguments to JSON. AgentDefinition dataclasses become dicts, so the activity reconstructs them:
+
+```python
+agent_defs = {
+    name: AgentDefinition(**agent_data)
+    for name, agent_data in agents.items()
+}
+```
+
+### Hook Callback Signatures
+
+Claude SDK expects specific signatures:
+
+```python
+async def pre_tool_use(
+    input_data: dict[str, Any],  # Contains tool_name, tool_input
+    tool_use_id: str | None,     # Unique ID for this call
+    context: Any,                # HookContext (currently unused)
+) -> dict[str, Any]:             # Return {} to allow, or modify behavior
+```
+
+## Comparison with OpenAI Integration
+
+| Aspect | OpenAI | Claude |
+|--------|--------|--------|
+| **Plugin** | `OpenAIAgentsPlugin` (official) | Manual activity wrapper |
+| **Streaming** | Token-level deltas | Message block-level |
+| **Tool Results** | `ToolResultBlock` | `UserMessage` (with acceptEdits) |
+| **Hooks** | `RunHooks` class | `HookMatcher` with callbacks |
+| **Context Threading** | ContextInterceptor | ContextInterceptor (reused!) |
+| **Subagents** | Agent handoffs | AgentDefinition config |
+
+## Notes
+
+**Message Block Streaming**: Claude SDK returns complete text blocks, not individual tokens. Text appears instantly rather than animating character-by-character. This is inherent to Claude SDK's API design.
+
+**In-Process Subagents**: Subagents run within Claude SDK via config-based routing, not as separate Temporal workflows. This is by design - subagents are specializations, not independent agents.
+
+**Manual Activity Calls**: Unlike OpenAI which has an official Temporal plugin, Claude integration requires explicit `workflow.execute_activity()` calls. A future enhancement could create an automatic plugin.
+
+## License
+
+Apache 2.0 (same as AgentEx SDK)

agentex_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/manifest.yaml

@@ -0,0 +1,59 @@
+kind: Agent
+
+# Build Configuration
+build:
+  context:
+    root: ../
+    include_paths:
+      - 090_claude_agents_sdk_mvp
+    dockerfile: 090_claude_agents_sdk_mvp/Dockerfile
+    dockerignore: 090_claude_agents_sdk_mvp/.dockerignore
+
+# Local Development Configuration
+local_development:
+  agent:
+    port: 8000
+    host_address: host.docker.internal
+  paths:
+    acp: project/acp.py
+    worker: project/run_worker.py
+
+# Agent Configuration
+agent:
+  acp_type: async
+  name: claude-mvp-agent
+  description: Claude Agents SDK MVP - proof of concept integration with AgentEx
+
+  temporal:
+    enabled: true
+    workflows:
+      - name: ClaudeMvpWorkflow
+        queue_name: claude-mvp-queue
+
+  credentials:
+    - env_var_name: ANTHROPIC_API_KEY
+      secret_name: anthropic-api-key
+      secret_key: api-key
+    - env_var_name: REDIS_URL
+      secret_name: redis-url-secret
+      secret_key: url
+
+# Deployment Configuration
+deployment:
+  image:
+    repository: ""
+    tag: "latest"
+  imagePullSecrets:
+    - name: my-registry-secret
+  global:
+    agent:
+      name: "claude-mvp-agent"
+      description: "Claude Agents SDK MVP"
+    replicaCount: 1
+    resources:
+      requests:
+        cpu: "500m"
+        memory: "1Gi"
+      limits:
+        cpu: "1000m"
+        memory: "2Gi"

agentex_sdk-0.7.0/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/acp.py

@@ -0,0 +1,75 @@
+import os
+import sys
+
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
+
+# === DEBUG SETUP (AgentEx CLI Debug Support) ===
+if os.getenv("AGENTEX_DEBUG_ENABLED") == "true":
+    print("test me")
+    try:
+        import debugpy
+
+        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)
+
+        print(f"🐛 [{debug_type.upper()}] Debug server listening on port {debug_port}")
+
+        if wait_for_attach:
+            print(f"⏳ [{debug_type.upper()}] Waiting for debugger to attach...")
+            debugpy.wait_for_client()
+            print(f"✅ [{debug_type.upper()}] Debugger attached!")
+        else:
+            print(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.types.fastacp import TemporalACPConfig
+from agentex.lib.sdk.fastacp.fastacp import FastACP
+from agentex.lib.core.temporal.plugins.openai_agents.models.temporal_streaming_model import (
+    TemporalStreamingModelProvider,
+)
+from agentex.lib.core.temporal.plugins.openai_agents.interceptors.context_interceptor import ContextInterceptor
+
+context_interceptor = ContextInterceptor()
+temporal_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
+        # We are also adding the Open AI Agents SDK plugin to the ACP.
+        type="temporal",
+        temporal_address=os.getenv("TEMPORAL_ADDRESS", "localhost:7233"),
+        plugins=[OpenAIAgentsPlugin(model_provider=temporal_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
+