agent-framework-hosting-a2a 1.0.0a260721__tar.gz

agent_framework_hosting_a2a-1.0.0a260721/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    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

agent_framework_hosting_a2a-1.0.0a260721/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: agent-framework-hosting-a2a
+Version: 1.0.0a260721
+Summary: A2A conversion helpers for app-owned Agent Framework hosting.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: a2a-sdk>=1.0.0,<2
+Requires-Dist: agent-framework-core>=1.11.0,<2
+Requires-Dist: agent-framework-hosting==1.0.0a260721
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# agent-framework-hosting-a2a
+
+A2A conversion helpers for app-owned Agent Framework hosting.
+
+The package deliberately does not choose a web framework or wrap the A2A SDK
+server lifecycle. It provides two conversion functions:
+
+- `a2a_to_run(...)` converts a native A2A `Message` into Agent Framework run
+  arguments.
+- `a2a_from_run(...)` converts an `AgentResponse`, `Message`, or streaming
+  `AgentResponseUpdate` into native A2A `Part` values.
+
+Application code keeps ownership of the A2A SDK's `AgentExecutor`,
+`RequestContext`, `TaskUpdater`, event queue, task store, routes, task state,
+artifact IDs, authentication, and deployment.
+
+`a2a_from_run(...)` preserves content-level metadata on each returned part and
+flattens completed responses in message order. The application decides how to
+group those parts into A2A messages or artifacts and owns their message-level
+metadata and boundaries.
+
+```python
+run = a2a_to_run(context.message)
+session_id = f"a2a:{context.tenant}:{context.context_id}"
+session = await state.get_or_create_session(session_id)
+result = await agent.run(
+    run["messages"],
+    session=session,
+    options=run["options"],
+)
+await state.set_session(session_id, session)
+parts = a2a_from_run(result)
+
+# Native A2A SDK application code publishes `parts` with TaskUpdater.
+```
+
+The surrounding A2A application may use Starlette, FastAPI, another ASGI
+framework, or the SDK's own application builders. These helpers do not care.
+

agent_framework_hosting_a2a-1.0.0a260721/README.md

@@ -0,0 +1,38 @@
+# agent-framework-hosting-a2a
+
+A2A conversion helpers for app-owned Agent Framework hosting.
+
+The package deliberately does not choose a web framework or wrap the A2A SDK
+server lifecycle. It provides two conversion functions:
+
+- `a2a_to_run(...)` converts a native A2A `Message` into Agent Framework run
+  arguments.
+- `a2a_from_run(...)` converts an `AgentResponse`, `Message`, or streaming
+  `AgentResponseUpdate` into native A2A `Part` values.
+
+Application code keeps ownership of the A2A SDK's `AgentExecutor`,
+`RequestContext`, `TaskUpdater`, event queue, task store, routes, task state,
+artifact IDs, authentication, and deployment.
+
+`a2a_from_run(...)` preserves content-level metadata on each returned part and
+flattens completed responses in message order. The application decides how to
+group those parts into A2A messages or artifacts and owns their message-level
+metadata and boundaries.
+
+```python
+run = a2a_to_run(context.message)
+session_id = f"a2a:{context.tenant}:{context.context_id}"
+session = await state.get_or_create_session(session_id)
+result = await agent.run(
+    run["messages"],
+    session=session,
+    options=run["options"],
+)
+await state.set_session(session_id, session)
+parts = a2a_from_run(result)
+
+# Native A2A SDK application code publishes `parts` with TaskUpdater.
+```
+
+The surrounding A2A application may use Starlette, FastAPI, another ASGI
+framework, or the SDK's own application builders. These helpers do not care.

