Metadata-Version: 2.5
Name: managed-agent-sdk
Version: 0.0.7
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/README.md
Project-URL: Repository, https://cnb.cool/codebuddy/managed-agent-doc
Project-URL: Issues, https://cnb.cool/codebuddy/managed-agent-doc/-/issues
Project-URL: Changelog, https://cnb.cool/codebuddy/managed-agent-doc/-/blob/main/python/CHANGELOG.md
Author-email: Tencent CodeBuddy <codebuddy@tencent.com>
License: MIT
License-File: LICENSE
Keywords: acp,agent,llm,managed-agent,sandbox
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: agent-client-protocol<0.13,>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: tencentcloud-sdk-python-common>=3.0.1000
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Description-Content-Type: text/markdown

# managed-agent-sdk（Python）

腾讯云 **WorkBuddy 企业版 Managed Agent** 的 Python SDK。包名 `managed-agent-sdk`，模块名 `managed_agent_sdk`。

控制面支持腾讯云 API（TC3 签名）与 WorkBuddy OpenAPI（API key 鉴权）两种后端，数据面使用 ACP 协议；SDK 自动获取并缓存数据面凭证。
**API 与 Node 版 [`@tencent-ai/managed-agent-sdk`](https://www.npmjs.com/package/@tencent-ai/managed-agent-sdk) 一一对应**（命名按 Python 惯例转 snake_case），差异见 §3。

```bash
pip install managed-agent-sdk
```

要求 Python 3.10 ~ 3.14。

想先看能跑的完整代码：[**入门示例**](https://cnb.cool/codebuddy/managed-agent-doc/-/blob/main/example/README.md)（`example/python/main.py`）。

---

## 目录

- [1. 快速开始](#1-快速开始)
- [2. 通用约定](#2-通用约定)
- [3. 与 Node 版的差异](#3-与-node-版的差异)
- [4. ManagedAgentClient](#4-managedagentclient)
- [5. Agent 管理](#5-agent-管理)
- [6. 版本管理](#6-版本管理)
- [7. 会话管理](#7-会话管理)
- [8. 对话（数据面）](#8-对话数据面)
- [9. A2A Inbound](#9-a2a-inbound)
- [10. A2A Outbound](#10-a2a-outbound)
- [11. 目录资源查询（连接器 / 技能 / 专家）](#11-目录资源查询连接器--技能--专家)
- [12. ManifestBuilder](#12-manifestbuilder)
- [13. 错误处理](#13-错误处理)
- [14. 类型索引](#14-类型索引)

---

## 1. 快速开始

### 凭证

#### 腾讯云 API（默认）

SecretId / SecretKey 在 [腾讯云访问管理控制台的 API 密钥管理](https://console.cloud.tencent.com/cam/capi) 获取。

从环境变量读取，或通过 `ClientOpts(capi=CapiOpts(credentials=Credentials(secret_id=..., secret_key=...)))` 显式传入：

```bash
export TENCENTCLOUD_SECRET_ID=你的SecretId
export TENCENTCLOUD_SECRET_KEY=你的SecretKey
```

#### WorkBuddy OpenAPI

API key 有两种，按需选择其一：

- 开放平台 API key：在 [WorkBuddy 管理后台的开放平台应用列表](https://workbuddy.cn/admin/integration/oauth/list) 获取
- 企业个人 API key：在 [WorkBuddy 个人中心的 API key 页面](https://www.workbuddy.cn/profile/keys) 获取

设置企业 ID 与 API key：

```bash
export WORKBUDDY_ENTERPRISE_ID=你的企业ID
export WORKBUDDY_API_KEY=你的APIKey
```

传入 `ClientOpts(openapi=OpenApiOpts())` 即选择 OpenAPI 后端，省略的字段从上述环境变量读取：

```python
from managed_agent_sdk import ClientOpts, ManagedAgentClient, OpenApiOpts

# 从环境变量读取企业 ID 与 API key
client = ManagedAgentClient(ClientOpts(openapi=OpenApiOpts()))
```

```python
# 显式传入优先于环境变量
client = ManagedAgentClient(
    ClientOpts(openapi=OpenApiOpts(enterprise_id="...", api_key="ck_..."))
)
```

服务地址、鉴权方式等字段见 [§4 `OpenApiOpts`](#openapiopts)。

数据面（ACP）的凭证由 SDK 用控制面凭证自动换取并缓存，无需单独配置，见 [§8 数据面凭证](#数据面凭证)。

### 第一个 Agent

```python
import asyncio

from managed_agent_sdk import (
    ClientOpts,
    CreateAgentOpts,
    ManagedAgentClient,
    ManifestBuilder,
    OpenApiOpts,
    PromptOpts,
)


def on_chunk(n) -> None:
    update = n.update
    if update.session_update == "agent_message_chunk" and update.content.type == "text":
        print(update.content.text, end="", flush=True)


async def main() -> None:
    # 腾讯云 API：读 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY
    opts = ClientOpts()
    # WorkBuddy OpenAPI：读 WORKBUDDY_ENTERPRISE_ID / WORKBUDDY_API_KEY
    # opts = ClientOpts(openapi=OpenApiOpts())
    async with ManagedAgentClient(opts) as client:
        # 1. 选一个可用模型。控制面不校验 model，填错要到对话时才报错，见 §4.0
        models = await client.models.list()
        model = next(
            (m["ModelId"] for m in models.items if m.get("Status") == "ENABLED"),
            None,
        )
        if model is None:
            raise RuntimeError("没有可用模型")

        # 2. 创建 Agent。服务端自动生成 default 版本，model 与 manifest 写在这个版本上
        agent = await client.agents.create(
            CreateAgentOpts(
                agent_name="日志分析助手",
                model=model,
                manifest=ManifestBuilder().system_prompt("你是日志分析专家，回答简洁。").build(),
            )
        )

        # 3. 创建会话。不传 version_id 时按 Agent 的 routing 分流，新 Agent 只有 default 版本；
        #    每个会话拉起一个真实沙箱
        session = await agent.sessions.create()

        # 4. 对话。回复文本从 on_chunk 读取，返回值只带 stop_reason 等结束信息
        res = await session.prompt(
            "分析这段日志：ERROR connection refused", PromptOpts(on_chunk=on_chunk)
        )
        print("\nstop_reason:", res.stop_reason)  # 不是 end_turn 时查看 res.refusal

        # 5. 断开连接；删除 Agent 时版本与会话一并删除
        await session.disconnect()
        await agent.delete()


asyncio.run(main())
```

**所有网络方法都是 `async`。** 建议用 `async with` 管理客户端，退出时自动调用 `aclose()`。

要用另一个模型或另一份配置时，新建版本并显式传入 `model`（新版本不继承 `default` 版本的模型），
再用这个版本建会话：

```python
version = await agent.versions.create(CreateVersionOpts(model=model, manifest=manifest))
session = await agent.sessions.create(CreateSessionOpts(version_id=version.version_id))
```

### 核心对象

| 对象 | 职责 |
| --- | --- |
| `ManagedAgentClient` | 入口，持有 `agents` / `sessions` / `models` / `connectors` / `skills` / `experts` |
| `Agent` | 单个 Agent，持有 `versions` / `sessions` / `a2a` / `external_agents`；`info()` 读取最新数据 |
| `Version` | 版本；`info()` 读取最新数据 |
| `Session` | 会话，控制面查询 + ACP 数据面对话；`info()` 读取最新数据 |
| `ManifestBuilder` | 流式构造 Agent 配置清单 |

`client.agents.get()` / `agent.versions.get()` / `client.sessions.get()` 返回实例，用来执行操作；
实例不缓存数据。读取最新数据用 `info()`，每次调用都请求接口。
写操作（`update` / `update_routing` / `a2a.update` / `migrate`）的返回值只含部分字段。

---

## 2. 通用约定

### 入参 snake_case，出参 PascalCase

入参用 Python 惯例的 snake_case；**出参沿用云 API 的字段名**，是 PascalCase 的 dict。

```python
info = await agent.info()
info["AgentId"]   # ✅
info["agent_id"]  # ❌ 不存在
```

出参与云 API 文档的字段一致，可以直接对照排查。出参用 `TypedDict`，IDE 有补全但运行时就是普通 dict。

### 入参用 dataclass

```python
from managed_agent_sdk import CreateAgentOpts

# model 是自由字符串、控制面不校验，建议先 client.models.list() 取 ModelId（§4.0）
await client.agents.create(CreateAgentOpts(agent_name="x", model=model_id))
```

### 时间格式

所有时间字段都是 RFC3339 字符串。**无值时字段缺省**，用 `.get()` 判空即可。

### 分页

列表方法统一用 `PageOpts(offset=..., limit=...)`，返回 `Page`：

```python
page = await client.agents.list(PageOpts(limit=10))
page.total_count       # 满足条件的总数
page.items             # 当页数据
len(page)              # 当页条数
for a in page: ...     # 可直接迭代
```

`limit` 默认 20，**全部列表方法统一上限 100**（导出常量 `MAX_PAGE_LIMIT`）。
超限抛 `ValidationError`，不发请求。

⚠️ **`offset` 必须是 `limit` 的整数倍**，否则抛
`ValidationError`：

```python
await client.agents.list(PageOpts(offset=30, limit=20))  # ValidationError
await client.agents.list(PageOpts(offset=40, limit=20))  # 正常
```

省略 `limit` 时按默认的 20 校验。按固定的 `limit` 逐页翻页即可满足该要求。

### 逐请求选项

所有方法的 opts 都继承 `RequestOpts`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `timeout` | `int \| None` | 覆盖本次超时（毫秒） |
| `headers` | `dict[str, str] \| None` | 追加请求头（如 `traceparent`），不覆盖签名头 |

### 重试与重连

控制面失败直接抛出异常，不做自动重试。

创建类接口重复调用会重复创建资源，例如重试 `sessions.create()` 会重复拉起沙箱并产生实际费用。异常上的 `retryable` 仅作信息提示。

ACP 支持断线自动重连（从断开处继续接收，不重新发送 prompt）。

### 会话即沙箱，且不会自动回收

`sessions.create()` 每次调用都拉起一个**真实沙箱**，占用计算与磁盘资源。

⚠️ **`disconnect()` 只断 ACP 连接，不释放沙箱** —— 会话仍在服务端存活。而且：

- **没有**销毁或归档会话的接口，会话只能创建、查询、迁移
- **没有**空闲超时自动回收 —— `IDLE` 只表示「上一轮对话结束」，沙箱照常运行
- `ARCHIVED` 状态**无法主动进入**，只在会话异常时由服务端设置

所以循环建会话会持续堆积沙箱。测试脚本尤其容易遇到这个问题 —— 复用同一个会话，不要每次都新建。
删除 Agent（`agent.delete()`）时，它的版本与会话一并删除。

---

## 3. 与 Node 版的差异

只有这几处，**不影响 API 的含义**：

| 项 | Node | Python |
|----|------|--------|
| 命名 | `camelCase` | `snake_case` |
| 入参传递 | 对象字面量 | `dataclass` |
| 关闭客户端 | `close()` | **`aclose()`** |
| **数据面出参** | plain object，`res.stopReason` | **pydantic 模型，`res.stop_reason`** |
| 取消对话 | `AbortSignal` | `asyncio.Event` |
| 日志方法 | `logger.warn` | `logger.warning`（兼容标准库 `logging.Logger`） |

⚠️ **控制面与数据面的取值方式相反**，这是最容易出错的一处：

```python
# 控制面：TypedDict + PascalCase → 下标取值
info = await agent.a2a.update(UpdateA2AOpts(enabled=True))
info["A2AConfig"]["A2AEnabled"]

# 数据面：pydantic 模型 + snake_case → 属性取值
res = await session.prompt("hi")
res.stop_reason          # ✅
res["stopReason"]        # ❌ TypeError
res.get("stopReason")    # ❌ AttributeError
```

控制面（Agent、版本、会话的管理接口）的出参是 `TypedDict`；数据面（`prompt`、流式通知）的类型来自
`agent-client-protocol` 包。`session.messages()` 属于**控制面**，所以仍是 `TypedDict` —— 取 token 用量写
`event.get("Message", {}).get("TokenUsage")`（**不是每个事件都有**，见 §7.3）。

---

## 4. ManagedAgentClient

### `ManagedAgentClient(opts=None)`

**入参** `ClientOpts`：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `capi` | `CapiOpts \| None` | `CapiOpts()` | 腾讯云 API 后端配置（默认后端），见下表 |
| `openapi` | `OpenApiOpts \| None` | — | 传入时改用 WorkBuddy OpenAPI，见下方配置 |
| `timeout` | `int` | `30000` | 单请求超时（毫秒），对两个后端都生效 |
| `transport` | `httpx.AsyncBaseTransport \| None` | — | 配置 OpenAPI 与 ACP 的 HTTP 传输层；对应 Node 侧的 `ClientOpts.fetch` |
| `logger` | `LoggerOpts \| None` | 控制台开启（`warn`） | 日志配置，见[§ 日志](#日志)。`LoggerOpts(enable=False)` 关闭控制台；文件日志需单独配置。 |
| `telemetry` | `TelemetryOpts \| None` | 上报开启 | 运行指标上报，见[§ 上报](#上报)。`TelemetryOpts(enabled=False)` 关闭 |

`CapiOpts`：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `credentials` | `Credentials \| None` | 读环境变量 | 腾讯云 API 凭证；省略则读 `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY` |
| `region` | `str` | `"ap-beijing"` | 腾讯云 API 地域 |
| `endpoint` | `str` | `"workbuddyenterprise.ap-beijing.tencentcloudapi.com"` | 腾讯云 API 接入点域名（不含协议） |
| `api_version` | `str` | `"2026-07-09"` | 云 API 版本号 |

`Credentials(secret_id=..., secret_key=...)`。缺少凭证时构造即抛 `AuthError`；
`logger.level` 传上表以外的值抛 `ValidationError`（错误信息会列出合法取值）。

### `OpenApiOpts`

通过 `ClientOpts(openapi=OpenApiOpts())` 选择 OpenAPI。各字段优先使用显式配置，省略时读取环境变量：

- `enterprise_id: str | None`：企业 ID；环境变量为 `WORKBUDDY_ENTERPRISE_ID`。
- `api_key: str | None`：API key；环境变量为 `WORKBUDDY_API_KEY`。`pt_` 前缀用 `Authorization: Bearer` 头，其余（如 `ck_` 前缀）用 `X-Api-Key` 头。
- `endpoint: str | None`：服务地址（含协议，不含路径），默认 `https://www.workbuddy.cn`。传入时须为 http(s) 根地址，否则构造抛出 `ValidationError`。

缺企业 ID 时构造抛出 `ValidationError`；缺 API key 时抛出 `AuthError`。`capi` 与 `openapi` 只能传其一，同时传入时构造抛出 `ValidationError`。

```python
import asyncio

from managed_agent_sdk import ClientOpts, ManagedAgentClient, OpenApiOpts


async def main() -> None:
    async with ManagedAgentClient(ClientOpts(openapi=OpenApiOpts())) as client:
        page = await client.models.list()
        print(page.items)


asyncio.run(main())
```

逐请求 `headers` 不覆盖 SDK 管理的鉴权头。

所有方法的用法与腾讯云 API 后端相同，出参同样是 PascalCase。新建 Agent 默认不在 WorkBuddy 客户端中显示。

### 属性与方法

| 成员 | 类型 | 说明 |
|------|------|------|
| `region` | `str \| None` | 腾讯云 API 地域；OpenAPI 后端为 `None` |
| `agents` | — | Agent 管理，见 §5 |
| `sessions` | — | 跨 Agent 会话查询，见 §7.1 |
| `models` | — | 平台内置模型查询，见 §4.0 |
| `aclose()` | `async` | 等待上报发送完成并释放客户端资源；会话数据面连接需单独关闭 |

---

## 4.0 `client.models` —— 平台内置模型查询

`model` 字段是**自由字符串，创建时不校验**。填了不存在的模型，Agent 仍能建成，
直到对话时才报错。**`model` 建议从 `models.list()` 的 `ModelId` 里取**：

```python
# ✅ 先查，过滤 ENABLED，取 ModelId
page = await client.models.list()
enabled = [m for m in page.items if m.get("Status") == "ENABLED"]

if not enabled:
    raise RuntimeError("no enabled model available")

agent = await client.agents.create(CreateAgentOpts(
    agent_name="日志分析助手",
    model=enabled[0].get("ModelId"),   # 从可用模型里选，而非写死字符串
    manifest=ManifestBuilder().system_prompt("你是日志分析专家").build(),
))
```

> 想指定某个具体模型？也先用 `models.list()` 确认它在列表里且 `Status == "ENABLED"`，
> 再用它的 `ModelId` —— 模型名拼写、大小写、版本后缀都可能与你的预期不符。

### `client.models.list(opts=None)`

**入参** `PageOpts`（`offset` / `limit`）；**出参** `Page[BuiltinModel]`。

`BuiltinModel`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `ModelId` | `str` | **传给 `agents.create`/`versions.create` 的 `model`** |
| `Name` | `str` | 展示名 |
| `Vendor` | `str` | 厂商 |
| `MaxInputTokens` / `MaxOutputTokens` | `int` | 上下文/输出上限 |
| `SupportsToolCall` | `bool` | 是否支持工具调用 |
| `SupportsImages` | `bool` | 是否支持图像输入。⚠️ **仅表示声明支持** —— 部分声明支持的模型收到图片后仍回复「没有看到图片」，见 [§8 多模态输入](#多模态输入) |
| `Tags` / `Clients` | `list[str]` | 标签 / 适用客户端 |
| `Status` | `str` | **仅 `ENABLED` 可用** |
| `AgentCount` | `int` | 本企业内绑定该模型的 Agent 数 |
| `ServiceEndpoint` | `str` | 模型服务接入点 |
| `DescriptionZh` / `DescriptionEn` | `str` | 描述 |

内置模型数量很少，一页即可取完，所以只提供 `list()`。

---

## 5. Agent 管理

### `client.agents.create(opts)`

**入参** `CreateAgentOpts`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `agent_name` | `str` | ✅ | 长度 2~50 字符（中文按 1 计） |
| `model` | `str \| None` | | 模型标识。**控制面不校验合法性**，建议取 `client.models.list()` 的 `ModelId`，见 §4.0 |
| `manifest` | `dict \| str \| None` | | dict 会自动序列化 |
| `description` | `str \| None` | | |
| `avatar_url` | `str \| None` | | |
| `connector_ids` | `list[str] \| None` | | 绑定的连接器 ID。服务端据此在 `default` 版本的 manifest 里写入 `mcp_servers` 条目，因此 `manifest` 里**不要**再写这些条目。⚠️ **非空时必须同时提供 `manifest`**，否则抛 `ValidationError` |
| `account_id` | `str \| None` | | 绑定的企业账号 ID。**创建时确定、之后不能更换**；必须是当前账号已获授权的企业账号 |

**出参**：`Agent`

服务端会自动创建唯一的 `default` 版本承载 `model` 与 `manifest`。不传 `model` 时 `default` 版本没有模型，
用它对话返回 `stop_reason == "refusal"`。

> ⚠️ 非幂等：重复调用会创建多个同名 Agent。

### `client.agents.get(agent_id, opts=None)`

**入参**：`agent_id: str`、`opts: RequestOpts | None`
**出参**：`Agent`

会请求一次服务端确认 Agent 存在，不存在时抛 `NotFoundError`。读取 Agent 数据用
`agent.info()`。

### `client.agents.list(opts=None)`

**入参**：`PageOpts`
**出参**：`Page[AgentListItem]`

`AgentListItem` 不含 `RoutingSet` / `A2AConfig` /
`ActiveSessionCount`，需要这些字段用 `agent.info()`。字段：`AgentId` / `AgentName` /
`Description` / `AvatarUrl` / `CreatedTime` / `ModifiedTime` / `A2AEnabled` /
`A2AEndpoint` / `A2AStatus` / `PublicApiEnabled` / `PublicApiUrl` / `CreatorUin` /
`SessionCount` / `Model` / `LatestVersionId` / `LatestVersionName`。其中最新版本
的三项让列表场景无需对每个 Agent 再调 `agent.info()`。

手动翻页时用导出的 `MAX_PAGE_LIMIT`（100）作为步长 —— 这个值对所有列表方法都适用：

```python
from managed_agent_sdk import MAX_PAGE_LIMIT, PageOpts

offset = 0
while True:
    page = await client.agents.list(PageOpts(offset=offset, limit=MAX_PAGE_LIMIT))
    for a in page.items:
        print(a["AgentId"])
    offset += len(page.items)
    if not page.items or offset >= page.total_count:
        break
```

### Agent 属性

Agent 实例用来执行操作，只保存 `agent_id`，不缓存 Agent 数据。

| 属性 | 类型 | 说明 |
|------|------|------|
| `agent_id` | `str` | |
| `versions` | `AgentVersions` | §6 |
| `sessions` | `AgentSessions` | §7.2 |
| `a2a` | `AgentA2A` | §9 |
| `external_agents` | `AgentExternalAgents` | §10.1 |

### `agent.info(opts=None)`

读取 Agent 的最新数据，每次调用都请求服务端。

**出参**：`AgentInfo` —— `AgentId` / `AgentName` / `Description` / `AvatarUrl` / `IsDebug` /
`RoutingSet`（未配置时为 `[]`）/ `ActiveSessionCount`（缺省表示没有统计，**不等于 0**）/
`AccountId` / `CreatedTime` / `ModifiedTime` / `A2AConfig`（§9）

```python
info = await agent.info()
print(info.get("AgentName"), info.get("RoutingSet"))
```

### `agent.update(opts)`

**入参** `UpdateAgentOpts`：`agent_name` / `description` / `avatar_url`（均可选，只传要改的）
**出参**：`AgentInfo`，只含部分字段；读取完整数据用 `agent.info()`。

三个字段全为 `None` 时 SDK **本地**抛 `ValidationError`，不发请求。

### `agent.update_routing(routing, opts=None)`

覆盖式设置流量分发。

**入参**：`routing: list[RoutingItem]`，`RoutingItem` 是 `{"VersionId": str, "Weight": float}`

校验规则（不满足时抛 `ValidationError`，不发请求）：

- `VersionId` 必填且不可重复
- `0 < Weight <= 1`
- 所有 `Weight` 之和必须为 `1`（容差 `1e-9`）
- **禁止空列表** —— 服务端不允许用空路由让 Agent 下线。要下线 Agent 请用 `agent.delete()`

**出参**：`AgentInfo`

```python
await agent.update_routing([
    {"VersionId": "ver-1", "Weight": 0.2},
    {"VersionId": "ver-2", "Weight": 0.8},
])
```

> `VersionId` 是字符串 —— 版本 ID 有 19 位，用数字表示可能丢失精度。

### `agent.delete(opts=None)`

**出参**：`None`

> ⚠️ 非幂等：重复删除抛 `NotFoundError`。

---

## 6. 版本管理

### 版本模型

创建 Agent 时服务端自动生成一个初始版本，之后可以用 `versions.create()` /
`create_from_source()` 追加新版本。版本承载配置快照（`model` / `manifest`），
互不影响。

创建版本不等于对外生效，要再调 `agent.update_routing()` 切流量。

### `agent.versions.create(opts)`

**入参** `CreateVersionOpts`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | `str \| None` | | 同 §4.0，建议取 `client.models.list()` 的 `ModelId`。**不继承 `default` 版本的模型**，不传时用该版本对话返回 `stop_reason == "refusal"` |
| `manifest` | `dict \| str \| None` | ✅ | 空值抛 `ValidationError`。要沿用已有版本的 manifest 请用 `create_from_source()` |
| `description` | `str \| None` | | |

**出参**：`Version`

⚠️ **两个「不继承」要留意**：

1. **没有 `connector_ids` 入参** —— 创建版本时不能绑定连接器，
   新版本一律是「无连接器」状态。要带连接器只能两步走：
   ```python
   v = await agent.versions.create(CreateVersionOpts(manifest=m))
   await v.update(UpdateVersionOpts(manifest=m, connector_ids=["conn-1"]))
   ```
2. **manifest 是整体替换，不继承任何现有版本的内容** —— 传进去的就是全部。
   想「基于现有版本改一点」请用 `create_from_source()`，它会连连接器一起沿用。

### `agent.versions.create_from_source(opts)`

基于源版本创建新版本，未传的字段沿用源版本。

**入参** `CreateVersionFromSourceOpts`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source_version_id` | `str` | ✅ | 任意未废弃版本 |
| `model` / `manifest` / `description` | | | 覆盖源版本；未传则沿用。`model` 同 §4.0 取 `ModelId` |

**出参**：`Version`

### `agent.versions.list(opts=None)`

**入参**：`PageOpts`
**出参**：`Page[AgentVersionItem]`

`AgentVersionItem`：
`VersionId` / `VersionName` / `Model` / `Status`（`DRAFT` / `ENABLED` / `DISABLED`）/ `SessionCount` / `CreatedTime` / `ModifiedTime`

### `agent.versions.get(version_id, opts=None)`

**出参**：`Version`

会请求一次服务端确认版本存在，不存在时抛 `NotFoundError`。读取版本数据用
`version.info()`。

### Version 属性

Version 实例用来执行操作，只保存 `version_id`，不缓存版本数据。

| 属性 | 类型 | 说明 |
|------|------|------|
| `version_id` | `str` | |

### `version.info(opts=None)`

读取版本的最新数据，每次调用都请求服务端。

**出参**：`VersionInfo` —— `VersionId` / `AgentId` / `VersionName`（形如 `default` / `test-3` /
`prod-2`）/ `VersionType`（`DEFAULT` / `TEST` / `PROD`）/ `Status`（见下表）/ `Description` /
`Model` / `Manifest`（JSON 字符串）/ `SessionCount` / `CreatedTime` / `ModifiedTime`

**版本状态取值**

| 值 | 含义 |
|----|------|
| `"DRAFT"` | 草稿 |
| `"ENABLED"` | 已启用 |
| `"DISABLED"` | 已停用 |

### `version.update(opts)`

**入参** `UpdateVersionOpts`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `model` | `str \| None` | |
| `manifest` | `dict \| str \| None` | |
| `description` | `str \| None` | |
| `connector_ids` | `list[str] \| None` | 腾讯云 API 后端的连接器，该版本最终要绑的完整集合，见下 |
| `console_connectors` | `list[ConsoleConnectorRef] \| None` | 管理台登记的连接器，仅 OpenAPI 后端可用，见下 |

`connector_ids` 是**三态**语义：

| 传值 | 含义 |
|---|---|
| 省略（`None`）| 本次不改动连接器绑定 |
| `[]` | **解绑全部** |
| `["conn-1"]` | 最终只绑 `conn-1`，其余一律解绑 |

服务端按本列表做全量覆盖 —— **解绑直接从列表里去掉即可**，不需要自己改 manifest。
manifest 里自己声明的 MCP 服务与 A2A 出站条目 `a2a-agents` 不受影响，回传 manifest 时原样保留。

`console_connectors` 选中管理台登记的连接器，元素是
`ConsoleConnectorRef(name, credential_id=None, credential_type=None)`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | `str` | 连接器目录（`connectors.list()`）条目的 `Name` 字段，全局唯一 |
| `credential_id` | `str \| None` | 绑定的凭证 ID；省略则不绑定凭证 |
| `credential_type` | `str \| None` | 凭证类型（如 `"API_KEY"`）；省略时由服务端按连接器的鉴权方式推断 |

```python
await v.update(
    UpdateVersionOpts(
        console_connectors=[ConsoleConnectorRef(name="finenter", credential_id="cred-1")]
    )
)
```

三态语义与 `connector_ids` 一致（省略 = 不改动，`[]` = 解绑全部管理台
连接器，非空 = 全量覆盖）。它与 `connector_ids` 互相独立，两个
列表可以在同一次调用里同时出现。

该字段只在 OpenAPI 后端可用，在腾讯云 API 后端上使用会在本地抛 `ValidationError`。

**出参**：`VersionInfo`，只含部分字段；读取完整数据用 `version.info()`。

全部字段为 `None` 时抛 `ValidationError`。`connector_ids`、`console_connectors` 都计入可更新字段，可以只改连接器。

`PROD` 版本内容已冻结，修改时服务端拒绝并抛 `ConflictError`。

### 读取 manifest

`Manifest` 是 JSON 字符串，读取时自行解析：

```python
import json

v = await agent.versions.get("ver-xxx")
manifest = json.loads((await v.info()).get("Manifest") or "{}")
```

---

## 7. 会话管理

### 7.1 跨 Agent

#### `client.sessions.get(session_id, opts=None)`

**出参**：`Session`，**可直接用于数据面**。

会请求一次服务端确认会话存在并取得所属 `AgentId`，不存在时抛
`NotFoundError`。读取会话数据用 `session.info()`。

#### `client.sessions.list(opts=None)`

**入参**：`PageOpts`。返回全租户的会话，只要某个 Agent 的会话用 `agent.sessions.list()`
**出参**：`Page[SessionItem]`

`SessionItem`：`SessionId` / `SessionName` / `AgentId` / `AgentName` / `VersionId` / `VersionName` / `Status` / `Creator` / `Source` / `CreatedTime` / `ModifiedTime`

`Source` 取值：`CLOUD` / `CHANNEL` / `SCHEDULED_TASK` / `A2A`

### 7.2 本 Agent

#### `agent.sessions.create(opts=None)`

**入参** `CreateSessionOpts`：`version_id`（可选，不传则按 routing 分流）
**出参**：`Session`

> ⚠️ **非幂等，且沙箱不会自动回收** —— 每次调用都拉起一个真实沙箱。网络超时后重试前，先用 `list()` 确认是否已创建成功。
>
> 会话**没有**销毁接口，也**没有**空闲超时回收。`session.disconnect()`
> 只断 ACP 连接，会话与沙箱仍在服务端存活。循环建会话会持续堆积资源 ——
> 应当**复用同一会话**（配置变更用 `migrate()` 热更新，不必重建）。删除 Agent 时，它的版本与会话一并删除。

#### `agent.sessions.list(opts=None)`

**出参**：`Page[SessionItem]`，只返回本 Agent 的会话。

### 7.3 Session 属性

Session 实例保存会话标识与 ACP 连接，不缓存会话数据。

| 属性 | 类型 | 说明 |
|------|------|------|
| `session_id` | `str` | |
| `agent_id` | `str` | 所属 Agent |
| `connection_state` | `str` | ACP 状态，未建连时 `"CLOSED"` |

### `session.info(opts=None)`

读取会话的最新数据，每次调用都请求服务端。

**出参**：`SessionInfo` —— `SessionId` / `SessionName` / `Status` / `AgentId` / `AgentName` / `VersionId` / `VersionName` / `Creator` / `Source` / `EndpointSet` / `CreatedTime` / `ModifiedTime`

> 取接入点地址用 `EndpointSet[0].Url`，**不要手工拼域名**。

### `session.messages(opts=None)`

查询对话消息（含 token 用量）。

**入参** `MessageListOpts`：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `offset` | `int \| None` | `0` | |
| `limit` | `int \| None` | `20` | **上限 100**，超出本地抛 `ValidationError` |
| `event_types` | `list[str]` | `[]` | 如 `["USER", "ASSISTANT"]` |

**出参**：`Page[MessageEvent]`

`MessageEvent` 按 `EventType` 区分：

| 字段 | 类型 | 说明 |
|------|------|------|
| `Sequence` | `int` | 会话内序号 |
| `EventType` | `"USER" \| "ASSISTANT" \| "TOOL"` | |
| `OccurredAt` | `str` | RFC3339 |
| `Message` | `Message` | 仅 `USER` / `ASSISTANT` |
| `ToolCall` | `ToolCall` | 仅 `TOOL` |

`Message`：`Content`（已对凭证与内部路径脱敏，仍应按不可信文本安全渲染）/ `TokenUsage`（**仅该轮最后的 `ASSISTANT` 携带**，见下）

`ToolCall`：`ToolCallId` / `ToolName` / `Status`（`PENDING`/`IN_PROGRESS`/`SUCCEEDED`/`FAILED`）/ `Input` / `Output`（JSON 字符串）/ `StartedAt` / `EndedAt` / `DurationMs`

`TokenUsage`：`InputTokens` / `OutputTokens` / `TotalTokens` / `Scope`（`TURN` = **整轮累计**，不可归因到单个工具调用，也不可与同轮其它分段相加）

```python
page = await session.messages(MessageListOpts(event_types=["TOOL"]))
for e in page.items:
    if e["EventType"] == "TOOL":
        print(e["ToolCall"]["ToolName"], e["ToolCall"]["Status"])
    else:
        print(e["Message"]["Content"])
```

#### 读 token 用量

两个来源，给的东西不同，别混用：

| 来源 | 有没有 | 给的是什么 |
|------|--------|-----------|
| `session.prompt()` 的返回值（`usage`） | ✅ | **本轮消耗**（input/output/缓存细节 + 实际模型），最及时 |
| `session.messages()` 的 `Message["TokenUsage"]` | ✅ | **按轮次累计的用量**，做历史对账用 |
| ACP `usage_update` 通知 | ✅ | **当前上下文水位**（`used` / `size` / `cost`），做水位提示用 |
| `session.info()` | ❌ | 出参无 token 字段 |

`usage_update` 经 `subscribe()` / `on_chunk` 的通知通道下发，字段见
[§8 `session.subscribe`](#sessionsubscribelistener)。做计费用 `prompt()` 返回值的
`usage`（及时）或 `session.messages()`（对账）—— `usage_update` 的 `used`
是上下文占用，不是本轮消耗。

⚠️ **不是每个 `ASSISTANT` 事件都带 `TokenUsage`。** 一轮对话可能分段输出多个
`ASSISTANT` 事件，只有该轮**正常结束**时的最后一个事件带用量，数值是整轮累计。
所以**按「有没有 `TokenUsage`」筛选，就等于按轮次统计**：

```python
page = await session.messages(MessageListOpts(limit=100))

# 每个 TokenUsage 代表一个完整轮次
turns = [u for e in page.items if (u := e.get("Message", {}).get("TokenUsage"))]
total = sum(u.get("TotalTokens", 0) for u in turns)
print(f"{len(turns)} 轮，共 {total} tokens")
```

`event_types=["ASSISTANT"]` 仍可用来减少传输量，但过滤后**不代表每条都有用量**。

⚠️ **轮次没有正常结束时不记录用量** —— 模型向用户提问、工具调用失败、用户取消都属于这种情况。
因此**求和结果会低于实际消耗**，用于计费或配额时要考虑这一点。

### `session.migrate(version_id, opts=None)`

把会话迁移到指定版本，**原沙箱热更新配置** —— `session_id`、沙箱、已建立的 ACP 连接都不变，用户无感。典型场景是「改完 Agent 配置，让运行中的测试会话立即生效」，不必重建会话丢上下文。

**出参**：`SessionInfo`，只含部分字段，不一定包含 `VersionId`；确认迁移结果用
`session.info()`。

约束：

- 目标版本必须属于**同一 Agent**
- 目标版本不能已废弃
- 仅 `ACTIVE` / `IDLE` / `FAILED` 可迁移；`MIGRATING` 抛 `ConflictError`

> `FAILED` 也允许迁移 —— 配置写错导致启动失败时，改完可直接救回原会话。

⚠️ **迁移不会重新加载沙箱内已连接的 MCP 服务** —— 把会话从「带连接器」的版本迁到
没有连接器的版本后，原连接器仍在沙箱里，`session.info()` 却已显示新的 `VersionId`。

所以 `migrate()` 能热更新的是 `model` / `system_prompt` 这类**纯配置**；
**增删连接器必须新建会话**才生效。

---

## 8. 对话（数据面）

数据面走 ACP 协议，调用顺序是 `connect()` → `prompt()`。

### 数据面凭证

对话使用的凭证由 SDK 用控制面凭证自动换取，并在内部缓存、临近过期时刷新，调用方无需处理。
两种控制面后端都是如此。

建连时 SDK 从会话信息里取接入点地址（`session.info()` 的 `EndpointSet`），**不要自行拼接地址**。
会话没有可用接入点时 `connect()` 抛 `ValidationError`。

### `session.connect(opts=None)`

**幂等** —— 已连接时直接返回。`prompt` 会自动确保连接就绪，一般无需手工调用；显式调用适合「先建连再订阅」。

**入参**：`ConnectOpts`

| 字段 | 默认 | 说明 |
|------|------|------|
| `headers` | — | 追加请求头 |
| `acp_token` | — | 显式指定数据面凭证（缺省由 SDK 自动获取） |
| `auto_refresh_token` | `True` | 凭证临近过期时自动刷新 |
| `initialize` | `True` | 建连后立即发送协议初始化 |
| `last_event_id` | — | 断线续传起点，通常无需手工传 |
| `reconnect_backoff_ms` | `300` | 重连初始等待时长 |
| `reconnect_max_backoff_ms` | `30000` | 重连最大等待时长 |
| `reconnect_max_attempts` | `inf` | 最大重连次数 |
| `heartbeat_timeout_ms` | `45000` | 心跳超时 |

会话没有可用接入点时抛 `ValidationError`。

### `session.prompt(input, opts=None)`

**入参**

| 参数 | 类型 | 说明 |
|------|------|------|
| `input` | `str \| list` | 传字符串时 SDK 包成 `[{"type": "text", "text": ...}]`；传 list 支持多模态，见[下节](#多模态输入) |
| `opts.on_chunk` | `Callable` | 流式增量回调 |
| `opts.cancel_event` | `asyncio.Event` | 置位时向服务端发取消 |
| `opts.on_question` | `Callable[[QuestionRequest], Awaitable[QuestionAnswer]]` | Agent 向用户提问时触发，返回用户的回答，见[下节](#向用户提问) |
| `opts.trace_id` | `str \| None` | 本轮 trace id（32 位小写 hex，非全 0）；不传时 SDK 自生成，格式不合法抛 `ValidationError` |
| `opts.telemetry` | `TurnTelemetryOpts \| None` | 本轮上报上下文，见[§ 上报](#上报) |
| `opts.mcp_key` | `dict[str, Any] \| None` | 连接器的动态 API Key，见[下节](#连接器动态-api-key) |

**出参**：`PromptResponse`（`managed_agent_sdk.acp_types`）

| 字段 | 类型 | 说明 |
|------|------|------|
| `stop_reason` | `str` | 本轮结束原因，如 `end_turn` |
| `refusal` | `RefusalReason \| None` | 仅 `stop_reason == "refusal"` 时可能有值，见下 |
| `trace_id` | `str` | 本轮的 W3C trace id；`prompt()` 正常返回时可用于检索服务端链路。请求抛出异常时没有返回值。 |
| `usage` | `UsageInfo \| None` | 本轮 token 消耗，服务端下发时有值，见下 |

**`UsageInfo`** —— 本轮 token 消耗。字段
全部可选：`input_tokens` / `output_tokens` / `total_tokens` /
`thought_tokens` / `cached_read_tokens` / `cached_write_tokens`（缓存命中，
计费折扣依据），以及 `model`（实际使用的模型，`model="auto"` 时有用）与 `request_id`（请求 ID，与 `refusal.request_id` 同一类）。

⚠️ `input_tokens` 包含 manifest 与系统提示词 —— 一句用户输入对应近 2 万
input token 是正常的，成本预估按这个量级算。

**`RefusalReason`** —— 被拒绝的结构化原因：

| 字段 | 类型 | 说明 |
|------|------|------|
| `category` | `str \| None` | 分类，如 `rate_limit` / `internal`。可能新增取值，**不要只匹配已知取值** |
| `details` | `str \| None` | 面向人的完整描述，可直接展示。例：`"429 企业总额度已全部用尽，请联系企业管理员购买加量包。"` |
| `request_id` | `str \| None` | 请求 ID，报告问题时带上它 |
| `status_code` | `int \| None` | HTTP 状态码，如 `429` |
| `source` | `str \| None` | 产生拒绝的服务组件 |

```python
res = await session.prompt("...")
if res.stop_reason == "refusal" and res.refusal:
    # 每个字段都可能是 None
    print(res.refusal.category, res.refusal.details, res.refusal.request_id)
```

> 即使 `stop_reason == "refusal"`，`refusal` 也**可能为 `None`**。判断原因时 `details` 比 `category` 更可靠。
> SDK 同时会记一条 `warning` 日志，含分类与 `request_id`。

> **回复文本不在返回值里**。两种读取方式：
> 用 `on_chunk` / `subscribe` 接收增量，或在本轮结束后调 `session.messages()`
> 按 `EventType == "ASSISTANT"` 取 `Message["Content"]`。

同一会话的并发 `prompt` 会**自动排队**。

> **没有请求超时** —— `prompt` 在服务端不响应时会一直等待。需要上限用
> `asyncio.wait_for(...)` 或 `PromptOpts(cancel_event=...)`，后者置位时 SDK 会向
> 服务端发取消。

需要拼出完整回复时，把片段收集到列表里：

```python
parts: list[str] = []


def collect(n) -> None:
    update = n.update
    if update.session_update == "agent_message_chunk" and update.content.type == "text":
        parts.append(update.content.text)


res = await session.prompt("你好", PromptOpts(on_chunk=collect))
print("".join(parts), res.stop_reason)
```

### 向用户提问

模型调用 `AskUserQuestion` 工具时，Agent 会暂停本轮，等待用户回答。SDK 把提问交给
`opts.on_question`，用它的返回值回复 Agent。不传 `on_question` 时 SDK 一律回复跳过。

**`QuestionRequest`**

| 字段 | 类型 | 说明 |
|------|------|------|
| `tool_call_id` | `str \| None` | 与流式通知里 `AskUserQuestion` 工具调用的 `tool_call_id` 相同 |
| `questions` | `list[QuestionItem]` | 题目，通常 1～4 道 |

**`QuestionItem`**

| 字段 | 类型 | 说明 |
|------|------|------|
| `key` | `str` | 作答键：`q_0`、`q_1`……按题目顺序编号 |
| `question` | `str` | 题目文本；模型没填时依次取 `header`、`Q1` 这样的序号 |
| `header` | `str \| None` | 题目的简短标签 |
| `options` | `list[QuestionOption]` | 选项（`label` 与可选的 `description`）。为空时这道题只能由用户直接输入文字 |
| `multi_select` | `bool` | 是否允许多选 |

**`QuestionAnswer`**

| 取值 | 说明 |
|------|------|
| `QuestionAnswer(type="submit", answers=...)` | 提交回答。`answers` 以 `key` 为键，单选题给字符串，多选题给字符串列表；用户也可以直接输入文字。没有出现在 `answers` 里、或者内容为空的题，SDK 回传 `未回答` |
| `QuestionAnswer(type="skip")` | 用户不回答，Agent 用已有信息继续本轮 |

```python
from managed_agent_sdk import PromptOpts, QuestionAnswer, QuestionRequest

async def on_question(req: QuestionRequest) -> QuestionAnswer:
    # 展示表单，等用户提交
    answers = await show_question_form(req.questions)
    if answers is None:
        return QuestionAnswer(type="skip")
    return QuestionAnswer(type="submit", answers=answers)

res = await session.prompt("帮我规划一个项目", PromptOpts(on_question=on_question))
```

- 本轮结束或被停止（`cancel_event` 置位、`prompt()` 所在 task 被取消）时，回调所在的 task
  会被取消，回调里的 `await` 抛出 `asyncio.CancelledError`。
- 回调抛异常，或返回的回答不合法（不是 `QuestionAnswer`、`answers` 里有不存在的键、值类型
  不对、单选题给了多个值），SDK 向服务端发取消，`prompt()` 抛出该异常（回答不合法时是
  `ValidationError`）。
- 网络短暂中断时 SDK 仍能收到提问，同一次提问只调用一次 `on_question`。

### 多模态输入

`input` 传 block 列表即可在一轮对话里混合文本、图片与文件引用。block 可以传 `dict`，
也可以传 `acp.schema` 里的 Pydantic 模型。可用的三个类型：

| 子类 | 关键字段 |
|------|---------|
| `text` | `text: str` |
| `image` | `data: str`（base64，**不带 `data:` 前缀**）、`mime_type: str`、`uri: str \| None` |
| `resource_link` | `uri: str`（仅公网 http(s)）、`name: str`、`mime_type` / `size` / `title` 可选 |

> 传 `dict` 时 `mime_type` 与 `mimeType` **两种 key 都可用**。

发图片：

```python
res = await session.prompt([
    {"type": "text", "text": "这张图片是什么颜色？"},
    {"type": "image", "data": png_base64, "mime_type": "image/png"},
])

# 传 Pydantic 模型等价
from acp.schema import ImageContentBlock, TextContentBlock

res = await session.prompt([
    TextContentBlock(type="text", text="这张图片是什么颜色？"),
    ImageContentBlock(type="image", data=png_base64, mime_type="image/png"),
])
```

发文件（md / json / txt 等）有两种方式：

```python
# ① 小文件：内容内联进 text
content = Path("config.json").read_text(encoding="utf-8")
await session.prompt(
    f'告诉我 buildId 的值：\n\n<file name="config.json">\n{content}\n</file>'
)

# ② 大文件：resource_link 指向公网 URL，服务端下载后交给 Agent 读
await session.prompt([
    {"type": "text", "text": "这个 JSON 里 name 字段的值是什么？"},
    {
        "type": "resource_link",
        "uri": "https://example.com/pkg.json",
        "name": "pkg.json",
        "mimeType": "application/json",
    },
])
```

`resource_link` 的两条要求：

- **`uri` 必须是公网可访问的 http(s) URL** —— `file://` 与内网地址都不行。
- **单文件上限 100 MiB。**

> 没有「向沙箱上传文件」的接口，文件内容只能用上面两种方式传。

发图片时要注意三点：

- **`SupportsImages` 只是声明** —— 部分声明支持图片的模型收到图片后仍回复「没有看到图片」，且 `stop_reason` 仍是 `end_turn`。
  **光看 `stop_reason` 判断不出图片是否生效**，选定模型后请先用一张图片测试
- **模型按版本生效** —— 会话使用哪个版本，就用那个版本的 `model`：`agents.create(CreateAgentOpts(model=...))` 写到 `default` 版本，
  `versions.create(CreateVersionOpts(model=...))` 写到新建的版本。确认会话所用版本的模型能读图
- **base64 必须是完整有效的图片** —— 残缺图片会被拒绝，表现为 `stop_reason == "refusal"`

### 连接器动态 API Key

连接器调用外部服务需要的 API Key 随用户或租户变化时，在每轮 `prompt` 时用 `PromptOpts(mcp_key=...)` 传入。
SDK 把它原样放进本轮 `session/prompt` 请求的 `params._meta["X-MCP-Key"]` 发给服务端，不解析、不校验其中的内容。

```python
from managed_agent_sdk import PromptOpts

await session.prompt(
    "查一下我本月的订单",
    PromptOpts(mcp_key={"key1": user_api_key, "tenant_id": "tenant-9"}),
)
```

- 值是一个 `dict`，里面的键名和取值由连接器决定，SDK 不做限制。
- 只对本轮生效，SDK 不在多轮之间保存。后续每轮需要时都要再传。
- 不传时请求里不带 `_meta` 字段。
- 它是密钥，请从服务端安全来源读取，不要写在前端代码或日志里。

### `session.subscribe(listener)`

**入参**：`listener: Callable[[SessionNotification], None]`
**出参**：`Callable[[], None]`（退订函数）

要求**先 `connect()`**，否则抛 `ValidationError`。

Listener 收到 `SessionNotification` 原样，不聚合、不改造。

`update.session_update` 的取值：

| 取值 | 含义 |
|------|------|
| `agent_message_chunk` | Assistant 回复增量 |
| `agent_thought_chunk` | Assistant 思考过程增量 |
| `user_message_chunk` | 用户消息内容 |
| `tool_call` / `tool_call_update` | 工具调用开始 / 状态更新 |
| `plan` / `plan_update` / `plan_removed` | 计划事件 |
| `available_commands_update` | 可用命令变化 |
| `current_mode_update` | 当前模式变化 |
| `config_option_update` | 配置项变化 |
| `session_info_update` | 会话信息变化 |
| `usage_update` | 上下文水位更新 |

`usage_update` 的字段：

| 字段 | 含义 |
|------|------|
| `used` | **当前上下文占用的 token**，不是本轮消耗 |
| `size` | 上下文窗口总大小 |
| `cost` | 会话累计成本（`amount` + `currency`），可选 |
| `input_tokens` / `output_tokens` | 本轮输入 / 输出 |
| `cached_read_tokens` / `cached_write_tokens` | 缓存读 / 写命中 |
| `model` | 实际使用的模型 |

拿它做水位提示（`used / size`）是合适的；**做计费统计用 `prompt()` 返回值的
`usage`**，见 [§7.3 读 token 用量](#读-token-用量)。

> `used`（水位）与 `input_tokens`（本轮）数值一致是正常的 —— 前者表示上下文占用，后者表示本轮输入。

以上字段在订阅回调里都直接以属性访问，如 `update.input_tokens`、`update.model`。

### `session.cancel()`

取消进行中的对话。幂等，未建连时为空操作。

| 观察点 | 结果 |
|------|------|
| 是否真的停止 | ✅ 调用后不再产生新的 `agent_message_chunk` |
| `cancel()` 自身耗时 | 约 2 秒，**不是立即返回** |
| `prompt` 的 `stop_reason` | **`"end_turn"`**，不是 `"cancelled"` |

⚠️ **不要用 `stop_reason == "cancelled"` 判断是否取消成功** —— 目前返回的是
`end_turn`，与正常结束无法区分。需要判断时请在调用
`cancel()` 前自行设置一个标记。

### `session.set_model(model_id)`

切换本会话模型。

> **实验性** —— 底层协议尚未稳定。

### `session.disconnect()`

断开连接，**不影响服务端会话本身**，可重新 `connect()`。

---

## 9. A2A Inbound

### 读取配置：`(await agent.info())["A2AConfig"]`

A2A 配置在 `AgentInfo` 的 `A2AConfig` 字段里（类型 `A2AConfig`）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `A2AEnabled` | `bool` | 配置里是否开启 |
| `A2APublicRef` | `str` | 对外标识，已注册时非空 |
| `A2AEndpoint` | `str` | 对外 A2A 地址（Agent Card 获取地址），已注册时非空 |
| `A2AStatus` | `str` | `DRAFT` / `REGISTERED` / `DISABLED` / `NONE` / `UNKNOWN` |

`A2AEnabled` 与 `A2AStatus` **含义不同**：前者是你在配置里的设置，后者是实际注册状态。注册由 `a2a.update()` 的 `enabled` 开关**直接触发**，不需要发布版本 —— 开启后一次调用即 `REGISTERED` 并分配 `A2AEndpoint`。

状态流转：

| 时机 | `A2AEnabled` | `A2AStatus` |
|------|------|------|
| 从未开启 | `False` | `"NONE"` |
| `update(UpdateA2AOpts(enabled=True))` 后 | `True` | `"REGISTERED"` |
| `update(UpdateA2AOpts(enabled=False))` 后 | `False` | `"DISABLED"` |

`NONE`（从未注册）与 `DISABLED`（注册过又关掉）含义不同；`UNKNOWN` 表示查询注册状态失败。
`A2APublicRef` / `A2AEndpoint` 一旦分配即长期保留，停用后仍会返回 —— **判断能否对外调用要看 `A2AStatus`，不能看 `A2AEndpoint` 是否非空**。

> 四个 `A2A*` 字段在 **`AgentInfo["A2AConfig"]`** 里，
> 直接读取 `info["A2AEnabled"]` 会 `KeyError`。`a2a.update()` 的返回值包含完整四个字段；
> 其它写接口（`agent.update()` / `update_routing()`）的返回值里 `A2AConfig` 可能不全，
> 读取 A2A 配置用 `agent.info()`。

> 技能清单不在 `A2AConfig` 里返回，要读取版本的 `Manifest` 后取 `a2a.skills`：
>
> ```python
> v = await agent.versions.get(default_version_id)
> manifest = json.loads((await v.info()).get("Manifest") or "{}")
> skills = manifest.get("a2a", {}).get("skills")
> ```

### `agent.a2a.update(opts)`

**入参** `UpdateA2AOpts`：

| 字段 | 类型 | 语义 |
|------|------|------|
| `enabled` | `bool \| None` | **`None` = 不修改**；`False` 关闭 A2A 但保留已宣告的技能 |
| `skills` | `list[A2ASkill] \| None` | **`None` = 不修改；`[]` = 清空** |

`A2ASkill(id, name, description=None, tags=None, examples=None, input_modes=None, output_modes=None)`

**出参**：`AgentInfo`

---

## 10. A2A Outbound

让自己的 Agent 调用外部 A2A Agent。**入口只有一个**：`agent.external_agents`。

> **外部 Agent 从哪来** —— 它们在 **Agent Registry** 注册与管理，SDK 与控制台都不提供注册和注销。
> SDK 负责「把已注册的外部 Agent 绑到自己的 Agent 上」。
> 因此查询列出的是**企业内已注册**的 A2A Agent；新接入的外部 Agent 若不在列表里，
> 说明它还没在 Registry 注册完成。
>
> 注销外部 Agent 会删除企业内**所有** Agent 对它的绑定，且无法恢复。
> 外部 Agent 的凭证暂不支持修改，只能「注销 + 重新注册」。生产环境请谨慎。

### 10.1 `agent.external_agents`

| 方法 | 入参 | 出参 |
|------|------|------|
| `bind(a2a_agent_id, opts=None)` | `str`、`BindExternalAgentOpts \| None` | `BindResult(binding_id=..., status=...)` |
| `unbind(binding_id, opts=None)` | `str`、`UnbindExternalAgentOpts \| None` | `UnbindResult(status=...)` |
| `list(opts=None)` | `ListExternalAgentsOpts \| PageOpts \| None` | `Page[ExternalAgentInfo]`（默认 `bound="BOUND"`） |
| `get(a2a_agent_id, opts=None)` | `str`、`RequestOpts \| None` | `ExternalAgentInfo` |

#### 怎么找「可以绑定」的外部 Agent

用 `list()` 的 `UNBOUND` 视图：

| `bound` | 含义 |
|---------|------|
| `"BOUND"`（默认） | 已绑定到本 Agent 的 |
| `"UNBOUND"` | **尚未绑定的 —— 从这里挑一个传给 `bind()`** |
| `"ALL"` | 已绑定与未绑定的全部 |

```python
# 找这个版本下还能绑谁
candidates = await agent.external_agents.list(
    ListExternalAgentsOpts(bound="UNBOUND", version_id=version_id, limit=20)
)

result = await agent.external_agents.bind(
    candidates.items[0]["A2AAgentId"],
    BindExternalAgentOpts(version_id=version_id),   # ← 与查询用同一个版本
)
```

⚠️ **务必带 `version_id`** —— 绑定按版本区分，不传则按 `default` 版本判断：已绑到**其它版本**的条目
会照样出现在 `UNBOUND` 结果里，不要拿它们再次 `bind()`。

> 列表会**排除 Agent 自身**（即便自己已开启 A2A 并注册过，也不出现在可选列表里）。
>
> 传普通 `PageOpts`（无 `bound` / `version_id` 字段）时按 `BOUND` 视图查询。

⚠️ **`get()` 只能查到 `default` 版本上的绑定** —— 它不接受 `version_id`。绑到其他版本的
条目调 `get()` 会抛 `NotFoundError`。

这个报错**不代表绑定失败** —— 用 `list(ListExternalAgentsOpts(bound="BOUND", version_id=...))`
仍能查到。要查其他版本的绑定详情，用 `list()` 后自行按 `A2AAgentId` 筛选。

`BindExternalAgentOpts` / `UnbindExternalAgentOpts` / `ListExternalAgentsOpts` 的
公共字段 `version_id`：指定绑定在父 Agent 的哪个版本上，**缺省为 `default` 版本**。
要绑到其他版本上必须显式传 `version_id`，否则读起来像没绑上。指定已发布的版本会直接改变该版本的运行行为。

⚠️ **`unbind()` 必须传与 `bind()` 相同的 `version_id`**。以下三种情况都抛同一个
`NotFoundError`（`retryable=False`），**无法从错误区分是哪种**：

| 情况 | 结果 |
|------|------|
| 重复解绑（已解过） | `NotFoundError` —— **不幂等** |
| `binding_id` 不存在 | `NotFoundError` |
| 绑在其他版本上却省略 `version_id` | `NotFoundError` |

所以解绑前用 `list(ListExternalAgentsOpts(bound="BOUND", version_id=...))`
确认状态，不要靠捕获异常判断。

`ListExternalAgentsOpts` 额外支持 `bound: Literal["BOUND", "UNBOUND", "ALL"]`
（默认 `BOUND`）：`ALL` 返回全部（已绑定 + 未绑定）。

`ExternalAgentInfo`：`A2AAgentId` / `BindingId`（仅已绑定）/ `Name` / `Description` / `IconUrl` / `Endpoint` / `A2AVersion` / `A2ASkillSet` / `Bound`

`Bound` 不一定返回：

| 查询方式 | `Bound` 的值 |
|------|------|
| `list(ListExternalAgentsOpts(bound="BOUND", version_id=...))` | 全部为 `True` |
| `list(ListExternalAgentsOpts(bound="ALL", version_id=...))` | 已绑定项为 `True`，未绑定项是 `None` |
| `bound="UNBOUND"` | 不返回 |
| **任意视图但不传 `version_id`** | 不返回 |

**判断绑定状态用 `is_bound(item)`**，不要直接写 `if item.get("Bound")`：

```python
from managed_agent_sdk import is_bound

page = await agent.external_agents.list(
    ListExternalAgentsOpts(bound="ALL", version_id=version_id)
)
bound = [x for x in page.items if is_bound(x)]
```

它在 `Bound is True` **或** `BindingId` 非空时返回 `True`。

⚠️ 它**不能区分「未绑定」与「查询时没传 `version_id`」** —— 后者两个字段都
不返回，同样得到 `False`。查询务必带 `version_id`。

凭证不会返回。`unbind` 用 `bind` 返回的 `binding_id`。

---

## 11. 目录资源查询（连接器 / 技能 / 专家）

这三类是**平台上已存在的资源**，SDK 只能查询：查到 ID 后配置到 Agent 或版本上。
创建与管理请到控制台操作。

### 11.0 三者的配置入口互不相同

这是最容易搞错的地方 —— **连接器不写进 manifest，技能和专家只能写进 manifest**：

| 资源 | 查询 | 配置入口 | 最终位置 |
|---|---|---|---|
| 连接器 | `client.connectors.list()` | `version.update()` 的 `connector_ids` | manifest 的 `mcp_servers`（由服务端写入） |
| 技能 | `client.skills.list()` | `ManifestBuilder.skills()` | manifest 的 `skills` |
| 专家 | `client.experts.list()` | `ManifestBuilder.experts()` | manifest 的 `experts` |

连接器只传 ID，条目由服务端写入。**自己再往 manifest 里写 `mcp_servers` 会重复**。

⚠️ **连接器凭证失效会阻断整个对话** —— 绑定一个 `Status: "ACTIVE"` 但凭证
已失效的连接器后，`prompt()` 不再回答任何问题，只回复：

```
连接器 **<slug>** 凭据校验被拒绝，请联系管理员排查。
```

`stop_reason` 仍是 `"end_turn"`，**从返回值看不出失败**。两点要注意：

1. **`ConnectorItem["Status"]` 不反映凭证是否可用** —— `ACTIVE` 只表示连接器本身已启用
2. 这与「skill / expert ID 不存在」完全不同 —— 后者只是缺少该能力，对话正常；
   连接器凭证失效会**阻断整个对话**

排查时先去掉连接器，新建一个会话对比（`migrate()` 不会重新加载连接器，必须新建会话）。

出参的 `Source`（`BUILTIN`）转成小写后就是 manifest 里的 `type`（`builtin`）。

⚠️ 服务端**不检查** skill / expert ID 是否存在。填了不存在的 ID 依然创建成功，但该能力在运行时缺失，
只能在对话时发现 —— ID 建议直接取自 `list()` 的返回，不要手写。

完整流程：

```python
# 1. 查询
skills = await client.skills.list("BUILTIN", ListSkillsOpts(limit=50))
experts = await client.experts.list("BUILTIN")
connectors = await client.connectors.list_active()

# 2. 配置
agent = await client.agents.create(
    CreateAgentOpts(
        agent_name="运维助手",
        manifest=(
            ManifestBuilder()
            .system_prompt("你是运维助手")
            .skills([{"type": "builtin", "id": s["SkillId"]} for s in skills.items])
            .experts([{"type": "builtin", "id": e["ExpertId"]} for e in experts.items])
            .build()
        ),
        # 连接器单独传入，不写进 manifest
        connector_ids=[c["ConnectorId"] for c in connectors.items],
    )
)
```

### 11.1 `client.connectors.list(opts=None)`

腾讯云 API 后端返回当前账号的连接器，**没有企业 ID 入参**。

OpenAPI 后端返回管理台登记的连接器，条目没有 `ConnectorId` / `ConnectorSlug` / `ConnectorKey`，
多出 `DisplayName`、`HeaderMappings`、`UnbindableReason`。这些连接器按 `Name` 用
`version.update(UpdateVersionOpts(console_connectors=...))` 绑定，见 [§6 version.update](#versionupdateopts)；§11.0 与 §11.3 的 `connector_ids` 用法只适用于腾讯云 API 后端。

**入参** `PageOpts`：`offset` / `limit`

**出参** `Page[ConnectorItem]`。`ConnectorItem` 的三个标识不要混用：

| 字段 | 说明 |
|---|---|
| `ConnectorId` | 连接器 ID，跨版本不变 —— **配置时用这个** |
| `ConnectorSlug` | 等于 manifest 里 `mcp_servers` 条目的 `name` |
| `ConnectorKey` | **版本级** key（含 `-v{N}` 后缀），不要自己拼 |
| `Name` / `Description` / `AvatarUrl` | |
| `Source` | `ENTERPRISE_AGENT` / `ASSISTANT` |
| `EnterpriseId` | 所属企业 ID |
| `Type` | `MCP_SERVER` / `A2A` / `API_SERVICE` |
| `ServiceUrl` | |
| `AuthModes` | `list[str]`，取值 `NONE` / `ONEID` / `OAUTH2_IDP` |
| `LatestVersionNo` | `int` |
| `Status` | `ACTIVE` / `DISABLED` |
| `CreatorId` / `CreatedTime` / `ModifiedTime` | |

### 11.2 `client.connectors.list_active(opts=None)`

只取状态为 `ACTIVE` 的连接器，入参同 `list()`。
`DISABLED` 的连接器绑上去不生效，绝大多数场景要用这个方法。

### 11.3 改连接器绑定

`connector_ids` 是该版本最终要绑的完整集合，服务端按它做全量覆盖：

```python
# 当前绑了 conn-1 / conn-2，只想留 conn-1
await v.update(UpdateVersionOpts(connector_ids=["conn-1"]))

# 解绑全部
await v.update(UpdateVersionOpts(connector_ids=[]))

# 只改别的、不动连接器绑定 —— 省略即可
await v.update(UpdateVersionOpts(model="m-2"))
```

回传 manifest 时**不需要**为连接器做任何处理：

```python
v = await agent.versions.get(version_id)
mft = json.loads((await v.info()).get("Manifest") or "{}")
mft["system_prompt"] = "改点东西"
await v.update(UpdateVersionOpts(manifest=mft, connector_ids=["conn-1"]))
```

自己声明的 MCP 服务、A2A 出站条目 `a2a-agents` 原样保留。

想知道「当前绑了哪些」，读 manifest 的 `mcp_servers`：连接器条目的 `name`
即连接器的 `ConnectorSlug`，可用 `client.connectors.list()` 查到对应的 `ConnectorId`。

### 11.4 `client.skills.list(source, opts=None)`

**`source` 必填**，决定查哪个技能库：

| 取值 | 技能库 | 备注 |
|---|---|---|
| `BUILTIN` | 平台预置 | |
| `CUSTOM` | 本企业自建 | |
| `AUTHORIZED` | 其他企业授权给本企业的 | 可配 `account_id` / `agent_id` 缩小范围 |

三个技能库**一次查不全**，要各查一次再合并。

**入参** `ListSkillsOpts`：`offset` / `limit` / `account_id` / `agent_id`

草稿与已停用的技能都会返回；`AUTHORIZED` 只返回已发布且启用的。

**出参** `SkillPage`（继承 `Page[SkillItem]`，多一个 `counts`）：

| 字段 | 说明 |
|---|---|
| `SkillId` | `skill_` 前缀 —— 填到 `skills()` 的 `id` |
| `Source` | `BUILTIN` / `CUSTOM` |
| `Name` | 仅 `CUSTOM` 返回 |
| `DisplayName` / `Description` / `Icon` | |
| `SkillVersion` | `v` 前缀 + 1~3 段数字，如 `v1.0.0` |
| `DownloadUrl` | `CUSTOM` / `AUTHORIZED` 为带签名的临时下载地址 |
| `Enabled` | `bool` |

`counts` 为 `SkillCounts`（`Builtin` / `Custom` / `Total`），可能为 `None`。

### 11.5 `client.experts.list(source, opts=None)`

**`source` 必填，且只有 `BUILTIN` / `CUSTOM`** —— 与技能不同，专家**没有 `AUTHORIZED`**，传了会被拒绝。

**入参** `PageOpts`：`offset` / `limit`（没有 `account_id` / `agent_id`）

**出参** `ExpertPage`（继承 `Page[ExpertItem]`，多一个 `counts`）：

| 字段 | 说明 |
|---|---|
| `ExpertId` | `ex_` 前缀，最长 15 字符 |
| `Source` | `BUILTIN` / `CUSTOM` |
| `ExpertType` | `AGENT`（普通专家）/ `TEAM`（专家团）。专家团暂不能绑定到 Agent，填进 `experts()` 后创建或修改版本会抛出 `InvalidRequestError` |
| `Name` | 仅 `CUSTOM` 返回 |
| `DisplayName` / `Description` / `Icon` | |
| `ExpertVersion` | **没有 `v` 前缀**（默认 `1.0.0`），与技能的格式不同 |
| `CategoryId` / `CategoryName` | `CategoryName` 仅 `BUILTIN` 返回 |
| `PublishStatus` | 仅 `CUSTOM` 返回 |
| `Enabled` | `bool` |
| `DisabledReason` / `DownloadUrl` / `UpdatedBy` | |
| `Status` | `ENABLED` / `DISABLED` |
| `ZipFileName` / `ZipMd5` / `ZipSha256` | |
| `ZipSizeBytes` | **字符串形式的整数** |
| `ModifiedTime` | |

---

## 12. ManifestBuilder

Manifest 是 JSON 字符串，本 builder 提供带类型的构建方式。

```python
manifest = (
    ManifestBuilder()
    .system_prompt("你是日志分析专家")
    .skills(["sk-log-parse"])
    .secret("API_KEY", "${source.api_key}")
    .env_var("TZ", "Asia/Shanghai")
    .build()
)
```

所有 setter 返回 `self`，支持链式调用。

| 方法 | 入参 | 出参 | 说明 |
|------|------|------|------|
| `system_prompt(prompt)` | `str` | `self` | 覆盖式 |
| `skills(ids)` | `list[str]` | `self` | **累加** |
| `experts(ids)` | `list[str]` | `self` | **累加** |
| `secret(key, value)` | `str, str` | `self` | 值支持 `${source.api_key}` 占位符 |
| `env_var(key, value)` | `str, str` | `self` | |
| `set(key, value)` | `str, Any` | `self` | 自定义扩展，统一写入 `metadata.<key>`（保留字段如 `version` 会被拒绝） |
| `to_dict()` | — | `dict` | 未序列化 |
| `build()` | — | `str` | JSON 字符串 |

### 不由 builder 设置的两类配置

manifest 里的 `mcp_servers` 与 `a2a.skills` **由服务端写入**，builder 不提供对应方法。
自己写这两个字段会与服务端写入的内容重复。

| manifest 字段 | 正确入口 |
|---|---|
| `mcp_servers` | `CreateAgentOpts(connector_ids=...)`<br>`UpdateVersionOpts(connector_ids=...)` |
| `a2a.skills` | `agent.a2a.update(UpdateA2AOpts(skills=...))` |

**校验**：`to_dict()` / `build()` 要求至少有 `system_prompt` 或一个 skill。

⚠️ **其他顶层字段不报错，而是被直接丢弃**。所以拼错字段名的表现是「能力失效」而不是报错，
更难排查。建议用 builder 构建，不要手写 JSON。会被拒绝的只有三类：顶层不是 JSON object、
字段的**类型**不匹配（如 `system_prompt` 传数字）、超过 256 KiB。

产出结构用 snake_case（`system_prompt`），`version` 为 `MANIFEST_VERSION`（`"2.0"`）。

---

## 13. 错误处理

全部继承 `CloudAgentError`。`CapiError` 及其子类携带 `capi_code`、`request_id`、`http_status`。

```python
from managed_agent_sdk import CapiError, ConflictError, NotFoundError, UpdateVersionOpts

try:
    await version.update(UpdateVersionOpts(model=model))
except ConflictError as e:
    print(e.capi_code, e.request_id)
except NotFoundError as e:
    print(e.capi_code, e.request_id)
except CapiError as e:
    print(e.type, e.retryable)
```

排障请带上 `request_id`，它对定位服务端问题很关键。

| 类 | HTTP | `type` | 典型场景 |
|----|------|--------|---------|
| `InvalidRequestError` | 400 | `invalid_request` | 参数不合法 |
| `AuthError` | 401 | `authentication_error` | 鉴权失败 |
| `PermissionDeniedError` | 403 | `permission_denied` | 有身份但无权限、服务未开通 |
| `NotFoundError` | 404 | `not_found` | 资源不存在或不属于当前租户 |
| `ConflictError` | 409 | `conflict` | 资源状态冲突 |
| `RateLimitError` | 429 | `rate_limit` | 频控或配额 |
| `ServerError` | 500 | `server_error` | 服务端内部错误 |
| `ServiceUnavailableError` | 503 | `service_unavailable` | 依赖不可用 |
| `NetworkError` | — | `service_unavailable` | 传输层失败，**无 `capi_code`** |
| `TimeoutError` | — | — | 请求超时 |
| `ValidationError` | — | — | 本地校验失败，**未发请求** |
| `AcpNetworkError` | — | — | ACP 建连失败或长连接中断，`session.connect()` 抛出 |
| `AcpAuthError` | 401 / 403 | — | ACP 数据面鉴权失败，**不重试**，见下 |
| `AcpProtocolError` | — | — | ACP 报文不合规、方法不支持、响应格式异常 |

`AcpNetworkError` / `AcpAuthError` / `AcpProtocolError` 继承 `CloudAgentError` 而不是
`CapiError` —— 它们是会话长连接层的错误，与「控制面请求可能未到达服务端」的
`NetworkError` 是两件事，`except NetworkError` 捕不到它们。

**两种后端的分类规则。** 腾讯云 API 后端按错误码前缀分类：

| 错误码 | 异常 |
|---|---|
| `InvalidParameter.*` / `InvalidParameterValue.*` / `MissingParameter` / `InvalidAction` | `InvalidRequestError` |
| `AuthFailure.*`（下面两个除外） | `AuthError` |
| `UnauthorizedOperation.*` / `AuthFailure.UnauthorizedOperation` / `AuthFailure.EntitlementRequired` | `PermissionDeniedError` |
| `ResourceNotFound.*` | `NotFoundError` |
| `FailedOperation.*` | `ConflictError` |
| `LimitExceeded.*` / `RequestLimitExceeded` | `RateLimitError` |
| `ResourceUnavailable.*` / `ResourceInsufficient.*` | `ServiceUnavailableError` |
| `InternalError.*` 及其余错误码 | `ServerError` |

OpenAPI 后端：响应带字符串错误码时按上表分类；没有错误码时（如网关拒绝、非 JSON 响应体）按 HTTP 状态码分类：

| HTTP 状态码 | 异常 |
|---|---|
| 400 / 422 | `InvalidRequestError` |
| 401 | `AuthError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 429 | `RateLimitError` |
| 502 / 503 / 504 | `ServiceUnavailableError` |
| 其余 | `ServerError` |

`retryable` 为 `True` 的仅 `rate_limit` / `server_error` / `service_unavailable`。**它只是提示，SDK 不会自动重试。**

### `AcpAuthError` 与 `AcpNetworkError` 的处理方式相反

同样是建连失败：网络波动应当重连，鉴权失败重连多少次结果都一样。所以
遇到 401 / 403 时 SDK 会**立即停止重试**并抛 `AcpAuthError`。

异常上带着排查问题需要的信息：

```python
from managed_agent_sdk import AcpAuthError

try:
    await session.connect()
except AcpAuthError as e:
    print(e.http_status)  # 401
    print(e.request_id)   # 请求 ID
    print(e)              # 含服务端返回的原因
    raise                 # 重试无意义
```

报告问题时请附上 `request_id` 与异常消息。

### `NetworkError` 要特别对待

它意味着**无法判断服务端是否已执行**。重试非幂等操作（创建 Agent / 版本 / 会话）前，应先调对应查询接口确认状态。

```python
from managed_agent_sdk import ConflictError, NetworkError, NotFoundError

try:
    await session.migrate("ver-new")
except ConflictError:
    pass       # 会话正在迁移中，稍后再试
except NotFoundError:
    pass       # 版本不存在或不属于该 Agent
except NetworkError as e:
    # 不确定是否已执行 —— 先 session.info() 查状态
    # （NetworkError 没有 capi_code：请求可能根本没到服务端）
    print(e.request_id)
```

`ValidationError` 在**发请求之前**抛出，说明参数写错了，重试无意义。

### 日志

一个 `logger` 配置对象管两个出口，各自独立开关与级别。默认开启控制台日志（`warn` 及更高级别），文件日志需显式配置 `file`。设置 `LoggerOpts(enable=False)` 可关闭控制台；文件出口独立控制：

```python
from managed_agent_sdk import ClientOpts, LogFileOpts, LoggerOpts, ManagedAgentClient

client = ManagedAgentClient(ClientOpts(
    logger=LoggerOpts(
        enable=True,        # 控制台
        level="warn",
        sink=lg,            # 缺省用模块级 logging.getLogger("managed_agent_sdk")
        file=LogFileOpts(   # 写入文件。传了即开启，与控制台互不影响
            level="debug",  # 文件记录全部级别
        ),
    ),
))
```

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enable` | `bool` | `True` | 控制台日志开关；`False` 显式关闭 |
| `level` | `LogLevel \| None` | `"warn"` | 控制台级别；`debug` 会输出**已脱敏**的请求参数。传上表以外的值抛 `ValidationError` |
| `sink` | `Logger \| None` | 模块级 logger | 输出目标，兼容 `logging.Logger`；由 SDK 按配置的级别过滤，再由标准库决定最终输出 |
| `file` | `LogFileOpts \| None` | — | 文件日志配置，见下；传了即开启 |

`LogFileOpts`：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `dir` | `str \| None` | `cwd/.wma-log` | 日志目录；无法创建时改用系统临时目录，开启时的提示会给出实际路径 |
| `filename` | `str \| None` | `"sdk-debug"` | 文件名（不含扩展名） |
| `level` | `LogLevel \| None` | `"debug"` | 文件级别，独立于控制台 |
| `max_bytes` | `int \| None` | `10 MB` | 单文件上限，超过即轮转 |
| `max_files` | `int \| None` | `3` | 归档保留数（磁盘上限约 `max_bytes × (max_files + 1)`） |
| `retention_days` | `int \| None` | `7` | 归档保留天数，`0` 不按时间清理 |
| `flush_ms` | `int \| None` | `1000` | 缓冲写入间隔 |

文件开头记录环境信息（SDK 版本、运行时、地域、端点、超时），每行带时间戳与级别；
`AKID` / `Bearer` / `secret_key` 类凭证写入前会被遮蔽。
进程退出时自动写完缓冲；`client.aclose()` 也会写完缓冲。多次运行追加到同一文件，
每次运行开头记录 pid 与开始时间。

SDK **不调用 `basicConfig`、不添加任何 handler** —— 默认使用模块级 logger；最终是否输出仍受你的 `logging` 配置影响。

控制面与数据面（ACP）共用这一组配置：

| 级别 | 覆盖内容 |
|------|---------|
| `error` | ACP 鉴权失败（401/403，不重试）、数据面凭证为空 |
| `warn` | 重连次数耗尽、心跳超时、数据面凭证刷新失败、收到不合规报文 |
| `debug` | 建连 / 断开 / 重连等待时长、控制面请求参数（已脱敏）、数据面凭证缓存情况 |

客户端默认按 `"warn"` 过滤，也可配置 `level="off"` 或 `enable=False` 关闭控制台。即使你启用了 root logger，显式关闭仍有效。

日志带固定前缀，Node 与 Python 一致，可用同一套关键词检索：

| 前缀 | 内容 |
|------|---|
| `[capi <traceId>]` | 腾讯云 API 调用。同一请求的请求、响应、错误日志共用一个 `traceId` |
| `[openapi <id>]` | OpenAPI 调用。`<id>` 是 SDK 为每个请求生成的随机标识，同一请求的日志共用；错误日志带服务端 `reqId` |
| `[session <sessionId>]` | 每轮 prompt 的开始、结束或失败，带完整 `traceId`；失败时只记错误类型，不记录对话正文 |
| `[auth]` | 数据面凭证的获取与刷新 |
| `[acp-transport conn=<id>]` | 数据面连接，带连接 ID |

> **ACP 日志不记录报文内容**，只记连接 ID、字节数、重连次数、错误类型 ——
> 报文里有用户对话正文。需要查看报文请在自己的 `on_chunk` / `subscribe` 里处理。

### 日志脱敏

`LoggerOpts(level="debug")` 会打印控制面请求参数与耗时，其中这些字段被**递归遮蔽**为 `***`（大小写不敏感，递归 4 层）：

`secretId`、`secretKey`、`token`、`password`、`apiKey`、`secret`、`credential`、`authorization`、`chatToken`、`accessToken`、`manifest`

### 上报

SDK **默认开启**运行指标上报，用于统计对话的耗时与成功率。上报在后台批量进行，失败时直接丢弃，不影响业务调用。

```python
from managed_agent_sdk import ClientOpts, ManagedAgentClient, PromptOpts, TelemetryOpts, TurnTelemetryOpts

client = ManagedAgentClient()  # 默认开启上报

await session.prompt("...", PromptOpts(
    trace_id=trace_id,                                       # 可选：业务在点击发送时生成的 trace
    telemetry=TurnTelemetryOpts(click_time_ms=clicked_at),   # 可选：点击时刻，用于计算端到端耗时
))

# 关闭上报
ManagedAgentClient(ClientOpts(telemetry=TelemetryOpts(enabled=False)))
```

**上报的内容**：每轮对话的发送、首个回复片段、长时间无响应、结束这几个时间点，以及每次数据面请求与建连的耗时和状态码。
每条记录带本轮 `trace_id`、会话 ID、模型、SDK 版本、操作系统类型（仅 macOS / Windows），以及由主机名与用户名计算的哈希值（不上报原值）。

> **不上报对话内容** —— 用户输入、模型回复、图片、异常消息、拒绝详情与响应正文
> 都不会发送。错误只上报分类，不上报错误信息。

`TelemetryOpts`（`ClientOpts.telemetry`）：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enabled` | `bool` | `True` | 上报开关；`False` 关闭 |
| `uid` | `str \| None` | `""` | 用户标识，随上报记录发送 |
| `app_version` | `str \| None` | SDK 版本 | 应用版本号 |
| `entry_source` | `str \| None` | `"wma_sdk_python"` | 入口来源，可被单轮配置覆盖 |
| `http_post` | `Callable \| None` | urllib | 替换上报请求函数，签名 `(url, body, headers) -> None` |

`TurnTelemetryOpts`（`session.prompt()` 的 `opts.telemetry`）：

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `click_time_ms` | `int \| None` | `prompt()` 调用时刻 | 用户点击发送的时刻（epoch 毫秒），用于计算端到端耗时 |
| `entry_source` | `str \| None` | 客户端配置 | 覆盖本轮入口来源 |
| `scene` | `str \| None` | 自动判定 | 新建会话首轮为 `new`，后续轮次及恢复的会话为 `continue` |
| `model` | `str \| None` | 服务端返回的模型 | 本轮使用的模型 |

`await client.aclose()` 会等待剩余记录发送完毕，进程正常退出前也会尝试发送剩余记录；
会话的数据面连接需要单独关闭。

---

## 14. 类型索引

### 出参类型（`TypedDict`，PascalCase）

| 类型 | 字段 |
|------|------|
| `AgentInfo` | `AgentId` `AgentName` `Description` `AvatarUrl` `IsDebug` `RoutingSet` `ActiveSessionCount` `AccountId` `CreatedTime` `ModifiedTime` `A2AConfig`（含 `A2AEnabled` `A2APublicRef` `A2AEndpoint` `A2AStatus`） |
| `AgentListItem` | `AgentInfo` 的子集，见 §5 |
| `VersionInfo` | `VersionId` `AgentId` `VersionName` `Status` `Description` `Model` `Manifest` `SessionCount` `CreatedTime` `ModifiedTime` |
| `AgentVersionItem` | 见 §6 |
| `SessionInfo` / `SessionItem` | 见 §7 |
| `MessageEvent` / `Message` / `ToolCall` / `TokenUsage` | 见 §7.3 |
| `ExternalAgentInfo` / `A2ASkillItem` | 见 §10.1 |
| `A2AConfig` | 见 §9 |
| `BuiltinModel` | 见 §4.0 |
| `ConnectorItem` | 见 §11.1 |
| `SkillItem` / `SkillCounts` | 见 §11.4 |
| `ExpertItem` / `ExpertCounts` | 见 §11.5 |
| `RoutingItem` | `VersionId`（str）`Weight`（float） |

两个易错点：

- `ActiveSessionCount` 缺省表示**没有统计，不等于 0**
- `RoutingSet` 空路由时是 `[]` 而非缺省 —— 「未配置路由」与「字段缺失」含义不同

### 数据面类型（ACP）

`session.prompt()` 相关的类型从包根导出，无需 `import acp.schema`：

| 类型 | 说明 |
|------|------|
| `ContentBlock` | `TextContent` / `ImageContent` / `AudioContent` / `ResourceLink` / `EmbeddedResource` 的联合。`prompt()` 传字符串时 SDK 自动包成 `[{"type": "text", "text": ...}]`，多数场景无需直接使用 |
| `PromptResponse` | `stop_reason`（`"end_turn"` / `"max_tokens"` / `"max_turn_requests"` / `"refusal"` / `"cancelled"`）`refusal` `trace_id` `usage` |
| `UsageInfo` | 本轮 token 消耗：`total_tokens` `input_tokens` `output_tokens` `thought_tokens` `cached_read_tokens` `cached_write_tokens` `model` `request_id`（全部可选，可能不返回） |
| `RefusalReason` | `stop_reason == "refusal"` 时的结构化原因：`category` `details` `request_id` `status_code` `source`（可能整个 `refusal` 为 `None`） |
| `SessionNotification` | `{ session_id, update, _meta? }`，订阅回调收到的通知 |
| `AcpConnectionState` | `"INITIAL"` / `"CONNECTING"` / `"OPEN"` / `"CLOSING"` / `"CLOSED"` |
| `NotificationListener` | 订阅者签名 `Callable[[SessionNotification], None]`，`session.subscribe()` 用 |

### 枚举

| 类型 | 取值 |
|------|------|
| `VersionStatus` | `"DRAFT"` / `"ENABLED"` / `"DISABLED"` |
| `SessionStatus` | `"CREATING"` / `"ACTIVE"` / `"IDLE"` / `"MIGRATING"` / `"FAILED"` / `"ARCHIVED"` |
| `SessionSource` | `"CLOUD"` / `"CHANNEL"` / `"SCHEDULED_TASK"` / `"A2A"` |
| `A2AStatus` | `"DRAFT"` / `"REGISTERED"` / `"DISABLED"` / `"NONE"` / `"UNKNOWN"` |
| `MessageEventType` | `"USER"` / `"ASSISTANT"` / `"TOOL"` |
| `ToolCallStatus` | `"PENDING"` / `"IN_PROGRESS"` / `"SUCCEEDED"` / `"FAILED"` |
| `CapiErrorType` | 8 值，见 §13 |
| `SkillSource`（入参） | `"BUILTIN"` / `"CUSTOM"` / `"AUTHORIZED"` |
| `ExpertSource`（入参） | `"BUILTIN"` / `"CUSTOM"`（**无 `AUTHORIZED`**） |
| `ExpertType` | `"AGENT"` / `"TEAM"` |
| `PublishStatus` | `"DRAFT"` / `"PUBLISHED"` |
| `EnabledStatus` | `"ENABLED"` / `"DISABLED"` |
| `ConnectorStatus` | `"ACTIVE"` / `"DISABLED"` |
| `ConnectorSource` | `"ENTERPRISE_AGENT"` / `"ASSISTANT"` |
| `ConnectorType` | `"MCP_SERVER"` / `"A2A"` / `"API_SERVICE"` |
| `ConnectorAuthMode` | `"NONE"` / `"ONEID"` / `"OAUTH2_IDP"` |

`SessionStatus` 有两个容易误解的取值：

- **`IDLE` 不代表沙箱已释放** —— 它表示「上一轮对话结束、等待下一轮输入」，沙箱照常运行。
  沙箱休眠时也显示为 `IDLE`，**两者无法区分**。
- **`ARCHIVED` 无法主动进入** —— 没有归档接口，该状态只在会话异常
  （例如初始化失败）时由服务端设置，不是「正常用完后的最终状态」。

### 入参类型（`dataclass`，snake_case）

`CreateAgentOpts`、`UpdateAgentOpts`、`CreateSessionOpts`、`UpdateA2AOpts`、`CreateVersionOpts`、`CreateVersionFromSourceOpts`、`UpdateVersionOpts`、`ConsoleConnectorRef`、`MessageListOpts`、`PromptOpts`、`A2ASkill`

向用户提问（见 [§ 向用户提问](#向用户提问)）：`QuestionRequest`、`QuestionItem`、`QuestionOption`、`QuestionAnswer`

目录资源查询：`ListSkillsOpts`、`SkillPage`、`ExpertPage`、`StripGatewayMcpResult`、`GatewayMcpEntry`

### 配置类型

`ClientOpts`、`CapiOpts`、`RequestOpts`、`PageOpts`、
`Page`、`Credentials`、`OpenApiOpts`、`Logger`、`LogLevel`

### 常量

| 常量 | 值 |
|------|-----|
| `DEFAULT_ENDPOINT` | `"workbuddyenterprise.ap-beijing.tencentcloudapi.com"` |
| `DEFAULT_API_VERSION` | `"2026-07-09"` |
| `DEFAULT_REGION` | `"ap-beijing"` |
| `DEFAULT_TIMEOUT_MS` | `30000` |
| `MAX_PAGE_LIMIT` | `100`，**全部列表方法统一** |
| `MANIFEST_VERSION` | `"2.0"` |
| `__version__` | 当前 SDK 版本号，如 `"0.0.4"`。报告问题时附上它 |

### 工具函数

| 函数 | 用途 |
|------|------|
| `is_bound(item)` | 判断外部 Agent 是否已绑定，见 §10.1 |
