distributed-a2a 0.1.5rc17__py3-none-any.whl

distributed_a2a/__init__.py

@@ -0,0 +1,7 @@
+from .client import RoutingA2AClient
+from .server import load_app
+
+__all__ = [
+    "load_app",
+    "RoutingA2AClient"
+]

distributed_a2a/agent.py

@@ -0,0 +1,61 @@
+from typing import Literal
+
+from a2a.types import TaskState
+from langchain.agents import create_agent
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from langgraph.checkpoint.memory import MemorySaver
+from pydantic import BaseModel, Field
+
+from .model import get_model, AgentConfig, LLMConfig
+
+
+class AgentResponse(BaseModel):
+    status: Literal[TaskState.rejected, TaskState.completed, TaskState.rejected, TaskState.failed] = Field(
+        description=(
+            f'You should select status as {TaskState.rejected} for requests that fall outside your area of expertise.'
+            f'You should select status as {TaskState.completed} if the request is fully addressed and no further input is needed. '
+            f'You should select status as {TaskState.input_required} if you need more information from the user or are asking a clarifying question. '
+            f'You should select status as {TaskState.failed} if an error occurred or the request cannot be fulfilled.'
+        )
+    )
+
+class RoutingResponse(AgentResponse):
+    agent_card: str = Field(description="The stringified json of the agent card to be returned to the user")
+
+class StringResponse(AgentResponse):
+    response: str = Field(description="The main response to be returned to the user")
+
+
+class StatusAgent[ResponseT: AgentResponse]:
+
+    def __init__(self, llm_config: LLMConfig, name: str, system_prompt: str, api_key: str, is_routing: bool, tools: list[BaseTool]):
+        response_format: type[AgentResponse]
+        if is_routing:
+            response_format = RoutingResponse
+        else:
+            response_format = StringResponse
+
+        self.agent = create_agent(
+            get_model(api_key=api_key,
+                      model=llm_config.model,
+                      base_url=llm_config.base_url,
+                      reasoning_effort=llm_config.reasoning_effort),
+            tools=tools,
+            checkpointer=MemorySaver(),  # TODO replace by dynamodb
+            system_prompt=system_prompt,
+            response_format=response_format,
+            name=name
+        )
+
+    async def __call__(self, message: str, context_id: str = None) -> ResponseT:
+        config: RunnableConfig = RunnableConfig(configurable={'thread_id': context_id})
+        response = await self.agent.ainvoke(LangGraphMessage(message), config)
+        return response['structured_response']
+
+
+class LangGraphMessage(BaseModel):
+    messages: list[tuple[Literal['user'], str]]
+
+    def __init__(self, messages: str):
+        super().__init__(messages=[("user", messages)])

distributed_a2a/client.py

