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

ksadk/a2a/credential.py

@@ -0,0 +1,99 @@
+"""A2ACredentialProvider — 按 credential binding 获取短时出站凭据 (goal-06 §3.2)。
+
+契约 §3.2:``A2ACredentialProvider`` 按 credential binding handle 解析出站调用凭据;
+``credential_scheme_name``/``credential_secret_ref`` 表达 external 出站凭据 scheme 与
+Secret reference(可空)。7 月范围(§「7 月 credential adapter」):支持 **none / HTTP
+bearer / HTTP basic / API key**;**OAuth2/OIDC 未支持**——注册可保存 schema,但调用返回
+明确 capability error,不静默成功也不伪造 token。
+"""
+
+from __future__ import annotations
+
+import base64
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+class CredentialCapabilityError(RuntimeError):
+    """credential scheme 超出当前能力(OAuth2/OIDC 未支持)时抛出。"""
+
+
+@dataclass
+class OutboundCredential:
+    """解析后的出站凭据(已物化为 HTTP 头;``scheme`` 记录来源 scheme)。"""
+
+    scheme: str  # "none" | "bearer" | "basic" | "apikey"
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+class A2ACredentialProvider(ABC):
+    """按 credential binding handle 解析出站凭据。"""
+
+    @abstractmethod
+    async def resolve(self, credential_handle: Optional[str]) -> OutboundCredential:
+        """把 credential binding handle 解析为出站 HTTP 头。无 handle → ``none``。"""
+        raise NotImplementedError
+
+
+#: 7 月支持的 scheme(其余注册可存,调用报 capability error)。
+_SUPPORTED_SCHEMES = frozenset({"none", "bearer", "basic", "apikey"})
+_UNSUPPORTED_OAUTH_SCHEMES = frozenset({"oauth2", "oidc", "oauth2_client_credentials"})
+
+
+class StaticCredentialProvider(A2ACredentialProvider):
+    """从注入的 ``handle -> binding`` 映射解析出站凭据(测试/本地;生产由 STS/Secret 后端替换)。
+
+    binding 结构::
+
+        {"scheme": "bearer", "token": "..."}
+        {"scheme": "basic", "username": "...", "password": "..."}
+        {"scheme": "apikey", "header": "X-API-Key", "key": "..."}
+        {"scheme": "none"}
+        {"scheme": "oauth2", ...}   # 注册可存,resolve 抛 CredentialCapabilityError
+    """
+
+    def __init__(self, bindings: Optional[dict[str, dict[str, Any]]] = None) -> None:
+        self._bindings = dict(bindings or {})
+
+    def register(self, handle: str, binding: dict[str, Any]) -> None:
+        self._bindings[handle] = binding
+
+    async def resolve(self, credential_handle: Optional[str]) -> OutboundCredential:
+        if not credential_handle:
+            return OutboundCredential(scheme="none", headers={})
+        binding = self._bindings.get(credential_handle)
+        if binding is None:
+            raise KeyError(f"未知 credential binding handle: {credential_handle!r}")
+        scheme = str(binding.get("scheme") or "none").lower()
+        if scheme in _UNSUPPORTED_OAUTH_SCHEMES:
+            raise CredentialCapabilityError(
+                f"credential scheme {scheme!r} 当前未支持(7 月仅 none/bearer/basic/apikey);"
+                " 注册可保存 schema,调用返回明确 capability error"
+            )
+        if scheme not in _SUPPORTED_SCHEMES:
+            raise CredentialCapabilityError(f"未知 credential scheme: {scheme!r}")
+
+        if scheme == "bearer":
+            return OutboundCredential(
+                scheme="bearer",
+                headers={"Authorization": f"Bearer {binding.get('token', '')}"},
+            )
+        if scheme == "basic":
+            raw = f"{binding.get('username', '')}:{binding.get('password', '')}"
+            token = base64.b64encode(raw.encode()).decode()
+            return OutboundCredential(scheme="basic", headers={"Authorization": f"Basic {token}"})
+        if scheme == "apikey":
+            header = str(binding.get("header") or "X-API-Key")
+            return OutboundCredential(
+                scheme="apikey", headers={header: str(binding.get("key", ""))}
+            )
+        return OutboundCredential(scheme="none", headers={})
+
+
+__all__ = [
+    "A2ACredentialProvider",
+    "CredentialCapabilityError",
+    "OutboundCredential",
+    "StaticCredentialProvider",
+]

ksadk/a2a/event_adapter.py

@@ -0,0 +1,149 @@
+"""A2AEventAdapter — A2A Message/Task/Artifact 与 RuntimeEvent 的双向转换 (goal-05)。
+
+契约 §3.2:``A2AEventAdapter`` 负责 A2A wire 对象与 G0.2 RuntimeEvent 的双向转换;
+§7.2:artifact/message ↔ RuntimeEvent artifact/text/data。
+
+方向:
+- ``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``(用于出站)。
+
+wire 对象是 protobuf(``a2a_pb2``);文本用 ``Part(text=...)``。
+"""
+
+from __future__ import annotations
+
+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,
+}
+
+
+class A2AEventAdapter:
+    """A2A wire 对象 ↔ RuntimeEvent 双向转换器。"""
+
+    # ---- A2A → RuntimeEvent ----
+
+    def task_status_to_event(
+        self,
+        status: TaskStatus,
+        *,
+        agent_id: str,
+        user_id: str,
+        session_id: str,
+        invocation_id: str,
+        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,
+        )
+
+    def artifact_to_event(
+        self,
+        artifact: Any,
+        *,
+        agent_id: str,
+        user_id: str,
+        session_id: str,
+        invocation_id: str,
+        seq_id: int,
+        event_id: Optional[str] = None,
+    ) -> RuntimeEvent:
+        """A2A Artifact → RuntimeEvent(artifact.*)。"""
+        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,
+        )
+
+    def message_to_event(
+        self,
+        text: str,
+        *,
+        final: bool,
+        agent_id: str,
+        user_id: str,
+        session_id: str,
+        invocation_id: str,
+        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,
+        )
+
+    # ---- 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):
+            return None
+        text = str(event.payload.get("text") or "")
+        return Part(text=text) if text else None
+
+    @staticmethod
+    def _parts_text(parts: Any) -> str:
+        if not parts:
+            return ""
+        texts = []
+        for part in parts:
+            value = getattr(part, "text", None)
+            if value:
+                texts.append(str(value))
+        return "".join(texts)
+
+
+__all__ = ["A2AEventAdapter"]