PR04：Agent Card and Capability Discovery

版本说明：本文以 MCP 2026-07-28 与 A2A 1.0 的稳定架构概念为基准。协议字段可能演进，生产实现必须固定版本并运行 conformance tests。

它解决什么问题

Client 在调用前需要知道远程 Agent 是谁、在哪里、支持哪些接口和技能，以及如何认证。

核心定义

Agent Card 是 A2A 的机器可读能力描述，包含身份、接口、能力、认证要求与 skills；Discovery 找到并验证 Card，再做能力匹配。

工作原理

获取 Card 后校验来源、签名/信任、版本、接口、认证和 skill schema；缓存有 TTL，变更后重新评估权限。

架构视图

Architecture View
Registry/well-known -> Agent Card -> trust+compatibility -> capability match

Product View
User intent -> trusted client/host -> external capability -> status/artifact
                 | consent/auth        | failure / revoke / SLA

最小可运行实践

运行 examples/protocols/protocol_boundaries.py 的 discovery 场景。实验模拟能力发现、MCP 风格工具调用、A2A 风格远程 Task、Artifact、认证受众检查和 sync/stream/async 状态，不依赖网络或 SDK。

正常场景

Client 选择支持 A2A 1.0、文件 Artifact 和所需认证的翻译 Agent。

失败与恢复场景

Card 被篡改指向攻击端点时，信任策略、域绑定与审核拒绝；不能把发现结果自动加入允许列表。

什么时候使用

动态或跨组织发现 Remote Agent 时使用。

什么时候不要使用

固定内部服务可配置注册，但仍应保留版本和能力契约。

Trade-offs

动态发现提高可组合性，也扩大供应链和能力漂移风险。

产品视角

用户与业务问题

连接新 Agent 前展示提供方、能力、数据用途和授权。

产品价值

降低人工适配并支持能力路由。

用户体验

用户看到连接主体、请求权限、远程处理状态、产物与责任边界；协议握手、轮询和重试由产品吸收。

自主性边界

发现能力不等于允许调用。Host/Client 按用户授权、策略、风险和当前 Task 重新决定；远程 Agent 不能获得本地全部权限。

数据与权限

令牌绑定目标受众，禁止 token passthrough；请求最小化并标注主体、目的和保留责任。远程服务视为独立信任域。

失败与降级

版本/能力不兼容时协商或拒绝；远程任务超时可取消、查询或返回部分 Artifact；连接撤销后立即停止新调用。

产品指标

衡量集成周期、连接成功率、授权放弃率、远程成功率、P95 延迟、取消生效率、SLA 违约和数据边界事件。

框架中的对应实现

A2A Agent Card 是标准对象；框架内部 agent registry 不自动等价。

Capability Matching、Identity、Registry、Versioning。

检查清单

协议连接的是 Tool/Resource 还是独立 Agent？
版本与 capability 是否显式协商？
身份、授权主体和 token audience 是否正确？
Task、Message 和 Artifact 是否分开？
超时、取消、流式与异步如何呈现？

延伸练习与参考资料

模拟 Card skill 或 endpoint 变化，验证缓存失效与重新授权。