@@ -0,0 +1,110 @@
+import json
+import time
+from uuid import uuid4
+
+import httpx
+from a2a.client import ClientConfig, ClientFactory, A2ACardResolver, ClientEvent
+from a2a.client import create_text_message_object
+from a2a.types import (
+    AgentCard,
+    Message, TaskQueryParams, Task, Artifact, Part, TextPart
+)
+from a2a.types import TaskState
+
+
+class RemoteAgentConnection:
+    """A class to hold the connections to the remote agents."""
+
+    def __init__(self, agent_card: AgentCard, client: httpx.AsyncClient):
+        client_config = ClientConfig(
+            httpx_client=client,
+            supported_transports=[agent_card.preferred_transport],
+            streaming=agent_card.capabilities.streaming,
+            polling=True
+        )
+        client_factory = ClientFactory(config=client_config)
+        self.agent_client = client_factory.create(agent_card)
+
+    async def _send_message_to_agent(self, message_request: Message) -> Task:
+
+        responses: list[ClientEvent] = []
+        async for response in self.agent_client.send_message(message_request):
+            responses.append(response)
+
+        task_response: Task | None = None
+        match responses:
+            case [(task, _)]:
+                task_response = task
+            case _:
+                raise Exception("Wrong response format")
+        return task_response
+
+    async def _get_task(self, task_id: str) -> Task:
+        query_params: TaskQueryParams = TaskQueryParams(id=task_id)
+        response: Task = await self.agent_client.get_task(query_params)
+        return response
+
+    async def send_message(self, message_to_send: str, context_id, task_id: None | str = None,
+                           count=0) -> str | AgentCard:
+        message: Message = create_text_message_object(content=message_to_send)
+        message.message_id = str(uuid4())
+        message.context_id = context_id
+
+        response: Task
+        if task_id is None:
+            response = await self._send_message_to_agent(message)
+        else:
+            response = await self._get_task(task_id)
+
+        task_state = response.status.state
+        if task_state == TaskState.working or task_state == TaskState.submitted:
+            if count < 20:
+                time.sleep(1)
+                return await self.send_message(message_to_send, context_id, response.id, count + 1)
+            else:
+                raise Exception("Timeout waiting for agent to respond")
+
+        if task_state == TaskState.failed:
+            raise Exception("A2ATaskFailed")
+        elif task_state == TaskState.auth_required:
+            raise Exception("A2ATaskAuthRequired")
+
+        match response.artifacts:
+            case [Artifact(name='target_agent', parts=[Part(root=TextPart(text=agent_card))])]:
+                return AgentCard(**json.loads(agent_card))
+            case [Artifact(name='current_result', parts=[Part(root=TextPart(text=result))])]:
+                return result
+            case _:
+                raise Exception("Wrong response format")
+
+
+MAX_RECURSION_DEPTH = 10
+
+
+class RoutingA2AClient:
+    def __init__(self, initial_url: str):
+        self.url = initial_url
+        self.client = httpx.AsyncClient()
+        self.current_card: AgentCard | None = None
+
+    async def fetch_current_card(self):
+        card_resolver = A2ACardResolver(
+            self.client, self.url
+        )
+        self.current_card = (
+            await card_resolver.get_agent_card()
+        )
+
+    async def send_message(self, message: str, context_id: str, depth: int = 0) -> str:
+        if depth > MAX_RECURSION_DEPTH:
+            raise Exception("Maximum recursion depth exceeded. This is likely due to an infinite loop in your agent.")
+        if self.current_card is None:
+            await self.fetch_current_card()
+
+        agent_connection = RemoteAgentConnection(self.current_card, self.client)
+
+        agent_response: str | AgentCard = await agent_connection.send_message(message, context_id)
+        if isinstance(agent_response, AgentCard):
+            self.current_card = agent_response
+            return await self.send_message(message, context_id, depth + 1)
+        return agent_response

distributed_a2a/executors.py

@@ -0,0 +1,82 @@
+import json
+import logging
+import os
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.types import TaskStatusUpdateEvent, TaskStatus, TaskState, TaskArtifactUpdateEvent, Artifact
+from a2a.utils import new_text_artifact
+from langchain_core.tools import BaseTool
+
+from .agent import StatusAgent, RoutingResponse, StringResponse
+from .model import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+ROUTING_SYSTEM_PROMPT = """
+You are a helpful routing assistant which routes user requests to specialized remote agents. Your main task is to:
+1. look up available agents via their A2A agent cards
+2. select the best matching agent for the user query
+3. return the matching agent card for that agent."""
+
+
+class RoutingAgentExecutor(AgentExecutor):
+
+    def __init__(self, agent_config: AgentConfig, routing_tool: BaseTool, tools: list[BaseTool] | None = None):
+        super().__init__()
+        api_key = os.environ.get(agent_config.agent.llm.api_key_env)
+        self.agent = StatusAgent[StringResponse](
+            llm_config=agent_config.agent.llm,
+            system_prompt=agent_config.agent.system_prompt,
+            name=agent_config.agent.card.name,
+            api_key=api_key,
+            is_routing=False,
+            tools=[] if tools is None else tools,
+        )
+        self.routing_agent = StatusAgent[RoutingResponse](
+            llm_config=agent_config.agent.llm,
+            system_prompt=ROUTING_SYSTEM_PROMPT,
+            name="Router",
+            api_key=api_key,
+            is_routing=True,
+            tools=[routing_tool]
+        )
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        raise NotImplementedError
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        # set status to processing
+        await event_queue.enqueue_event(TaskStatusUpdateEvent(status=TaskStatus(state=TaskState.working),
+                                                              final=False,
+                                                              context_id=context.context_id,
+                                                              task_id=context.task_id))
+        agent_response: StringResponse = await self.agent(message=context.get_user_input(),
+                                                          context_id=context.context_id)
+
+        artifact: Artifact
+        if agent_response.status == TaskState.rejected:
+            agent_response: RoutingResponse = await self.routing_agent(message=context.get_user_input(),
+                                                                       context_id=context.context_id)
+            agent_name: str = json.loads(agent_response.agent_card)["name"]
+            logger.info(f"Request with id {context.context_id} got rejected and will be rerouted to a '{agent_name}'.",
+                        extra={"card": agent_response.agent_card})
+            artifact = new_text_artifact(name='target_agent', description='New target agent for request.',
+                                         text=agent_response.agent_card)
+        else:
+            logger.info(f"Request with id {context.context_id} was successfully processed by agent.")
+            artifact = new_text_artifact(name='current_result', description='Result of request to agent.',
+                                         text=agent_response.response)
+
+        # publish actual result
+        await event_queue.enqueue_event(TaskArtifactUpdateEvent(append=False,
+                                                                context_id=context.context_id,
+                                                                task_id=context.task_id,
+                                                                last_chunk=True,
+                                                                artifact=artifact))
+        # set and publish the final status
+        await event_queue.enqueue_event(TaskStatusUpdateEvent(status=TaskStatus(
+            state=TaskState(agent_response.status)),
+            final=True,
+            context_id=context.context_id,
+            task_id=context.task_id))

