agent-studio-client 0.0.1__py3-none-any.whl

agent_studio/__init__.py

@@ -0,0 +1,60 @@
+"""Agent Studio 运行时 API 的 Python 客户端。"""
+
+from ._meta import StudioMeta
+from ._version import EVENT_SCHEMA_MAJOR, __version__
+from .async_client import AsyncAgentHandle, AsyncRunHandle, AsyncStudioClient
+from .client import AgentHandle, RunHandle, StudioClient
+from .errors import (
+    StudioApiError,
+    StudioCompatibilityError,
+    StudioConnectionError,
+    StudioError,
+    StudioFeatureUnavailableError,
+    StudioProtocolError,
+    StudioStreamGapError,
+)
+from .models import (
+    ActionAccepted,
+    CapabilityList,
+    ClientCapabilities,
+    Event,
+    PendingAction,
+    Run,
+    RunStatus,
+    RunUsage,
+    Thread,
+    ThreadList,
+    ThreadMessage,
+    ThreadSummary,
+)
+
+__all__ = [
+    "EVENT_SCHEMA_MAJOR",
+    "ActionAccepted",
+    "AgentHandle",
+    "AsyncAgentHandle",
+    "AsyncRunHandle",
+    "AsyncStudioClient",
+    "CapabilityList",
+    "ClientCapabilities",
+    "Event",
+    "PendingAction",
+    "Run",
+    "RunHandle",
+    "RunStatus",
+    "RunUsage",
+    "StudioApiError",
+    "StudioClient",
+    "StudioCompatibilityError",
+    "StudioConnectionError",
+    "StudioError",
+    "StudioFeatureUnavailableError",
+    "StudioMeta",
+    "StudioProtocolError",
+    "StudioStreamGapError",
+    "Thread",
+    "ThreadList",
+    "ThreadMessage",
+    "ThreadSummary",
+    "__version__",
+]

agent_studio/_api.py

