a2a-distributed 0.0.0__tar.gz

a2a_distributed-0.0.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: a2a-distributed
+Version: 0.0.0
+Summary: Add your description here
+Author: Tomas Pilar
+Author-email: Tomas Pilar <thomas7pilar@gmail.com>
+Requires-Dist: a2a-redis>=0.2.1
+Requires-Dist: a2a-sdk>=0.3.24
+Requires-Dist: bullmq>=2.19.5
+Requires-Dist: celery>=5.6.2
+Requires-Dist: rq>=2.7.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# a2a-distributed
+
+`a2a-distributed` provides distributed execution capabilities for A2A agents. It allows you to offload agent execution to background workers using popular task queues like **Celery**, **BullMQ**, or **RQ (Redis Queue)**.
+
+## Architecture
+
+The package follows a Client/Worker architecture:
+
+1.  **DistributedAgentExecutor (Client Side):** Used by the A2A server to enqueue agent execution tasks into a distributed queue.
+2.  **DistributedAgentWorker (Worker Side):** A background process that listens to the queue, reconstructs the execution context, and runs the agent using a local `AgentExecutor`.
+
+## Exports
+
+### Base Classes
+- `DistributedAgentExecutor`: Abstract base class for all distributed executors.
+- `DistributedAgentWorker`: Abstract base class for all distributed workers.
+
+### Celery Implementation
+- `CeleryAgentExecutor`: Enqueues tasks to Celery.
+- `CeleryAgentWorker`: Handles Celery tasks.
+
+### BullMQ Implementation
+- `BullMQAgentExecutor`: Enqueues jobs to BullMQ.
+- `BullMQAgentWorker`: Processes BullMQ jobs.
+
+### RQ Implementation
+- `RQAgentExecutor`: Enqueues jobs to Redis Queue.
+- `RQAgentWorker`: Processes RQ jobs.
+
+### Utilities
+- `run_worker`: A utility function to run any `DistributedAgentWorker` with built-in signal handling for graceful shutdown.
+
+## Usage Example
+
+### 1. Setting up the Executor (Client Side)
+
+```python
+from a2a_distributed import BullMQAgentExecutor
+
+# Initialize the executor with connection options
+executor = BullMQAgentExecutor(
+    queue_name="agent-tasks",
+    redis_opts={"host": "localhost", "port": 6379}
+)
+
+# Use it in your A2A server configuration
+# server = A2AServer(executor=executor, ...)
+```
+
+### 2. Setting up the Worker (Worker Side)
+
+```python
+import asyncio
+from a2a_distributed import BullMQAgentWorker, run_worker
+from a2a.server.agent_execution import LocalAgentExecutor
+from a2a_redis import RedisEventQueue
+
+async def main():
+    # 1. Local executor that actually runs the agent logic
+    local_executor = LocalAgentExecutor(...) 
+    
+    # 2. Event queue for reporting status/results back
+    event_queue = RedisEventQueue(...)
+    
+    # 3. The Distributed Worker
+    worker = BullMQAgentWorker(
+        agent_executor=local_executor,
+        event_queue=event_queue,
+        queue_name="agent-tasks",
+        redis_opts={"host": "localhost", "port": 6379}
+    )
+    
+    # 4. Run the worker using the utility
+    await run_worker(worker)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Running Workers
+
+To run a worker, simply call `await worker.run()` or use the `run_worker(worker)` utility which handles `SIGINT` and `SIGTERM` signals for you.
+
+For Celery and RQ, the workers are often started via their respective CLI tools, but the `DistributedAgentWorker` classes provided here allow for programmatic control and integration within your own async loops.

a2a_distributed-0.0.0/README.md

@@ -0,0 +1,84 @@
+# a2a-distributed
+
+`a2a-distributed` provides distributed execution capabilities for A2A agents. It allows you to offload agent execution to background workers using popular task queues like **Celery**, **BullMQ**, or **RQ (Redis Queue)**.
+
+## Architecture
+
+The package follows a Client/Worker architecture:
+
+1.  **DistributedAgentExecutor (Client Side):** Used by the A2A server to enqueue agent execution tasks into a distributed queue.
+2.  **DistributedAgentWorker (Worker Side):** A background process that listens to the queue, reconstructs the execution context, and runs the agent using a local `AgentExecutor`.
+
+## Exports
+
+### Base Classes
+- `DistributedAgentExecutor`: Abstract base class for all distributed executors.
+- `DistributedAgentWorker`: Abstract base class for all distributed workers.
+
+### Celery Implementation
+- `CeleryAgentExecutor`: Enqueues tasks to Celery.
+- `CeleryAgentWorker`: Handles Celery tasks.
+
+### BullMQ Implementation
+- `BullMQAgentExecutor`: Enqueues jobs to BullMQ.
+- `BullMQAgentWorker`: Processes BullMQ jobs.
+
+### RQ Implementation
+- `RQAgentExecutor`: Enqueues jobs to Redis Queue.
+- `RQAgentWorker`: Processes RQ jobs.
+
+### Utilities
+- `run_worker`: A utility function to run any `DistributedAgentWorker` with built-in signal handling for graceful shutdown.
+
+## Usage Example
+
+### 1. Setting up the Executor (Client Side)
+
+```python
+from a2a_distributed import BullMQAgentExecutor
+
+# Initialize the executor with connection options
+executor = BullMQAgentExecutor(
+    queue_name="agent-tasks",
+    redis_opts={"host": "localhost", "port": 6379}
+)
+
+# Use it in your A2A server configuration
+# server = A2AServer(executor=executor, ...)
+```
+
+### 2. Setting up the Worker (Worker Side)
+
+```python
+import asyncio
+from a2a_distributed import BullMQAgentWorker, run_worker
+from a2a.server.agent_execution import LocalAgentExecutor
+from a2a_redis import RedisEventQueue
+
+async def main():
+    # 1. Local executor that actually runs the agent logic
+    local_executor = LocalAgentExecutor(...) 
+    
+    # 2. Event queue for reporting status/results back
+    event_queue = RedisEventQueue(...)
+    
+    # 3. The Distributed Worker
+    worker = BullMQAgentWorker(
+        agent_executor=local_executor,
+        event_queue=event_queue,
+        queue_name="agent-tasks",
+        redis_opts={"host": "localhost", "port": 6379}
+    )
+    
+    # 4. Run the worker using the utility
+    await run_worker(worker)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Running Workers
+
+To run a worker, simply call `await worker.run()` or use the `run_worker(worker)` utility which handles `SIGINT` and `SIGTERM` signals for you.
+
+For Celery and RQ, the workers are often started via their respective CLI tools, but the `DistributedAgentWorker` classes provided here allow for programmatic control and integration within your own async loops.