distributed_a2a/model.py

@@ -0,0 +1,59 @@
+import os
+from typing import List, Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_openai import ChatOpenAI
+from pydantic import BaseModel, Field
+
+
+class SkillConfig(BaseModel):
+    id: str = Field(description="The id of the skill e.g. weather")
+    name: str = Field(description="The name of the skill e.g. weather")
+    description: str = Field(description="A short description of the skill")
+    tags: List[str] = Field(description="The tags associated with the skill")
+
+
+class LLMConfig(BaseModel):
+    base_url: str = Field(description="The base url of the LLM provider")
+    model: str = Field(description="The model to use for the LLM e.g. gpt-3.5-turbo")
+    api_key_env: str = Field(description="The environment variable containing the api key for the LLM provider")
+    reasoning_effort: str  = Field(description="The reasoning effort to use for the LLM e.g. high", default="high")
+
+
+class CardConfig(BaseModel):
+    name: str = Field(description="The name of the agent" )
+    description: str = Field(description="A short description of the agent")
+    version: str = Field(description="The version of the agent")
+    default_input_modes: List[str]  = Field(description="The default input modes supported by the agent", default=["text","text/plaintext"])
+    default_output_modes: List[str] = Field(description="The default output modes supported by the agent", default=["text","text/plaintext"])
+    preferred_transport_protocol: str = Field(description="The preferred transport protocol for the agent", default="HTTP+JSON")
+    url: str = Field(description="The url of the agent")
+    skills: List[SkillConfig] = Field(description="The skills supported by the agent", default=[])
+
+
+class AgentItem(BaseModel):
+    card: CardConfig = Field(description="The agent card configuration node")
+    llm: LLMConfig = Field(description="The LLM configuration node")
+    system_prompt: str = Field(description="The system prompt to use for the LLM or a path to a file containing the system prompt")
+
+    def __init__(self, /, **data: Any) -> None:
+        prompt_or_path= data['system_prompt']
+        if os.path.exists(prompt_or_path):
+            with open(prompt_or_path, "r", encoding="utf-8") as f:
+                data['system_prompt'] =  f.read()
+
+        super().__init__(**data)
+
+
+class AgentConfig(BaseModel):
+    agent: AgentItem = Field(description="The agent configuration node")
+
+
+
+def get_model(api_key: str, model: str, base_url: str, reasoning_effort: str) -> BaseChatModel:
+    return ChatOpenAI(
+        model=model,
+        base_url=base_url,
+        api_key=lambda: api_key,
+        reasoning_effort=reasoning_effort
+    )

distributed_a2a/registry.py

