KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA
02. 协作为什么要从任务契约开始？ — keel 龙骨
“请指标 Agent 看一下这个故障”对人类同事或许足够，对程序不够。系统至少不知道：看什么数据、输出什么结构、何时算完成、失败能否重试，以及结果应该回到哪次运行。
“请指标 Agent 看一下这个故障”对人类同事或许足够，对程序不够。系统至少不知道：看什么数据、输出什么结构、何时算完成、失败能否重试，以及结果应该回到哪次运行。
多 Agent 协作首先是一组协议对象。
六个对象先分清
| 对象 | 回答的问题 | 示例 |
|---|---|---|
| AgentSpec | 谁能承担什么任务 | metrics_analyst 具有 analyze_metrics 能力 |
| CollaborationTask | 具体要完成什么 | 分析 INC-001 的指标证据 |
| TaskAssignment | 当前任务交给了谁 | task-1 -> metrics_analyst |
| TaskResult | 执行是否成功 | succeeded / failed / cancelled |
| Artifact | 产生了什么可复用成果 | 带证据 ID 的指标发现 |
| CollaborationEvent | 运行中发生了什么 | task.assigned、task.succeeded |
它们不能只用一条聊天消息代替。消息负责传输，任务负责工作生命周期，工件负责保存成果，事件负责解释过程。
Agent 契约描述能力，不描述人格
class AgentSpec(BaseModel):
name: str
description: str
capabilities: set[str]
max_concurrency: int = 1
description 帮助人和模型理解用途；真正用于分派的是结构化 capabilities。max_concurrency 则限制同一 Agent 同时承担多少任务。
生产系统还可能加入：
- 允许使用的工具集合；
- 可读取的数据作用域；
- 模型和 prompt 版本；
- 每次任务的 token、时间和调用预算；
- 是否允许接受其他 Agent 的委派；
- 是否能产生副作用。
Task 必须能够独立验收
项目中的 CollaborationTask 包含：
class CollaborationTask(BaseModel):
task_id: str
objective: str
required_capability: str
input_data: dict[str, Any]
expected_output: str
depends_on: list[str] = []
required: bool = True
timeout_seconds: float = 10.0
字段分别解决不同问题：
task_id让结果、事件和重试能够关联；objective描述当前工作，而不是整次用户愿望；required_capability用于选择 Agent；input_data是经过筛选的任务上下文；expected_output提供验收标准；depends_on表示开始前必须完成的任务；required决定失败是否阻断最终结果；timeout_seconds限制任务占用运行预算。
Result 和 Artifact 为什么分开
TaskResult 描述执行结局：
task_id: task-metrics
agent_name: metrics_analyst
status: succeeded
artifact_id: artifact-17
Artifact 保存工作成果：
claim: 连接池等待时间在发布后显著上升
evidence_ids: [metric-pool-wait, deploy-202]
confidence: 0.86
limitations: [缺少数据库端连接数]
结果状态可能被频繁查询；工件可能被 reviewer、最终汇聚器或未来审计引用。把两者分开，才能在不复制大段正文的情况下传递 artifact_id。
任务状态是一台小状态机
stateDiagram-v2
[*] --> pending
pending --> assigned
assigned --> running
running --> succeeded
running --> failed
running --> cancelled
assigned --> cancelled
需要重试时，不要把同一个失败悄悄覆盖成 running。记录 attempt，或者创建新的 execution attempt；否则无法解释某个工件来自哪次执行。
运行第一个确定性实验
python courses/advanced/multi-agent-collaboration/course/project/examples/01_task_contract.py
示例直接构造一个任务，交给白名单 Registry 中的确定性 Worker。运行前先预测：
- 请求不存在的 capability 会在哪里被拒绝？
- Worker 返回的
task_id与请求不一致时，谁负责发现？ input_data缺少必要证据时，应该返回空成功还是结构化失败？
这些错误必须由协议层发现，不依赖模型自觉修正。
检查理解
- 为什么
role="SRE"不能替代 capability？ - 为什么 Message 不是 Task？
- 为什么最终报告应该引用 artifact，而不是复制无法追踪的 Agent 文本？
- 为什么重试需要 attempt 或新的执行记录？
任务和结果有了稳定形状后，模型只需要填充它擅长的语义内容。