@@ -0,0 +1,188 @@
+"""运行时 API 端点定义。每个函数只描述请求与响应解析，由同步或异步客户端负责发送，两者共享同一份端点逻辑。
+
+路径均相对于 /v1/projects/{projectId}。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from ._transport import check_idempotency_key, drop_none, segment
+from .errors import StudioProtocolError
+from .models import (
+    ActionAccepted,
+    CapabilityList,
+    ClientCapabilities,
+    Event,
+    PendingAction,
+    Run,
+    Thread,
+    ThreadList,
+    ThreadMessage,
+)
+
+T = TypeVar("T")
+M = TypeVar("M", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class Request(Generic[T]):
+    method: str
+    path: str
+    parse: Callable[[Any], T]
+    json: dict[str, Any] | None = None
+    params: dict[str, Any] | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+def decode(response: httpx.Response) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as error:
+        raise StudioProtocolError(f"响应不是 JSON（HTTP {response.status_code}）") from error
+
+
+def _model(model: type[M], key: str | None = None) -> Callable[[Any], M]:
+    def parse(body: Any) -> M:
+        try:
+            return model.model_validate(body[key] if key else body)
+        except (KeyError, TypeError, ValidationError) as error:
+            raise StudioProtocolError(f"响应不符合接口契约：{model.__name__}") from error
+    return parse
+
+
+def _list(model: type[M], key: str) -> Callable[[Any], list[M]]:
+    def parse(body: Any) -> list[M]:
+        try:
+            return [model.model_validate(item) for item in body[key]]
+        except (KeyError, TypeError, ValidationError) as error:
+            raise StudioProtocolError(f"响应不符合接口契约：{model.__name__} 列表") from error
+    return parse
+
+
+def _none(_: Any) -> None:
+    return None
+
+
+def _raw(body: Any) -> Any:
+    return body
+
+
+# ---- Thread ----
+
+def create_thread(agent_id: str | None = None, agent_slug: str | None = None) -> Request[Thread]:
+    if (agent_id is None) == (agent_slug is None):
+        raise ValueError("agent_id 与 agent_slug 需且只能提供一个")
+    body = {"agentId": agent_id} if agent_id else {"agentSlug": agent_slug}
+    return Request("POST", "/threads", _model(Thread, "thread"), json=body)
+
+
+def get_thread(thread_id: str) -> Request[Thread]:
+    return Request("GET", f"/threads/{segment(thread_id)}", _model(Thread, "thread"))
+
+
+def delete_thread(thread_id: str) -> Request[None]:
+    return Request("DELETE", f"/threads/{segment(thread_id)}", _none)
+
+
+def list_threads(agent_id: str | None = None, before: str | None = None) -> Request[ThreadList]:
+    return Request("GET", "/threads", _model(ThreadList), params=drop_none({"agentId": agent_id, "before": before}))
+
+
+def get_thread_messages(thread_id: str) -> Request[list[ThreadMessage]]:
+    return Request("GET", f"/threads/{segment(thread_id)}/messages", _list(ThreadMessage, "messages"))
+
+
+# ---- Run ----
+
+def create_run(
+    thread_id: str,
+    input: str,
+    idempotency_key: str,
+    *,
+    context: dict[str, str | int | float | bool | None] | None = None,
+    attachments: list[str] | None = None,
+    capabilities: ClientCapabilities | None = None,
+    agent_version: int | None = None,
+) -> Request[Run]:
+    if not input.strip():
+        raise ValueError("input 不能为空")
+    if len(input) > 20000:
+        raise ValueError("input 不能超过 20000 个字符")
+    body = drop_none({
+        "threadId": thread_id,
+        "input": input,
+        "context": context,
+        "attachments": [{"fileId": file_id} for file_id in attachments] if attachments else None,
+        "capabilities": capabilities.model_dump(by_alias=True) if capabilities else None,
+        "agentVersion": agent_version,
+    })
+    return Request("POST", "/runs", _model(Run, "run"), json=body,
+                   headers={"Idempotency-Key": check_idempotency_key(idempotency_key)})
+
+
+def get_run(run_id: str) -> Request[Run]:
+    return Request("GET", f"/runs/{segment(run_id)}", _model(Run, "run"))
+
+
+def list_runs() -> Request[list[Run]]:
+    return Request("GET", "/runs", _list(Run, "runs"))
+
+
+def cancel_run(run_id: str) -> Request[Run]:
+    return Request("POST", f"/runs/{segment(run_id)}/cancel", _model(Run, "run"))
+
+
+def list_events(run_id: str, after: int = 0, limit: int = 100) -> Request[list[Event]]:
+    if after < 0 or not 1 <= limit <= 200:
+        raise ValueError("after 不能为负数，limit 范围为 1~200")
+    return Request("GET", f"/runs/{segment(run_id)}/events", _list(Event, "events"),
+                   params={"after": after, "limit": limit})
+
+
+# ---- 审批与客户端工具 ----
+
+def get_pending(run_id: str) -> Request[list[PendingAction]]:
+    return Request("GET", f"/runs/{segment(run_id)}/pending", _list(PendingAction, "pending"))
+
+
+def submit_approval(run_id: str, action: PendingAction, decision: str,
+                    args: dict[str, Any] | None = None) -> Request[ActionAccepted]:
+    if action.kind != "approval":
+        raise ValueError("客户端工具请求需用 submit_client_tool_result 回传")
+    if decision not in action.allowed_decisions:
+        raise ValueError(f"该请求不允许决定 {decision}")
+    if (decision == "edit") != (args is not None):
+        raise ValueError("只有 edit 决定需要且必须提供 args")
+    body = drop_none({"argsHash": action.args_hash, "decision": decision, "args": args})
+    return Request("POST", f"/runs/{segment(run_id)}/requests/{segment(action.id)}/decision",
+                   _model(ActionAccepted), json=body)
+
+
+def submit_client_tool_result(run_id: str, action: PendingAction, device_id: str, *, approved: bool,
+                              result: dict[str, Any] | None = None) -> Request[ActionAccepted]:
+    if action.kind != "client_tool":
+        raise ValueError("审批请求需用 submit_approval 提交")
+    if approved and result is None:
+        raise ValueError("批准执行时必须回传 result")
+    body = drop_none({"deviceId": device_id, "argsHash": action.args_hash,
+                      "decision": "approved" if approved else "rejected", "result": result if approved else None})
+    return Request("POST", f"/runs/{segment(run_id)}/requests/{segment(action.id)}/result",
+                   _model(ActionAccepted), json=body)
+
+
+# ---- 其他 ----
+
+def delete_actor_data(actor_ref: str) -> Request[dict[str, Any]]:
+    return Request("POST", "/privacy/deletions", _raw, json={"scope": "actor", "targetRef": actor_ref})
+
+
+def get_capabilities() -> Request[CapabilityList]:
+    return Request("GET", "/capabilities", _model(CapabilityList))

agent_studio/_meta.py

@@ -0,0 +1,41 @@
+"""能力发现：GET /v1/meta。旧版服务端没有该端点，视为 1.0.0 且所有新能力不可用。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from ._sse import check_event_schema
+from .errors import StudioFeatureUnavailableError, StudioProtocolError
+from .models import _Model
+
+LEGACY_API_VERSION = "1.0.0"
+
+
+class StudioMeta(_Model):
+    api_version: str
+    event_schema_version: str
+    features: dict[str, bool] = {}
+
+    def supports(self, feature: str) -> bool:
+        # 缺失的能力键视为不支持，服务端新增的未知键被忽略
+        return self.features.get(feature, False)
+
+    def require(self, feature: str) -> None:
+        if not self.supports(feature):
+            raise StudioFeatureUnavailableError(feature, self.api_version)
+
+
+LEGACY_META = StudioMeta(api_version=LEGACY_API_VERSION, event_schema_version="1.0", features={})
+
+
+def parse_meta(status: int, body: Any) -> StudioMeta:
+    if status == 404:
+        return LEGACY_META
+    try:
+        meta = StudioMeta.model_validate(body)
+    except ValidationError as error:
+        raise StudioProtocolError("能力发现响应不符合接口契约") from error
+    check_event_schema(meta.event_schema_version)
+    return meta

