10 分钟上手 Brief:多 Agent 任务委托完整快速入门教程
10 分钟上手 Brief:多 Agent 任务委托完整快速入门教程
Brief 是首个专门解决多 Agent 任务委托的开放协议——用两个标准 Markdown 文件(.brief.md 请求简报 + .response.md 响应结果),就能让 Agent 之间完成结构化、可审计的任务交接。本文是一份面向新手的多 Agent 任务委托快速入门教程,10 分钟带你从零跑通第一次 Agent 任务委托。
为什么需要 Brief:解决多 Agent 任务交接的痛点
如果你正在搭建多 Agent 系统,大概率遇到过这些问题:
- 上下文丢失:Agent A 把任务甩给 Agent B,却说不清"到底要什么、为什么、交付标准是什么"
- 黑盒难审计:任务在多个 Agent 之间流转,出了问题无从追溯
- 级联失控:A → B → C → D 的链式委托没有深度控制,容易无限套娃
业界把这种乱象称为 "隐式交接"(Implicit Handoff)。而 MCP 解决了工具调用、A2A 解决了 Agent 通信,唯独"一个 Agent 如何正式地把任务委托给另一个 Agent"缺少标准——这正是 Brief 协议要填补的空白。
💡 Brief 的定位很克制:它不是又一个框架,而是一层语义层,与 MCP、A2A 协作而非替代。
Brief 工作原理:两个 Markdown 文件搞定任务委托
整个协议的核心简单到极致——两个 Markdown 文件:
Agent A 发送 brief-001.brief.md
"我需要什么、为什么需要、期望你返回什么。"
Agent B 发送 brief-001.response.md
"我做了什么、交付了什么成果。"
没有新的 DSL,没有二进制格式,没有框架锁定。会写 Markdown 就能用 Brief。
图:Brief 协议委托时序图——从创建简报、发送、验证、执行到回传响应的完整流程
一份标准的 .brief.md 由 YAML frontmatter(元数据)+ 四段式正文组成:
| 部分 | 内容 |
|---|---|
| Objective(目标) | 需要做什么 |
| Context(上下文) | 为什么做、相关背景 |
| Constraints(约束) | 规则和限制 |
| Expected Deliverables(交付物) | 期望返回什么 |
快速安装 Brief SDK:一条命令完成
Brief 官方提供了 TypeScript SDK,安装只需一行:
npm install brief-sdk
# 或
pnpm add brief-sdk
SDK 核心 API 只有四个,源码结构一目了然(见 packages/brief-sdk/src/index.ts):
| API | 作用 |
|---|---|
Brief |
创建、解析简报,发起子委托 |
BriefResponse |
创建、解析响应 |
Trace |
记录完整审计日志 |
parseDocument / validateBriefMeta |
解析与校验 |
上手实战:三步完成第一次任务委托
下面以最经典的"委托代码审查"场景为例,完整走一遍流程(完整可运行代码见 examples/01-simple-delegation/index.ts)。
第一步:创建委托简报(委托方)
import { Brief } from 'brief-sdk';
const brief = Brief.create({
delegator: 'agent-orchestrator', // 谁委托
delegatee: 'agent-code-reviewer', // 委托给谁
body: `# 简报:审查 PR #42
## 1. Objective
审查 OAuth 2.0 迁移代码的安全问题。
## 2. Context
登录流程已从 session 认证重构为 OAuth 2.0。
## 3. Key Constraints
- 重点关注 token 的处理和存储。
## 4. Expected Deliverables
1. 审查摘要及发现。
2. 批准或拒绝建议。`,
});
brief.content 就是一个合法的 .brief.md 字符串,用任何方式发出去都行(HTTP、消息队列、文件……),传输层完全交给 A2A 等协议处理。
第二步:接收方解析并执行任务
const incoming = Brief.parse(receivedMarkdown);
console.log(incoming.delegator); // "agent-orchestrator"
console.log(incoming.isSubBrief); // false
一行 Brief.parse 就把 Markdown 还原成结构化对象(解析器实现见 packages/brief-sdk/src/parser.ts),Agent B 据此执行任务即可。
第三步:回传结构化响应(被委托方)
const response = incoming.createResponse({
status: 'success',
body: `# 审查完成
## Findings
- 批准,有少量建议。
## Recommendation
**Approve** — 修复小问题后合并。`,
});
response.content 就是合法的 .response.md。委托方收到后可用 BriefResponse.parse 校验状态,闭环完成。
级联委托 A → B → C:内置深度控制
真实场景中,Agent B 接到任务后可能还要继续向下委托。Brief 通过 parentId、maxDepth、currentDepth 三个字段原生支持链式委托:
const parentBrief = Brief.parse(receivedMarkdown);
// parentId 和深度自动设置,无需手动维护
const subBrief = parentBrief.createSubBrief({
delegator: 'agent-fullstack-dev',
delegatee: 'agent-docs-writer',
body: '# 为新端点编写 API 文档。',
});
创建根简报时指定 maxDepth: 3,SDK 会自动判断当前简报是否还能继续下委托(canDelegate),从协议层面杜绝无限套娃。子委托实现见 packages/brief-sdk/src/brief.ts。
图:级联委托全景——Agent A 下发根简报,B 并行拆分两个子任务给 C 和 D,结果扇入合并后逐层回传,全过程沉淀为 trace.md 审计轨迹
Trace 审计日志:完整追踪委托链路
Brief 的另一个杀手锏是可审计性:每笔委托动作都追加到 trace.md 审计日志中。
import { Trace } from 'brief-sdk';
const trace = Trace.create();
trace.append({
agent: 'agent-orchestrator',
action: '委托了代码审查任务。',
briefId: 'brief-001',
});
多级委托时还能用 trace.clone() 把副本交给子任务、完成后 trace.merge() 合并回来,最终得到一条贯穿整条链路的完整审计轨迹。
运行官方示例:两条命令跑通全流程
仓库自带可运行示例,git clone https://gitcode.com/gh_mirrors/brief9/brief 后直接执行:
# 简单的 A → B 委托
pnpm example:simple
# 级联 A → B → C 链
pnpm example:cascade
终端会实时打印每一步生成的 .brief.md、.response.md 和最终 trace.md,是理解协议最快的方式。两个示例源码分别是 examples/01-simple-delegation/index.ts 和 examples/02-cascade-chain/index.ts。
总结:Brief 的核心价值一览
| 维度 | Brief 的表现 |
|---|---|
| 学习成本 | 会写 Markdown 就能上手 |
| 上下文隔离 | 显式契约,不再污染共享内存 |
| 可审计性 | trace.md 完整追踪每一条链路 |
| 级联 / 扇出 | 内置深度控制,原生支持 A→(B∥C) |
| 生态兼容 | 与 MCP + A2A 互补,不替代 |
回顾一下这 10 分钟:你认识了 Brief 多 Agent 任务委托协议,理解了"两个 Markdown 文件"的核心机制,学会了 create → parse → createResponse 三步委托闭环,还掌握了级联委托与 Trace 审计。
下一步建议:
- 深入协议细节:docs/design-zh.md
- 了解生态与竞品分析:docs/competitive-analysis-zh.md
- 参与贡献:CONTRIBUTING.md
🎯 记住 Brief 的口号:Agent 值得一份正式的简报,而不是含糊的甩锅。