a2a_distributed-0.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "a2a-distributed"
+version = "0.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Tomas Pilar", email = "thomas7pilar@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "a2a-redis>=0.2.1",
+    "a2a-sdk>=0.3.24",
+    "bullmq>=2.19.5",
+    "celery>=5.6.2",
+    "rq>=2.7.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"

a2a_distributed-0.0.0/src/a2a_distributed/__init__.py

@@ -0,0 +1,17 @@
+from a2a_distributed.executor import DistributedAgentExecutor, DistributedAgentWorker
+from a2a_distributed.celery_executor import CeleryAgentExecutor, CeleryAgentWorker
+from a2a_distributed.rq_executor import RQAgentExecutor, RQAgentWorker
+from a2a_distributed.bullmq_executor import BullMQAgentExecutor, BullMQAgentWorker
+from a2a_distributed.runner import run_worker
+
+__all__ = [
+    "DistributedAgentExecutor",
+    "DistributedAgentWorker",
+    "CeleryAgentExecutor",
+    "CeleryAgentWorker",
+    "RQAgentExecutor",
+    "RQAgentWorker",
+    "BullMQAgentExecutor",
+    "BullMQAgentWorker",
+    "run_worker",
+]

a2a_distributed-0.0.0/src/a2a_distributed/bullmq_executor.py