agent_studio/_sse.py

@@ -0,0 +1,71 @@
+"""Server-Sent Events 解析与事件序号检查，纯函数实现，同步与异步流共用。"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+
+from pydantic import ValidationError
+
+from ._version import EVENT_SCHEMA_MAJOR
+from .errors import StudioCompatibilityError, StudioProtocolError, StudioStreamGapError
+from .models import Event
+
+# 与服务端单帧上限对齐，防止异常服务端让客户端无限累积内存。
+MAX_FRAME_BYTES = 1_048_576
+
+
+class SseParser:
+    """逐行喂入 SSE 文本，产出每一帧的 data 字段。注释行（心跳）与 id/event 字段被忽略，序号以信封内 seq 为准。"""
+
+    def __init__(self) -> None:
+        self._data: list[str] = []
+        self._size = 0
+
+    def feed(self, line: str) -> Iterator[str]:
+        line = line.rstrip("\r")
+        if line == "":
+            if self._data:
+                data = "\n".join(self._data)
+                self._data, self._size = [], 0
+                yield data
+            return
+        if line.startswith(":"):
+            return
+        field, _, value = line.partition(":")
+        if field == "data":
+            value = value[1:] if value.startswith(" ") else value
+            self._size += len(value)
+            if self._size > MAX_FRAME_BYTES:
+                raise StudioProtocolError("事件帧超过 1 MiB 上限")
+            self._data.append(value)
+
+
+class EventSequencer:
+    """解析事件信封、校验主版本与 seq 连续性，并维护续传游标。"""
+
+    def __init__(self, run_id: str, after: int):
+        if after < 0:
+            raise ValueError("事件游标不能为负数")
+        self.run_id = run_id
+        self.cursor = after
+
+    def accept(self, data: str) -> Event | None:
+        """返回新事件；重复或属于其他 Run 的事件返回 None。"""
+        try:
+            event = Event.model_validate(json.loads(data))
+        except (ValueError, ValidationError) as error:
+            raise StudioProtocolError("事件不符合接口契约") from error
+        check_event_schema(event.event_schema_version)
+        if event.run_id != self.run_id or event.seq <= self.cursor:
+            return None
+        if event.seq != self.cursor + 1:
+            raise StudioStreamGapError(self.cursor + 1, event.seq)
+        self.cursor = event.seq
+        return event
+
+
+def check_event_schema(version: str) -> None:
+    major = version.split(".", 1)[0]
+    if major != str(EVENT_SCHEMA_MAJOR):
+        raise StudioCompatibilityError(f"{EVENT_SCHEMA_MAJOR}.x", version)

agent_studio/_transport.py

@@ -0,0 +1,132 @@
+"""同步与异步客户端共用的请求构造、错误映射与重试策略，不做任何 I/O。"""
+
+from __future__ import annotations
+
+import logging
+import random
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from .errors import StudioApiError
+
+logger = logging.getLogger("agent_studio")
+
+_ACTOR = re.compile(r"^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$")
+_IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{8,128}$")
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    base_url: str
+    project_id: str
+    api_key: str
+    actor_ref: str
+    timeout: float = 30.0
+    max_retries: int = 3
+    max_reconnects: int = 5
+    # 服务端每 15 秒发一次心跳；超过 3 倍心跳仍无数据视为连接失效。
+    heartbeat_timeout: float = 45.0
+
+    def __post_init__(self) -> None:
+        if not self.base_url:
+            raise ValueError("base_url 必填，SDK 不内置默认实例地址")
+        if not _UUID.match(self.project_id):
+            raise ValueError("project_id 必须是 UUID")
+        if not self.api_key.startswith("sk_studio_"):
+            raise ValueError("api_key 格式无效，应以 sk_studio_ 开头")
+        if not _ACTOR.match(self.actor_ref):
+            raise ValueError("actor_ref 只能包含字母、数字和 :._-，且不超过 128 个字符")
+        if self.max_retries < 0 or self.max_reconnects < 0:
+            raise ValueError("重试次数不能为负数")
+        object.__setattr__(self, "base_url", self.base_url.rstrip("/"))
+        url = httpx.URL(self.base_url)
+        if url.scheme != "https" and url.host not in _LOCAL_HOSTS:
+            logger.warning("Studio 地址未使用 HTTPS，API Key 将以明文传输")
+
+    @property
+    def project_url(self) -> str:
+        return f"{self.base_url}/v1/projects/{self.project_id}"
+
+    def headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Studio-Actor": self.actor_ref,
+            "Studio-Sdk": f"python/{__version__}",
+            "Accept": "application/json",
+        }
+
+
+def segment(value: str) -> str:
+    """URL 路径片段转义，防止标识中的 / 或 .. 改变请求路径。"""
+    return quote(value, safe="")
+
+
+def is_uuid(value: str) -> bool:
+    return bool(_UUID.match(value))
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def check_idempotency_key(key: str) -> str:
+    if not _IDEMPOTENCY_KEY.match(key):
+        raise ValueError("idempotency_key 需为 8~128 个字母、数字或 ._:- 字符")
+    return key
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+    except ValueError:
+        try:
+            seconds = (parsedate_to_datetime(value) - datetime.now(timezone.utc)).total_seconds()
+        except (TypeError, ValueError):
+            return None
+    return min(max(seconds, 0.0), 30.0)
+
+
+def error_from_response(response: httpx.Response) -> StudioApiError:
+    """按服务端统一错误格式 {"error": {code, message, retryable}} 映射；非该格式（如代理 HTML）也给出稳定的错误码。"""
+    status = response.status_code
+    fallback_retryable = status == 429 or status >= 500
+    retry_after = parse_retry_after(response.headers.get("retry-after"))
+    try:
+        body = response.json()
+        error = body["error"]
+        return StudioApiError(
+            str(error["code"]), str(error.get("message", "")), status,
+            bool(error.get("retryable", fallback_retryable)), retry_after,
+        )
+    except (ValueError, KeyError, TypeError):
+        return StudioApiError("unexpected_response", f"服务端返回了非预期响应（HTTP {status}）", status,
+                              fallback_retryable, retry_after)
+
+
+def is_retryable(error: BaseException) -> bool:
+    if isinstance(error, StudioApiError):
+        return error.retryable
+    return isinstance(error, httpx.TransportError)
+
+
+def backoff(attempt: int, error: BaseException | None = None) -> float:
+    """第 attempt 次重试（从 0 开始）前的等待秒数；服务端给出 Retry-After 时以其为准。"""
+    if isinstance(error, StudioApiError) and error.retry_after is not None:
+        return error.retry_after
+    return float(min(8.0, 0.5 * 2**attempt) * random.uniform(0.5, 1.0))
+
+
+def drop_none(body: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in body.items() if value is not None}

agent_studio/_version.py

@@ -0,0 +1,4 @@
+__version__ = "0.0.1"
+
+# SDK 能解析的事件 Schema 主版本；服务端主版本不同时抛 StudioCompatibilityError。
+EVENT_SCHEMA_MAJOR = 1