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

ksadk/a2a/control_plane.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import binascii
 import errno
@@ -9,6 +10,7 @@ import json
 import os
 import stat
 import time
+import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -19,6 +21,7 @@ from a2a.types import AgentCard
 from google.protobuf.json_format import ParseDict, ParseError
 
 from ksadk.a2a.ids import require_a2a_resource_id
+from ksadk.common.kop_client import KOPClient, KOPError
 
 ENV_A2A_CONTROL_PLANE_URL = "KSADK_A2A_CONTROL_PLANE_URL"
 ENV_A2A_TOKEN_DIR = "KSADK_A2A_TOKEN_DIR"
@@ -581,6 +584,232 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
         return self._token_provider.get_token(AUDIENCE_GATEWAY)
 
 
+class A2AAgentCardClient(A2AControlPlane):
+    """Card-driven control-plane client for hosted/external A2A discovery.
+
+    发现面通过 KOP 调 server 对外 Action (ListAToASpaceAgents) 拿到 space 内
+    每个 agent 的完整投影后 AgentCard（含 callable url）；调用面直接用
+    card.url 发 A2A 请求，不回连 server 做 permit/credential。
+    runtime 只需一个 service_url（KOP 对外 API，默认 aicp.api.ksyun.com），
+    与 ksadk/skills 同款；card.url 由 server 投影，runtime 不需要知道 gateway 域名。
+
+    KOP 鉴权（AICP AK/SK 签名）复用 ksadk.common.kop_client.KOPClient，
+    和 skill/mcp 共用同一公共层。
+    """
+
+    def __init__(
+        self,
+        service_url: str,
+        *,
+        service_token: str = "",
+        httpx_client: httpx.AsyncClient | None = None,
+        timeout: float = 15.0,
+    ) -> None:
+        if not service_url:
+            raise ValueError("A2AAgentCardClient requires a non-empty service_url")
+        self._service_url = service_url.rstrip("/")
+        self._service_token = service_token
+        self._client = httpx_client
+        self._timeout = timeout
+        self._cards_by_agent: dict[str, tuple[AgentCard, str, str]] = {}
+        self._kop = KOPClient(base_url=service_url, service_token=service_token, timeout=timeout)
+
+    async def _post_action(self, action: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            return await asyncio.to_thread(self._kop.post_action, action, payload)
+        except KOPError as exc:
+            raise A2AControlPlaneError(
+                code=exc.code,
+                message=exc.message,
+                error_code=f"KOP_{exc.code}",
+                retryable=exc.code >= 500,
+                action=action,  # type: ignore[arg-type]
+            ) from exc
+
+    async def list_space_agents(
+        self,
+        space_id: str,
+        *,
+        prompt: str | None = None,
+        skill_id: str | None = None,
+        include_blocked: bool = False,
+        if_none_match: str | None = None,
+        cursor: str | None = None,
+        page_size: int = 50,
+    ) -> SpaceAgentPage:
+        _ = (prompt, skill_id, if_none_match)
+        payload: dict[str, Any] = {
+            "A2ASpaceId": space_id,
+            "Status": "available" if not include_blocked else "",
+            "PageSize": page_size,
+        }
+        if cursor:
+            payload["PageNumber"] = int(cursor) if str(cursor).isdigit() else 1
+        data = await self._post_action("ListAToASpaceAgents", payload)
+        agents: list[DiscoveredAgent] = []
+        for item in data.get("Agents") or []:
+            if not isinstance(item, dict):
+                continue
+            a2a_agent_id = str(item.get("A2AAgentId") or "").strip()
+            if not a2a_agent_id:
+                continue
+            # server 用纯 uuid,ksadk 内部要求 a2a-agent- 前缀;补前缀适配契约。
+            if not a2a_agent_id.startswith("a2a-agent-"):
+                a2a_agent_id = f"a2a-agent-{a2a_agent_id}"
+            invocation_status = str(item.get("InvocationStatus") or "")
+            if invocation_status and invocation_status != "available":
+                continue
+            card_payload = item.get("AgentCard")
+            if not isinstance(card_payload, dict):
+                continue
+            try:
+                card = _agent_card_from_wire(card_payload)
+            except A2AControlPlaneError:
+                continue
+            sha = str(item.get("CardSha256") or "")
+            version_id = str(item.get("VersionId") or "") or sha
+            if version_id and not version_id.startswith("a2a-version-"):
+                version_id = f"a2a-version-{version_id}"
+            source = str(item.get("Source") or "hosted")
+            self._cards_by_agent[a2a_agent_id] = (card, sha, version_id)
+            agents.append(
+                DiscoveredAgent(
+                    agent_id=a2a_agent_id,
+                    version_id=version_id,
+                    source=source if source in {"hosted", "external"} else "hosted",
+                    agent_card=card,
+                    card_sha256=sha,
+                    callable=True,
+                    route_kind="hosted_gateway" if source == "hosted" else "external_public",
+                )
+            )
+        return SpaceAgentPage(agents=agents)
+
+    async def _resolve_card(self, target_agent_id: str) -> tuple[AgentCard, str, str]:
+        cached = self._cards_by_agent.get(target_agent_id)
+        if cached is not None:
+            return cached
+        await self.list_space_agents(os.getenv("KSADK_A2A_SPACE_ID", ""), page_size=100)
+        cached = self._cards_by_agent.get(target_agent_id)
+        if cached is None:
+            raise A2AControlPlaneError(
+                code=404,
+                message=f"A2A agent {target_agent_id} not discoverable",
+                error_code="A2A_AGENT_NOT_FOUND",
+                action="PrepareA2ACall",  # type: ignore[arg-type]
+            )
+        return cached
+
+    async def _direct_prepared(
+        self,
+        *,
+        target_agent_id: str,
+        version_id: str,
+        card: AgentCard,
+        card_sha256: str,
+    ) -> PreparedA2AOperation:
+        interfaces = list(card.supported_interfaces or [])
+        interface = interfaces[0] if interfaces else None
+        if interface is None or not interface.url:
+            raise A2AControlPlaneError(
+                code=502,
+                message="discovered agent card has no callable interface url",
+                error_code="A2A_CONTROL_PLANE_INVALID_RESPONSE",
+                action="PrepareA2ACall",  # type: ignore[arg-type]
+            )
+        route = A2ARoute(
+            kind="hosted_gateway",
+            interface=A2ARouteInterface(
+                url=str(interface.url),
+                protocol_binding=str(interface.protocol_binding or "JSONRPC"),
+                protocol_version=str(interface.protocol_version or "1.0"),
+            ),
+        )
+        return PreparedA2AOperation(
+            platform_task_id=f"a2a-task-{uuid.uuid4().hex}",
+            target=A2ATarget(
+                agent_id=target_agent_id,
+                version_id=version_id,
+                card_sha256=card_sha256,
+            ),
+            route=route,
+            call_permit="",
+            call_permit_expires_at="",
+        )
+
+    async def prepare_call(
+        self,
+        *,
+        space_id: str,
+        target_agent_id: str,
+        expected_version_id: str | None,
+        message_id: str,
+        message_sha256: str,
+        idempotency_token: str,
+    ) -> PreparedA2AOperation:
+        _ = (space_id, expected_version_id, message_id, message_sha256, idempotency_token)
+        card, sha, version_id = await self._resolve_card(target_agent_id)
+        return await self._direct_prepared(
+            target_agent_id=target_agent_id,
+            version_id=version_id,
+            card=card,
+            card_sha256=sha,
+        )
+
+    async def prepare_task_operation(
+        self,
+        *,
+        platform_task_id: str,
+        operation: A2AOperation,
+        message_id: str | None = None,
+        message_sha256: str | None = None,
+        idempotency_token: str | None = None,
+        agent_id: str | None = None,
+    ) -> PreparedA2AOperation:
+        _ = (operation, message_id, message_sha256, idempotency_token)
+        target_id = agent_id or platform_task_id
+        card, sha, version_id = await self._resolve_card(target_id)
+        return await self._direct_prepared(
+            target_agent_id=target_id,
+            version_id=version_id,
+            card=card,
+            card_sha256=sha,
+        )
+
+    async def bind_remote_task(
+        self,
+        *,
+        platform_task_id: str,
+        remote_task_id: str,
+        remote_context_id: str | None,
+        observed_at: str,
+    ) -> dict[str, Any]:
+        _ = (platform_task_id, remote_context_id, observed_at)
+        return {"RemoteTaskId": remote_task_id, "Bound": True}
+
+    async def append_task_events(
+        self,
+        *,
+        platform_task_id: str,
+        events: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        _ = (platform_task_id, events)
+        return {"Appended": len(events)}
+
+    async def resolve_credential(
+        self,
+        *,
+        platform_task_id: str,
+        credential_handle: str | None,
+        call_permit: str,
+    ) -> CredentialInjection:
+        _ = (platform_task_id, credential_handle, call_permit)
+        return CredentialInjection()
+
+    def gateway_token(self) -> str:
+        return self._service_token
+
+
 def _credential_string_map(value: Any, *, field_name: str) -> dict[str, str]:
     if value is None:
         return {}
@@ -654,8 +883,16 @@ def _agent_card_from_wire(payload: Any) -> AgentCard:
             message="AgentCard must be an object",
             error_code="A2A_CONTROL_PLANE_INVALID_RESPONSE",
         )
+    # 兼容 0.3 card：顶层 url/preferredTransport 折叠进 supportedInterfaces[0]。
+    if not payload.get("supportedInterfaces") and payload.get("url"):
+        payload = dict(payload)
+        payload["supportedInterfaces"] = [{
+            "url": payload["url"],
+            "protocolBinding": payload.get("preferredTransport", "JSONRPC"),
+            "protocolVersion": payload.get("protocolVersion", "0.3"),
+        }]
     try:
-        return ParseDict(payload, AgentCard())
+        return ParseDict(payload, AgentCard(), ignore_unknown_fields=True)
     except (ParseError, TypeError, ValueError) as exc:
         raise A2AControlPlaneError(
             code=502,
@@ -798,6 +1035,7 @@ __all__ = [
     "A2AInternalAction",
     "A2A_INTERNAL_ACTIONS",
     "A2A_INTERNAL_PATH_PREFIX",
+    "A2AAgentCardClient",
     "A2AControlPlane",
     "A2AControlPlaneError",
     "A2AOperation",

ksadk/a2a/event_adapter.py

@@ -5,31 +5,37 @@
 
 方向:
 - ``task_status_to_event``:A2A TaskStatus/TaskState → RuntimeEvent(run.*)。
-- ``artifact_to_event``:A2A Artifact → RuntimeEvent(artifact.*)。
-- ``message_to_event``:A2A Message → RuntimeEvent(text.*)。
-- ``event_to_text_part``:RuntimeEvent(text.*)→ A2A ``Part``(用于出站)。
+- ``artifact_to_event``:A2A Artifact → RuntimeEvent(item.*,item_kind="artifact")。
+- ``message_to_event``:A2A Message → RuntimeEvent(item.*,item_kind="message")。
+- ``event_to_text_part``:RuntimeEvent(item.*,item_kind="message")→ A2A ``Part``(用于出站)。
 
 wire 对象是 protobuf(``a2a_pb2``);文本用 ``Part(text=...)``。
 """
 
 from __future__ import annotations
 
+import time
 from typing import Any, Optional
 
 from a2a.types import Part, TaskState, TaskStatus
 
-from ksadk.events.runtime_event import EventType, RuntimeEvent
-
-#: A2A TaskState → RuntimeEvent run.* 事件类型映射。
-_TASK_STATE_TO_RUN_EVENT = {
-    TaskState.TASK_STATE_SUBMITTED: EventType.RUN_STARTED,
-    TaskState.TASK_STATE_WORKING: EventType.RUN_PROGRESS,
-    TaskState.TASK_STATE_COMPLETED: EventType.RUN_COMPLETED,
-    TaskState.TASK_STATE_FAILED: EventType.RUN_FAILED,
-    TaskState.TASK_STATE_CANCELED: EventType.RUN_CANCELED,
-    TaskState.TASK_STATE_INPUT_REQUIRED: EventType.RUN_INTERRUPTED,
-    TaskState.TASK_STATE_REJECTED: EventType.RUN_FAILED,
-}
+from ksadk.events.canonical import (
+    ContentSnapshot,
+    ErrorInfo,
+    ItemCompleted,
+    ItemStarted,
+    ItemUpdated,
+    RunCanceled,
+    RunCompleted,
+    RunFailed,
+    RunInterrupted,
+    RunProgress,
+    RunStarted,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.content import TextContent
+from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
 
 
 class A2AEventAdapter:
@@ -48,25 +54,57 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A TaskStatus → RuntimeEvent(run.*)。"""
-        event_type = _TASK_STATE_TO_RUN_EVENT.get(status.state, EventType.RUN_PROGRESS)
-        state_name = TaskState.Name(status.state) if status.state is not None else "unknown"
-        payload: dict[str, Any] = {"status": state_name}
-        if event_type == EventType.RUN_CANCELED:
-            payload["cancel_result"] = "interrupted_active_turn"
-        elif event_type == EventType.RUN_FAILED:
-            message = getattr(status, "message", None)
-            payload["error"] = self._parts_text(getattr(message, "parts", None)) or state_name
-        return RuntimeEvent.create(
-            event_type,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            payload=payload,
-            event_id=event_id,
+        """A2A TaskStatus → canonical RuntimeEvent(run.*)。"""
+        state = status.state
+        state_name = TaskState.Name(state) if state is not None else "unknown"
+        scope_id = stable_scope_id("a2a", session_id, invocation_id)
+        run_id = invocation_id
+        source = SourceRef(
+            framework="a2a",
+            native_run_id=invocation_id,
+            metadata={"agent_id": agent_id, "user_id": user_id, "status": state_name},
+        )
+        timestamp = time.time()
+        eid = event_id or stable_event_id(
+            "a2a", scope_id, run_id, "run", "run", invocation_id, seq_id
         )
+        common: dict[str, Any] = {
+            "schema_version": 2,
+            "event_id": eid,
+            "seq": seq_id,
+            "timestamp": timestamp,
+            "run_id": run_id,
+            "scope_id": scope_id,
+            "source": source,
+        }
+        if state == TaskState.TASK_STATE_SUBMITTED:
+            return RunStarted(**common, status="running")
+        if state == TaskState.TASK_STATE_WORKING:
+            return RunProgress(**common, status="running", message=state_name)
+        if state == TaskState.TASK_STATE_COMPLETED:
+            return RunCompleted(**common, status="completed", output_refs=())
+        if state in {TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_REJECTED}:
+            message = getattr(status, "message", None)
+            error_text = self._parts_text(getattr(message, "parts", None)) or state_name
+            return RunFailed(
+                **common,
+                status="failed",
+                error=ErrorInfo(
+                    code=(
+                        "a2a_task_rejected"
+                        if state == TaskState.TASK_STATE_REJECTED
+                        else "a2a_task_failed"
+                    ),
+                    message=error_text,
+                    source="a2a",
+                    scope_id=scope_id,
+                ),
+            )
+        if state == TaskState.TASK_STATE_CANCELED:
+            return RunCanceled(**common, status="canceled", reason="interrupted_active_turn")
+        if state == TaskState.TASK_STATE_INPUT_REQUIRED:
+            return RunInterrupted(**common, status="interrupted", reason=state_name)
+        return RunProgress(**common, status="running", message=state_name)
 
     def artifact_to_event(
         self,
@@ -79,23 +117,40 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A Artifact → RuntimeEvent(artifact.*)。"""
+        """A2A Artifact → canonical RuntimeEvent(item.started,item_kind="artifact")。"""
+        artifact_id = str(getattr(artifact, "artifact_id", None) or "")
         name = getattr(artifact, "name", None) or "artifact"
         text = self._parts_text(getattr(artifact, "parts", None))
-        return RuntimeEvent.create(
-            EventType.ARTIFACT_CREATED,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            payload={
-                "artifact_id": str(getattr(artifact, "artifact_id", None) or ""),
-                "name": name,
-                "version": 1,
-                "text": text,
-            },
-            event_id=event_id,
+        scope_id = stable_scope_id("a2a", session_id, invocation_id)
+        item_id = stable_item_id(
+            "a2a", session_id, invocation_id, "artifact", artifact_id or name
+        )
+        source = SourceRef(
+            framework="a2a",
+            native_run_id=invocation_id,
+            native_item_id=artifact_id or None,
+            metadata={"agent_id": agent_id, "user_id": user_id, "artifact_name": name},
+        )
+        eid = event_id or stable_event_id(
+            "a2a", scope_id, item_id, "item.started", "artifact", invocation_id, seq_id
+        )
+        initial = (
+            ContentSnapshot(parts=(TextContent(part_id="text", text=text),))
+            if text
+            else None
+        )
+        return ItemStarted(
+            schema_version=2,
+            event_id=eid,
+            seq=seq_id,
+            timestamp=time.time(),
+            run_id=invocation_id,
+            scope_id=scope_id,
+            source=source,
+            item_id=item_id,
+            item_kind="artifact",
+            phase="final_answer",
+            initial=initial,
         )
 
     def message_to_event(
@@ -110,29 +165,66 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A Message 文本 → RuntimeEvent(text.*,带相位)。"""
-        return RuntimeEvent.create(
-            EventType.TEXT_COMPLETED if final else EventType.TEXT_DELTA,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            phase="final_answer" if final else "commentary",
-            payload={"text": text},
-            event_id=event_id,
+        """A2A Message 文本 → canonical RuntimeEvent(item.*,item_kind="message")。"""
+        scope_id = stable_scope_id("a2a", session_id, invocation_id)
+        item_id = stable_item_id("a2a", session_id, invocation_id, "message", "response")
+        source = SourceRef(
+            framework="a2a",
+            native_run_id=invocation_id,
+            metadata={"agent_id": agent_id, "user_id": user_id},
+        )
+        timestamp = time.time()
+        if final:
+            eid = event_id or stable_event_id(
+                "a2a", scope_id, item_id, "item.completed", "snapshot", invocation_id, seq_id
+            )
+            return ItemCompleted(
+                schema_version=2,
+                event_id=eid,
+                seq=seq_id,
+                timestamp=timestamp,
+                run_id=invocation_id,
+                scope_id=scope_id,
+                source=source,
+                item_id=item_id,
+                item_kind="message",
+                snapshot=ContentSnapshot(
+                    parts=(TextContent(part_id="text-0", text=text),)
+                ),
+            )
+        eid = event_id or stable_event_id(
+            "a2a", scope_id, item_id, "item.updated", "text-0", invocation_id, seq_id
+        )
+        return ItemUpdated(
+            schema_version=2,
+            event_id=eid,
+            seq=seq_id,
+            timestamp=timestamp,
+            run_id=invocation_id,
+            scope_id=scope_id,
+            source=source,
+            item_id=item_id,
+            item_kind="message",
+            op="append",
+            update=TextContent(part_id="text-0", text=text),
         )
 
     # ---- RuntimeEvent → A2A ----
 
     @staticmethod
     def event_to_text_part(event: RuntimeEvent) -> Optional[Part]:
-        """RuntimeEvent(text.*)→ A2A ``Part``(用于出站 message/artifact)。"""
-        event.validate_conformance()
-        if event.event_type not in (EventType.TEXT_DELTA, EventType.TEXT_COMPLETED):
+        """RuntimeEvent(item.*,item_kind="message")→ A2A ``Part``(用于出站 message/artifact)。"""
+        if isinstance(event, ItemUpdated) and event.item_kind == "message":
+            if isinstance(event.update, TextContent):
+                text = event.update.text
+                return Part(text=text) if text else None
+            return None
+        if isinstance(event, ItemCompleted) and event.item_kind == "message":
+            if event.snapshot.parts and isinstance(event.snapshot.parts[0], TextContent):
+                text = event.snapshot.parts[0].text
+                return Part(text=text) if text else None
             return None
-        text = str(event.payload.get("text") or "")
-        return Part(text=text) if text else None
+        return None
 
     @staticmethod
     def _parts_text(parts: Any) -> str: