managed-agent-sdk 0.0.2__tar.gz → 0.0.4__tar.gz

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/CHANGELOG.md

@@ -6,6 +6,81 @@ managed-agent-sdk（Python）的所有重要更新都会记录在这里。
 
 ## [未发布]
 
+## [0.0.4] - 2026-10-19
+
+### ✨ 新增
+
+- 新增 `agent.info()`（请求 `DescribeAgent`）与 `version.info()`（请求 `DescribeAgentVersion`），
+  返回最新数据
+- 新增 WorkBuddy OpenAPI 控制面后端，通过 `ClientOpts(openapi=OpenApiOpts(...))` 选择。
+  Agent、Version、Session 与目录方法保持一致，出参统一为 PascalCase
+- `OpenApiOpts` 需要 `enterprise_id` 与 `api_key`，显式传入或读
+  `WORKBUDDY_ENTERPRISE_ID` / `WORKBUDDY_API_KEY`；缺企业 ID 时构造抛出 `ValidationError`，
+  缺 API key 时抛出 `AuthError`。服务地址固定在 SDK 内，不对外暴露配置
+- OpenAPI 鉴权支持两种凭证，按 `api_key` 前缀自动选择：`ck_` 前缀的开放平台 key 走
+  `X-Api-Key` 头；`pt_` 前缀的幻影令牌走 `Authorization: Bearer` 头。可用
+  `OpenApiOpts(auth_scheme=...)` 显式指定，覆盖前缀推断
+- `ClientOpts.transport` 同时适用于 OpenAPI 与 ACP；OpenAPI 的 HTTP 连接池通过
+  `aclose()` 释放，新建 Agent 默认不下发到 WorkBuddy 客户端
+
+### 🐛 修复
+
+- `session.connect()` 每次建连都请求 `DescribeAgentSession` 获取当前接入点，服务端更换接入点后
+  重新建连不再使用旧地址
+
+## [0.0.3] - 2026-10-09
+
+### 🔒 安全
+
+- 不再泄漏 SecretId 与请求签名 —— 官方 SDK 会在 `DEBUG` 级别把完整
+  `Authorization` 头打进日志，现已将其 logger（`tencentcloud_sdk_common`）
+  钉在 `WARNING`。确需查看原始请求时，显式对该 logger 设 `DEBUG` 即可
+
+### ⚠️ 不兼容变更
+
+- 日志配置合并为 `LoggerOpts(enable, level, sink, file)`，删除
+  `ClientOpts` 上原有的 `log_level` 字段，`logger` 的类型由 `Logger` 改为 `LoggerOpts`。原写法
+  `ClientOpts(logger=..., log_level="debug")` 改为
+  `ClientOpts(logger=LoggerOpts(level="debug"))`
+- 控制台日志**默认开启**（`warn` 级别），原先默认静默。用
+  `LoggerOpts(enable=False)` 关闭；关闭后即使宿主配置了 root logger 也不输出
+
+### ✨ 新增
+
+- `prompt()` 返回值新增 `refusal`，携带服务端给出的结构化拒绝原因；
+  同时导出 `RefusalReason` 类型
+- `prompt()` 返回值新增 `trace_id`（本轮 W3C trace id）与 `usage`（本轮
+  token 消耗）；入参新增 `trace_id`，不传时自动生成，每轮通过
+  `traceparent` 请求头传给服务端。导出 `UsageInfo` 类型
+- 文件日志：配置 `LoggerOpts(file=LogFileOpts())` 后写入
+  `.wma-log/sdk-debug.log`，与控制台分别设置级别；凭据自动脱敏，按大小
+  轮转、按天清理
+- 接入伽利略上报：记录对话轮次的开始、结束、失败等事件，默认开启，可用
+  `TelemetryOpts(enabled=False)` 关闭。`aclose()` 会等待上报发送完成
+
+### 🐛 修复
+
+- 收到 401 时作废 token 缓存，不再反复用同一张已失效的票重试
+- `invalidate()` 补上世代守卫：换票在途时作废，其结果不再写回缓存
+
+### ✨ 优化
+
+- 补齐运行期日志：ACP 数据面（建连、重连、心跳、SSE）与 OneID 换票层
+  此前均无日志
+- 数据面日志改走 `ClientOpts.logger`，`log_level` 对其生效；传了 `logger`
+  未指定级别时按 `"warn"` 兜底
+- 控制面日志带上 TraceId，贯穿请求 / 响应 / 错误三条日志，并写入
+  `X-TC-TraceId` 请求头
+- 日志降噪：连接 ID 截断显示，不再逐次记录 token 缓存命中
+- 更正 `aclose()` 的文档说明 —— 它当前是空实现，不调用不会漏资源
+
+### 📖 文档
+
+- 快速开始简化为 3 步，去掉多余的 `versions.create()`
+- 新增「回复文本怎么拿」「版本要不要自己建」两节
+
+## [0.0.2] - 2026-09-22
+
 ### ✨ 优化
 
 - 优化部分功能

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: managed-agent-sdk
-Version: 0.0.2
-Summary: Managed Agent SDK (Python) — 控制面走腾讯云 API，数据面走 ACP
+Version: 0.0.4
+Summary: Managed Agent SDK (Python) — 控制面支持腾讯云 API 与 WorkBuddy OpenAPI，数据面使用 ACP
 Project-URL: Homepage, https://cnb.cool/codebuddy/managed-agent-doc/-/tree/main/python
 Project-URL: Documentation, https://cnb.cool/codebuddy/managed-agent-doc/-/blob/main/python/api.md
 Project-URL: Repository, https://cnb.cool/codebuddy/managed-agent-doc
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 腾讯云 **WorkBuddy 企业版 Managed Agent** 的 Python SDK。
 
