Brief 实战:完成第一次 Agent 间任务委托的 5 个步骤
Brief 实战:完成第一次 Agent 间任务委托的 5 个步骤
在构建多 Agent 系统时,如何让一个 Agent 正式地把任务委托给另一个 Agent?开源项目 Brief 正是为解决这个痛点而生——它是首个面向 Agent 间任务委托的开放协议,仅靠两个 Markdown 文件就能完成结构化、可审计的任务交接。本文带你用 5 个步骤,快速完成第一次 Agent 间任务委托。
💡 一句话理解:会写 Markdown,就能用 Brief。没有新 DSL、没有二进制格式、没有框架锁定。
为什么需要 Brief 协议?
在多 Agent 协作中,最大的隐患是 "隐式甩锅"(Implicit Handoff):Agent 之间传递任务时缺乏结构化上下文,导致决策冲突、上下文丢失、系统脆弱。
工具调用有 MCP、Agent 发现与传输有 A2A、能力描述有 Agent Skills,但**"一个 Agent 如何正式委托任务给另一个 Agent"** 长期没有标准。Brief 正是补上这块缺失的语义层。
整个协议就两个文件,简洁直观:
| 文件 | 角色 | 内容 |
|---|---|---|
.brief.md |
委托方发出 | 需要什么、为什么、期望返回什么 |
.response.md |
被委托方回复 | 做了什么、交付了哪些成果 |
下面这张时序图完整展示了 Agent 间任务委托的标准执行流程——从委托方构建简报,到被委托方执行任务并回复,每一步都清晰可追溯。
5 个步骤完成第一次委托
📦 本指南基于官方可运行示例 01-simple-delegation/index.ts,场景为:编排 Agent 委托代码审查 Agent 审查 PR #42。
步骤 1:安装 brief-sdk
在项目中安装 SDK,这是所有后续操作的基础:
npm install brief-sdk
# 或使用 pnpm
pnpm add brief-sdk
步骤 2:创建委托简报(委托方)
委托方用 Brief.create 构造一份结构化简报。body 里就是标准的 Markdown 任务说明:
import { Brief } from 'brief-sdk';
const brief = Brief.create({
delegator: 'agent-orchestrator', // 谁委托
delegatee: 'agent-code-reviewer', // 委托给谁
body: `# Briefing: Review PR #42
## Objective
Review the OAuth 2.0 migration code for security issues.
## Key Constraints
- Focus on token handling and storage.
## Expected Deliverables
1. Review summary with findings.
2. Approve or reject recommendation.`,
});
console.log(brief.content); // 一份合法的 .brief.md 字符串
🔑
brief.content就是可以直接发送的.brief.md内容,id、时间戳、协议版本等元信息都会自动生成,无需手动维护。
步骤 3:接收并解析简报(被委托方)
被委托方收到 Markdown 文本后,用 Brief.parse 解析校验,即可安全读取任务详情:
const incoming = Brief.parse(receivedMarkdown);
console.log(incoming.delegator); // "agent-orchestrator"
console.log(incoming.body); // 任务正文
解析时会做 Schema 校验,格式不合法的简报会被直接拦截,避免下游出错。
步骤 4:生成结构化响应(被委托方)
任务执行完成后,用 createResponse 生成一份结构化响应,明确标注执行状态:
const response = incoming.createResponse({
status: 'success', // 成功 / 失败
body: `# Review Complete
## Findings
- Approved with minor suggestions.
## Recommendation
**Approve** — merge after minor fixes.`,
});
委托方收到后可用 BriefResponse.parse(response.content) 解析,并通过 isSuccess 判断任务是否成功。
步骤 5:追踪整条委托链(可选但推荐)
Trace 是一份只增不改的审计日志,记录整条链路上每个 Agent 的每一步动作,让协作过程完全可审计:
import { Trace } from 'brief-sdk';
const trace = Trace.create();
trace.append({ agent: 'agent-orchestrator', action: 'Delegated code review.' });
trace.append({ agent: 'agent-code-reviewer', action: 'Review complete. Success.' });
console.log(trace.toString()); // 序列化为 trace.md
至此,一次完整的 Agent 间任务委托 就闭环了:创建 → 发送 → 解析 → 执行 → 响应 → 追踪,全程结构化、可审计。
进阶:级联委托 A → B → C
当任务足够复杂时,中间 Agent 还可以继续向下委托。Brief 内置了深度控制(maxDepth / currentDepth / parentId),避免无限嵌套。
创建子简报只需一行,parentId 和深度会自动继承:
const subBrief = parentBrief.createSubBrief({
delegator: 'agent-fullstack-dev',
delegatee: 'agent-docs-writer',
body: '# Write API docs for the new endpoints.',
});
console.log(subBrief.isSubBrief); // true
console.log(subBrief.parentId); // 自动指向父简报 id
⚠️ 当委托深度达到
maxDepth上限时,createSubBrief会主动抛错,防止失控的级联。完整级联示例见 02-cascade-chain/index.ts。
项目资源导航
想深入了解 Brief 协议的设计细节与生态定位,可以从以下资源入手:
- 🚀 可运行示例:examples/01-simple-delegation/index.ts(A → B)、examples/02-cascade-chain/index.ts(A → B → C)
- 📚 中文入门文档:README-zh.md
- 🏗️ 协议设计详解:docs/design-zh.md
- 📊 竞品与市场分析:docs/competitive-analysis-zh.md
- ⚙️ 核心实现:packages/brief-sdk/src/brief.ts、packages/brief-sdk/src/trace.ts
小结
通过本文的 5 个步骤,你已经掌握了 Brief 协议完成第一次 Agent 间任务委托 的核心流程:
| 步骤 | 核心 API | 作用 |
|---|---|---|
| 1 | npm install |
安装 brief-sdk |
| 2 | Brief.create |
创建委托简报 |
| 3 | Brief.parse |
解析收到的简报 |
| 4 | createResponse |
生成结构化响应 |
| 5 | Trace |
追踪委托链 |
Brief 让多 Agent 协作从"含糊甩锅"变成"正式简报"——因为 Agent 值得一份正式的 briefing,而不是一次随意的 handoff。🎯