agent_framework_hosting_a2a-1.0.0a260721/agent_framework_hosting_a2a/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""A2A conversion helpers for app-owned Agent Framework hosting."""
+
+import importlib.metadata
+
+from ._conversion import a2a_from_run, a2a_to_run
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "a2a_from_run",
+    "a2a_to_run",
+]

agent_framework_hosting_a2a-1.0.0a260721/agent_framework_hosting_a2a/_conversion.py

@@ -0,0 +1,158 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Conversion between native A2A values and Agent Framework run values."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from collections.abc import Sequence
+from typing import Any, cast
+
+from a2a.types import Message as A2AMessage
+from a2a.types import Part
+from agent_framework import AgentResponse, AgentResponseUpdate, ChatOptions, Content, Message
+from agent_framework_hosting import AgentRunArgs
+from google.protobuf.json_format import MessageToDict
+
+logger = logging.getLogger("agent_framework.hosting.a2a")
+
+
+def a2a_to_run(message: A2AMessage, *, stream: bool = False) -> AgentRunArgs:
+    """Convert an A2A message into Agent Framework run arguments.
+
+    A2A text, URL, raw-byte, and structured-data parts become Agent Framework
+    content. The helper does not create sessions, inspect task stores, or
+    interact with an A2A request handler.
+
+    Args:
+        message: Native A2A message to convert.
+
+    Keyword Args:
+        stream: Whether the caller intends to run the agent in streaming mode.
+
+    Returns:
+        Arguments corresponding to ``Agent.run(...)``.
+
+    Raises:
+        ValueError: If the message has no supported content parts.
+    """
+    contents: list[Content] = []
+    for part in message.parts:
+        metadata = MessageToDict(part.metadata) if part.metadata else None
+        match part.WhichOneof("content"):
+            case "text":
+                contents.append(
+                    Content.from_text(
+                        text=part.text,
+                        additional_properties=metadata,
+                        raw_representation=part,
+                    )
+                )
+            case "url":
+                contents.append(
+                    Content.from_uri(
+                        uri=part.url,
+                        media_type=part.media_type or None,
+                        additional_properties=metadata,
+                        raw_representation=part,
+                    )
+                )
+            case "raw":
+                contents.append(
+                    Content.from_data(
+                        data=part.raw,
+                        media_type=part.media_type or "application/octet-stream",
+                        additional_properties=metadata,
+                        raw_representation=part,
+                    )
+                )
+            case "data":
+                contents.append(
+                    Content.from_text(
+                        text=json.dumps(MessageToDict(part.data), separators=(",", ":"), sort_keys=True),
+                        additional_properties=metadata,
+                        raw_representation=part,
+                    )
+                )
+            case unsupported:
+                logger.warning("A2A message part type %s is not supported and was omitted.", unsupported)
+
+    if not contents:
+        raise ValueError("A2A message has no supported text, URL, raw, or data parts to convert to a run.")
+
+    return AgentRunArgs(
+        messages=[
+            Message(
+                "user",
+                contents,
+                message_id=message.message_id or None,
+                additional_properties={"a2a_metadata": MessageToDict(message.metadata)} if message.metadata else None,
+                raw_representation=message,
+            )
+        ],
+        options=cast("ChatOptions[Any]", {}),
+        stream=stream,
+    )
+
+
+def a2a_from_run(result: AgentResponse[Any] | Message | AgentResponseUpdate) -> list[Part]:
+    """Convert Agent Framework output into native A2A parts.
+
+    ``AgentResponse`` values are flattened in message order. User-role
+    messages are omitted. Text, external URI, and inline data content become
+    the corresponding native A2A part types. Content-level metadata is
+    preserved on each part. The caller remains responsible for grouping parts
+    into A2A messages or artifacts, including message boundaries and metadata,
+    and publishing them through ``TaskUpdater`` or an event queue.
+
+    Args:
+        result: A completed response, response message, or streaming update.
+
+    Returns:
+        Native A2A parts ready for an A2A SDK message or artifact.
+
+    Raises:
+        ValueError: If Agent Framework data content contains an invalid data URI.
+    """
+    items: Sequence[Message | AgentResponseUpdate] = result.messages if isinstance(result, AgentResponse) else [result]
+
+    parts: list[Part] = []
+    for item in items:
+        if item.role == "user":
+            continue
+        for content in item.contents:
+            metadata = content.additional_properties or {}
+            match content.type:
+                case "text" if content.text is not None:
+                    parts.append(Part(text=content.text, metadata=metadata))
+                case "uri" if content.uri is not None:
+                    parts.append(
+                        Part(
+                            url=content.uri,
+                            media_type=content.media_type or "",
+                            metadata=metadata,
+                        )
+                    )
+                case "data" if content.uri is not None:
+                    prefix, separator, encoded = content.uri.partition(",")
+                    if not separator or not prefix.startswith("data:") or ";base64" not in prefix:
+                        raise ValueError("Agent Framework data content must contain a base64 data URI.")
+                    try:
+                        raw = base64.b64decode(encoded, validate=True)
+                    except ValueError as exc:
+                        raise ValueError("Agent Framework data content contains invalid base64 data.") from exc
+                    parts.append(
+                        Part(
+                            raw=raw,
+                            media_type=content.media_type or "",
+                            metadata=metadata,
+                        )
+                    )
+                case _:
+                    logger.warning(
+                        "Agent Framework content type %s is not supported by A2A and was omitted.",
+                        content.type,
+                    )
+    return parts

agent_framework_hosting_a2a-1.0.0a260721/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "agent-framework-hosting-a2a"
+description = "A2A conversion helpers for app-owned Agent Framework hosting."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260721"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "a2a-sdk>=1.0.0,<2",
+    "agent-framework-core>=1.11.0,<2",
+    "agent-framework-hosting==1.0.0a260721",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+markers = [
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_hosting_a2a"]
+exclude = ['tests']
+
+[tool.bandit]
+targets = ["agent_framework_hosting_a2a"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_hosting_a2a --cov-report=term-missing:skip-covered tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"