@@ -0,0 +1,18 @@
+import boto3
+from langchain_core.tools import StructuredTool
+
+
+class DynamoDbRegistryLookup:
+    def __init__(self, agent_card_tabel: str):
+        dynamo = boto3.resource("dynamodb", region_name="eu-central-1")
+        self.table = dynamo.Table(agent_card_tabel)
+
+    def get_agent_cards(self) -> list[str]:
+
+        items = self.table.scan().get("Items", [])
+        cards: list[str] = [it["card"] for it in items]
+        return cards
+
+    def as_tool(self) -> StructuredTool:
+        return StructuredTool.from_function(func=lambda: self.get_agent_cards(), name="agent_card_lookup",
+                                            description="Gets all available agent cards")

distributed_a2a/server.py

@@ -0,0 +1,87 @@
+import asyncio
+import time
+from contextlib import asynccontextmanager
+from typing import Any
+
+import boto3
+from a2a.server.apps import A2ARESTFastAPIApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import AgentSkill, \
+    AgentCapabilities, AgentCard
+from fastapi import FastAPI
+
+from .executors import RoutingAgentExecutor
+from .model import AgentConfig
+from .registry import DynamoDbRegistryLookup
+
+CAPABILITIES = AgentCapabilities(streaming=False, push_notifications=False)
+
+HEART_BEAT_INTERVAL_SEC = 5
+MAX_HEART_BEAT_MISSES = 3
+
+AGENT_CARD_TABLE = "agent-cards"
+
+def get_expire_at() -> int:
+    return int(time.time() + MAX_HEART_BEAT_MISSES * HEART_BEAT_INTERVAL_SEC)
+
+async def heart_beat(name: str, agent_card_table: str, agent_card: AgentCard):
+    table = boto3.resource("dynamodb", region_name="eu-central-1").Table(agent_card_table)
+    table.put_item(Item={"id": name, "card": agent_card.model_dump_json(), "expireAt": get_expire_at()})
+    while True:
+        await asyncio.sleep(HEART_BEAT_INTERVAL_SEC)
+        table.update_item(
+            Key={"id": name},
+            UpdateExpression="SET expireAt = :expire_at",
+            ExpressionAttributeValues={":expire_at": get_expire_at()}
+        )
+
+
+
+
+def load_app(agent_config: dict[str, Any]) -> FastAPI:
+
+    agent_config= AgentConfig.model_validate(agent_config)
+
+    skills = [AgentSkill(
+        id=skill.id,
+        name=skill.name,
+        description=skill.description,
+        tags=skill.tags)
+    for skill in agent_config.agent.card.skills]
+    skills.append(AgentSkill(
+        id='routing',
+        name='Agent routing',
+        description='Identifies the most suitable agent for the given task and returns the agent card',
+        tags=['agent', 'routing']
+    ))
+
+    agent_card = AgentCard(
+        name=agent_config.agent.card.name,
+        description=agent_config.agent.card.description,
+        url=agent_config.agent.card.url,
+        version=agent_config.agent.card.version,
+        default_input_modes=agent_config.agent.card.default_input_modes,
+        default_output_modes=agent_config.agent.card.default_output_modes,
+        skills=skills,
+        preferred_transport=agent_config.agent.card.preferred_transport_protocol,
+        capabilities=CAPABILITIES
+    )
+
+
+    executor = RoutingAgentExecutor(agent_config=agent_config,
+                                    routing_tool=DynamoDbRegistryLookup(agent_card_tabel=AGENT_CARD_TABLE).as_tool())
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        asyncio.create_task(heart_beat(name=agent_card.name, agent_card_table=AGENT_CARD_TABLE, agent_card=agent_card))
+        yield
+
+
+    return A2ARESTFastAPIApplication(
+        agent_card=agent_card,
+        http_handler=DefaultRequestHandler(
+            agent_executor=executor,
+            task_store=InMemoryTaskStore() #TODO replace with dynamodb store
+
+        )).build(title=agent_card.name, lifespan=lifespan, root_path=f"/{agent_config.agent.card.name}") #TODO use extra parameter

