feat: 补齐 Agent API 与分页能力

Author: StableOps

README.md

@@ -10,15 +10,16 @@ confirmation tracking. StableOps watches supported chains, matches transfers,
 tracks confirmations, checks reorgs, and delivers webhook events to your app.
 
 This SDK is for server-side Python applications that create payment orders and
-checkout sessions, manage merchant subscriptions, manage webhook endpoints, and
-verify webhook signatures.
+checkout sessions, manage merchant subscriptions, webhooks and agent audit
+resources, and verify webhook signatures.
 
 ## Features
 
 - Type-safe client (Pydantic v2 models) for payment orders, checkout sessions,
   merchant subscriptions, and webhooks.
 - Sync (`StableOps`) and async (`AsyncStableOps`) clients with an identical API.
-- Built-in request retries and explicit idempotency for write operations.
+- Conservative retries for reads plus explicitly idempotent payment-order and
+  checkout-session creation; other writes are never retried automatically.
 - Constant-time webhook signature verification.
 
 ## Requirements

README.zh-CN.md

@@ -8,14 +8,14 @@ StableOps 把链上稳定币转账封装成熟悉的支付原语：支付订单
 Webhook、自动重试与确认数跟踪。StableOps 负责扫描支持的链、匹配转账、跟踪确认数、
 校验 reorg，并把 Webhook 事件投递到你的应用。
 
-本 SDK 面向服务端 Python 应用：创建支付订单与 Checkout Session、管理商户订阅、
-管理 Webhook 端点、校验 Webhook 签名。
+本 SDK 面向服务端 Python 应用：创建支付订单与收银台会话、管理商户订阅、
+管理 Webhook 端点与智能体审计资源，并校验 Webhook 签名。
 
 ## 特性
 
 - 类型安全客户端（Pydantic v2 模型），覆盖支付订单、Checkout Session、商户订阅、Webhook。
 - 同步（`StableOps`）与异步（`AsyncStableOps`）客户端，API 一致。
-- 内置请求重试，写操作显式幂等。
+- 读取请求自动重试；支付订单和收银台会话创建依靠幂等键安全重试，其他写操作不自动重试。
 - 常数时间的 Webhook 签名校验。
 
 ## 要求

stableops/__init__.py

@@ -17,6 +17,11 @@
 from stableops.errors import StableOpsError
 from stableops.types import (
     AcceptedAssetInput,
+    AgentAction,
+    AgentActionList,
+    AgentPolicy,
+    AgentSession,
+    AgentSessionList,
     AmountMode,
     CancelEndUserSubscriptionInput,
     ChangeEndUserSubscriptionPlanInput,
@@ -44,19 +49,23 @@
     PaymentOrder,
     PaymentOrderDetail,
     PaymentOrderInstruction,
+    PaymentOrderList,
     PaymentOrderStatus,
     PaymentOrderTimelineEntry,
     PayMerchantInvoiceResponse,
     PortalSession,
     ReplayDeadLetterItem,
     ReplayDeadLettersResult,
     ReplayDeliveryResult,
+    RequestAgentActionResult,
     UpdateMerchantBillingSettingsInput,
     UpdateMerchantPlanInput,
     UpdateWebhookEndpointInput,
     WebhookDelivery,
+    WebhookDeliveryList,
     WebhookDeliveryStatus,
     WebhookEndpoint,
+    WebhookEndpointList,
     WebhookEventType,
 )
 from stableops.webhooks import (
@@ -67,7 +76,7 @@
     verify_webhook_signature,
 )
 