-控制面走腾讯云 API（TC3 签名），数据面走 ACP 协议，两段凭证由 SDK 内部缝合。
+控制面支持腾讯云 API（TC3 签名）与 WorkBuddy OpenAPI（OAuth2），数据面使用 ACP 协议；SDK 自动获取并缓存数据面凭证。
 
 ```bash
 pip install managed-agent-sdk
@@ -57,7 +57,39 @@ export TENCENTCLOUD_SECRET_ID=你的SecretId
 export TENCENTCLOUD_SECRET_KEY=你的SecretKey
 ```
 
-只支持长期密钥，不支持 STS 临时密钥。数据面（ACP）的凭证由 SDK 用这套密钥自动换取并缓存，无需单独配置。
+腾讯云 API 支持长期密钥。数据面（ACP）的凭证由 SDK 通过控制面自动换取并缓存，无需单独配置。
+
+### WorkBuddy OpenAPI
+
+配置应用凭证（API key 与企业 ID）：
+
+```bash
+export WORKBUDDY_ENTERPRISE_ID=你的企业ID
+export WORKBUDDY_API_KEY=你的APIKey
+```
+
+传入 `ClientOpts(openapi=OpenApiOpts())` 选择 OpenAPI：
+
+```python
+import asyncio
+
+from managed_agent_sdk import ClientOpts, ManagedAgentClient, OpenApiOpts
+
+
+async def main() -> None:
+    async with ManagedAgentClient(ClientOpts(openapi=OpenApiOpts())) as client:
+        print((await client.models.list()).items)
+
+
+asyncio.run(main())
+```
+
+`OpenApiOpts` 的字段均可显式传入；省略时读取对应环境变量。服务地址固定在 SDK 内，
+不支持配置；每个控制面请求带 `X-Api-Key` 头，缺企业 ID 或 API key 时构造抛出异常。
+
+领域方法及 PascalCase 出参与腾讯云 API 相同；新建 Agent 默认不下发到 WorkBuddy 客户端。
+
+传入 `openapi` 后，`credentials`、`region`、`endpoint`、`api_version`、`language` 不参与控制面请求；同时传入 `proxy` 会抛出 `ValidationError`。`transport` 可配置 OpenAPI 与 ACP 的 HTTP 传输层。
 
 ## 快速开始
 
