spakky-a2a 6.10.0__tar.gz

spakky_a2a-6.10.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.3
+Name: spakky-a2a
+Version: 6.10.0
+Summary: A2A (Agent2Agent) protocol server plugin for Spakky framework
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+License: MIT
+Requires-Dist: a2a-sdk[http-server]>=1.1.0
+Requires-Dist: grpcio>=1.68.0
+Requires-Dist: pydantic>=2.4
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: spakky>=6.10.0
+Requires-Dist: spakky-agent>=6.10.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# spakky-a2a
+
+A2A (Agent2Agent) protocol server plugin for the Spakky framework.
+
+## Remote teammate delegation
+
+`A2AAgentDelegate` implements the core `IAgentDelegate` port for teammates whose
+`AgentExecutionSpec.teammates` entry points at a remote AgentCard URL. The core
+agent runner exposes each teammate as a model-callable delegation tool named
+`teammate.<name>.delegate`; local teammate pods run in-process, while remote
+teammates use the official `a2a-sdk` client.
+
+```python
+from spakky.agent import Agent, AgentExecutionSpec, AgentTeammate
+from spakky.plugins.a2a import A2AAgentDelegate
+
+
+@Agent(
+    spec=AgentExecutionSpec(
+        name="orchestrator",
+        teammates=(
+            AgentTeammate(
+                name="researcher",
+                card_url="https://agents.example.com/.well-known/agent-card.json",
+            ),
+        ),
+    )
+)
+class Orchestrator:
+    def __init__(self, delegate: A2AAgentDelegate) -> None:
+        self._delegate = delegate
+```
+
+Remote delegation sends `message/send` through the SDK client, tracks the remote
+task stream, and maps child task/message/artifact updates back into Spakky's
+protocol-neutral event stream with the parent run id preserved.
+
+## REST HTTP+JSON transport
+
+`build_a2a_rest_app()` builds a mountable Starlette app for the official A2A
+HTTP+JSON binding. The transport reuses the same AgentCard derivation,
+`TaskStore`, `SpakkyAgentExecutor`, and neutral agent-event projection used by
+the JSON-RPC and gRPC transports.
+
+```python
+from spakky.plugins.a2a.rest_transport import build_a2a_rest_app
+
+app = build_a2a_rest_app(
+    assistant_agent,
+    base_url="https://agents.example.com/a2a",
+    version="1.0.0",
+)
+```
+
+The SDK route names differ from JSON-RPC method strings:
+
+| A2A operation | REST route |
+|---------------|------------|
+| `message/send` | `POST /message:send` |
+| `message/stream` | `POST /message:stream` |
+| `tasks/get` | `GET /tasks/{id}` |
+| `tasks/cancel` | `POST /tasks/{id}:cancel` |
+| `tasks/subscribe` | `GET /tasks/{id}:subscribe` or `POST /tasks/{id}:subscribe` |
+
+REST request and response bodies use the A2A SDK protobuf JSON encoding. For
+example, send a user message with `{"message":{"role":"ROLE_USER","messageId":"m1","parts":[{"text":"hi"}]}}`.
+
+## HITL and auth interrupts
+
+`SpakkyAgentExecutor` consumes the core `AgentRunner.run_events()` stream. Approval
+and auth pauses arrive as protocol-neutral `RunPausedEvent` items rather than as
+successful `RunFinishedEvent` terminals. The A2A projector maps
+`reason=approval_required` to `TASK_STATE_INPUT_REQUIRED` and includes the
+approval id plus allowed decisions in a data part. It maps `reason=auth_required`
+to `TASK_STATE_AUTH_REQUIRED`, so auth-required is reachable without inspecting
+durable `state.reason` after the run stream drains.
+
+## gRPC transport
+
+`build_a2a_grpc_handler()` builds a `grpc.GenericRpcHandler` for the official
+`lf.a2a.v1.A2AService` descriptor. The transport exposes:
+
+- `SendMessage`
+- `SendStreamingMessage`
+- `GetTask`
+- `CancelTask`
+
+The gRPC handler reuses the same AgentCard derivation, `TaskStore`,
+`SpakkyAgentExecutor`, and neutral agent-event projection used by the JSON-RPC
+transport. Add the handler to a `spakky-grpc` `GrpcServerSpec` or another
+`grpc.aio.Server`, then call `/lf.a2a.v1.A2AService/<Method>` with the protobuf
+message classes provided by `a2a-sdk`.

