agentex-sdk 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

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 get_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,86 +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
-                        refreshed_environment_variables.AGENT_ID = agent_id
-                        refreshed_environment_variables.AGENT_NAME = agent_name
-                        get_async_agentex_client()  # refresh cache
-                        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/sdk/fastacp/impl/agentic_base_acp.py

@@ -1,4 +1,6 @@
 from typing import Any
+
+from agentex.lib.adk.utils._modules.client import create_async_agentex_client
 from typing_extensions import override
 from agentex import AsyncAgentex
 from agentex.lib.sdk.fastacp.base.base_acp_server import BaseACPServer
@@ -24,7 +26,7 @@ class AgenticBaseACP(BaseACPServer):
     def __init__(self):
         super().__init__()
         self._setup_handlers()
-        self._agentex_client = AsyncAgentex()
+        self._agentex_client = create_async_agentex_client()
 
     @classmethod
     @override

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/tasks.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
+from typing import Optional
+
 import httpx
 
+from ..types import task_list_params
 from .._types import NOT_GIVEN, Body, Query, Headers, NotGiven
+from .._utils import maybe_transform, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
 from .._response import (
@@ -78,6 +82,8 @@ class TasksResource(SyncAPIResource):
     def list(
         self,
         *,
+        agent_id: Optional[str] | NotGiven = NOT_GIVEN,
+        agent_name: Optional[str] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -85,11 +91,32 @@ class TasksResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> TaskListResponse:
-        """List all tasks."""
+        """
+        List all tasks.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
         return self._get(
             "/tasks",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "agent_id": agent_id,
+                        "agent_name": agent_name,
+                    },
+                    task_list_params.TaskListParams,
+                ),
             ),
             cast_to=TaskListResponse,
         )
@@ -320,6 +347,8 @@ class AsyncTasksResource(AsyncAPIResource):
     async def list(
         self,
         *,
+        agent_id: Optional[str] | NotGiven = NOT_GIVEN,
+        agent_name: Optional[str] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -327,11 +356,32 @@ class AsyncTasksResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> TaskListResponse:
-        """List all tasks."""
+        """
+        List all tasks.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
         return await self._get(
             "/tasks",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform(
+                    {
+                        "agent_id": agent_id,
+                        "agent_name": agent_name,
+                    },
+                    task_list_params.TaskListParams,
+                ),
             ),
             cast_to=TaskListResponse,
         )

agentex/types/__init__.py

@@ -19,6 +19,7 @@ from .message_author import MessageAuthor as MessageAuthor
 from .agent_rpc_params import AgentRpcParams as AgentRpcParams
 from .agent_rpc_result import AgentRpcResult as AgentRpcResult
 from .span_list_params import SpanListParams as SpanListParams
+from .task_list_params import TaskListParams as TaskListParams
 from .agent_list_params import AgentListParams as AgentListParams
 from .event_list_params import EventListParams as EventListParams
 from .state_list_params import StateListParams as StateListParams

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/types/task_list_params.py

@@ -0,0 +1,14 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import TypedDict
+
+__all__ = ["TaskListParams"]
+
+
+class TaskListParams(TypedDict, total=False):
+    agent_id: Optional[str]
+
+    agent_name: Optional[str]

{agentex_sdk-0.2.5.dist-info → agentex_sdk-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.2.5
+Version: 0.2.7
 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.