Merge pull request #6 from stainless-sdks/feat/debugging-worker

Add --debug-workers to support breakpoint workflow with vscode

Author: prassanna-ravishankar

.vscode/launch.json

@@ -0,0 +1,39 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Attach to AgentEx Worker",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": false,
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Attach to AgentEx Worker (Port 5679)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5679
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": false,
+            "console": "integratedTerminal"
+        }
+    ]
+} 

README.md

@@ -67,6 +67,37 @@ asyncio.run(main())
 
 Functionality between the synchronous and asynchronous clients is otherwise identical.
 
+## Debugging
+
+AgentEx provides built-in debugging support for **temporal projects** during local development.
+
+```bash
+# Basic debugging
+uv run agentex agents run --manifest manifest.yaml --debug-worker
+
+# Wait for debugger to attach before starting
+uv run agentex agents run --manifest manifest.yaml --debug-worker --wait-for-debugger
+
+# Custom debug port
+uv run agentex agents run --manifest manifest.yaml --debug-worker --debug-port 5679
+```
+
+For **VS Code**, add this configuration to `.vscode/launch.json`:
+
+```json
+{
+  "name": "Attach to AgentEx Worker",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": { "host": "localhost", "port": 5678 },
+  "pathMappings": [{ "localRoot": "${workspaceFolder}", "remoteRoot": "." }],
+  "justMyCode": false,
+  "console": "integratedTerminal"
+}
+```
+
+The debug server automatically finds an available port starting from 5678 and prints connection details when starting.
+
 ### With aiohttp
 
 By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.

examples/tutorials/10_agentic/10_temporal/000_hello_acp/project/run_worker.py

@@ -1,9 +1,9 @@
 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.utils.debug import setup_debug_if_enabled
 from agentex.lib.environment_variables import EnvironmentVariables
 
 from workflow import At000HelloAcpWorkflow
@@ -15,6 +15,9 @@
 
 
 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")

examples/tutorials/10_agentic/10_temporal/000_hello_acp/pyproject.toml

@@ -19,6 +19,7 @@ dev = [
     "black",
     "isort",
     "flake8",
+    "debugpy>=1.8.15",
 ]
 
 [tool.hatch.build.targets.wheel]

examples/tutorials/10_agentic/10_temporal/010_agent_chat/project/run_worker.py

@@ -3,6 +3,7 @@
 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 workflow import At010AgentChatWorkflow
@@ -15,6 +16,9 @@
 
 
 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")

examples/tutorials/10_agentic/10_temporal/010_agent_chat/pyproject.toml

@@ -10,6 +10,7 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "agentex-sdk",
+    "debugpy>=1.8.15",
     "scale-gp",
 ]
 
@@ -30,4 +31,4 @@ target-version = ['py312']
 
 [tool.isort]
 profile = "black"
-line_length = 88 
+line_length = 88 

examples/tutorials/10_agentic/10_temporal/020_state_machine/project/run_worker.py

@@ -3,6 +3,7 @@
 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 workflow import At020StateMachineWorkflow
@@ -14,6 +15,9 @@
 
 
 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")

examples/tutorials/10_agentic/10_temporal/020_state_machine/pyproject.toml

@@ -19,6 +19,7 @@ dev = [
     "black",
     "isort",
     "flake8",
+    "debugpy>=1.8.15",
 ]
 
 [tool.hatch.build.targets.wheel]

pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
     "pytest>=8.4.0",
     "pytest-asyncio>=1.0.0",
     "scale-gp-beta==0.1.0a20",
-    "ipykernel>=6.29.5",
+    "ipykernel>=6.29.5",    
 ]
 requires-python = ">= 3.12,<4"
 classifiers = [
@@ -86,6 +86,7 @@ dev-dependencies = [
     "rich>=13.7.1",
     "nest_asyncio==1.6.0",
     "pytest-xdist>=3.6.1",
+    "debugpy>=1.8.15",
 ]
 
 [tool.rye.scripts]

src/agentex/lib/cli/commands/agents.py

@@ -11,6 +11,7 @@
     build_agent,
     run_agent,
 )
+from agentex.lib.cli.debug import DebugConfig, DebugMode
 from agentex.lib.cli.handlers.cleanup_handlers import cleanup_agent_workflows
 from agentex.lib.cli.handlers.deploy_handlers import (
     DeploymentError,
@@ -171,7 +172,13 @@ def run(
         False, 
         help="Clean up existing workflows for this agent before starting"
     ),
-):
+    # Debug options
+    debug: bool = typer.Option(False, help="Enable debug mode for both worker and ACP (disables auto-reload)"),
+    debug_worker: bool = typer.Option(False, help="Enable debug mode for temporal worker only"),
+    debug_acp: bool = typer.Option(False, help="Enable debug mode for ACP server only"),
+    debug_port: int = typer.Option(5678, help="Port for remote debugging (worker uses this, ACP uses port+1)"),
+    wait_for_debugger: bool = typer.Option(False, help="Wait for debugger to attach before starting"),
+) -> None:
     """
     Run an agent locally from the given manifest.
     """
@@ -196,8 +203,35 @@ def run(
             console.print(f"[yellow]⚠ Pre-run cleanup failed: {str(e)}[/yellow]")
             logger.warning(f"Pre-run cleanup failed: {e}")
 
+    # Create debug configuration based on CLI flags
+    debug_config = None
+    if debug or debug_worker or debug_acp:
+        # Determine debug mode
+        if debug:
+            mode = DebugMode.BOTH
+        elif debug_worker and debug_acp:
+            mode = DebugMode.BOTH
+        elif debug_worker:
+            mode = DebugMode.WORKER
+        elif debug_acp:
+            mode = DebugMode.ACP
+        else:
+            mode = DebugMode.NONE
+        
+        debug_config = DebugConfig(
+            enabled=True,
+            mode=mode,
+            port=debug_port,
+            wait_for_attach=wait_for_debugger,
+            auto_port=False  # Use fixed port to match VS Code launch.json
+        )
+        
+        console.print(f"[blue]🐛 Debug mode enabled: {mode.value}[/blue]")
+        if wait_for_debugger:
+            console.print("[yellow]⏳ Processes will wait for debugger attachment[/yellow]")
+    
     try:
-        run_agent(manifest_path=manifest)
+        run_agent(manifest_path=manifest, debug_config=debug_config)
     except Exception as e:
         typer.echo(f"Error running agent: {str(e)}", err=True)
         logger.exception("Error running agent")