@@ -67,15 +99,15 @@ import asyncio
 from managed_agent_sdk import (
     CreateAgentOpts,
     CreateSessionOpts,
-    CreateVersionOpts,
     ManagedAgentClient,
     ManifestBuilder,
+    PromptOpts,
 )
 
 
 async def main() -> None:
     async with ManagedAgentClient() as client:
-        # 创建 Agent
+        # 1. 创建 Agent —— 服务端顺带建好承载 manifest 的 default 版本
         agent = await client.agents.create(
             CreateAgentOpts(
                 agent_name="日志分析助手",
@@ -84,21 +116,17 @@ async def main() -> None:
             )
         )
 
-        # 创建版本（manifest 服务端必填）
-        version = await agent.versions.create(
-            CreateVersionOpts(
-                manifest=ManifestBuilder().system_prompt("你是日志分析专家").build(),
-            )
-        )
+        # 2. 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
+        session = await agent.sessions.create(CreateSessionOpts())
 
-        # 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
-        session = await agent.sessions.create(
-            CreateSessionOpts(version_id=version.version_id)
-        )
+        # 3. 对话。回复文本走 on_chunk，见下方说明
+        def on_chunk(n) -> None:
+            u = n.update
+            if u.sessionUpdate == "agent_message_chunk" and u.content.type == "text":
+                print(u.content.text, end="", flush=True)
 
-        # 对话
-        res = await session.prompt("分析这份日志")
-        print(res.stop_reason)
+        res = await session.prompt("分析这份日志", PromptOpts(on_chunk=on_chunk))
+        print(f"\nstop_reason: {res.stop_reason}")
 
         await session.disconnect()
 
@@ -106,7 +134,23 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-`prompt()` 的返回值只携带 `stop_reason`，回复文本从 `on_chunk` 取 —— 流式内容与终局结果分两条通道，这是 ACP 的协议设计。
+### 回复文本怎么拿
+
+`prompt()` 的返回值只携带 `stop_reason` 与 `refusal`，**不含回复正文** ——
+流式内容与终局结果分两条通道，这是 ACP 的协议设计。两条路都能拿到正文：
+
+- **`on_chunk`**（上面的写法）：实时增量，适合边生成边展示
+- **`session.messages()`**：轮次结束后按 `EventType == "ASSISTANT"` 取 `Message["Content"]`，
+  适合只要最终结果、不关心过程
+
+### 版本要不要自己建
+
+入门不需要。`agents.create()` 传了 `manifest` / `model` 时，服务端会建好一个
+`default` 版本承载它们；`sessions.create()` 不传 `version_id` 时按 Agent 的
+routing 配置分流，也会落到它。
+
+要灰度多个配置（A/B、逐步放量）时才用 `agent.versions.create()` 显式建版本，
+再配合 `agent.update_routing()` 分流。
 
 ## 配置连接器 / 技能 / 专家
 