@@ -0,0 +1,165 @@
+from typing import Any, Dict, Optional
+from bullmq import Queue, Worker
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a_distributed.executor import DistributedAgentExecutor, DistributedAgentWorker
+
+
+class BullMQAgentExecutor(DistributedAgentExecutor):
+    """Distributed Agent Executor using BullMQ.
+
+    This executor delegates task execution to a BullMQ worker.
+    """
+
+    def __init__(
+        self,
+        queue_name: str = "default",
+        redis_opts: Optional[Dict[str, Any]] = None,
+        job_name: str = "a2a_execute_task",
+    ):
+        """Initializes the BullMQAgentExecutor.
+
+        Args:
+            queue_name: The name of the BullMQ queue.
+            redis_opts: Redis connection options (e.g., {"host": "localhost", "port": 6379}).
+            job_name: The name of the BullMQ job.
+        """
+        self.queue_name = queue_name
+        self.redis_opts = redis_opts or {}
+        self.job_name = job_name
+        self._queue: Optional[Queue] = None
+
+    def _get_queue(self) -> Queue:
+        """Returns the BullMQ Queue instance, initializing it if necessary."""
+        if self._queue is None:
+            self._queue = Queue(self.queue_name, connection=self.redis_opts)
+        return self._queue
+
+    async def execute(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Executes the agent logic by adding a job to BullMQ."""
+        payload = self._get_payload(context)
+        queue = self._get_queue()
+        
+        # Add a job to the queue
+        await queue.add(
+            self.job_name,
+            payload,
+            jobId=context.task_id,
+        )
+
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Cancels the agent logic.
+        
+        BullMQ job cancellation is usually handled by job removal or worker-side
+        interruption. Here we provide a way to mark it for cancellation.
+        """
+        if context.task_id:
+            queue = self._get_queue()
+            # In BullMQ, you can remove a job if it hasn't started, 
+            # or signal cancellation via a separate mechanism.
+            # For now, we attempt to remove the job from the queue.
+            job = await queue.getJob(context.task_id)
+            if job:
+                await job.remove()
+
+    def _get_payload(self, context: RequestContext) -> Dict[str, Any]:
+        """Extracts serializable payload from the request context."""
+        return {
+            "task_id": context.task_id,
+            "context_id": context.context_id,
+            "message": context.message.model_dump() if context.message else None,
+            "metadata": context.metadata,
+        }
+
+    async def close(self) -> None:
+        """Closes the BullMQ queue connection."""
+        if self._queue:
+            await self._queue.close()
+            self._queue = None
+
+
+class BullMQAgentWorker(DistributedAgentWorker):
+    """Distributed Agent Worker using BullMQ.
+    
+    This worker handles jobs enqueued by BullMQAgentExecutor.
+    """
+
+    def __init__(
+        self,
+        agent_executor: AgentExecutor,
+        event_queue: EventQueue,
+        queue_name: str = "default",
+        redis_opts: Optional[Dict[str, Any]] = None,
+    ):
+        """Initializes the BullMQAgentWorker.
+
+        Args:
+            agent_executor: The local AgentExecutor to use for actual execution.
+            event_queue: The event queue to use for reporting status updates and results.
+            queue_name: The name of the BullMQ queue to listen to.
+            redis_opts: Redis connection options.
+        """
+        super().__init__(agent_executor, event_queue)
+        self.queue_name = queue_name
+        self.redis_opts = redis_opts or {}
+        self._worker: Optional[Worker] = None
+        self._stop_event: Optional[asyncio.Event] = None
+
+    async def run(self) -> None:
+        """Starts the BullMQ worker and waits until closed."""
+        if self._worker is None:
+            self._worker = Worker(
+                self.queue_name,
+                self._process_job,
+                connection=self.redis_opts
+            )
+        
+        self._stop_event = asyncio.Event()
+        await self._stop_event.wait()
+
+    async def _process_job(self, job: Any) -> None:
+        """Internal processor for BullMQ jobs."""
+        await self._execute_job(job.data)
+
+    async def _execute_job(self, payload: Dict[str, Any]) -> None:
+        """Executes a single job with the given payload."""
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.execute(context, self.event_queue)
+
+    async def _cancel_job(self, payload: Dict[str, Any]) -> None:
+        """Cancels a single job with the given payload.
+        
+        Note: In BullMQ, cancellation is often handled via job removal or 
+        external signals, but we provide this for consistency.
+        """
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.cancel(context, self.event_queue)
+
+    def _reconstruct_context(self, payload: Dict[str, Any]) -> RequestContext:
+        """Reconstructs RequestContext from payload."""
+        from a2a.server.agent_execution.context import RequestContext
+        from a2a.models.messages import BaseMessage
+        
+        message = None
+        if payload.get("message"):
+            message = BaseMessage.model_validate(payload["message"])
+
+        return RequestContext(
+            task_id=payload.get("task_id"),
+            context_id=payload.get("context_id"),
+            message=message,
+            metadata=payload.get("metadata", {}),
+        )
+
+    async def close(self) -> None:
+        """Closes the BullMQ worker."""
+        if self._stop_event:
+            self._stop_event.set()
+        if self._worker:
+            await self._worker.close()
+            self._worker = None

a2a_distributed-0.0.0/src/a2a_distributed/celery_executor.py

@@ -0,0 +1,158 @@
+from typing import Any, Dict, Optional
+from celery import Celery
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a_distributed.executor import DistributedAgentExecutor, DistributedAgentWorker
+
+
+class CeleryAgentExecutor(DistributedAgentExecutor):
+    """Distributed Agent Executor using Celery.
+
+    This executor delegates task execution to a Celery worker.
+    """
+
+    def __init__(
+        self,
+        celery_app: Celery,
+        task_name: str = "a2a_execute_task",
+        cancel_task_name: str = "a2a_cancel_task",
+    ):
+        """Initializes the CeleryAgentExecutor.
+
+        Args:
+            celery_app: The Celery application instance.
+            task_name: The name of the Celery task to execute the agent logic.
+            cancel_task_name: The name of the Celery task to cancel the agent logic.
+        """
+        self.celery_app = celery_app
+        self.task_name = task_name
+        self.cancel_task_name = cancel_task_name
+
+    async def execute(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Executes the agent logic by triggering a Celery task.
+
+        Note: In a distributed environment, the worker should report status updates
+        and results back through a shared event mechanism (e.g., Redis Pub/Sub)
+        which this executor or the server should listen to.
+        """
+        # Serialize the context or necessary parts of it
+        # For now, we assume the worker can handle the task_id and message
+        payload = self._get_payload(context)
+        
+        # Trigger the Celery task
+        self.celery_app.send_task(
+            self.task_name,
+            kwargs={"payload": payload},
+            task_id=context.task_id,
+        )
+
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Cancels the agent logic by revoking the Celery task or sending a cancel task."""
+        if context.task_id:
+            # Option 1: Revoke the task (standard Celery)
+            self.celery_app.control.revoke(context.task_id, terminate=True)
+            
+            # Option 2: Send a dedicated cancellation task if needed
+            self.celery_app.send_task(
+                self.cancel_task_name,
+                kwargs={"task_id": context.task_id},
+            )
+
+    def _get_payload(self, context: RequestContext) -> Dict[str, Any]:
+        """Extracts serializable payload from the request context."""
+        return {
+            "task_id": context.task_id,
+            "context_id": context.context_id,
+            "message": context.message.model_dump() if context.message else None,
+            "metadata": context.metadata,
+        }
+
+
+class CeleryAgentWorker(DistributedAgentWorker):
+    """Distributed Agent Worker using Celery.
+    
+    This worker handles tasks enqueued by CeleryAgentExecutor.
+    """
+
+    def __init__(
+        self,
+        agent_executor: AgentExecutor,
+        event_queue: EventQueue,
+        celery_app: Celery,
+        task_name: str = "a2a_execute_task",
+        cancel_task_name: str = "a2a_cancel_task",
+    ):
+        """Initializes the CeleryAgentWorker.
+
+        Args:
+            agent_executor: The local AgentExecutor to use for actual execution.
+            event_queue: The event queue to use for reporting status updates and results.
+            celery_app: The Celery application instance.
+            task_name: The name of the Celery task to listen to.
+            cancel_task_name: The name of the Celery task for cancellation.
+        """
+        super().__init__(agent_executor, event_queue)
+        self.celery_app = celery_app
+        self.task_name = task_name
+        self.cancel_task_name = cancel_task_name
+        self._setup_tasks()
+        self._stop_event: Optional[asyncio.Event] = None
+
+    def _setup_tasks(self) -> None:
+        """Registers the Celery tasks."""
+        
+        @self.celery_app.task(name=self.task_name)
+        def execute_task(payload: Dict[str, Any]) -> None:
+            import asyncio
+            asyncio.run(self._execute_job(payload))
+
+        @self.celery_app.task(name=self.cancel_task_name)
+        def cancel_task(payload: Dict[str, Any]) -> None:
+            import asyncio
+            asyncio.run(self._cancel_job(payload))
+
+    async def run(self) -> None:
+        """Starts the Celery worker and waits until closed.
+        
+        Note: In Celery, workers are typically started via the CLI.
+        This method allows for programmatic waiting if needed.
+        """
+        self._stop_event = asyncio.Event()
+        await self._stop_event.wait()
+
+    async def close(self) -> None:
+        """Closes the worker."""
+        if self._stop_event:
+            self._stop_event.set()
+
+    async def _execute_job(self, payload: Dict[str, Any]) -> None:
+        """Executes a single job with the given payload."""
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.execute(context, self.event_queue)
+
+    async def _cancel_job(self, payload: Dict[str, Any]) -> None:
+        """Cancels a single job with the given payload."""
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.cancel(context, self.event_queue)
+
+    def _reconstruct_context(self, payload: Dict[str, Any]) -> RequestContext:
+        """Reconstructs RequestContext from payload."""
+        from a2a.server.agent_execution.context import RequestContext
+        from a2a.models.messages import BaseMessage
+        
+        message = None
+        if payload.get("message"):
+            # Note: This assumes BaseMessage.model_validate can handle the dict
+            message = BaseMessage.model_validate(payload["message"])
+
+        return RequestContext(
+            task_id=payload.get("task_id"),
+            context_id=payload.get("context_id"),
+            message=message,
+            metadata=payload.get("metadata", {}),
+        )

a2a_distributed-0.0.0/src/a2a_distributed/executor.py

@@ -0,0 +1,49 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.events.event_queue import EventQueue
+
+
+class DistributedAgentExecutor(AgentExecutor, ABC):
+    """Abstract base class for distributed agent executors (Client side).
+    
+    This class is responsible for enqueuing jobs and requesting cancellations.
+    """
+    pass
+
+
+class DistributedAgentWorker(ABC):
+    """Abstract base class for distributed agent workers (Worker side).
+    
+    This class is responsible for receiving jobs from the queue and 
+    executing them using a local AgentExecutor.
+    """
+
+    def __init__(self, agent_executor: AgentExecutor, event_queue: EventQueue):
+        """Initializes the DistributedAgentWorker.
+
+        Args:
+            agent_executor: The local AgentExecutor to use for actual execution.
+            event_queue: The event queue to use for reporting status updates and results.
+        """
+        self.agent_executor = agent_executor
+        self.event_queue = event_queue
+
+    @abstractmethod
+    async def run(self) -> None:
+        """Starts the worker to listen for and execute jobs."""
+        pass
+
+    async def close(self) -> None:
+        """Closes the worker and releases resources."""
+        pass
+
+    @abstractmethod
+    async def _execute_job(self, payload: Dict[str, Any]) -> None:
+        """Internal: Executes a single job with the given payload."""
+        pass
+
+    @abstractmethod
+    async def _cancel_job(self, payload: Dict[str, Any]) -> None:
+        """Internal: Cancels a single job with the given payload."""
+        pass

a2a_distributed-0.0.0/src/a2a_distributed/rq_executor.py

@@ -0,0 +1,157 @@
+from typing import Any, Dict, Optional
+from redis import Redis
+from rq import Queue, Worker
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a_distributed.executor import DistributedAgentExecutor, DistributedAgentWorker
+
+
+class RQAgentExecutor(DistributedAgentExecutor):
+    """Distributed Agent Executor using RQ (Redis Queue).
+
+    This executor delegates task execution to an RQ worker.
+    """
+
+    def __init__(
+        self,
+        redis_conn: Redis,
+        queue_name: str = "default",
+        task_func_path: str = "a2a_distributed.rq_executor.execute_task",
+        cancel_func_path: str = "a2a_distributed.rq_executor.cancel_task",
+    ):
+        """Initializes the RQAgentExecutor.
+
+        Args:
+            redis_conn: The Redis connection to use for the RQ queue.
+            queue_name: The name of the RQ queue to use.
+            task_func_path: The fully qualified path to the worker function for execution.
+            cancel_func_path: The fully qualified path to the worker function for cancellation.
+        """
+        self.redis_conn = redis_conn
+        self.queue = Queue(queue_name, connection=self.redis_conn)
+        self.task_func_path = task_func_path
+        self.cancel_func_path = cancel_func_path
+
+    async def execute(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Executes the agent logic by enqueuing a task to RQ."""
+        payload = self._get_payload(context)
+        
+        # Enqueue the task with the context's task_id as the RQ job ID
+        self.queue.enqueue(
+            self.task_func_path,
+            payload=payload,
+            job_id=context.task_id,
+        )
+
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Cancels the agent logic by sending a cancel task to RQ."""
+        if context.task_id:
+            payload = self._get_payload(context)
+            # Enqueue the cancellation task
+            self.queue.enqueue(
+                self.cancel_func_path,
+                payload=payload,
+            )
+
+    def _get_payload(self, context: RequestContext) -> Dict[str, Any]:
+        """Extracts serializable payload from the request context."""
+        return {
+            "task_id": context.task_id,
+            "context_id": context.context_id,
+            "message": context.message.model_dump() if context.message else None,
+            "metadata": context.metadata,
+        }
+
+
+class RQAgentWorker(DistributedAgentWorker):
+    """Distributed Agent Worker using RQ.
+    
+    This worker handles tasks enqueued by RQAgentExecutor.
+    """
+
+    _instance: Optional["RQAgentWorker"] = None
+
+    def __init__(
+        self,
+        agent_executor: AgentExecutor,
+        event_queue: EventQueue,
+        redis_conn: Redis,
+        queue_name: str = "default",
+    ):
+        """Initializes the RQAgentWorker.
+
+        Args:
+            agent_executor: The local AgentExecutor to use for actual execution.
+            event_queue: The event queue to use for reporting status updates and results.
+            redis_conn: The Redis connection to use.
+            queue_name: The name of the RQ queue to listen to.
+        """
+        super().__init__(agent_executor, event_queue)
+        self.redis_conn = redis_conn
+        self.queue_name = queue_name
+        self._worker: Optional[Worker] = None
+        RQAgentWorker._instance = self
+
+    @classmethod
+    def get_instance(cls) -> "RQAgentWorker":
+        if cls._instance is None:
+            raise RuntimeError("RQAgentWorker instance not initialized")
+        return cls._instance
+
+    async def run(self) -> None:
+        """Starts the RQ worker."""
+        if self._worker is None:
+            self._worker = Worker([self.queue_name], connection=self.redis_conn)
+            self._worker.work()
+
+    async def close(self) -> None:
+        """Closes the RQ worker."""
+        # Note: RQ's Worker.work() is usually blocking. 
+        # For a clean async stop, one might need to use signals or 
+        # a custom worker loop.
+        pass
+
+    async def _execute_job(self, payload: Dict[str, Any]) -> None:
+        """Executes a single job with the given payload."""
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.execute(context, self.event_queue)
+
+    async def _cancel_job(self, payload: Dict[str, Any]) -> None:
+        """Cancels a single job with the given payload."""
+        context = self._reconstruct_context(payload)
+        await self.agent_executor.cancel(context, self.event_queue)
+
+    def _reconstruct_context(self, payload: Dict[str, Any]) -> RequestContext:
+        """Reconstructs RequestContext from payload."""
+        from a2a.server.agent_execution.context import RequestContext
+        from a2a.models.messages import BaseMessage
+        
+        message = None
+        if payload.get("message"):
+            message = BaseMessage.model_validate(payload["message"])
+
+        return RequestContext(
+            task_id=payload.get("task_id"),
+            context_id=payload.get("context_id"),
+            message=message,
+            metadata=payload.get("metadata", {}),
+        )
+
+
+def execute_task(payload: Dict[str, Any]) -> None:
+    """Global task function for RQ."""
+    import asyncio
+    worker = RQAgentWorker.get_instance()
+    asyncio.run(worker._execute_job(payload))
+
+
+def cancel_task(payload: Dict[str, Any]) -> None:
+    """Global cancel task function for RQ."""
+    import asyncio
+    worker = RQAgentWorker.get_instance()
+    asyncio.run(worker._cancel_job(payload))

a2a_distributed-0.0.0/src/a2a_distributed/runner.py

@@ -0,0 +1,33 @@
+import asyncio
+import signal
+from a2a_distributed.executor import DistributedAgentWorker
+
+
+async def run_worker(worker: DistributedAgentWorker) -> None:
+    """Utility to run a DistributedAgentWorker and handle termination signals.
+
+    This function starts the worker and waits for a SIGINT or SIGTERM signal
+    to perform a graceful shutdown.
+
+    Args:
+        worker: The DistributedAgentWorker instance to run.
+    """
+    loop = asyncio.get_running_loop()
+
+    # Setup shutdown logic
+    shutdown_task = asyncio.create_task(worker.run())
+
+    def shutdown_handler():
+        print(f"Shutdown signal received. Closing {worker.__class__.__name__}...")
+        asyncio.create_task(worker.close())
+
+    # Register signal handlers
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, shutdown_handler)
+
+    try:
+        await shutdown_task
+    except asyncio.CancelledError:
+        pass
+    finally:
+        print(f"{worker.__class__.__name__} stopped.")