10 分钟上手 Brief:多 Agent 任务委托完整快速入门教程

原创2026-10-12 17:02:311,702 阅读

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 多 Agent 任务委托流程图:委托方 Agent 与被委托方 Agent 之间的简报交接 8 步时序

图: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。

Brief 级联委托流程图:Agent A 到 B 到 C 的链式任务交接与并行扇出执行

图:级联委托全景——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 审计。

下一步建议:

🎯 记住 Brief 的口号:Agent 值得一份正式的简报,而不是含糊的甩锅。

登录后查看全文
brief