agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

{agentengine_sdk_python-0.8.0.dist-info → agentengine_sdk_python-0.8.2.dist-info}/WHEEL

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

ksadk/a2a/__init__.py

@@ -84,6 +84,7 @@ from ksadk.a2a.routes import A2AConfig, add_a2a_protocol_routes
 from ksadk.a2a.server import A2AProtocolServer
 from ksadk.a2a.space_client import (
     ENV_A2A_ENABLE_PUBLIC_EGRESS,
+    ENV_A2A_SPACE_ID,
     ENV_A2A_SPACE_IDS,
     ERR_PUBLIC_EGRESS_DISABLED,
     A2APlatformTask,
@@ -151,6 +152,7 @@ __all__ = [
     "ENV_A2A_CONTROL_PLANE_URL",
     "ENV_A2A_ENABLE_PUBLIC_EGRESS",
     "ENV_A2A_EVENT_OUTBOX_PATH",
+    "ENV_A2A_SPACE_ID",
     "ENV_A2A_SPACE_IDS",
     "ENV_A2A_TOKEN_DIR",
     "ERR_PUBLIC_EGRESS_DISABLED",

ksadk/a2a/_space_client_events.py

@@ -0,0 +1,381 @@
+"""A2ASpaceClient 的事件投影与持久化实现（纯移动自 ``ksadk.a2a.space_client``，行为不变）。
+
+以 mixin 形式被 :class:`A2ASpaceClient` 继承，依赖宿主提供 ``_event_adapter`` /
+``_event_dispatcher`` / ``_event_sink`` / ``_persisted_wire_events`` / ``_space_id`` /
+``_seq`` / ``_backend`` 及校验辅助方法。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from a2a.types import TaskState
+from google.protobuf.json_format import MessageToDict
+
+from ksadk.a2a.control_plane import DiscoveredAgent
+from ksadk.a2a.event_adapter import A2AEventAdapter
+from ksadk.events.runtime_event import RuntimeEvent
+
+if TYPE_CHECKING:
+    pass
+
+
+def _utc_now() -> str:
+    from ksadk.a2a.space_client import _utc_now as _impl
+
+    return _impl()
+
+
+def _canonical_proto(value: Any) -> dict[str, Any]:
+    from ksadk.a2a.space_client import _canonical_proto as _impl
+
+    return _impl(value)
+
+
+def _present_message_field(value: Any, field_name: str) -> Any | None:
+    from ksadk.a2a.space_client import _present_message_field as _impl
+
+    return _impl(value, field_name)
+
+
+class _SpaceClientEventMixin:
+    async def _project_stream_item(
+        self,
+        platform_task_id: str,
+        item: Any,
+        agent: DiscoveredAgent,
+        *,
+        wire_position: int,
+        operation_instance_id: str,
+    ) -> list[RuntimeEvent]:
+        runtime_events = self._stream_item_to_events(
+            item,
+            agent,
+            wire_position=wire_position,
+            invocation_id=platform_task_id,
+        )
+        platform_events = self._platform_events(
+            item,
+            platform_task_id,
+            operation_instance_id=operation_instance_id,
+            wire_position=wire_position,
+        )
+        if platform_events:
+            await self._event_dispatcher.enqueue(
+                platform_task_id=platform_task_id,
+                events=platform_events,
+            )
+        return await self._persist_events(runtime_events)
+
+    def _platform_events(
+        self,
+        item: Any,
+        platform_task_id: str,
+        *,
+        operation_instance_id: str,
+        wire_position: int,
+    ) -> list[dict[str, Any]]:
+        events: list[dict[str, Any]] = []
+
+        def append_event(
+            kind: str,
+            payload: dict[str, Any],
+            *,
+            status: str | None = None,
+            occurred_at: str | None = None,
+        ) -> None:
+            events.append(
+                self._platform_event(
+                    kind,
+                    payload,
+                    platform_task_id,
+                    operation_instance_id=operation_instance_id,
+                    wire_position=wire_position,
+                    event_ordinal=len(events),
+                    status=status,
+                    occurred_at=occurred_at,
+                )
+            )
+
+        task = _present_message_field(item, "task")
+        if task is None and hasattr(item, "status") and hasattr(item, "id"):
+            task = item
+        status_update = _present_message_field(item, "status_update")
+        artifact_update = _present_message_field(item, "artifact_update")
+        message = _present_message_field(item, "message")
+        if task is not None and getattr(task, "status", None) is not None:
+            payload = _canonical_proto(task.status)
+            state_name = TaskState.Name(task.status.state)
+            append_event(
+                "status",
+                payload,
+                status=state_name.removeprefix("TASK_STATE_").lower(),
+                occurred_at=str(payload.get("timestamp") or _utc_now()),
+            )
+            for artifact in getattr(task, "artifacts", None) or []:
+                append_event(
+                    "artifact",
+                    {
+                        "Artifact": _canonical_proto(artifact),
+                        "Append": False,
+                        "LastChunk": True,
+                    },
+                )
+        if status_update is not None and getattr(status_update, "status", None) is not None:
+            payload = _canonical_proto(status_update.status)
+            state_name = TaskState.Name(status_update.status.state)
+            append_event(
+                "status",
+                payload,
+                status=state_name.removeprefix("TASK_STATE_").lower(),
+                occurred_at=str(payload.get("timestamp") or _utc_now()),
+            )
+        if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
+            append_event(
+                "artifact",
+                {
+                    "Artifact": _canonical_proto(artifact_update.artifact),
+                    "Append": bool(getattr(artifact_update, "append", False)),
+                    "LastChunk": bool(getattr(artifact_update, "last_chunk", False)),
+                },
+            )
+        if message is not None:
+            payload = _canonical_proto(message)
+            append_event("message", payload)
+            append_event(
+                "status",
+                {"state": "TASK_STATE_COMPLETED", "message": payload},
+                status="completed",
+            )
+        return events
+
+    @staticmethod
+    def _platform_event(
+        kind: str,
+        payload: dict[str, Any],
+        platform_task_id: str,
+        *,
+        operation_instance_id: str,
+        wire_position: int,
+        event_ordinal: int,
+        status: str | None = None,
+        occurred_at: str | None = None,
+    ) -> dict[str, Any]:
+        source_id = hashlib.sha256(
+            (
+                f"{platform_task_id}:{operation_instance_id}:{wire_position}:{event_ordinal}:{kind}"
+            ).encode("utf-8")
+        ).hexdigest()
+        event: dict[str, Any] = {
+            "SourceEventId": source_id,
+            "EventKind": kind,
+            "Payload": payload,
+            "OccurredAt": occurred_at or _utc_now(),
+        }
+        if status:
+            event["Status"] = status
+        return event
+
+    async def flush_pending_events(self) -> int:
+        """Deliver all currently queued platform event batches or raise on failure."""
+
+        return await self._event_dispatcher.drain(raise_on_error=True)
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    def _event_ctx(
+        self,
+        agent: DiscoveredAgent,
+        invocation_id: str,
+        *,
+        event_id: str | None = None,
+    ) -> dict[str, Any]:
+        return {
+            "agent_id": agent.agent_id,
+            "user_id": "a2a_space",
+            "session_id": self._space_id,
+            "invocation_id": invocation_id,
+            "seq_id": self._next_seq(),
+            "event_id": event_id,
+        }
+
+    def task_to_event(self, task: Any, agent: DiscoveredAgent) -> RuntimeEvent:
+        return self._event_adapter.task_status_to_event(
+            task.status, **self._event_ctx(agent, invocation_id=str(task.id))
+        )
+
+    def _stream_item_to_events(
+        self,
+        item: Any,
+        agent: DiscoveredAgent,
+        *,
+        wire_position: int = 0,
+        invocation_id: str | None = None,
+    ) -> list[RuntimeEvent]:
+        events: list[RuntimeEvent] = []
+        task = _present_message_field(item, "task")
+        if task is None and hasattr(item, "status") and hasattr(item, "id"):
+            task = item
+        status_update = _present_message_field(item, "status_update")
+        artifact_update = _present_message_field(item, "artifact_update")
+        message = _present_message_field(item, "message")
+        resolved_invocation_id = invocation_id or str(
+            getattr(item, "task_id", None)
+            or getattr(task, "id", "")
+            or getattr(status_update, "task_id", "")
+            or getattr(artifact_update, "task_id", "")
+            or getattr(message, "task_id", "")
+            or ""
+        )
+
+        def ctx(kind: str, value: Any) -> dict[str, Any]:
+            metadata = getattr(value, "metadata", None)
+            native_event_id = ""
+            if metadata is not None:
+                if isinstance(metadata, Mapping):
+                    metadata_dict = dict(metadata)
+                else:
+                    try:
+                        metadata_dict = MessageToDict(metadata, preserving_proto_field_name=True)
+                    except (AttributeError, TypeError, ValueError):
+                        metadata_dict = {}
+                native_event_id = str(
+                    metadata_dict.get("event_id") or metadata_dict.get("ksadk_event_id") or ""
+                )
+            message_id = str(getattr(value, "message_id", "") or "")
+            artifact = getattr(value, "artifact", None)
+            artifact_id = str(
+                getattr(value, "artifact_id", "") or getattr(artifact, "artifact_id", "") or ""
+            )
+            source_id = native_event_id or message_id or artifact_id
+            event_id = uuid.uuid5(
+                uuid.NAMESPACE_URL,
+                f"ksadk:a2a:{resolved_invocation_id}:{wire_position}:{kind}:{source_id}",
+            ).hex
+            return self._event_ctx(agent, invocation_id=resolved_invocation_id, event_id=event_id)
+
+        if task is not None and getattr(task, "status", None) is not None:
+            task_status_message = _present_message_field(task.status, "message")
+            task_status_text = A2AEventAdapter._parts_text(
+                getattr(task_status_message, "parts", None)
+            )
+            task_is_terminal = task.status.state in {
+                TaskState.TASK_STATE_COMPLETED,
+                TaskState.TASK_STATE_FAILED,
+                TaskState.TASK_STATE_CANCELED,
+                TaskState.TASK_STATE_REJECTED,
+            }
+            if not task_is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        task.status,
+                        **ctx("task", task),
+                    )
+                )
+            if task_status_text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        task_status_text,
+                        final=task_is_terminal,
+                        **ctx("task-status-message", task_status_message),
+                    )
+                )
+            if task_is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        task.status,
+                        **ctx("task", task),
+                    )
+                )
+        if status_update is not None and getattr(status_update, "status", None) is not None:
+            status_message = _present_message_field(status_update.status, "message")
+            text = A2AEventAdapter._parts_text(getattr(status_message, "parts", None))
+            terminal_states = {
+                TaskState.TASK_STATE_COMPLETED,
+                TaskState.TASK_STATE_FAILED,
+                TaskState.TASK_STATE_CANCELED,
+                TaskState.TASK_STATE_REJECTED,
+            }
+            is_terminal = status_update.status.state in terminal_states
+            if not is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        status_update.status, **ctx("status", status_update)
+                    )
+                )
+            if text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        text,
+                        final=is_terminal,
+                        **ctx("status-message", status_message),
+                    )
+                )
+            if is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        status_update.status, **ctx("status", status_update)
+                    )
+                )
+        if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
+            artifact = artifact_update.artifact
+            events.append(
+                self._event_adapter.artifact_to_event(artifact, **ctx("artifact", artifact_update))
+            )
+            artifact_text = A2AEventAdapter._parts_text(getattr(artifact, "parts", None))
+            if artifact_text and str(getattr(artifact, "name", "") or "") == "response":
+                events.append(
+                    self._event_adapter.message_to_event(
+                        artifact_text,
+                        final=bool(getattr(artifact_update, "last_chunk", False)),
+                        **ctx("artifact-text", artifact_update),
+                    )
+                )
+        if message is not None:
+            text = A2AEventAdapter._parts_text(getattr(message, "parts", None))
+            if text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        text, final=True, **ctx("message", message)
+                    )
+                )
+        return events
+
+    async def _persist_events(self, events: list[RuntimeEvent]) -> list[RuntimeEvent]:
+        existing_ids = set(self._persisted_wire_events)
+        if self._event_sink is not None:
+            list_events = getattr(self._event_sink, "list", None)
+            if callable(list_events) and events:
+                session_id = str(events[0].source.metadata.get("session_id") or self._space_id)
+                persisted_before = await list_events(session_id)
+                existing_ids.update(event.event_id for event in persisted_before)
+        fresh = [event for event in events if event.event_id not in existing_ids]
+        if not fresh:
+            return []
+        if self._event_sink is not None:
+            append = getattr(self._event_sink, "append", None)
+            if append is None:
+                raise TypeError("event_sink must provide async append(events)")
+            # RuntimeEventStore.append(session_id, events) requires session_id;
+            # fall back to single-arg call for non-canonical sinks.
+            session_id_for_persist = (
+                str(events[0].source.metadata.get("session_id") or self._space_id)
+                if events
+                else self._space_id
+            )
+            try:
+                persisted = await append(session_id_for_persist, fresh)
+            except TypeError:
+                persisted = await append(fresh)
+            if persisted is not None:
+                fresh = list(persisted)
+        self._persisted_wire_events.update(event.event_id for event in fresh)
+        return fresh
+
+
+__all__ = ["_SpaceClientEventMixin"]

ksadk/a2a/bootstrap.py

@@ -241,7 +241,6 @@ class AgentEngineA2ABootstrap:
         self,
         app: FastAPI,
         *,
-        runner: Any,
         runtime_adapter: RuntimeAdapter,
         runtime_type: str,
     ) -> Any | None:
@@ -276,7 +275,6 @@ class AgentEngineA2ABootstrap:
         )
         self._server = add_a2a_protocol_routes(
             app,
-            runner,
             config,
             task_adapter=task_adapter,
             task_store=_require(self._task_store, "task_store"),

ksadk/a2a/card.py

@@ -1,117 +1,12 @@
-"""A2A AgentCard 构造 (goal-05,wire 1.0)。
+"""Compatibility exports for the lightweight shared AgentCard builder."""
 
-契约(`a2a-center-productization-2026-07.md` §2.1):
-- AgentCard 使用 ``supportedInterfaces[]``,每项 ``url`` / ``protocolBinding`` /
-  ``protocolVersion: "1.0"``;**不用顶层 ``url``,不提供 0.3 fallback,不挂
-  ``/.well-known/agent.json`` 旧路径**。
-- 我方托管 Agent 7 月优先暴露 ``JSONRPC``,同时挂 SDK 已提供的 ``HTTP+JSON`` 路由。
-- a2a-sdk 1.1.0 的 wire 对象是 protobuf(``a2a_pb2``),非 pydantic。
-"""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from a2a.types import (
-    AgentCapabilities,
-    AgentCard,
-    AgentInterface,
-    AgentSkill,
+from ksadk.a2a_card import (
+    A2A_PROTOCOL_VERSION,
+    JSONRPC_PATH,
+    REST_PATH_PREFIX,
+    build_agent_card,
 )
 
-#: wire 协议版本(契约 §2.1 固定 1.0)。
-A2A_PROTOCOL_VERSION = "1.0"
-#: 托管 Agent 的 A2A 路由路径(契约 §3.3:/a2a/jsonrpc 与 /a2a/v1/*)。
-JSONRPC_PATH = "/a2a/jsonrpc"
-REST_PATH_PREFIX = "/a2a/v1"
-
-_DEFAULT_IO_MODES = ["text/plain"]
-
-
-def build_agent_card(
-    *,
-    name: str,
-    base_url: str,
-    description: str = "",
-    version: str = "1.0.0",
-    skills: Sequence[str | AgentSkill] | None = None,
-    streaming: bool = True,
-    provider: dict[str, str] | None = None,
-) -> AgentCard:
-    """构造符合 wire 1.0 的 AgentCard(supportedInterfaces)。
-
-    参数:
-        name: Agent 名称。
-        base_url: 该 Agent 对外宣告的基础地址(各 interface url 由此拼出)。
-        description: 描述。
-        version: 业务版本。
-        skills: 标准 ``AgentSkill`` 列表，或本地配置使用的技能 id 列表(空则给 general)。
-        streaming: 是否声明 streaming 能力。
-        provider: 可选 provider 信息(如 {"organization": ..., "url": ...})。
-    """
-    base = base_url.rstrip("/")
-    supported_interfaces = [
-        AgentInterface(
-            url=f"{base}{JSONRPC_PATH}",
-            protocol_binding="JSONRPC",
-            protocol_version=A2A_PROTOCOL_VERSION,
-        ),
-        AgentInterface(
-            url=f"{base}{REST_PATH_PREFIX}",
-            protocol_binding="HTTP+JSON",
-            protocol_version=A2A_PROTOCOL_VERSION,
-        ),
-    ]
-
-    card_kwargs: dict = {
-        "name": name,
-        "description": description or f"{name} agent powered by ksadk",
-        "version": version,
-        "supported_interfaces": supported_interfaces,
-        "capabilities": AgentCapabilities(streaming=streaming, push_notifications=False),
-        "default_input_modes": list(_DEFAULT_IO_MODES),
-        "default_output_modes": list(_DEFAULT_IO_MODES),
-        "skills": _build_skills(skills),
-    }
-    if provider:
-        from a2a.types import AgentProvider
-
-        card_kwargs["provider"] = AgentProvider(
-            organization=provider.get("organization", ""),
-            url=provider.get("url", ""),
-        )
-    return AgentCard(**card_kwargs)
-
-
-def _build_skills(skills: Sequence[str | AgentSkill] | None) -> list[AgentSkill]:
-    if not skills:
-        return [
-            AgentSkill(
-                id="general",
-                name="General",
-                description="General purpose agent powered by ksadk",
-                tags=["general"],
-            )
-        ]
-    result: list[AgentSkill] = []
-    for skill in skills:
-        if isinstance(skill, AgentSkill):
-            result.append(skill)
-            continue
-        if not isinstance(skill, str) or not skill.strip():
-            raise TypeError("AgentCard skills must be non-empty strings or AgentSkill objects")
-        skill_id = skill.strip()
-        result.append(
-            AgentSkill(
-                id=skill_id,
-                name=skill_id.replace("_", " ").title(),
-                description=f"Skill: {skill_id}",
-                tags=[skill_id],
-            )
-        )
-    return result
-
-
 __all__ = [
     "A2A_PROTOCOL_VERSION",
     "JSONRPC_PATH",