spakky_a2a-6.10.0/README.md

@@ -0,0 +1,92 @@
+# spakky-a2a
+
+A2A (Agent2Agent) protocol server plugin for the Spakky framework.
+
+## Remote teammate delegation
+
+`A2AAgentDelegate` implements the core `IAgentDelegate` port for teammates whose
+`AgentExecutionSpec.teammates` entry points at a remote AgentCard URL. The core
+agent runner exposes each teammate as a model-callable delegation tool named
+`teammate.<name>.delegate`; local teammate pods run in-process, while remote
+teammates use the official `a2a-sdk` client.
+
+```python
+from spakky.agent import Agent, AgentExecutionSpec, AgentTeammate
+from spakky.plugins.a2a import A2AAgentDelegate
+
+
+@Agent(
+    spec=AgentExecutionSpec(
+        name="orchestrator",
+        teammates=(
+            AgentTeammate(
+                name="researcher",
+                card_url="https://agents.example.com/.well-known/agent-card.json",
+            ),
+        ),
+    )
+)
+class Orchestrator:
+    def __init__(self, delegate: A2AAgentDelegate) -> None:
+        self._delegate = delegate
+```
+
+Remote delegation sends `message/send` through the SDK client, tracks the remote
+task stream, and maps child task/message/artifact updates back into Spakky's
+protocol-neutral event stream with the parent run id preserved.
+
+## REST HTTP+JSON transport
+
+`build_a2a_rest_app()` builds a mountable Starlette app for the official A2A
+HTTP+JSON binding. The transport reuses the same AgentCard derivation,
+`TaskStore`, `SpakkyAgentExecutor`, and neutral agent-event projection used by
+the JSON-RPC and gRPC transports.
+
+```python
+from spakky.plugins.a2a.rest_transport import build_a2a_rest_app
+
+app = build_a2a_rest_app(
+    assistant_agent,
+    base_url="https://agents.example.com/a2a",
+    version="1.0.0",
+)
+```
+
+The SDK route names differ from JSON-RPC method strings:
+
+| A2A operation | REST route |
+|---------------|------------|
+| `message/send` | `POST /message:send` |
+| `message/stream` | `POST /message:stream` |
+| `tasks/get` | `GET /tasks/{id}` |
+| `tasks/cancel` | `POST /tasks/{id}:cancel` |
+| `tasks/subscribe` | `GET /tasks/{id}:subscribe` or `POST /tasks/{id}:subscribe` |
+
+REST request and response bodies use the A2A SDK protobuf JSON encoding. For
+example, send a user message with `{"message":{"role":"ROLE_USER","messageId":"m1","parts":[{"text":"hi"}]}}`.
+
+## HITL and auth interrupts
+
+`SpakkyAgentExecutor` consumes the core `AgentRunner.run_events()` stream. Approval
+and auth pauses arrive as protocol-neutral `RunPausedEvent` items rather than as
+successful `RunFinishedEvent` terminals. The A2A projector maps
+`reason=approval_required` to `TASK_STATE_INPUT_REQUIRED` and includes the
+approval id plus allowed decisions in a data part. It maps `reason=auth_required`
+to `TASK_STATE_AUTH_REQUIRED`, so auth-required is reachable without inspecting
+durable `state.reason` after the run stream drains.
+
+## gRPC transport
+
+`build_a2a_grpc_handler()` builds a `grpc.GenericRpcHandler` for the official
+`lf.a2a.v1.A2AService` descriptor. The transport exposes:
+
+- `SendMessage`
+- `SendStreamingMessage`
+- `GetTask`
+- `CancelTask`
+
+The gRPC handler reuses the same AgentCard derivation, `TaskStore`,
+`SpakkyAgentExecutor`, and neutral agent-event projection used by the JSON-RPC
+transport. Add the handler to a `spakky-grpc` `GrpcServerSpec` or another
+`grpc.aio.Server`, then call `/lf.a2a.v1.A2AService/<Method>` with the protobuf
+message classes provided by `a2a-sdk`.

