agentex-sdk 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

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

@@ -6,7 +6,6 @@ build-backend = "hatchling.build"
 name = "{{ project_name }}"
 version = "0.1.0"
 description = "{{ description }}"
-readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "agentex-sdk",

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

@@ -15,6 +15,8 @@ RUN apt-get update && apt-get install -y \
     gcc \
     cmake \
     netcat-openbsd \
+    node \
+    npm \ 
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 

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

@@ -6,7 +6,6 @@ build-backend = "hatchling.build"
 name = "{{ project_name }}"
 version = "0.1.0"
 description = "{{ description }}"
-readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "agentex-sdk",

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

@@ -15,6 +15,8 @@ RUN apt-get update && apt-get install -y \
     gcc \
     cmake \
     netcat-openbsd \
+    node \
+    npm \ 
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 

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

@@ -1,4 +1,35 @@
 import os
+import sys
+
+# === DEBUG SETUP (AgentEx CLI Debug Support) ===
+if os.getenv("AGENTEX_DEBUG_ENABLED") == "true":
+    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.sdk.fastacp.fastacp import FastACP
 from agentex.lib.types.fastacp import TemporalACPConfig
 

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

@@ -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 {{ workflow_class }}
@@ -15,6 +15,9 @@ logger = make_logger(__name__)
 
 
 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")

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

@@ -6,7 +6,6 @@ build-backend = "hatchling.build"
 name = "{{ project_name }}"
 version = "0.1.0"
 description = "{{ description }}"
-readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "agentex-sdk",
@@ -20,6 +19,7 @@ dev = [
     "black",
     "isort",
     "flake8",
+    "debugpy>=1.8.15",
 ]
 
 [tool.hatch.build.targets.wheel]

agentex/lib/core/services/adk/acp/acp.py

@@ -64,7 +64,7 @@ class ACPService:
             else:
                 raise ValueError("Either agent_name or agent_id must be provided")
 
-            task_entry = Task.model_validate(json_rpc_response["result"])
+            task_entry = Task.model_validate(json_rpc_response.result)
             if span:
                 span.output = task_entry.model_dump()
             return task_entry
@@ -115,7 +115,7 @@ class ACPService:
             else:
                 raise ValueError("Either agent_name or agent_id must be provided")
 
-            task_message = TaskMessage.model_validate(json_rpc_response["result"])
+            task_message = TaskMessage.model_validate(json_rpc_response.result)
             if span:
                 span.output = task_message.model_dump()
             return task_message
@@ -147,7 +147,7 @@ class ACPService:
                     agent_name=agent_name,
                     method="event/send",
                     params={
-                        "task_name": task_name,
+                        "task_id": task_id,
                         "content": cast(TaskMessageContentParam, content.model_dump()),
                     },
                 )
@@ -163,7 +163,7 @@ class ACPService:
             else:
                 raise ValueError("Either agent_name or agent_id must be provided")
 
-            event_entry = Event.model_validate(json_rpc_response["result"])
+            event_entry = Event.model_validate(json_rpc_response.result)
             if span:
                 span.output = event_entry.model_dump()
             return event_entry
@@ -204,7 +204,7 @@ class ACPService:
             else:
                 raise ValueError("Either task_name or task_id must be provided")
 
-            task_entry = Task.model_validate(json_rpc_response["result"])
+            task_entry = Task.model_validate(json_rpc_response.result)
             if span:
                 span.output = task_entry.model_dump()
             return task_entry

agentex/lib/core/temporal/workers/worker.py

@@ -24,6 +24,8 @@ from temporalio.worker import (
 )
 
 from agentex.lib.utils.logging import make_logger
+from agentex.lib.utils.registration import register_agent
+from agentex.lib.environment_variables import EnvironmentVariables
 
 logger = make_logger(__name__)
 
@@ -103,9 +105,16 @@ class AgentexWorker:
         workflow: type,
     ):
         await self.start_health_check_server()
+        await self._register_agent()
         temporal_client = await get_temporal_client(
             temporal_address=os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"),
         )
