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 一一对应(命名按 Python 惯例转 snake_case),差异见 §3。
pip install managed-agent-sdk
要求 Python 3.10 ~ 3.14。
想先看能跑的完整代码:入门示例(example/python/main.py)。
目录
- 1. 快速开始
- 2. 通用约定
- 3. 与 Node 版的差异
- 4. ManagedAgentClient
- 5. Agent 管理
- 6. 版本管理
- 7. 会话管理
- 8. 对话(数据面)
- 9. A2A Inbound
- 10. A2A Outbound
- 11. 目录资源查询(连接器 / 技能 / 专家)
- 12. ManifestBuilder
- 13. 错误处理
- 14. 类型索引
1. 快速开始
凭证
腾讯云 API(默认)
SecretId / SecretKey 在 腾讯云访问管理控制台的 API 密钥管理 获取。
从环境变量读取,或通过 ClientOpts(capi=CapiOpts(credentials=Credentials(secret_id=..., secret_key=...))) 显式传入:
export TENCENTCLOUD_SECRET_ID=你的SecretId
export TENCENTCLOUD_SECRET_KEY=你的SecretKey
WorkBuddy OpenAPI
API key 有两种,按需选择其一:
- 开放平台 API key:在 WorkBuddy 管理后台的开放平台应用列表 获取
- 企业个人 API key:在 WorkBuddy 个人中心的 API key 页面 获取
设置企业 ID 与 API key:
export WORKBUDDY_ENTERPRISE_ID=你的企业ID
export WORKBUDDY_API_KEY=你的APIKey
传入 ClientOpts(openapi=OpenApiOpts()) 即选择 OpenAPI 后端,省略的字段从上述环境变量读取:
from managed_agent_sdk import ClientOpts, ManagedAgentClient, OpenApiOpts
# 从环境变量读取企业 ID 与 API key
client = ManagedAgentClient(ClientOpts(openapi=OpenApiOpts()))
# 显式传入优先于环境变量
client = ManagedAgentClient(
ClientOpts(openapi=OpenApiOpts(enterprise_id="...", api_key="ck_..."))
)
服务地址、鉴权方式等字段见 §4 OpenApiOpts。
数据面(ACP)的凭证由 SDK 用控制面凭证自动换取并缓存,无需单独配置,见 §8 数据面凭证。
第一个 Agent
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 版本的模型),
再用这个版本建会话:
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。
info = await agent.info()
info["AgentId"] # ✅
info["agent_id"] # ❌ 不存在
出参与云 API 文档的字段一致,可以直接对照排查。出参用 TypedDict,IDE 有补全但运行时就是普通 dict。
入参用 dataclass
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:
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:
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) |
⚠️ 控制面与数据面的取值方式相反,这是最容易出错的一处:
# 控制面: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。
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 里取:
# ✅ 先查,过滤 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)作为步长 —— 这个值对所有列表方法都适用:
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)
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
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
⚠️ 两个「不继承」要留意:
- 没有
connector_ids入参 —— 创建版本时不能绑定连接器, 新版本一律是「无连接器」状态。要带连接器只能两步走:v = await agent.versions.create(CreateVersionOpts(manifest=m)) await v.update(UpdateVersionOpts(manifest=m, connector_ids=["conn-1"]))
- 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");省略时由服务端按连接器的鉴权方式推断 |
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 字符串,读取时自行解析:
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 = 整轮累计,不可归因到单个工具调用,也不可与同轮其它分段相加)
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。做计费用 prompt() 返回值的
usage(及时)或 session.messages()(对账)—— usage_update 的 used
是上下文占用,不是本轮消耗。
⚠️ 不是每个 ASSISTANT 事件都带 TokenUsage。 一轮对话可能分段输出多个
ASSISTANT 事件,只有该轮正常结束时的最后一个事件带用量,数值是整轮累计。
所以按「有没有 TokenUsage」筛选,就等于按轮次统计:
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,见下节 |
出参: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 |
产生拒绝的服务组件 |
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 会向 服务端发取消。
需要拼出完整回复时,把片段收集到列表里:
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 用已有信息继续本轮 |
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 都可用。
发图片:
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 等)有两种方式:
# ① 小文件:内容内联进 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"] 发给服务端,不解析、不校验其中的内容。
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 用量。
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: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" |
已绑定与未绑定的全部 |
# 找这个版本下还能绑谁
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"):
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",从返回值看不出失败。两点要注意:
ConnectorItem["Status"]不反映凭证是否可用 ——ACTIVE只表示连接器本身已启用- 这与「skill / expert ID 不存在」完全不同 —— 后者只是缺少该能力,对话正常; 连接器凭证失效会阻断整个对话
排查时先去掉连接器,新建一个会话对比(migrate() 不会重新加载连接器,必须新建会话)。
出参的 Source(BUILTIN)转成小写后就是 manifest 里的 type(builtin)。
⚠️ 服务端不检查 skill / expert ID 是否存在。填了不存在的 ID 依然创建成功,但该能力在运行时缺失,
只能在对话时发现 —— ID 建议直接取自 list() 的返回,不要手写。
完整流程:
# 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;§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 是该版本最终要绑的完整集合,服务端按它做全量覆盖:
# 当前绑了 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 时不需要为连接器做任何处理:
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 提供带类型的构建方式。
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=...)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。
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。
异常上带着排查问题需要的信息:
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 / 版本 / 会话)前,应先调对应查询接口确认状态。
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) 可关闭控制台;文件出口独立控制:
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 默认开启运行指标上报,用于统计对话的耗时与成功率。上报在后台批量进行,失败时直接丢弃,不影响业务调用。
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缺省表示没有统计,不等于 0RoutingSet空路由时是[]而非缺省 —— 「未配置路由」与「字段缺失」含义不同
数据面类型(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 |
Metadata
Release files for managed-agent-sdk 0.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| managed_agent_sdk-0.0.6.tar.gz | 180.9 kB | Without provenance | Details for managed_agent_sdk-0.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| managed_agent_sdk-0.0.6-py3-none-any.whl | Python 3 | none | any | Details for managed_agent_sdk-0.0.6-py3-none-any.whl |
Total release size: 353.6 kB
Release files / managed_agent_sdk-0.0.6.tar.gz
| Download URL | managed_agent_sdk-0.0.6.tar.gz |
|---|---|
| Size | 180.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8305eb2b86b043440ab11cf1b4f7b090748057e706ef10f4edc0fe78840cbc65
|
|
BLAKE2b-256 checksum How to use checksums |
1b16f6485f4d1246a74e8d141bda52ff707d3aa1e6e9cf30bd87760aaf1b75cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / managed_agent_sdk-0.0.6-py3-none-any.whl
| Download URL | managed_agent_sdk-0.0.6-py3-none-any.whl |
|---|---|
| Size | 172.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31d23e68d8481961025af2de2252c4e0c4b9af526703cf1bfe0e3738c232f767
|
|
BLAKE2b-256 checksum How to use checksums |
39ecd2453e41556c11b6a9cd54e547d43d3eb9c788ad55fc86d97fe7066b2e61
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for managed-agent-sdk 0.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.