spakky_a2a-6.10.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "spakky-a2a"
+version = "6.10.0"
+description = "A2A (Agent2Agent) protocol server plugin for Spakky framework"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+dependencies = [
+    "a2a-sdk[http-server]>=1.1.0",
+    "grpcio>=1.68.0",
+    "pydantic>=2.4",
+    "pydantic-settings>=2.13.1",
+    "spakky>=6.10.0",
+    "spakky-agent>=6.10.0",
+]
+
+[project.entry-points."spakky.plugins"]
+spakky-a2a = "spakky.plugins.a2a.main:initialize"
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=1.3.0",
+    "pytest-integration-mark>=0.2.0",
+    "httpx>=0.28.0",
+    "spakky-grpc>=6.9.1",
+    "types-grpcio>=1.0.0.20260614",
+    "types-protobuf>=7.34.1.20260518",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.plugins.a2a"
+
+[tool.pyrefly]
+python-version = "3.12"
+search_path = ["src", "."]
+project_excludes = ["**/__pycache__", "**/*.pyc"]
+
+[tool.ruff]
+builtins = ["_"]
+cache-dir = "~/.cache/ruff"
+
+[tool.pytest.ini_options]
+pythonpath = "src/spakky/plugins/a2a"
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+markers = ["known_issue(reason): 알려진 버그"]
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=load
+    -p no:warnings
+    -n auto
+    --spec
+    --with-integration
+"""
+spec_test_format = "{result} {docstring_summary}"
+
+[tool.coverage.run]
+include = ["src/spakky/plugins/a2a/**/*.py"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2
+fail_under = 100
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "@(typing\\.)?overload",
+    "\\.\\.\\.",
+    "pass",
+]
+
+[tool.uv.sources]
+spakky = { workspace = true }
+spakky-agent = { workspace = true }
+spakky-grpc = { workspace = true }

spakky_a2a-6.10.0/src/spakky/plugins/a2a/__init__.py

@@ -0,0 +1,31 @@
+"""A2A (Agent2Agent) protocol server plugin for the Spakky framework.
+
+Exposes a spakky ``@Agent`` as an A2A protocol server: an AgentCard is derived
+from the agent's spec, tools, and teammates, and JSON-RPC/HTTP plus SSE routes
+are mounted from the official ``a2a-sdk``. Marker, config, and plugin identifier
+are re-exported; transport types live under ``a2a-sdk``.
+"""
+
+from spakky.core.application.plugin import Plugin
+
+from spakky.plugins.a2a.config import (
+    SPAKKY_A2A_CONFIG_ENV_PREFIX,
+    A2AConfig,
+)
+from spakky.plugins.a2a.client import A2ARemoteAgentClient, RemoteA2AMessage
+from spakky.plugins.a2a.delegation import A2AAgentDelegate, A2AStreamEventMapper
+from spakky.plugins.a2a.stereotypes.a2a_agent_server import A2AAgentServer
+
+PLUGIN_NAME = Plugin(name="spakky-a2a")
+"""Plugin identifier for the A2A integration."""
+
+__all__ = [
+    "PLUGIN_NAME",
+    "SPAKKY_A2A_CONFIG_ENV_PREFIX",
+    "A2AConfig",
+    "A2AAgentDelegate",
+    "A2ARemoteAgentClient",
+    "A2AStreamEventMapper",
+    "A2AAgentServer",
+    "RemoteA2AMessage",
+]

spakky_a2a-6.10.0/src/spakky/plugins/a2a/card/__init__.py

@@ -0,0 +1 @@
+"""A2A plugin card package."""

spakky_a2a-6.10.0/src/spakky/plugins/a2a/card/derivation.py

@@ -0,0 +1,123 @@
+"""AgentCard derivation from an @Agent declaration.
+
+Maps a spakky ``@Agent`` spec, its discovered tool catalog, and its declared
+teammates onto an a2a-sdk ``AgentCard``. The a2a-sdk 1.x ``AgentCard`` is a
+protobuf message (``a2a_pb2``) whose transport endpoint is expressed as an
+``AgentInterface`` entry rather than a flat ``url`` field, so the base URL is
+advertised through ``supported_interfaces``.
+"""
+
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+)
+from a2a.utils import TransportProtocol
+from spakky.agent.execution import Agent, AgentTeammate, StreamingExposureMode
+from spakky.agent.tooling import AgentToolDescriptor, AgentToolMetadata
+
+JSON_CONTENT_TYPE = "application/json"
+"""Tool skills advertise JSON-shaped input and output payloads."""
+
+TEXT_CONTENT_TYPE = "text/plain"
+"""The card's default conversational input and output content type."""
+
+TEAMMATE_DELEGATION_TAG = "delegation"
+"""Tag attached to a skill derived from a declared teammate."""
+
+
+class AgentCardFactory:
+    """Builds an a2a-sdk ``AgentCard`` from an @Agent Pod declaration."""
+
+    def build(
+        self,
+        agent: Agent,
+        base_url: str,
+        version: str,
+        protocol: TransportProtocol = TransportProtocol.JSONRPC,
+    ) -> AgentCard:
+        """Derive an AgentCard from an @Agent spec, tools, and teammates.
+
+        Args:
+            agent: The @Agent Pod metadata carrying spec and tool catalog.
+            base_url: Transport endpoint advertised on the card interface.
+            version: Semantic version advertised on the card.
+            protocol: A2A transport protocol advertised for ``base_url``.
+
+        Returns:
+            A protobuf ``AgentCard`` ready to publish on the well-known route.
+        """
+        spec = agent.spec
+        name = spec.name or agent.target.__name__
+        description = spec.objective or spec.instructions or name
+        # A guarded final-only profile suppresses incremental streaming exposure.
+        streaming = (
+            spec.streaming_exposure_mode
+            is not StreamingExposureMode.NO_STREAM_UNTIL_FINAL_GUARDED
+        )
+        tool_skills = [
+            self._tool_skill(descriptor)
+            for descriptor in agent.tool_catalog.descriptors
+            if not self._is_teammate_delegation_tool(descriptor)
+        ]
+        teammate_skills = [
+            self._teammate_skill(teammate) for teammate in spec.teammates
+        ]
+        return AgentCard(
+            name=name,
+            description=description,
+            version=version,
+            supported_interfaces=[
+                AgentInterface(
+                    url=base_url,
+                    protocol_binding=protocol.value,
+                )
+            ],
+            capabilities=AgentCapabilities(
+                streaming=streaming,
+                push_notifications=False,
+            ),
+            default_input_modes=[TEXT_CONTENT_TYPE],
+            default_output_modes=[TEXT_CONTENT_TYPE],
+            skills=[*tool_skills, *teammate_skills],
+        )
+
+    @staticmethod
+    def _tool_skill(descriptor: AgentToolDescriptor) -> AgentSkill:
+        """Project one tool descriptor onto an AgentSkill."""
+        return AgentSkill(
+            id=descriptor.identity.key,
+            name=descriptor.identity.name,
+            description=descriptor.description or descriptor.identity.name,
+            tags=AgentCardFactory._skill_tags(descriptor.metadata),
+            input_modes=[JSON_CONTENT_TYPE],
+            output_modes=[JSON_CONTENT_TYPE],
+        )
+
+    @staticmethod
+    def _teammate_skill(teammate: AgentTeammate) -> AgentSkill:
+        """Project one declared teammate onto a delegation AgentSkill."""
+        return AgentSkill(
+            id=f"teammate:{teammate.name}",
+            name=teammate.name,
+            description="Delegated teammate",
+            tags=[TEAMMATE_DELEGATION_TAG],
+        )
+
+    @staticmethod
+    def _is_teammate_delegation_tool(descriptor: AgentToolDescriptor) -> bool:
+        """Return whether a tool descriptor is the runner's synthetic teammate tool."""
+        return descriptor.schema.name.startswith(
+            "teammate."
+        ) and descriptor.schema.name.endswith(".delegate")
+
+    @staticmethod
+    def _skill_tags(metadata: AgentToolMetadata) -> list[str]:
+        """Derive deterministic skill tags from typed tool metadata."""
+        return [
+            *(permission.name for permission in metadata.permissions),
+            metadata.data_access.value,
+            metadata.externality.value,
+            metadata.idempotency.value,
+        ]