+        
+        # Enable debug mode if AgentEx debug is enabled (disables deadlock detection)
+        debug_enabled = os.environ.get("AGENTEX_DEBUG_ENABLED", "false").lower() == "true"
+        if debug_enabled:
+            logger.info("🐛 [WORKER] Temporal debug mode enabled - deadlock detection disabled")
+        
         worker = Worker(
             client=temporal_client,
             task_queue=self.task_queue,
@@ -115,6 +124,7 @@ class AgentexWorker:
             workflow_runner=UnsandboxedWorkflowRunner(),
             max_concurrent_activities=self.max_concurrent_activities,
             build_id=str(uuid.uuid4()),
+            debug_mode=debug_enabled,  # Disable deadlock detection in debug mode
         )
 
         logger.info(f"Starting workers for task queue: {self.task_queue}")
@@ -160,3 +170,17 @@ class AgentexWorker:
                         f"Failed to start health check server on alternative port {alt_port}: {e}"
                     )
                     raise
+
+    """
+    Register the worker with the Agentex server.
+    
+    Even though the Temporal server will also register the agent with the server,
+    doing this on the worker side is required to make sure that both share the API key
+    which is returned on registration and used to authenticate the worker with the Agentex server.
+    """
+    async def _register_agent(self):
+        env_vars = EnvironmentVariables.refresh()
+        if env_vars and env_vars.AGENTEX_BASE_URL:
+            await register_agent(env_vars)
+        else:
+            logger.warning("AGENTEX_BASE_URL not set, skipping worker registration")

agentex/lib/environment_variables.py

@@ -23,6 +23,7 @@ class EnvVarKeys(str, Enum):
     AGENT_NAME = "AGENT_NAME"
     AGENT_DESCRIPTION = "AGENT_DESCRIPTION"
     AGENT_ID = "AGENT_ID"
+    AGENT_API_KEY = "AGENT_API_KEY"
     # ACP Configuration
     ACP_URL = "ACP_URL"
     ACP_PORT = "ACP_PORT"
@@ -52,6 +53,7 @@ class EnvironmentVariables(BaseModel):
     AGENT_NAME: str
     AGENT_DESCRIPTION: str | None = None
     AGENT_ID: str | None = None
+    AGENT_API_KEY: str | None = None
     ACP_TYPE: str | None = "agentic"
     # ACP Configuration
     ACP_URL: str

agentex/lib/sdk/fastacp/base/base_acp_server.py

@@ -1,15 +1,10 @@
 import asyncio
-import base64
 import inspect
-import json
-import os
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from typing import Any
 
-import httpx
 import uvicorn
-from agentex.lib.adk.utils._modules.client import create_async_agentex_client
 from fastapi import FastAPI, Request
 from fastapi.responses import StreamingResponse
 from pydantic import TypeAdapter, ValidationError
@@ -30,6 +25,7 @@ from agentex.lib.types.task_message_updates import StreamTaskMessageFull, TaskMe
 from agentex.types.task_message_content import TaskMessageContent
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import BaseModel
+from agentex.lib.utils.registration import register_agent
 
 logger = make_logger(__name__)
 
@@ -74,7 +70,7 @@ class BaseACPServer(FastAPI):
         async def lifespan_context(app: FastAPI):
             env_vars = EnvironmentVariables.refresh()
             if env_vars.AGENTEX_BASE_URL:
-                await self._register_agent(env_vars)
+                await register_agent(env_vars)
             else:
                 logger.warning("AGENTEX_BASE_URL not set, skipping agent registration")
 
@@ -101,6 +97,16 @@ class BaseACPServer(FastAPI):
             data = await request.json()
             rpc_request = JSONRPCRequest(**data)
 
+            # Check if the request is authenticated
+            if refreshed_environment_variables and getattr(refreshed_environment_variables, "AGENT_API_KEY", None):
+                authorization_header = request.headers.get("x-agent-api-key")
+                if authorization_header != refreshed_environment_variables.AGENT_API_KEY:
+                    return JSONRPCResponse(
+                        id=rpc_request.id,
+                        error=JSONRPCError(code=-32601, message="Unauthorized"),
+                    )
+
+
             # Check if method is valid first
             try:
                 method = RPCMethod(rpc_request.method)