distributed_a2a-0.1.5rc17.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: distributed_a2a
+Version: 0.1.5rc17
+Summary: A library for building A2A agents with routing capabilities
+Home-page: https://github.com/Barra-Technologies/distributed-a2a
+Author: Fabian Bell
+Author-email: Fabian Bell <fabian.bell@barrabytes.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Barra-Technologies/distributed-a2a
+Project-URL: Repository, https://github.com/Barra-Technologies/distributed-a2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain>=0.1.0
+Requires-Dist: langchain-core>=0.1.0
+Requires-Dist: langchain-openai>=0.0.5
+Requires-Dist: langgraph>=0.0.20
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: a2a>=0.1.0
+Requires-Dist: build>=1.4.0
+Requires-Dist: twine>=6.2.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# A2A Agent Library
+
+A Python library for building A2A (Agent-to-Agent) agents with routing capabilities, DynamoDB-backed registry, and LangChain integration.
+
+## Features
+
+- **StatusAgent**: Base agent implementation with status tracking and structured responses
+- **RoutingAgentExecutor**: Agent executor with intelligent routing capabilities
+- **DynamoDB Registry**: Dynamic agent card registry with heartbeat mechanism
+- **Server Utilities**: FastAPI application builder with A2A protocol support
+- **LangChain Integration**: Built on LangChain for flexible model integration
+
+## Installation
+
+```bash
+pip install distributed-a2a
+```
+
+## Quick Start
+
+1. Start a server with your agent application:
+```python
+from distributed_a2a import load_app
+from a2a.types import AgentSkill
+
+# Define your agent's skills
+skills = [
+    AgentSkill(
+        id='example_skill',
+        name='Example Skill',
+        description='An example skill',
+        tags=['example']
+    )
+]
+
+# Create your agent application
+app = load_app(
+    name="MyAgent",
+    description="My specialized agent",
+    skills=skills,
+    api_key="your-api-key",
+    system_prompt="You are a helpful assistant...",
+    host="http://localhost:8000"
+)
+```
+
+2. Send a request with the client
+```python
+from uuid import uuid4
+
+from distributed_a2a import RoutingA2AClient
+
+if __name__ == "__main__":
+    import asyncio
+
+    request = "Tell me the weather in Bonn"
+    client = RoutingA2AClient("http://localhost:8000")
+    response: str = asyncio.run(client.send_message(request, str(uuid4())))
+    print(response)
+```
+
+## Requirements
+
+- Python 3.10+
+- langchain
+- langchain-core
+- langchain-openai
+- langgraph
+- pydantic
+- boto3
+- a2a
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

distributed_a2a-0.1.5rc17.dist-info/RECORD

@@ -0,0 +1,12 @@
+distributed_a2a/__init__.py,sha256=1q_7gRfBCGe-7sF_9YKzevyS97XQhtuFnZiYHIqaU-0,120
+distributed_a2a/agent.py,sha256=CpIeEASjkIflGCiVo4f5c5_xUg3VwMr27l-o4cj73Mw,2597
+distributed_a2a/client.py,sha256=2974Uw8YUuyBytwxxJJKYsWXCpEaIbGmMUHDraITxJ0,4149
+distributed_a2a/executors.py,sha256=TNHO3eEIlKWObqBblcx_XiP5KahcfaGK1YuajWmQ5rE,4187
+distributed_a2a/model.py,sha256=pvuoVg8QChYq21us49wZa7Pv-BlIU-mlfN2auVQvqdY,2676
+distributed_a2a/registry.py,sha256=197eZVR6TW0isOUE0VjWSWs7aCqbWqnBzcV8EVXAxrI,677
+distributed_a2a/server.py,sha256=eVccqBos4nMQqe9feyglGlMmUYIGz2t5jmBbMVt-NGE,3085
+distributed_a2a-0.1.5rc17.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+distributed_a2a-0.1.5rc17.dist-info/METADATA,sha256=DMa6qn4InHdNC5TSVGG8P4Q95FlVcIJvl3MZ4svvBQQ,3107
+distributed_a2a-0.1.5rc17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+distributed_a2a-0.1.5rc17.dist-info/top_level.txt,sha256=23qJ8n5k7796BHDK7a58uuO-X4GV0EgUWcGi8NIn-0k,16
+distributed_a2a-0.1.5rc17.dist-info/RECORD,,

distributed_a2a-0.1.5rc17.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

distributed_a2a-0.1.5rc17.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

distributed_a2a-0.1.5rc17.dist-info/top_level.txt

@@ -0,0 +1 @@
+distributed_a2a