@@ -146,7 +190,7 @@ agent = await client.agents.create(
 
 **入参 snake_case，出参 PascalCase。** 出参原样透传云 API 字段名，便于对照官方文档排查。
 
-**不做控制面自动重试。** `Create*` 类接口非幂等且服务端不提供 `ClientToken`，重试 `sessions.create()` 会重复拉起沙箱并产生真实费用。唯一例外是 ACP 断线重连（`Last-Event-ID` 断点续传，不重放 prompt）。
+**控制面重试。** 控制面失败直接抛出异常，不做自动重试。`Create*` 类接口非幂等且服务端不提供 `ClientToken`，重试 `sessions.create()` 会重复拉起沙箱并产生真实费用。ACP 支持断线重连（`Last-Event-ID` 断点续传，不重放 prompt）。
 
 **会话即沙箱，且不会自动回收。** `sessions.create()` 每次调用都拉起一个真实沙箱。注意 `disconnect()` **只断 ACP 连接，不释放沙箱** —— 服务端既没有销毁会话的接口，也没有空闲超时回收（`IDLE` 只是「上一轮对话结束」的轮次状态，沙箱照常运行）。要复用会话，别在循环里反复新建。
 

managed_agent_sdk-0.0.4/README.md

@@ -0,0 +1,162 @@
+# managed-agent-sdk（Python）
+
+腾讯云 **WorkBuddy 企业版 Managed Agent** 的 Python SDK。
+
+控制面支持腾讯云 API（TC3 签名）与 WorkBuddy OpenAPI（OAuth2），数据面使用 ACP 协议；SDK 自动获取并缓存数据面凭证。
+
+```bash
+pip install managed-agent-sdk
+```
+
+要求 Python 3.10 ~ 3.14。Node 版见 [`@tencent-ai/managed-agent-sdk`](https://www.npmjs.com/package/@tencent-ai/managed-agent-sdk)，两侧 API 语义一致。
+
+## 凭证
+
+从环境变量读取，或在构造时显式传入：
+
+```bash
+export TENCENTCLOUD_SECRET_ID=你的SecretId
+export TENCENTCLOUD_SECRET_KEY=你的SecretKey
+```
+
+腾讯云 API 支持长期密钥。数据面（ACP）的凭证由 SDK 通过控制面自动换取并缓存，无需单独配置。
+
+### WorkBuddy OpenAPI
+
+配置应用凭证（API key 与企业 ID）：
+
+```bash
+export WORKBUDDY_ENTERPRISE_ID=你的企业ID
+export WORKBUDDY_API_KEY=你的APIKey
+```
+
+传入 `ClientOpts(openapi=OpenApiOpts())` 选择 OpenAPI：
+
+```python
+import asyncio
+
+from managed_agent_sdk import ClientOpts, ManagedAgentClient, OpenApiOpts
+
+
+async def main() -> None:
+    async with ManagedAgentClient(ClientOpts(openapi=OpenApiOpts())) as client:
+        print((await client.models.list()).items)
+
+
+asyncio.run(main())
+```
+
+`OpenApiOpts` 的字段均可显式传入；省略时读取对应环境变量。服务地址固定在 SDK 内，
+不支持配置；每个控制面请求带 `X-Api-Key` 头，缺企业 ID 或 API key 时构造抛出异常。
+
+领域方法及 PascalCase 出参与腾讯云 API 相同；新建 Agent 默认不下发到 WorkBuddy 客户端。
+
+传入 `openapi` 后，`credentials`、`region`、`endpoint`、`api_version`、`language` 不参与控制面请求；同时传入 `proxy` 会抛出 `ValidationError`。`transport` 可配置 OpenAPI 与 ACP 的 HTTP 传输层。
+
+## 快速开始
+
+```python
+import asyncio
+
+from managed_agent_sdk import (
+    CreateAgentOpts,
+    CreateSessionOpts,
+    ManagedAgentClient,
+    ManifestBuilder,
+    PromptOpts,
+)
+
+
+async def main() -> None:
+    async with ManagedAgentClient() as client:
+        # 1. 创建 Agent —— 服务端顺带建好承载 manifest 的 default 版本
+        agent = await client.agents.create(
+            CreateAgentOpts(
+                agent_name="日志分析助手",
+                model="deepseek-v3",
+                manifest=ManifestBuilder().system_prompt("你是日志分析专家").build(),
+            )
+        )
+
+        # 2. 创建会话（拉起真实沙箱，不会自动回收 —— 尽量复用）
+        session = await agent.sessions.create(CreateSessionOpts())
+
+        # 3. 对话。回复文本走 on_chunk，见下方说明
+        def on_chunk(n) -> None:
+            u = n.update
+            if u.sessionUpdate == "agent_message_chunk" and u.content.type == "text":
+                print(u.content.text, end="", flush=True)
+
+        res = await session.prompt("分析这份日志", PromptOpts(on_chunk=on_chunk))
+        print(f"\nstop_reason: {res.stop_reason}")
+
+        await session.disconnect()
+
+
+asyncio.run(main())
+```
+
+### 回复文本怎么拿
+
+`prompt()` 的返回值只携带 `stop_reason` 与 `refusal`，**不含回复正文** ——
+流式内容与终局结果分两条通道，这是 ACP 的协议设计。两条路都能拿到正文：
+
+- **`on_chunk`**（上面的写法）：实时增量，适合边生成边展示
+- **`session.messages()`**：轮次结束后按 `EventType == "ASSISTANT"` 取 `Message["Content"]`，
+  适合只要最终结果、不关心过程
+
+### 版本要不要自己建
+
+入门不需要。`agents.create()` 传了 `manifest` / `model` 时，服务端会建好一个
+`default` 版本承载它们；`sessions.create()` 不传 `version_id` 时按 Agent 的
+routing 配置分流，也会落到它。
+
+要灰度多个配置（A/B、逐步放量）时才用 `agent.versions.create()` 显式建版本，
+再配合 `agent.update_routing()` 分流。
+
+## 配置连接器 / 技能 / 专家
+
+三类资源的**配置入口不统一**，这是最容易配错的地方：
+
+| 资源 | 查询 | 配置入口 | 最终落点 |
+| --- | --- | --- | --- |
+| 连接器（MCP） | `client.connectors.list()` | `connector_ids`（Action 入参） | 服务端物化成 manifest 的 `mcp_servers` |
+| 技能 | `client.skills.list()` | `ManifestBuilder.skills()` | manifest 的 `skills` |
+| 专家 | `client.experts.list()` | `ManifestBuilder.experts()` | manifest 的 `experts` |
+
+技能与专家进 manifest，连接器**不进** —— 只把 ID 交给服务端，由它查网关地址后物化。
+自己往 manifest 里写 `mcp_servers` 会与之重复。
+
+```python
+skills = await client.skills.list("BUILTIN", ListSkillsOpts(limit=50))
+connectors = await client.connectors.list_active()
+
+agent = await client.agents.create(
+    CreateAgentOpts(
+        agent_name="运维助手",
+        manifest=(
+            ManifestBuilder()
+            .system_prompt("你是运维专家")
+            .skills([{"type": "builtin", "id": s["SkillId"]} for s in skills.items])
+            .build()
+        ),
+        connector_ids=[c["ConnectorId"] for c in connectors.items],  # 独立入参
+    )
+)
+```
+
+`connector_ids` 是该版本最终要绑的完整集合，服务端按它做全量覆盖 ——
+改绑定直接传新集合，解绑从列表里去掉即可，传 `[]` 解绑全部。
+
+## 两条约定
+
+**入参 snake_case，出参 PascalCase。** 出参原样透传云 API 字段名，便于对照官方文档排查。
+
+**控制面重试。** 控制面失败直接抛出异常，不做自动重试。`Create*` 类接口非幂等且服务端不提供 `ClientToken`，重试 `sessions.create()` 会重复拉起沙箱并产生真实费用。ACP 支持断线重连（`Last-Event-ID` 断点续传，不重放 prompt）。
+
+**会话即沙箱，且不会自动回收。** `sessions.create()` 每次调用都拉起一个真实沙箱。注意 `disconnect()` **只断 ACP 连接，不释放沙箱** —— 服务端既没有销毁会话的接口，也没有空闲超时回收（`IDLE` 只是「上一轮对话结束」的轮次状态，沙箱照常运行）。要复用会话，别在循环里反复新建。
+
+## 文档
+
+完整 API 参考、错误码表、已知问题见
+[Managed Agent SDK 文档](https://cnb.cool/codebuddy/managed-agent-doc/-/blob/main/python/README.md)。

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "managed-agent-sdk"
 dynamic = ["version"]
-description = "Managed Agent SDK (Python) — 控制面走腾讯云 API，数据面走 ACP"
+description = "Managed Agent SDK (Python) — 控制面支持腾讯云 API 与 WorkBuddy OpenAPI，数据面使用 ACP"
 readme = "README.md"
 requires-python = ">=3.10,<3.15"
 license = { text = "MIT" }

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/src/managed_agent_sdk/__init__.py

@@ -49,9 +49,15 @@ from .acp_types import (
     EmbeddedResource,
     ImageContent,
     PromptResponse,
+    QuestionAnswer,
+    QuestionItem,
+    QuestionOption,
+    QuestionRequest,
+    RefusalReason,
     ResourceLink,
     SessionNotification,
     TextContent,
+    UsageInfo,
 )
 from .agent import (
     Agent,
@@ -70,8 +76,6 @@ from .catalog import (
     ConnectorRegistry,
     ExpertPage,
     ExpertRegistry,
-    ListConnectorsOpts,
-    ListExpertsOpts,
     ListSkillsOpts,
     SkillPage,
     SkillRegistry,
@@ -122,23 +126,21 @@ from .opts import (
     DEFAULT_REGION,
     DEFAULT_TIMEOUT_MS,
     MAX_PAGE_LIMIT,
-    AgentListOpts,
-    AgentSortBy,
     ClientOpts,
     ConnectOpts,
     Credentials,
-    Filter,
     Language,
+    LogFileOpts,
     Logger,
+    LoggerOpts,
     LogLevel,
+    OpenApiOpts,
     Page,
     PageOpts,
     RequestOpts,
-    SessionListOpts,
-    SessionSortBy,
-    SortDirection,
 )
 from .session import MessageListOpts, PromptOpts, Session
+from .telemetry import TelemetryOpts, TurnTelemetryOpts
 from .types import (
     A2AConfig,
     A2ASkillItem,
@@ -194,6 +196,11 @@ __all__ = [
     "ResourceLink",
     "EmbeddedResource",
     "PromptResponse",
+    "QuestionAnswer",
+    "QuestionItem",
+    "QuestionOption",
+    "QuestionRequest",
+    "RefusalReason",
     "SessionNotification",
     "AcpConnectionState",
     "NotificationListener",
@@ -226,10 +233,10 @@ __all__ = [
     "UpdateVersionOpts",
     "MessageListOpts",
     "PromptOpts",
+    "TelemetryOpts",
+    "TurnTelemetryOpts",
     "A2ASkill",
-    "ListConnectorsOpts",
     "ListSkillsOpts",
-    "ListExpertsOpts",
     "ManifestSkillRef",
     "ManifestExpertRef",
     "ManifestRefType",
@@ -275,9 +282,6 @@ __all__ = [
     "MessageEventType",
     "ToolCallStatus",
     "CapiErrorType",
-    "AgentSortBy",
-    "SessionSortBy",
-    "SortDirection",
     "SkillSource",
     "ExpertSource",
     "PublishStatus",
@@ -290,14 +294,15 @@ __all__ = [
     "ClientOpts",
     "RequestOpts",
     "PageOpts",
-    "AgentListOpts",
-    "SessionListOpts",
     "Page",
-    "Filter",
     "Credentials",
+    "OpenApiOpts",
     "Logger",
+    "LogFileOpts",
+    "LoggerOpts",
     "LogLevel",
     "Language",
+    "UsageInfo",
     # ── 错误 ────────────────────────────────
     "CloudAgentError",
     "ValidationError",

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/src/managed_agent_sdk/_generated/__init__.py

@@ -5,4 +5,7 @@ from __future__ import annotations
 from .actions import *  # noqa: F403
 from .defaults import *  # noqa: F403
 from .enums import *  # noqa: F403
+from .error_map import *  # noqa: F403
+from .rest_routes import *  # noqa: F403
+from .sensitive_keys import *  # noqa: F403
 from .types import *  # noqa: F403

{managed_agent_sdk-0.0.2 → managed_agent_sdk-0.0.4}/src/managed_agent_sdk/_generated/actions.py

@@ -46,19 +46,11 @@ DESCRIBE_AGENT_LIST: Final[ActionMapping] = {
     "request": [
         ("offset", "Offset"),
         ("limit", "Limit"),
-        ("filters", "Filters"),
-        ("sort_by", "SortBy"),
-        ("sort_direction", "SortDirection"),
     ],
     "response": {"kind": "page", "items": "AgentSet", "totalCount": "TotalCount"},
     "pagination": {"style": "offset_limit", "max": 100},
 }
-"""Agent 列表。可用 filter 名：AgentName（子串匹配）/ Model（精确匹配，
-
-命中「最新版本引用该模型」的 Agent）；多个 filter 之间是 AND。
-
-filters 的 name 拼错时服务端静默返回空列表而非报错。
-"""
+"""Agent 列表。"""
 
 MODIFY_AGENT: Final[ActionMapping] = {
     "action": "ModifyAgent",
@@ -162,17 +154,13 @@ DESCRIBE_AGENT_VERSION_LIST: Final[ActionMapping] = {
         ("agent_id", "AgentId"),
         ("offset", "Offset"),
         ("limit", "Limit"),
-        ("filters", "Filters"),
     ],
     "response": {"kind": "page", "items": "AgentVersionSet", "totalCount": "TotalCount"},
     "pagination": {"style": "offset_limit", "max": 100},
 }
-"""版本列表。可用 filter 名 VersionType，取值是大写枚举 DEFAULT / TEST / PROD
-
-—— 服务端只认大写，传小写会被当作「不过滤」而返回全部。
+"""版本列表。集合字段名是 AgentVersionSet（原 VersionSet 与 Skill 版本接口
 
-集合字段名是 AgentVersionSet（原 VersionSet 与 Skill 版本接口同名但元素
-类型不同，服务端已改名）。
+同名但元素类型不同，服务端已改名）。
 """
 
 MODIFY_AGENT_VERSION: Final[ActionMapping] = {
@@ -213,7 +201,7 @@ CREATE_AGENT_SESSION: Final[ActionMapping] = {
 只断 ACP 连接。循环建会话会持续堆积资源 —— 应复用同一会话，配置变更走
 MigrateAgentSession。
 
-出参是窄响应，不含 AgentId / VersionId，SDK 用已知值补齐。
+出参是窄响应，不含 AgentId / VersionId。
 """
 
 DESCRIBE_AGENT_SESSION: Final[ActionMapping] = {
@@ -224,10 +212,7 @@ DESCRIBE_AGENT_SESSION: Final[ActionMapping] = {
     ],
     "response": {"kind": "object"},
 }
-"""会话详情。出参含 EndpointSet，返回的会话可直接用于数据面。
-
-不同 Action 返回字段集不同，SDK 用合并而非覆盖更新快照，避免窄响应清空已知值。
-"""
+"""会话详情。出参含 EndpointSet，SDK 每次建立 ACP 连接时都调用它获取当前接入点。"""
 
 DESCRIBE_AGENT_SESSION_LIST: Final[ActionMapping] = {
     "action": "DescribeAgentSessionList",
@@ -236,15 +221,13 @@ DESCRIBE_AGENT_SESSION_LIST: Final[ActionMapping] = {
         ("offset", "Offset"),
         ("limit", "Limit"),
         ("filters", "Filters"),
-        ("sort_by", "SortBy"),
-        ("sort_direction", "SortDirection"),
     ],
     "response": {"kind": "page", "items": "SessionSet", "totalCount": "TotalCount"},
     "pagination": {"style": "offset_limit", "max": 100},
 }
-"""会话列表（服务端为租户级）。可用 filter 名：SessionId / Status /
+"""会话列表（服务端为租户级）。Filters 不对调用方开放，只由 SDK 内部下发：
 
-AgentId / UserId。agent.sessions.list() 会自动注入 AgentId filter 收窄。
+agent.sessions.list() 注入 AgentId filter 收窄到本 Agent。
 """
 
 MIGRATE_AGENT_SESSION: Final[ActionMapping] = {
@@ -262,7 +245,7 @@ MIGRATE_AGENT_SESSION: Final[ActionMapping] = {
 已建立的 ACP 连接都保持不变，用户无感。
 
 服务端入参名是 TargetVersionId，不是 VersionId。
-出参是窄响应、不一定回显版本，但我们明确知道迁到了哪个版本。
+出参是窄响应、不一定回显版本；确认迁移结果用 DescribeAgentSession。
 """
 
 BIND_EXTERNAL_AGENT: Final[ActionMapping] = {
@@ -339,7 +322,6 @@ DESCRIBE_BUILTIN_MODEL_LIST: Final[ActionMapping] = {
     "request": [
         ("offset", "Offset"),
         ("limit", "Limit"),
-        ("filters", "Filters"),
     ],
     "response": {"kind": "page", "items": "BuiltinModelSet", "totalCount": "TotalCount"},
     "pagination": {"style": "offset_limit", "max": 100},
@@ -367,6 +349,7 @@ DESCRIBE_MESSAGE_EVENT_LIST: Final[ActionMapping] = {
 （另有 DescribeSessionMessageList 尚未实现，SDK 不接）。
 
 服务端把 AgentId 列为必填，只传 SessionId 会报 InvalidParameter。
+Filters 只由 SDK 内部下发：session.messages() 的 eventTypes 转为 EventType filter。
 """
 
 DESCRIBE_USER_ACCESS_TOKEN: Final[ActionMapping] = {
@@ -408,9 +391,7 @@ DESCRIBE_CONNECTOR_LIST: Final[ActionMapping] = {
 整除（服务端要求 Offset 落在页边界上，非页边界直接报错），SDK 本地提前
 拦截，省一次必然失败的往返。
 
-服务端认可三个 filter 名：Name（子串）/ Status（精确，ACTIVE|DISABLED）/
-Source（精确，ENTERPRISE_AGENT|ASSISTANT）。与技能 / 专家不同，
-连接器域对未知 filter 名静默忽略而非报错。
+Filters 只由 SDK 内部下发：connectors.listActive() 注入 Status=ACTIVE。
 """
 
 DESCRIBE_SKILL_LIST: Final[ActionMapping] = {
@@ -418,7 +399,6 @@ DESCRIBE_SKILL_LIST: Final[ActionMapping] = {
     "domain": "skill",
     "request": [
         ("source", "Source"),
-        ("filters", "Filters"),
         ("account_id", "AccountId"),
         ("agent_id", "AgentId"),
         ("offset", "Offset"),
@@ -429,12 +409,7 @@ DESCRIBE_SKILL_LIST: Final[ActionMapping] = {
 }
 """技能列表（租户级）。Source 必填 —— 服务端把它当数据通路判别而非筛选条件。
 
-AUTHORIZED 链路服务端强制只返回已发布且启用的技能；另两条通路默认不过滤。
-
-服务端认可四个 filter 名：SkillId（精确多值 OR，最多 100 个）/
-Keyword（子串，只取首个值）/ PublishStatus / Status。
-与其他域不同：未知 filter 名直接报错；带 SkillId 时切换为按 ID 批量查询，
-offset / limit 被忽略。
+AUTHORIZED 链路服务端强制只返回已发布且启用的技能；另两条通路草稿与停用项都会返回。
 """
 
 DESCRIBE_EXPERT_LIST: Final[ActionMapping] = {
@@ -442,7 +417,6 @@ DESCRIBE_EXPERT_LIST: Final[ActionMapping] = {
     "domain": "expert",
     "request": [
         ("source", "Source"),
-        ("filters", "Filters"),
         ("offset", "Offset"),
         ("limit", "Limit"),
     ],
@@ -452,10 +426,6 @@ DESCRIBE_EXPERT_LIST: Final[ActionMapping] = {
 """专家列表（租户级）。Source 必填，且只有 BUILTIN / CUSTOM ——
 
 服务端校验白名单不含 AUTHORIZED（与技能不同）。
-
-服务端认可三个 filter 名：ExpertId（精确多值 OR，最多 100 个）/
-Keyword（子串，只取首个值）/ PublishStatus（精确，**大小写敏感** ——
-技能侧做了大写归一，专家侧没做）。专家不支持 Status filter。
 """