@@ -345,87 +351,4 @@ class BaseACPServer(FastAPI):
         """Start the Uvicorn server for async handlers."""
         uvicorn.run(self, host=host, port=port, **kwargs)
 
-    def _get_auth_principal(self, env_vars: EnvironmentVariables):
-        if not env_vars.AUTH_PRINCIPAL_B64:
-            return None
-
-        try:
-            decoded_str = base64.b64decode(env_vars.AUTH_PRINCIPAL_B64).decode('utf-8')
-            return json.loads(decoded_str)
-        except Exception:
-            return None
-
-    async def _register_agent(self, env_vars: EnvironmentVariables):
-        """Register this agent with the Agentex server"""
-        # Build the agent's own URL
-        full_acp_url = f"{env_vars.ACP_URL.rstrip('/')}:{env_vars.ACP_PORT}"
-
-        description = (
-            env_vars.AGENT_DESCRIPTION
-            or f"Generic description for agent: {env_vars.AGENT_NAME}"
-        )
-
-        # Prepare registration data
-        registration_data = {
-            "name": env_vars.AGENT_NAME,
-            "description": description,
-            "acp_url": full_acp_url,
-            "acp_type": env_vars.ACP_TYPE,
-            "principal_context": self._get_auth_principal(env_vars)
-        }
-
-        if env_vars.AGENT_ID:
-            registration_data["agent_id"] = env_vars.AGENT_ID
-
-        # Make the registration request
-        registration_url = f"{env_vars.AGENTEX_BASE_URL.rstrip('/')}/agents/register"
-        # Retry logic with configurable attempts and delay
-        max_retries = 3
-        base_delay = 5  # seconds
-        last_exception = None
-
-        attempt = 0
-        while attempt < max_retries:
-            try:
-                async with httpx.AsyncClient() as client:
-                    response = await client.post(
-                        registration_url, json=registration_data, timeout=30.0
-                    )
-                    if response.status_code == 200:
-                        agent = response.json()
-                        agent_id, agent_name = agent["id"], agent["name"]
-
-                        os.environ["AGENT_ID"] = agent_id
-                        os.environ["AGENT_NAME"] = agent_name
-                        env_vars.AGENT_ID = agent_id
-                        env_vars.AGENT_NAME = agent_name
-                        global refreshed_environment_variables
-                        refreshed_environment_variables = env_vars
-                        logger.info(
-                            f"Successfully registered agent '{env_vars.AGENT_NAME}' with Agentex server with acp_url: {full_acp_url}. Registration data: {registration_data}"
-                        )
-                        return  # Success, exit the retry loop
-                    else:
-                        error_msg = f"Failed to register agent. Status: {response.status_code}, Response: {response.text}"
-                        logger.error(error_msg)
-                        last_exception = Exception(
-                            f"Failed to startup agent: {response.text}"
-                        )
-
-            except Exception as e:
-                logger.error(
-                    f"Exception during agent registration attempt {attempt + 1}: {e}"
-                )
-                last_exception = e
-            attempt += 1
-            if attempt < max_retries:
-                delay = (attempt) * base_delay  # 5, 10, 15 seconds
-                logger.info(
-                    f"Retrying in {delay} seconds... (attempt {attempt}/{max_retries})"
-                )
-                await asyncio.sleep(delay)
-
-        # If we get here, all retries failed
-        raise last_exception or Exception(
-            f"Failed to register agent after {max_retries} attempts"
-        )
+    

agentex/lib/utils/debug.py

