distributed-a2a 0.2.1__tar.gz → 0.2.3__tar.gz

{distributed_a2a-0.2.1/distributed_a2a.egg-info → distributed_a2a-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed_a2a
-Version: 0.2.1
+Version: 0.2.3
 Summary: A library for building A2A agents with routing capabilities
 Home-page: https://github.com/Barra-Technologies/distributed-a2a
 Author: Fabian Bell
@@ -211,6 +211,27 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+### Binary content handling
+
+When an agent invokes an MCP tool that returns non-text content (files, images,
+`EmbeddedResource`, `ResourceLink`), the library keeps those payloads out of the
+LLM's context window and delivers them out-of-band as A2A `FilePart` artifacts.
+
+Concretely, `RoutingAgentExecutor` installs the
+`hide_binary_content_from_llm` tool-call interceptor on every
+`MultiServerMCPClient` it builds. The interceptor moves any non-`TextContent`
+block from `CallToolResult.content` into `CallToolResult.structuredContent`
+under the `non_text_content` key. The upstream adapter then carries that dict
+into `ToolMessage.artifact['structured_content']`, which LangChain does **not**
+surface to the model. After the graph run, the executor walks the message list,
+extracts the stashed blocks, and emits one `TaskArtifactUpdateEvent` per file
+before the terminating text artifact.
+
+Client-side, `RoutingA2AClient.send_message` returns an `AgentReply` that
+exposes both the LLM's text summary and any `FileRef` payloads (with either
+inline `bytes_b64` or a `uri`), so downstream integrations (e.g. Slack file
+uploads) can forward the bytes without ever routing them through a model.
+
 ### Environment Variables
 The library uses several environment variables for configuration. These can be set in your shell or via a `.env` file.
 

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3}/README.md

@@ -172,6 +172,27 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+### Binary content handling
+
+When an agent invokes an MCP tool that returns non-text content (files, images,
+`EmbeddedResource`, `ResourceLink`), the library keeps those payloads out of the
+LLM's context window and delivers them out-of-band as A2A `FilePart` artifacts.
+
+Concretely, `RoutingAgentExecutor` installs the
+`hide_binary_content_from_llm` tool-call interceptor on every
+`MultiServerMCPClient` it builds. The interceptor moves any non-`TextContent`
+block from `CallToolResult.content` into `CallToolResult.structuredContent`
+under the `non_text_content` key. The upstream adapter then carries that dict
+into `ToolMessage.artifact['structured_content']`, which LangChain does **not**
+surface to the model. After the graph run, the executor walks the message list,
+extracts the stashed blocks, and emits one `TaskArtifactUpdateEvent` per file
+before the terminating text artifact.
+
+Client-side, `RoutingA2AClient.send_message` returns an `AgentReply` that
+exposes both the LLM's text summary and any `FileRef` payloads (with either
+inline `bytes_b64` or a `uri`), so downstream integrations (e.g. Slack file
+uploads) can forward the bytes without ever routing them through a model.
+
 ### Environment Variables
 The library uses several environment variables for configuration. These can be set in your shell or via a `.env` file.
 

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3}/distributed_a2a/__init__.py

@@ -1,4 +1,6 @@
 from .client import A2ATimeoutError, AgentReply, FileRef, RoutingA2AClient
+from .mcp_interceptors import (NON_TEXT_CONTENT_KEY,
+                               hide_binary_content_from_llm)
 from .model import (AgentConfig, AgentItem, CardConfig, LLMConfig,
                     RegistryConfig, RegistryItemConfig, RouterConfig,
                     RouterItem, SkillConfig)
@@ -31,5 +33,7 @@ __all__ = [
     "AgentRegistryClient",
     "McpRegistryClient",
     "InMemoryAgentRegistry",
-    "InMemoryMcpRegistry"
+    "InMemoryMcpRegistry",
+    "hide_binary_content_from_llm",
+    "NON_TEXT_CONTENT_KEY",
 ]

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3}/distributed_a2a/executors.py

@@ -4,50 +4,23 @@ from typing import Any
 
 from a2a.server.agent_execution import AgentExecutor, RequestContext
 from a2a.server.events import EventQueue
-from a2a.types import (Artifact, FilePart, FileWithBytes, Part,
-                       TaskArtifactUpdateEvent, TaskState, TaskStatus,
-                       TaskStatusUpdateEvent)
+from a2a.types import (Artifact, FilePart, Part, TaskArtifactUpdateEvent,
+                       TaskState, TaskStatus, TaskStatusUpdateEvent)
 from a2a.utils import new_text_artifact