spakky_a2a-6.10.0/src/spakky/plugins/a2a/client.py

@@ -0,0 +1,127 @@
+"""Official a2a-sdk client wrapper for remote teammate calls."""
+
+from collections.abc import AsyncGenerator
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass, field
+from uuid import uuid4
+from urllib.parse import urlsplit
+
+import httpx
+from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
+from a2a.types import (
+    AgentCard,
+    GetTaskRequest,
+    Message,
+    Part,
+    Role,
+    SendMessageConfiguration,
+    SendMessageRequest,
+    StreamResponse,
+    Task,
+)
+
+DEFAULT_AGENT_CARD_PATH = "/.well-known/agent-card.json"
+"""Default A2A well-known AgentCard route."""
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteA2AMessage:
+    """Message envelope sent to a remote A2A teammate."""
+
+    text: str
+    task_id: str | None = None
+    context_id: str | None = None
+    message_id: str = field(default_factory=lambda: f"message-{uuid4()}")
+
+
+class A2ARemoteAgentClient:
+    """Small wrapper around the official a2a-sdk client and types."""
+
+    _httpx_client: httpx.AsyncClient | None
+    _config: ClientConfig
+    _factory: ClientFactory
+
+    def __init__(
+        self,
+        *,
+        httpx_client: httpx.AsyncClient | None = None,
+        config: ClientConfig | None = None,
+    ) -> None:
+        self._httpx_client = httpx_client
+        self._config = config or ClientConfig(httpx_client=httpx_client)
+        self._factory = ClientFactory(self._config)
+
+    async def resolve_card(self, card_url: str) -> AgentCard:
+        """Fetch a remote AgentCard with the SDK resolver."""
+        parts = urlsplit(card_url)
+        base_url = f"{parts.scheme}://{parts.netloc}"
+        path = parts.path or DEFAULT_AGENT_CARD_PATH
+        async with self._http_client() as client:
+            resolver = A2ACardResolver(client, base_url=base_url)
+            return await resolver.get_agent_card(path)
+
+    async def send_message(
+        self,
+        card_url: str,
+        message: RemoteA2AMessage,
+    ) -> tuple[StreamResponse, ...]:
+        """Send a message and collect the SDK response stream."""
+        return tuple([event async for event in self.stream_message(card_url, message)])
+
+    async def stream_message(
+        self,
+        card_url: str,
+        message: RemoteA2AMessage,
+    ) -> AsyncGenerator[StreamResponse, None]:
+        """Send a message and yield remote task/message updates as they arrive."""
+        card = await self.resolve_card(card_url)
+        client = self._factory.create(card)
+        request = SendMessageRequest(
+            message=Message(
+                role=Role.ROLE_USER,
+                message_id=message.message_id,
+                task_id=message.task_id or "",
+                context_id=message.context_id or "",
+                parts=[Part(text=message.text)],
+            ),
+            configuration=SendMessageConfiguration(return_immediately=False),
+        )
+        try:
+            async for event in client.send_message(request):
+                yield event
+        finally:
+            await client.close()
+
+    async def get_task(self, card_url: str, task_id: str) -> Task:
+        """Fetch a remote A2A task by id using the SDK client."""
+        card = await self.resolve_card(card_url)
+        client = self._factory.create(card)
+        try:
+            return await client.get_task(GetTaskRequest(id=task_id))
+        finally:
+            await client.close()
+
+    def _http_client(self) -> AbstractAsyncContextManager[httpx.AsyncClient]:
+        if self._httpx_client is not None:
+            return _BorrowedAsyncClient(self._httpx_client)
+        return httpx.AsyncClient()
+
+
+class _BorrowedAsyncClient:
+    """Async context manager that leaves caller-owned httpx clients open."""
+
+    _client: httpx.AsyncClient
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def __aenter__(self) -> httpx.AsyncClient:
+        return self._client
+
+    async def __aexit__(
+        self,
+        exc_type: object,
+        exc: object,
+        traceback: object,
+    ) -> None:
+        return None

spakky_a2a-6.10.0/src/spakky/plugins/a2a/config.py

@@ -0,0 +1,35 @@
+"""A2A plugin configuration."""
+
+from typing import ClassVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from spakky.core.stereotype.configuration import Configuration
+
+SPAKKY_A2A_CONFIG_ENV_PREFIX = "SPAKKY_A2A_"
+"""Environment prefix for A2A plugin settings."""
+
+DEFAULT_A2A_BASE_URL = "http://localhost:8000"
+"""Fallback base URL advertised on a derived AgentCard interface."""
+
+DEFAULT_A2A_VERSION = "1.0.0"
+"""Fallback semantic version advertised on a derived AgentCard."""
+
+
+@Configuration()
+class A2AConfig(BaseSettings):
+    """Configuration for the A2A protocol server integration."""
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix=SPAKKY_A2A_CONFIG_ENV_PREFIX,
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+    )
+
+    default_base_url: str = DEFAULT_A2A_BASE_URL
+    """Base URL advertised on a derived AgentCard transport interface."""
+
+    default_version: str = DEFAULT_A2A_VERSION
+    """Semantic version advertised on a derived AgentCard."""
+
+    def __init__(self) -> None:
+        super().__init__()