@@ -0,0 +1,63 @@
+"""
+Debug utilities for AgentEx development.
+
+Provides debugging setup functionality that can be used across different components.
+"""
+
+import os
+import debugpy  # type: ignore
+
+
+def setup_debug_if_enabled() -> None:
+    """
+    Setup debugpy if debug mode is enabled via environment variables.
+    
+    This function checks for AgentEx debug environment variables and configures
+    debugpy accordingly. It's designed to be called early in worker startup.
+    
+    Environment Variables:
+        AGENTEX_DEBUG_ENABLED: Set to "true" to enable debug mode
+        AGENTEX_DEBUG_PORT: Port for debug server (default: 5678)
+        AGENTEX_DEBUG_TYPE: Type identifier for logging (default: "worker")
+        AGENTEX_DEBUG_WAIT_FOR_ATTACH: Set to "true" to wait for debugger attachment
+    
+    Raises:
+        Any exception from debugpy setup (will bubble up naturally)
+    """
+    if os.getenv("AGENTEX_DEBUG_ENABLED") == "true":
+        debug_port = int(os.getenv("AGENTEX_DEBUG_PORT", "5678"))
+        debug_type = os.getenv("AGENTEX_DEBUG_TYPE", "worker")
+        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")
+
+
+def is_debug_enabled() -> bool:
+    """
+    Check if debug mode is currently enabled.
+    
+    Returns:
+        bool: True if AGENTEX_DEBUG_ENABLED is set to "true"
+    """
+    return os.getenv("AGENTEX_DEBUG_ENABLED", "false").lower() == "true"
+
+
+def get_debug_port() -> int:
+    """
+    Get the debug port from environment variables.
+    
+    Returns:
+        int: Debug port (default: 5678)
+    """
+    return int(os.getenv("AGENTEX_DEBUG_PORT", "5678"))

agentex/lib/utils/registration.py

@@ -0,0 +1,101 @@
+import base64
+import json
+import os
+import httpx
+import asyncio
+
+from agentex.lib.environment_variables import EnvironmentVariables, refreshed_environment_variables
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+def get_auth_principal(env_vars: EnvironmentVariables):
+    if not env_vars.AUTH_PRINCIPAL_B64:
+        return None
+
+    try:
+        decoded_str = base64.b64decode(env_vars.AUTH_PRINCIPAL_B64).decode('utf-8')
+        return json.loads(decoded_str)
+    except Exception:
+        return None
+
+async def register_agent(env_vars: EnvironmentVariables):
+    """Register this agent with the Agentex server"""
+    if not env_vars.AGENTEX_BASE_URL:
+        logger.warning("AGENTEX_BASE_URL is not set, skipping registration")
+        return
+    # Build the agent's own URL
+    full_acp_url = f"{env_vars.ACP_URL.rstrip('/')}:{env_vars.ACP_PORT}"
+
+    description = (
+        env_vars.AGENT_DESCRIPTION
+        or f"Generic description for agent: {env_vars.AGENT_NAME}"
+    )
+
+    # Prepare registration data
+    registration_data = {
+        "name": env_vars.AGENT_NAME,
+        "description": description,
+        "acp_url": full_acp_url,
+        "acp_type": env_vars.ACP_TYPE,
+        "principal_context": get_auth_principal(env_vars)
+    }
+
+    if env_vars.AGENT_ID:
+        registration_data["agent_id"] = env_vars.AGENT_ID
+
+    # Make the registration request
+    registration_url = f"{env_vars.AGENTEX_BASE_URL.rstrip('/')}/agents/register"
+    # Retry logic with configurable attempts and delay
+    max_retries = 3
+    base_delay = 5  # seconds
+    last_exception = None
+
+    attempt = 0
+    while attempt < max_retries:
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    registration_url, json=registration_data, timeout=30.0
+                )
+                if response.status_code == 200:
+                    agent = response.json()
+                    agent_id, agent_name = agent["id"], agent["name"]
+                    agent_api_key = agent["agent_api_key"]
+
+                    os.environ["AGENT_ID"] = agent_id
+                    os.environ["AGENT_NAME"] = agent_name
+                    os.environ["AGENT_API_KEY"] = agent_api_key
+                    env_vars.AGENT_ID = agent_id
+                    env_vars.AGENT_NAME = agent_name
+                    env_vars.AGENT_API_KEY = agent_api_key
+                    global refreshed_environment_variables
+                    refreshed_environment_variables = env_vars
+                    logger.info(
+                        f"Successfully registered agent '{env_vars.AGENT_NAME}' with Agentex server with acp_url: {full_acp_url}. Registration data: {registration_data}"
+                    )
+                    return  # Success, exit the retry loop
+                else:
+                    error_msg = f"Failed to register agent. Status: {response.status_code}, Response: {response.text}"
+                    logger.error(error_msg)
+                    last_exception = Exception(
+                        f"Failed to startup agent: {response.text}"
+                    )
+
+        except Exception as e:
+            logger.error(
+                f"Exception during agent registration attempt {attempt + 1}: {e}"
+            )
+            last_exception = e
+        attempt += 1
+        if attempt < max_retries:
+            delay = (attempt) * base_delay  # 5, 10, 15 seconds
+            logger.info(
+                f"Retrying in {delay} seconds... (attempt {attempt}/{max_retries})"
+            )
+            await asyncio.sleep(delay)
+
+    # If we get here, all retries failed
+    raise last_exception or Exception(
+        f"Failed to register agent after {max_retries} attempts"
+    )