-__version__ = "0.13.0"
+__version__ = "1.0.0"
 
 __all__ = [
     # Client
@@ -77,6 +86,11 @@
     "StableOpsError",
     # Types
     "AcceptedAssetInput",
+    "AgentAction",
+    "AgentActionList",
+    "AgentPolicy",
+    "AgentSession",
+    "AgentSessionList",
     "AmountMode",
     "CancelEndUserSubscriptionInput",
     "ChangeEndUserSubscriptionPlanInput",
@@ -104,19 +118,23 @@
     "PaymentOrder",
     "PaymentOrderDetail",
     "PaymentOrderInstruction",
+    "PaymentOrderList",
     "PaymentOrderStatus",
     "PaymentOrderTimelineEntry",
     "PayMerchantInvoiceResponse",
     "PortalSession",
     "ReplayDeadLetterItem",
     "ReplayDeadLettersResult",
     "ReplayDeliveryResult",
+    "RequestAgentActionResult",
     "UpdateMerchantBillingSettingsInput",
     "UpdateMerchantPlanInput",
     "UpdateWebhookEndpointInput",
     "WebhookDelivery",
+    "WebhookDeliveryList",
     "WebhookDeliveryStatus",
     "WebhookEndpoint",
+    "WebhookEndpointList",
     "WebhookEventType",
     # Webhooks
     "verify_webhook_signature",

stableops/agents.py

@@ -0,0 +1,269 @@
+"""Agent sessions, policies, and action audit APIs."""
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from stableops.http import AsyncHttpClient, HttpClient
+from stableops.types import (
+    AgentAction,
+    AgentActionList,
+    AgentPolicy,
+    AgentSession,
+    AgentSessionList,
+    RequestAgentActionResult,
+)
+
+
+def _path(value: str) -> str:
+    return quote(value, safe="")
+
+
+class AgentsApi:
+    """Agent API (synchronous)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self.http = http
+
+    def create_session(
+        self, label: Optional[str] = None, expires_at: Optional[str] = None
+    ) -> AgentSession:
+        response = self.http.request(
+            method="POST",
+            path="/v1/agent/sessions",
+            body={
+                key: value
+                for key, value in {"label": label, "expires_at": expires_at}.items()
+                if value is not None
+            },
+        )
+        return AgentSession(**response)
+
+    def list_sessions(
+        self, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> AgentSessionList:
+        response = self.http.request(
+            method="GET",
+            path="/v1/agent/sessions",
+            query={"limit": limit, "offset": offset},
+        )
+        return AgentSessionList(**response)
+
+    def revoke_session(self, session_id: str) -> AgentSession:
+        response = self.http.request(
+            method="POST", path=f"/v1/agent/sessions/{_path(session_id)}/revoke"
+        )
+        return AgentSession(**response)
+
+    def restore_session(self, session_id: str) -> AgentSession:
+        response = self.http.request(
+            method="POST", path=f"/v1/agent/sessions/{_path(session_id)}/restore"
+        )
+        return AgentSession(**response)
+
+    def get_policy(self) -> AgentPolicy:
+        return AgentPolicy(**self.http.request(method="GET", path="/v1/agent/policy"))
+
+    def upsert_policy(
+        self,
+        allowed_tools: Optional[List[str]] = None,
+        require_approval: Optional[bool] = None,
+    ) -> AgentPolicy:
+        body: Dict[str, Any] = {}
+        if allowed_tools is not None:
+            body["allowed_tools"] = allowed_tools
+        if require_approval is not None:
+            body["require_approval"] = require_approval
+        response = self.http.request(method="POST", path="/v1/agent/policy", body=body)
+        return AgentPolicy(**response)
+
+    def request_action(
+        self, agent_session_id: str, tool: str, input: Dict[str, Any]
+    ) -> RequestAgentActionResult:
+        response = self.http.request(
+            method="POST",
+            path="/v1/agent/actions",
+            body={"agent_session_id": agent_session_id, "tool": tool, "input": input},
+        )
+        return RequestAgentActionResult(**response)
+
+    def list_actions(
+        self,
+        session_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> AgentActionList:
+        response = self.http.request(
+            method="GET",
+            path="/v1/agent/actions",
+            query={"session_id": session_id, "limit": limit, "offset": offset},
+        )
+        return AgentActionList(**response)
+
+    def approve_action(self, action_id: str, approver_id: Optional[str] = None) -> AgentAction:
+        body = {} if approver_id is None else {"approver_id": approver_id}
+        response = self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/approve", body=body
+        )
+        return AgentAction(**response)
+
+    def reject_action(
+        self,
+        action_id: str,
+        approver_id: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> AgentAction:
+        body = {
+            key: value
+            for key, value in {"approver_id": approver_id, "reason": reason}.items()
+            if value is not None
+        }
+        response = self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/reject", body=body
+        )
+        return AgentAction(**response)
+
+    def mark_executed(
+        self,
+        action_id: str,
+        agent_session_id: str,
+        result: Any = None,
+        error_message: Optional[str] = None,
+    ) -> AgentAction:
+        if result is not None and error_message is not None:
+            raise ValueError("result and error_message are mutually exclusive")
+        body: Dict[str, Any] = {"agent_session_id": agent_session_id}
+        if error_message is not None:
+            body["error_message"] = error_message
+        else:
+            body["result"] = result
+        response = self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/executed", body=body
+        )
+        return AgentAction(**response)
+
+
+class AsyncAgentsApi:
+    """Agent API (asynchronous)."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self.http = http
+
+    async def create_session(
+        self, label: Optional[str] = None, expires_at: Optional[str] = None
+    ) -> AgentSession:
+        response = await self.http.request(
+            method="POST",
+            path="/v1/agent/sessions",
+            body={
+                key: value
+                for key, value in {"label": label, "expires_at": expires_at}.items()
+                if value is not None
+            },
+        )
+        return AgentSession(**response)
+
+    async def list_sessions(
+        self, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> AgentSessionList:
+        response = await self.http.request(
+            method="GET",
+            path="/v1/agent/sessions",
+            query={"limit": limit, "offset": offset},
+        )
+        return AgentSessionList(**response)
+
+    async def revoke_session(self, session_id: str) -> AgentSession:
+        response = await self.http.request(
+            method="POST", path=f"/v1/agent/sessions/{_path(session_id)}/revoke"
+        )
+        return AgentSession(**response)
+
+    async def restore_session(self, session_id: str) -> AgentSession:
+        response = await self.http.request(
+            method="POST", path=f"/v1/agent/sessions/{_path(session_id)}/restore"
+        )
+        return AgentSession(**response)
+
+    async def get_policy(self) -> AgentPolicy:
+        response = await self.http.request(method="GET", path="/v1/agent/policy")
+        return AgentPolicy(**response)
+
+    async def upsert_policy(
+        self,
+        allowed_tools: Optional[List[str]] = None,
+        require_approval: Optional[bool] = None,
+    ) -> AgentPolicy:
+        body: Dict[str, Any] = {}
+        if allowed_tools is not None:
+            body["allowed_tools"] = allowed_tools
+        if require_approval is not None:
+            body["require_approval"] = require_approval
+        response = await self.http.request(method="POST", path="/v1/agent/policy", body=body)
+        return AgentPolicy(**response)
+
+    async def request_action(
+        self, agent_session_id: str, tool: str, input: Dict[str, Any]
+    ) -> RequestAgentActionResult:
+        response = await self.http.request(
+            method="POST",
+            path="/v1/agent/actions",
+            body={"agent_session_id": agent_session_id, "tool": tool, "input": input},
+        )
+        return RequestAgentActionResult(**response)
+
+    async def list_actions(
+        self,
+        session_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> AgentActionList:
+        response = await self.http.request(
+            method="GET",
+            path="/v1/agent/actions",
+            query={"session_id": session_id, "limit": limit, "offset": offset},
+        )
+        return AgentActionList(**response)
+
+    async def approve_action(
+        self, action_id: str, approver_id: Optional[str] = None
+    ) -> AgentAction:
+        body = {} if approver_id is None else {"approver_id": approver_id}
+        response = await self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/approve", body=body
+        )
+        return AgentAction(**response)
+
+    async def reject_action(
+        self,
+        action_id: str,
+        approver_id: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> AgentAction:
+        body = {
+            key: value
+            for key, value in {"approver_id": approver_id, "reason": reason}.items()
+            if value is not None
+        }
+        response = await self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/reject", body=body
+        )
+        return AgentAction(**response)
+
+    async def mark_executed(
+        self,
+        action_id: str,
+        agent_session_id: str,
+        result: Any = None,
+        error_message: Optional[str] = None,
+    ) -> AgentAction:
+        if result is not None and error_message is not None:
+            raise ValueError("result and error_message are mutually exclusive")
+        body: Dict[str, Any] = {"agent_session_id": agent_session_id}
+        if error_message is not None:
+            body["error_message"] = error_message
+        else:
+            body["result"] = result
+        response = await self.http.request(
+            method="POST", path=f"/v1/agent/actions/{_path(action_id)}/executed", body=body
+        )
+        return AgentAction(**response)