-from langchain_core.messages import BaseMessage, ToolMessage
 from langchain_core.tools import BaseTool
 from langchain_mcp_adapters.client import MultiServerMCPClient
 from langgraph.checkpoint.base import BaseCheckpointSaver
-from mcp.types import BlobResourceContents, EmbeddedResource, ImageContent
 
 from .agent import RoutingResponse, StatusAgent, StringResponse
 from .config import settings
+from .file_extractors import extract_file_parts
+from .mcp_interceptors import hide_binary_content_from_llm
 from .model import AgentConfig, RouterConfig
 from .registry import AgentRegistryLookupClient, McpRegistryLookup
 
 logger = logging.getLogger(__name__)
 
 
-def _extract_file_parts(messages: list[BaseMessage]) -> list[tuple[str, FilePart]]:
-    out: list[tuple[str, FilePart]] = []
-    for message in messages:
-        if not isinstance(message, ToolMessage):
-            continue
-        artifact = getattr(message, "artifact", None)
-        if not artifact:
-            continue
-        for block in artifact:
-            if isinstance(block, EmbeddedResource) and isinstance(block.resource, BlobResourceContents):
-                uri_str = str(block.resource.uri)
-                name = uri_str.rsplit("/", 1)[-1] or "file.bin"
-                out.append((name, FilePart(file=FileWithBytes(
-                    name=name,
-                    mime_type=block.resource.mimeType or "application/octet-stream",
-                    bytes=block.resource.blob,
-                ))))
-            elif isinstance(block, ImageContent):
-                out.append(("image", FilePart(file=FileWithBytes(
-                    name="image",
-                    mime_type=block.mimeType,
-                    bytes=block.data,
-                ))))
-    return out
-
-
 class RoutingFailed(Exception):
     def __init__(self, message: str) -> None:
         super().__init__(message)
@@ -155,7 +128,7 @@ class RoutingAgentExecutor(AgentExecutor):
                 artifact = await _route_request_to_matching_agent(self.routing_agent, self.agent_registry, context)
             else:
                 logger.info(f"Request with id {context.context_id} was successfully processed by agent.")