agentex/resources/agents.py

@@ -508,17 +508,24 @@ class AgentsResource(SyncAPIResource):
         raise ValueError("Either agent_id or agent_name must be provided")
       
       with raw_agent_rpc_response as response:
-        for agent_rpc_response_str in response.iter_text():
-          if agent_rpc_response_str.strip():  # Only process non-empty lines
-            try:
-              chunk_rpc_response = SendMessageStreamResponse.model_validate(
-                json.loads(agent_rpc_response_str), 
-                from_attributes=True
-              )
-              yield chunk_rpc_response
-            except json.JSONDecodeError:
-              # Skip invalid JSON lines
-              continue
+        for _line in response.iter_lines():
+          if not _line:
+            continue
+          line = _line.strip()
+          # Handle optional SSE-style prefix
+          if line.startswith("data:"):
+            line = line[len("data:"):].strip()
+          if not line:
+            continue
+          try:
+            chunk_rpc_response = SendMessageStreamResponse.model_validate(
+              json.loads(line),
+              from_attributes=True
+            )
+            yield chunk_rpc_response
+          except json.JSONDecodeError:
+            # Skip invalid JSON lines
+            continue
     
     def send_event(
       self,
@@ -1048,17 +1055,24 @@ class AsyncAgentsResource(AsyncAPIResource):
         raise ValueError("Either agent_id or agent_name must be provided")
       
       async with raw_agent_rpc_response as response:
-        async for agent_rpc_response_str in response.iter_text():
-          if agent_rpc_response_str.strip():  # Only process non-empty lines
-            try:
-              chunk_rpc_response = SendMessageStreamResponse.model_validate(
-                json.loads(agent_rpc_response_str), 
-                from_attributes=True
-              )
-              yield chunk_rpc_response
-            except json.JSONDecodeError:
-              # Skip invalid JSON lines
-              continue
+        async for _line in response.iter_lines():
+          if not _line:
+            continue
+          line = _line.strip()
+          # Handle optional SSE-style prefix
+          if line.startswith("data:"):
+            line = line[len("data:"):].strip()
+          if not line:
+            continue
+          try:
+            chunk_rpc_response = SendMessageStreamResponse.model_validate(
+              json.loads(line),
+              from_attributes=True
+            )
+            yield chunk_rpc_response
+          except json.JSONDecodeError:
+            # Skip invalid JSON lines
+            continue
     
     async def send_event(
       self,

agentex/types/agent.py

@@ -1,6 +1,7 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 from typing import Optional
+from datetime import datetime
 from typing_extensions import Literal
 
 from .._models import BaseModel
@@ -16,12 +17,18 @@ class Agent(BaseModel):
     acp_type: AcpType
     """The type of the ACP Server (Either sync or agentic)"""
 
+    created_at: datetime
+    """The timestamp when the agent was created"""
+
     description: str
     """The description of the action."""
 
     name: str
     """The unique name of the agent."""
 
+    updated_at: datetime
+    """The timestamp when the agent was last updated"""
+
     status: Optional[Literal["Pending", "Building", "Ready", "Failed", "Unknown"]] = None
     """The status of the action, indicating if it's building, ready, failed, etc."""
 

{agentex_sdk-0.2.6.dist-info → agentex_sdk-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.2.6
+Version: 0.2.8
 Summary: The official Python library for the agentex API
 Project-URL: Homepage, https://github.com/scaleapi/agentex-python
 Project-URL: Repository, https://github.com/scaleapi/agentex-python
@@ -126,6 +126,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.