KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA

A2A Protocol Engineering 配套项目：Remote Agent Bridge — keel 龙骨

A2A Protocol Engineering 的配套项目：A2A Protocol Engineering 配套项目：Remote Agent Bridge

这是一个只依赖 Python 标准库的确定性 A2A Bridge 教学实现。它把协议拆成几层：

contracts (对象模型) -> agentcard (发现/签名) -> auth (凭据三元组)
    -> tasks (状态机/可见性) -> executor (委派执行) -> server (11 个操作) -> observability (trace)

它覆盖 A2A v1.0 的关键验证点，但不宣称是完整的 A2A SDK 或生产服务器。课程目标是先看懂边界，再替换基础设施。

运行环境

$env:PYTHONPATH = "courses/foundation/a2a-protocol-engineering/course/project/src"
python courses/foundation/a2a-protocol-engineering/course/project/examples/01_discovery.py

示例脚本通过 examples/_bootstrap.py 自动把 src/ 和 examples/ 加进 sys.path，直接运行即可，无需设置环境变量或安装任何第三方包。

示例顺序

示例	观察重点
`01_discovery.py`	well-known 路径、8 个必填字段校验、双方接口交集与首选接口
`02_version_binding.py`	`A2A-Version` 逐请求协商、三种绑定的方法名拼写、缺头与版本不匹配的错误形状
`03_parts_artifacts.py`	Part OneOf（四选一）、`kind` 已移除、`text`/`raw`/`url`/`data` 四种载体
`04_task_lifecycle.py`	9 个状态、中断态补输入、终态幂等、快照跨进程存活
`05_streaming.py`	流式帧按成员名判别、无 `final` 字段、重订阅补帧
`06_push.py`	推送配置 CRUD、回调投递、重复投递去重
`07_auth_card.py`	凭据三元组（scope/租户/受众）、签名卡验签、篡改检测
`08_compat.py`	任务可见性隔离、游标分页走完、`reason` 分类错误
`09_orchestrator.py`	附录配套：本地编排消费远端 Agent 的三个动作（派 / 跟 / 弃）与停止条件

01 与 03 的输出在多次运行间 md5 一致（示例自带确定性 id 工厂），可直接引用进正文。

测试

python -m pytest -q courses/foundation/a2a-protocol-engineering/course/project/tests

当前 32 个测试覆盖：Part OneOf 强制与无 kind、卡面必填字段与校验、服务端接口优先级、版本与绑定拒绝、签名卡篡改检测、Message/Task 两种返回、中断态与补输入恢复、终态不改写、未声明技能被 REJECTED、终态取消显式报错、快照存活、historyLength=0、凭据与租户/受众绑定、扩展卡需要额外 scope、按调用者隔离的任务可见性、游标分页、流式帧无 kind、能力与推送开关、推送配置生命周期、一次调用一个 trace。

真实网络、OAuth 2.0 + PKCE、gRPC 传输、官方 SDK 和 OpenTelemetry exporter 是生产替换点。

进入 keel 阅读