-                file_parts = _extract_file_parts(invocation.messages)
+                file_parts = extract_file_parts(invocation.messages)
                 artifact = new_text_artifact(
                     name='current_result',
                     description='Result of request to agent.',
@@ -234,10 +207,18 @@ class RoutingAgentExecutor(AgentExecutor):
             return
 
         logger.info(f"Agent {self.agent_config.agent.card.name} has access to the following tools: {mcp_server_raw}")
-        mcp_servers = {tool["name"]: {"url": tool["url"], "transport": tool["protocol"],
-                                      "headers": settings.get_mcp_auth_headers(tool["name"])} for tool in
-                       mcp_server_raw}
-        mcp_client = MultiServerMCPClient(mcp_servers)  # type: ignore[arg-type]
+        mcp_servers: dict[str, Any] = {
+            tool["name"]: {
+                "url": tool["url"],
+                "transport": tool["protocol"],
+                "headers": settings.get_mcp_auth_headers(tool["name"])
+            }
+            for tool in mcp_server_raw
+        }
+        mcp_client = MultiServerMCPClient(
+            connections=mcp_servers,
+            tool_interceptors=[hide_binary_content_from_llm],
+        )
         mcp_tools = await mcp_client.get_tools()
 
         self.agent = StatusAgent[StringResponse](

distributed_a2a-0.2.3/distributed_a2a/file_extractors.py

@@ -0,0 +1,142 @@
+import json
+import mimetypes
+from typing import Any
+
+from a2a.types import FilePart, FileWithBytes, FileWithUri
+from langchain_core.messages import BaseMessage, ToolMessage
+from mcp.types import (BlobResourceContents, EmbeddedResource, ImageContent,
+                       ResourceLink)
+
+from .mcp_interceptors import NON_TEXT_CONTENT_KEY
+
+_LANGCHAIN_BINARY_BLOCK_TYPES: dict[str, str] = {
+    "file": "attachment",
+    "image": "image",
+}
+
+
+def _filename_from_text_block(block: dict[str, Any]) -> str | None:
+    text = block.get("text")
+    if not isinstance(text, str):
+        return None
+    try:
+        payload = json.loads(text)
+    except (ValueError, TypeError):
+        return None
+    if isinstance(payload, dict):
+        name = payload.get("filename")
+        if isinstance(name, str) and name:
+            return name
+    return None
+
+
+def _synthetic_name(kind: str, index: int, mime_type: str) -> str:
+    guessed_ext = mimetypes.guess_extension(mime_type)
+    ext = guessed_ext if guessed_ext is not None else ""
+    suffix = f"-{index}" if index > 0 else ""
+    return f"{kind}{suffix}{ext}"
+
+
+def _name_from_uri(uri: str, fallback_kind: str, index: int, mime_type: str) -> str:
+    tail = uri.rsplit("/", 1)[-1]
+    if tail:
+        return tail
+    return _synthetic_name(fallback_kind, index, mime_type)
+
+
+def _extract_from_mcp_blocks(blocks: list[Any]) -> list[tuple[str, FilePart]]:
+    out: list[tuple[str, FilePart]] = []
+    counters: dict[str, int] = {"attachment": 0, "image": 0}
+    for block in blocks:
+        if isinstance(block, EmbeddedResource) and isinstance(block.resource, BlobResourceContents):
+            mime_type = block.resource.mimeType or "application/octet-stream"
+            uri = str(block.resource.uri) if block.resource.uri is not None else ""
+            kind = "image" if mime_type.startswith("image/") else "attachment"
+            if uri:
+                name = _name_from_uri(uri, kind, counters[kind], mime_type)
+            else:
+                name = _synthetic_name(kind, counters[kind], mime_type)
+            counters[kind] += 1
+            out.append((name, FilePart(file=FileWithBytes(
+                name=name, mime_type=mime_type, bytes=block.resource.blob,
+            ))))
+        elif isinstance(block, ImageContent):
+            mime_type = block.mimeType or "application/octet-stream"
+            name = _synthetic_name("image", counters["image"], mime_type)
+            counters["image"] += 1
+            out.append((name, FilePart(file=FileWithBytes(
+                name=name, mime_type=mime_type, bytes=block.data,
+            ))))
+        elif isinstance(block, ResourceLink):
+            mime_type = block.mimeType or "application/octet-stream"
+            uri = str(block.uri)
+            kind = "image" if mime_type.startswith("image/") else "attachment"
+            name = _name_from_uri(uri, kind, counters[kind], mime_type)
+            counters[kind] += 1
+            out.append((name, FilePart(file=FileWithUri(
+                name=name, mime_type=mime_type, uri=uri,
+            ))))
+    return out
+
+
+def _extract_from_langchain_content_blocks(content: list[Any]) -> list[tuple[str, FilePart]]:
+    out: list[tuple[str, FilePart]] = []
+    pending_name: str | None = None
+    counters: dict[str, int] = {"file": 0, "image": 0}
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        block_type = block.get("type")
+        if not isinstance(block_type, str):
+            continue
+        if block_type == "text":
+            hint = _filename_from_text_block(block)
+            if hint:
+                pending_name = hint
+            continue
+        kind = _LANGCHAIN_BINARY_BLOCK_TYPES.get(block_type)
+        if kind is None:
+            continue
+        b64 = block.get("base64")
+        if not isinstance(b64, str) or not b64:
+            continue
+        mime_type = block.get("mime_type") or "application/octet-stream"
+        if pending_name is not None:
+            name = pending_name
+            pending_name = None
+        else:
+            index = counters[block_type]
+            counters[block_type] = index + 1
+            name = _synthetic_name(kind, index, mime_type)
+        out.append((name, FilePart(file=FileWithBytes(
+            name=name, mime_type=mime_type, bytes=b64,
+        ))))
+    return out
+
+
+def _mcp_blocks_from_artifact(artifact: Any) -> list[Any] | None:
+    if not isinstance(artifact, dict):
+        return None
+    structured = artifact.get("structured_content")
+    if not isinstance(structured, dict):
+        return None
+    blocks = structured.get(NON_TEXT_CONTENT_KEY)
+    if not isinstance(blocks, list) or not blocks:
+        return None
+    return blocks
+
+
+def extract_file_parts(messages: list[BaseMessage]) -> list[tuple[str, FilePart]]:
+    parts: list[tuple[str, FilePart]] = []
+    for message in messages:
+        if not isinstance(message, ToolMessage):
+            continue
+
+        mcp_blocks = _mcp_blocks_from_artifact(message.artifact)
+        if mcp_blocks is not None:
+            parts.extend(_extract_from_mcp_blocks(mcp_blocks))
+            continue
+
+        if isinstance(message.content, list):
+            parts.extend(_extract_from_langchain_content_blocks(message.content))
+    return parts

distributed_a2a-0.2.3/distributed_a2a/mcp_interceptors.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from langchain_mcp_adapters.interceptors import (MCPToolCallRequest,
+                                                 MCPToolCallResult)
+from mcp.types import CallToolResult, TextContent
+
+"""Key under ``CallToolResult.structuredContent`` where the interceptor stashes
+any non-text MCP content blocks. Also the key under
+``ToolMessage.artifact['structured_content']`` where downstream extraction
+code (:func:`distributed_a2a.files.extract_file_parts`) reads them back."""
+NON_TEXT_CONTENT_KEY = "non_text_content"
+
+
+async def hide_binary_content_from_llm(
+    request: MCPToolCallRequest,
+    handler: Callable[
+        [MCPToolCallRequest],
+        Awaitable[MCPToolCallResult],  # pyright: ignore[reportInvalidTypeForm]
+    ],
+) -> MCPToolCallResult:  # pyright: ignore[reportInvalidTypeForm]
+    result = await handler(request)
+    if not isinstance(result, CallToolResult) or result.isError:
+        return result
+
+    text_blocks: list[TextContent] = []
+    non_text_blocks: list[Any] = []
+    for block in result.content:
+        if isinstance(block, TextContent):
+            text_blocks.append(block)
+        else:
+            non_text_blocks.append(block)
+
+    merged_structured: dict[str, Any] = (
+        dict(result.structuredContent) if result.structuredContent else {}
+    )
+    merged_structured[NON_TEXT_CONTENT_KEY] = non_text_blocks
+
+    return result.model_copy(update={
+        "content": text_blocks,
+        "structuredContent": merged_structured,
+    })

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3/distributed_a2a.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: distributed_a2a
-Version: 0.2.1
+Version: 0.2.3
 Summary: A library for building A2A agents with routing capabilities
 Home-page: https://github.com/Barra-Technologies/distributed-a2a
 Author: Fabian Bell
@@ -211,6 +211,27 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+### Binary content handling
+
+When an agent invokes an MCP tool that returns non-text content (files, images,
+`EmbeddedResource`, `ResourceLink`), the library keeps those payloads out of the
+LLM's context window and delivers them out-of-band as A2A `FilePart` artifacts.
+
+Concretely, `RoutingAgentExecutor` installs the
+`hide_binary_content_from_llm` tool-call interceptor on every
+`MultiServerMCPClient` it builds. The interceptor moves any non-`TextContent`
+block from `CallToolResult.content` into `CallToolResult.structuredContent`
+under the `non_text_content` key. The upstream adapter then carries that dict
+into `ToolMessage.artifact['structured_content']`, which LangChain does **not**
+surface to the model. After the graph run, the executor walks the message list,
+extracts the stashed blocks, and emits one `TaskArtifactUpdateEvent` per file
+before the terminating text artifact.
+
+Client-side, `RoutingA2AClient.send_message` returns an `AgentReply` that
+exposes both the LLM's text summary and any `FileRef` payloads (with either
+inline `bytes_b64` or a `uri`), so downstream integrations (e.g. Slack file
+uploads) can forward the bytes without ever routing them through a model.
+
 ### Environment Variables
 The library uses several environment variables for configuration. These can be set in your shell or via a `.env` file.
 

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3}/distributed_a2a.egg-info/SOURCES.txt

@@ -9,6 +9,8 @@ distributed_a2a/agent.py
 distributed_a2a/client.py
 distributed_a2a/config.py
 distributed_a2a/executors.py
+distributed_a2a/file_extractors.py
+distributed_a2a/mcp_interceptors.py
 distributed_a2a/model.py
 distributed_a2a/py.typed
 distributed_a2a/registry.py
@@ -30,6 +32,7 @@ distributed_a2a/schemas/router-agent-schema.json
 tests/test_app.py
 tests/test_client.py
 tests/test_executor_files.py
-tests/test_files.py
+tests/test_file_extractors.py
+tests/test_mcp_interceptors.py
 tests/test_rejection.py
 tests/test_timeout.py

{distributed_a2a-0.2.1 → distributed_a2a-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "distributed_a2a"
-version = "0.2.1"
+version = "0.2.3"
 description = "A library for building A2A agents with routing capabilities"
 readme = "README.md"
 requires-python = ">=3.14"