铃阅
❌

普通视图

从零构建Agent(十三):快速搭建Agent应用的SDK

2026年11月5日 19:22

原创 从码农到工匠 2026-11-05 19:22 上海

Agent SDK 的价值,并不是隐藏所有底层细节,而是提供一套稳定、简洁的接口,让开发者能够快速构建应用,并在复杂场景下保留扩展能力。

本文是「从零构建 Agent」系列的第 13 篇:快速搭建 Agent 应用的 SDK。

经历前 12 期的打磨,ZeroAgent 才初步具备可运行和可扩展的能力。由此可见,从零构建一个功能完备的 Agent 并非易事。

好在,市面上已经有不少 Agent SDK 和开发框架,例如 LangChain、CrewAI、Google ADK、OpenAI Agents SDK 等。它们将 Agent 的运行机制、工具调用、状态管理和多 Agent 协作等能力封装起来,让开发者可以更专注于应用本身。

本文将介绍什么是 Agent SDK,了解常见 SDK 的设计思路,并基于前 12 期构建的 ZeroAgent,实现一个轻量级 Agent SDK,支持快速创建 Agent 应用和 Multi-Agent 编排。

1. 什么是 Agent SDK?

前面 12 篇文章,我们一直在实现 Agent 的底层能力:

  • Model 管理:如何连接和使用不同的模型。

  • Tool:如何让 Agent 调用外部工具。

  • Agent Loop:如何驱动模型和工具循环执行。

  • SubAgent:如何将任务委派给其他 Agent。

  • Extension:如何扩展 Agent 的生命周期。

  • Memory:如何实现跨 Session 的长期记忆。

这些能力构成了 Agent 的运行时核心。

但对于应用开发者来说,每次构建一个 Agent,都需要理解并组装这些组件,仍然有不少工作。

例如,创建一个能够查询天气的 Agent,应用开发者真正关心的可能只是:

const agent = new Agent({
    name: 'Weather Agent',
    model: 'gpt-6',
    instructions: '你是一个天气助手。',
    tools: [weatherTool],
});
const result = await agent.run('东京今天天气怎么样?');

至于内部如何构造 Prompt、调用模型、执行工具,以及如何处理多轮交互,这些细节可以由 SDK 负责。

因此,Agent SDK 的核心价值,是将 Agent Runtime 封装成稳定、易用的编程接口。

一个实用的 Agent SDK,通常需要提供:

能力

作用

Agent 定义

配置模型、指令和工具

Agent 运行

提供统一的执行入口

Tool 集成

让 Agent 调用外部能力

Context / Session

管理对话上下文和状态

Multi-Agent

支持 Agent 之间的委派与协作

扩展机制

允许应用接入自定义逻辑

不同 SDK 的抽象方式有所区别,但核心目标相似:降低 Agent 应用的构建成本。

2. 常见的Agent SDK

2.1 LangChain

是目前较为成熟的 Agent 开发框架之一。

LangChain 提供模型、工具、消息和 Agent 等抽象,并通过统一的接口连接不同模型和工具。开发者可以使用预置的 Agent 模式快速构建应用,也可以通过 Middleware 扩展运行逻辑。

LangChain 生态中还有 LangGraph,主要用于构建更复杂的状态化工作流,例如持久化执行、人工介入、重试以及自定义流程控制。<Cite refs={["turn551982search7","turn551982search16"]}/>

它的特点是:

  • 丰富的模型和工具集成。

  • 提供相对成熟的 Agent 抽象。

  • 支持从简单 Agent 扩展到复杂工作流。

如果希望快速构建 Agent 应用,同时保留较强的扩展能力,LangChain 是一个值得考虑的选择。

2.2 CrewAI

更强调多个 Agent 之间的协作。

CrewAI 的核心抽象包括:

  • Agent:负责特定任务的智能体。

  • Crew:多个 Agent 组成的协作团队。

  • Flow:用于定义任务执行流程和状态管理。

例如,可以构建一个内容生产流程:

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
# 1. 定义两个角色
researcher = Agent(
    role="资深技术研究员",
    goal="找到关于 {topic} 的最新、可信的信息",
    backstory="你是一位经验丰富的分析师,擅长从多个来源交叉验证事实。",
    tools=[SerperDevTool()],  # 赋予它搜索网页的能力
    verbose=True,
)
writer = Agent(
    role="技术报告撰写人",
    goal="将研究发现整理成清晰、结构化的报告",
    backstory="你是一位技术写作专家,善于将复杂信息提炼成易读的文档。",
    verbose=True,
)
# 2. 定义任务,并建立依赖
research_task = Task(
    description="研究 {topic},找到至少 5 个关键事实和近期发展。",
    expected_output="一份包含来源链接的研究简报",
    agent=researcher,
)
write_task = Task(
    description="基于研究简报,撰写一份 800 字左右的 Markdown 报告。",
    expected_output="一份结构清晰的 Markdown 报告",
    agent=writer,
    context=[research_task],  # 关键:writer 会收到 research_task 的输出
    output_file="report.md",
)
# 3. 组建团队并执行
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True,
)
result = crew.kickoff(inputs={"topic": "AI Agent 框架的最新趋势"})
print(result.raw)

researcher 先使用搜索工具调研 {topic},产出一份简报;writer 随后基于这份简报撰写最终报告,并保存到 report.md 文件中。你只需要定义“谁做什么”,CrewAI 会处理 Agent 之间的协调和任务传递。

它更适合以角色分工和任务协作为核心的应用。

2.3 Google ADK

是 Google 推出的 Agent 开发框架。

ADK 不仅支持基于 LLM 的 Agent,也提供了用于确定性流程控制的 Workflow Agent,例如:

  • SequentialAgent:按顺序执行子 Agent。

  • ParallelAgent:并行执行子 Agent。

  • LoopAgent:循环执行任务。

ADK 的设计强调 Agent 组合、工具集成以及应用的构建、评估和部署。它支持多种模型和开发语言,并不局限于 Gemini。<Cite refs={["turn551982search4","turn551982search17"]}/>

ADK 的一个特点是:将 Multi-Agent 协作作为框架中的核心能力,而不是简单地在单个 Agent 上增加一个委派功能。

2.4 OpenAI Agents SDK

是 OpenAI 提供的轻量级 Agent SDK,支持 Python 和 TypeScript。

它的核心抽象包括:

  • Agent:定义模型、指令和工具。

  • Runner / run:执行 Agent。

  • Tools:提供函数调用等外部能力。

  • Handoffs:将任务交给其他 Agent。

  • Guardrails:对输入和输出进行校验。

  • Tracing:记录和调试 Agent 执行过程。

OpenAI Agents SDK 的设计思路是提供少量核心抽象,同时允许开发者定制运行行为。对于需要工具调用、多步骤执行以及 Agent 委派的应用,可以直接使用 SDK 管理 Agent Runtime。<Cite refs={["turn551982search1","turn551982search6"]}/>

需要区分的是,OpenAI SDK 与 OpenAI Agents SDK 并不是同一个概念:前者主要提供 API 客户端能力,后者则在 API 之上进一步封装 Agent 的运行和编排机制。<Cite refs={["turn551982search0","turn551982search3"]}/>

2.5 不同SDK该如何选择

这些 SDK 的侧重点有所不同:

SDK

主要特点

LangChain

模型、工具集成与可扩展 Agent Runtime

CrewAI

基于角色分工的 Multi-Agent 协作

Google ADK

Agent 组合与流程控制

OpenAI Agents SDK

轻量级 Agent Runtime 与委派机制

它们都在解决一个问题:如何将 Agent 的底层能力封装成更容易使用的开发接口。

接下来,我们基于 ZeroAgent 实现一个自己的 Agent SDK。

3. ZeroAgent SDK实现

前面 12 篇文章,我们已经构建了 ZeroAgent 的核心能力。本篇不再重新实现 Agent Loop,而是站在应用开发者的角度,对已有能力进行封装。

ZeroAgent SDK 的目标是:

  1. 提供统一的 Agent 定义和运行接口。

  2. 支持通过配置创建和运行 Agent。

  3. 支持多个 Agent 之间的任务委派与协作。

3.1 定义SDK Agent接口

首先,定义 Agent 的运行结果和统一接口:

exporttype AgentResult = {
    name: string;
    output: string;
    children?: AgentResult[];
};
exportinterface RunnableAgent {
    readonly name: string;
    run(
        input: string,
        options?: AgentRunOptions,
    ): Promise<AgentResult>;
}

这里有两个关键抽象:

  • RunnableAgent:所有可运行 Agent 的统一接口。无论是基于 LLM 的 Agent,还是负责协调多个 Agent 的 Coordinator,都可以通过 run() 执行任务。

  • AgentResult:统一的执行结果。除了 Agent 名称和输出内容,还可以通过 children 保存子 Agent 的执行结果。

children 是一个很重要的设计。它不仅可以返回最终答案,还能够保留任务委派过程中的子结果,形成一棵 Agent 执行树。

例如:

Coordinator
├── Researcher
│   └── 搜集资料
├── Writer
│   └── 生成文章
└── Reviewer
    └── 检查文章

通过 AgentResult,SDK 可以将最终结果和子 Agent 的执行结果统一返回。

3.2 创建并运行 Agent

有了统一接口,应用开发者就可以直接创建 Agent,而不需要关心底层的 Agent Loop、Model 请求和 Tool 调用细节。

例如,创建一个使用工具获取城市时间的 Agent:

const prompt =
    process.argv.slice(2).join(' ') || '杭州现在是什么时间.';
const tool = new FunctionTool({
    name: 'get_current_time',
    description: 'Get the current time in a city.',
    parameters: { city: 'The name of the city.'},
    execute: ({ city }) => ({
        city,
        time: '10:30 AM',
    }),
});
const agent = new LlmAgent({
    name: 'sdk-tool-test',
    model: new OpenAICompatibleLlm({
        model: modelName,
    }),
    tools: [tool],
});
console.log(`Sending a live request to ${modelName}...`);
const result = await agent.run(prompt, {
    signal: AbortSignal.timeout(60_000),
});
console.log(result.output);

这段代码展示了 SDK 的基本使用方式:

  1. 创建 Tool,提供 Agent 可以调用的外部能力。

  2. 创建 LLM 实例,指定使用的模型。

  3. 创建 LlmAgent,组合模型和工具。

  4. 调用 agent.run() 执行任务。

  5. 获取 AgentResult,读取最终输出。

其中,AbortSignal 可以用于控制请求的生命周期,避免调用长时间阻塞。

需要注意,示例中的 get_current_time 返回的是固定时间 10:30 AM,这里只是演示 Tool 的调用形式,并不是真正查询当前时间。

3.3 Multi-Agent编排

参考 Google ADK 的设计,ZeroAgent SDK 也提供了 Agent 编排能力。不过,目前我们暂时只支持两种简单、确定性的编排方式:SequentialAgent 和 ParallelAgent。

SequentialAgent 按顺序执行多个 Agent,并将前序步骤的结果传递给后续 Agent;ParallelAgent 则让多个 Agent 并行处理同一个输入,再汇总各自的结果。相比动态的任务规划与调度,这种方式更简单,也更容易理解和控制。

单个 Agent 可以通过工具完成任务,但对于复杂任务,我们往往需要多个 Agent 协作。

例如,构建一个技术文章生成应用:

User
 |
 v
SequentialAgent
 |
 +----> Researcher
 |
 +----> Writer
 |
 +----> Reviewer
 |
 v
Final Result

Researcher 负责搜集资料,Writer 负责撰写文章,Reviewer 负责审核。ZeroAgent SDK 当前实现了两种基础的 Workflow Agent:SequentialAgent 和 ParallelAgent。

它们都实现了 RunnableAgent 接口,因此可以像普通 Agent 一样被组合和调用。

SequentialAgent:串行执行

SequentialAgent 按照预先定义的顺序执行子 Agent。

exporttype WorkflowAgentOptions = {
    name: string;
    agents: readonly RunnableAgent[];
};

创建 Workflow 时,通过 agents 指定执行顺序:

const workflow = new SequentialAgent({
    name: 'Article Workflow',
    agents: [researcher, writer, reviewer],
});
const result = await workflow.run('撰写一篇关于 Agent Memory 的技术文章')

第一个 Agent 接收原始输入;后续 Agent 则会同时获得原始任务和前面步骤的执行结果。

ParallelAgent:并行执行

有些任务之间没有依赖关系,可以同时交给多个 Agent 处理。

例如:

                +----> Researcher A
                |
输入任务 --------+----> Researcher B
                |
                +----> Researcher C
                |
                v
             汇总结果

此时可以使用 ParallelAgent:

const workflow = new ParallelAgent({
    name: 'Research Workflow',
    agents: [researcherA, researcherB, researcherC],
});
const result = await workflow.run('从不同角度分析 Agent Memory');

ParallelAgent 使用 Promise.all 并行执行所有子 Agent:

const children = awaitPromise.all(
this.agents.map((agent) => agent.run(input, { ...options, signal })),
);

所有子 Agent 接收相同的输入,并行执行。执行完成后,SDK 将每个 Agent 的输出汇总:

return {
    name: this.name,
    output: children
        .map((child) =>`## ${child.name}\n${child.output}`)
        .join('\n\n'),
    children,
};

与 SequentialAgent 不同,ParallelAgent 不会将某个子 Agent 的输出传递给另一个子 Agent。它们彼此独立,最终由 Workflow 汇总结果。

由此可见,基于 Agent SDK 进行显式的 Agent 编排,相比完全依赖 Agent 自主规划和调度,能够提供更确定、可控的执行流程。当然,这也意味着流程需要由开发者提前定义,灵活性相对有限。

总结

前 12 篇文章中,我们从零构建了 ZeroAgent 的核心能力;第 13 篇则开始将这些能力封装为 SDK。

通过统一的 Agent 接口,应用开发者可以快速创建和运行 Agent;通过 Multi-Agent 编排,可以将复杂任务拆分给不同的 Agent 协作完成。

Agent SDK 的价值,并不是隐藏所有底层细节,而是提供一套稳定、简洁的接口,让开发者能够快速构建应用,并在复杂场景下保留扩展能力。

目前,ZeroAgent SDK 只支持串行和并行两种基础编排方式。后续还可以继续扩展更复杂的 Workflow,例如条件分支、循环执行和动态任务路由。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter13 中获取本文的完整源码。

若觉得本文对你有帮助,请支持我的新书:《Harness 工程实战》。

参考资料

  • Google ADK TypeScript Quickstart

  • Google ADK Workflows

  • Google ADK Sequential Agent

  • Google ADK Parallel Agent

  • LangChain Agents

  • LangChain Multi-agent

  • CrewAI Introduction

  • CrewAI First Crew

  • CrewAI First Flow

跳转微信打开

从零构建Agent(十二):长期Memory管理

2026年11月3日 14:56

原创 从码农到工匠 2026-11-03 14:56 上海

本文参考 Hermes 的 Memory 机制,基于 Extension 为 ZeroAgent 实现通用 Memory Provider,并通过 Hindsight 的事实提取、实体关联与记忆召回,实现跨 Session 的长期记忆能力。

本文是「从零构建 Agent」系列的第 12 篇:长期 Memory 管理。

我想写这篇文章很久了。长期 Memory 是 Agent 非常有意思的一个话题,也是体现 Agent 差异化能力的关键。

有段时间,大家热衷于“养马”——所谓“养马”,就是 Hermes Agent 用得越多,就越“聪明”。这种能力背后,离不开 Agent 的记忆与学习机制。

本文将分析 Hermes 的长期 Memory 设计,并基于上一篇实现的 Extension,为 ZeroAgent 增加一个通用的 Memory Provider 机制,最终通过 Hindsight 实现跨 Session 的长期记忆。

1. Agent 的长期记忆

Agent 的上下文窗口并不等于长期记忆。

上下文窗口包含当前请求发送给模型的内容;Session 通常保存一段对话的消息历史;而长期记忆需要在 Session 结束后仍然保留,并能够在之后被检索出来。

1.1 为什么 Memory 很重要

当前 ZeroAgent 的记忆主要依赖 Session 上下文。

虽然我们已经支持 Session 持久化,但如果每次对话都将所有历史消息重新放进 Prompt,会带来几个问题:

  1. 上下文和成本不断增长:历史越长,模型每轮需要处理的内容越多。

  2. 噪音累积:大部分旧消息与当前问题无关,可能干扰模型判断。

  3. 重要信息被淹没:稳定偏好、项目约定和一次性闲聊混在一起,难以区分。

  4. 记忆难以维护:事实可能过期或相互矛盾,也可能包含不应长期保存的敏感信息。

因此,Memory 系统处理的不只是“保存”,还包括:选择什么值得记、存在哪里、何时检索、如何更新和淘汰。

从用途上看,Agent 的记忆可以分为几类:

  • 语义记忆:相对稳定的事实、偏好和约定,例如用户使用的操作系统。

  • 情景记忆:过去发生过的对话或事件,例如某次排错过程。

  • 程序性记忆:完成某类任务的步骤、检查点和注意事项,通常适合封装成 Skill。

还需要注意,记忆并不等于指令。被检索的旧文本应当作为有来源、可能过时的上下文,而不是自动获得高于当前用户要求或系统策略的权限。

在正式实现之前,我们先看看 Hermes 的设计。

1.2 Hermes 的 Memory:四层能力模型

在研究 Agent Memory 时,我参考了 Hermes Agent 的设计。

Hermes 的记忆管理并不依赖单一机制,而是通过不同能力解决不同的问题。这里我将其归纳为四个层次:

Layer

机制

作用

Layer 1

MEMORY.md

 / USER.md

保存精简的长期记忆

Layer 2

Session Search(SQLite + FTS5)

检索历史对话

Layer 3

Memory Provider(如 Hindsight)

提供更丰富的记忆管理能力

Layer 4

Skills

保存可复用的知识和操作流程

这四层并不是互相替代的关系,而是分别解决不同类型的信息管理问题。

Layer 1:MEMORY.md 与 USER.md

Hermes 使用 MEMORY.md 和 USER.md 保存精简的持久化记忆。

  • MEMORY.md:保存项目背景、技术约定和经验。

  • USER.md:保存用户偏好和长期需求。

这类记忆通常会在 Session 开始时加载到上下文中。

它的优点是简单直接,但记忆文件必须保持精简,否则每次请求都会产生额外的 Token 开销。

Layer 2:FTS5 会话搜索与记忆整理

对于没有进入 Memory 文件的历史信息,可以通过 Session Search 按需查找。

Hermes 使用 SQLite 保存历史 Session,并利用 FTS5 提供全文检索能力。

Memory 与 Session Search 的区别在于:

  • Memory 保存提取后的长期信息。

  • Session Search 保存并检索原始历史对话。

前者解决「记住什么」,后者解决「找回过去发生的事情」。

Layer 3:Memory Provider——可替换的外部记忆后端

当记忆需要语义召回、跨设备共享、独立扩容或专门的记忆处理能力时,可以把存储与检索委托给外部 Provider,例如 Hindsight。

Agent 不应直接依赖每个后端的 SDK。可先定义统一接口:

exportinterface MemoryProvider {
    retain(content: string): Promise<void>;
    recall(query: string): Promise<readonly string[]>;
}

生命周期扩展只依赖 MemoryProvider,由具体 Provider 负责将调用映射到服务 API。未来增加另一个后端时,可以保持 Agent 的读写时机不变。

不同层可以共存,而不是互相替代:

  • Markdown 适合人工审阅和明确维护的事实。

  • FTS5 适合精确搜索本地历史。

  • 外部 Provider 适合语义检索或集中管理。

Layer 4:Skill——程序性记忆

严格来说,Skill 并不是传统意义上的 Memory。

Memory 记录的是「过去发生了什么」或者「我们知道什么」;Skill 则描述「遇到某类任务时应该如何做」。

例如:

Memory:
ZeroAgent 使用 TypeScript 实现。
Skill:
如何构建、测试和部署 TypeScript 项目。

Memory 提供背景信息,Skill 提供可复用的执行能力。

Memory和Skill的边界可以这样理解:记忆提供背景事实,Skill 提供可复用的操作方法。Skill 也需要维护和验证,不能因为它被保存下来就假定步骤永远正确。这种自修复能力,是Hermes变“聪明”的关键。

1.3 关于 Hindsight

Hindsight 是 Vectorize 推出的开源 Agent 记忆系统。

它的目标不是简单地保存聊天记录,而是让 Agent 能够记住过去的经历、理解事实之间的关系,并利用历史信息改善未来的回答。

在选择 Memory Provider 时,我最终选择了 Hindsight。

Hindsight 的核心操作可以概括为三个:

操作

作用

Retain

从交互中提取并保存记忆

Recall

检索与当前问题相关的记忆

Reflect

基于已有记忆进行综合推理

例如,用户告诉 Agent:

ZeroAgent 使用 TypeScript 实现,目前已经支持 SubAgent 和 Extension。

经过 Retain,这些信息可以被提取为独立的记忆。

当用户再次问:

ZeroAgent 目前已经实现了哪些能力?

Agent 就可以通过 Recall 检索相关记忆,并将结果注入当前上下文。

如果用户进一步问:

根据之前的讨论,ZeroAgent 接下来应该优先实现什么?

则可以利用 Reflect 对已有记忆进行综合分析。

一句话总结:Hindsight 是一个通过事实提取、关联、整合和反思,让 Agent 从历史交互中逐渐形成长期认知的记忆系统。

2. ZeroAgent的Memory实现

上一篇文章中,我实现了 Extension 能力,就是为了让后续功能更容易扩展。

在 Extension 中,我们提供了 before_agent_start 扩展点,可以在 Agent 发起模型请求之前修改 System Prompt,并注入额外的上下文。

这正好为 Memory 提供了两个关键入口:

  1. 请求开始前,检索相关记忆并注入上下文。

  2. 一轮对话结束后,将本轮对话保存到记忆服务。

2.1 Memory Provider接口

为了避免 ZeroAgent 与 Hindsight 绑定,我们先定义一个统一的 MemoryProvider 接口:

exportinterface MemoryProvider {
    retain(content: string): Promise<void>;
    recall(query: string): Promise<readonly string[]>;
}

retain 用于存储记忆,recall 根据查询召回相关记忆。具体的记忆服务通过实现该接口接入 ZeroAgent。

这里我们使用 Hindsight 作为默认实现。

2.2 HindsightMemoryProvider

HindsightMemoryProvider 封装 Hindsight Client,将记忆存储和召回操作统一到 MemoryProvider 接口中。

exportclass HindsightMemoryProvider implements MemoryProvider {
    readonly #client: HindsightClientLike;
    readonly #bankId: string;
async retain(content: string): Promise<void> {
const response = awaitthis.#client.retain(this.#bankId, content);
if (!response.success) {
thrownewError(`Hindsight failed to retain memory in bank "${this.#bankId}"`);
        }
    }
async recall(query: string): Promise<readonly string[]> {
const response = awaitthis.#client.recall(this.#bankId, query);
return response.results.map((memory) => memory.text);
    }
}

Provider 将 Hindsight 的具体调用细节封装起来。对于 ZeroAgent 来说,记忆后端只是一个实现了 MemoryProvider 的对象。

2.3 注册 Memory Extension

有了 Memory Provider,接下来只需要利用 Extension 生命周期,在 Agent 执行前召回记忆,在一轮对话结束后存储记忆。

exportfunctionregisterMemoryExtension(
    extensions: ExtensionRunner,
    provider: MemoryProvider,
): void
{
    extensions.on('before_agent_start', async (event) => {
try {
const memories = await provider.recall(event.input);
if (memories.length > 0) {
                event.systemPromptOptions.sections['long_term_memory'] = [
'Relevant long-term memories:',
                    ...memories.map((memory) =>`- ${memory}`),
                ].join('\n');
            }
        } catch (error) {
            reportMemoryError('recall', error);
        }
    });
    extensions.on('turn_end', async (event: Extract<AgentEvent, { type: 'turn_end' }>, context) => {
try {
await provider.retain(`User: ${context.input}\nAssistant: ${event.message.content}`);
        } catch (error) {
            reportMemoryError('retain', error);
        }
    });
}

这里有两个关键点:

  • Recall:在 before_agent_start 阶段,根据用户输入召回相关记忆,并注入 long_term_memory Prompt section,让模型在生成回答前获得必要的历史上下文。

  • Retain:在 turn_end 阶段,将用户输入和 Assistant 的最终回复存入记忆。对于工具调用消息、非 Assistant 消息以及空内容,不进行存储。

记忆服务的异常不会直接中断 Agent 主流程,而是通过 reportMemoryError 统一处理。

至此,ZeroAgent 的 Memory 能力就通过 Extension 接入了现有 Agent 流程。Agent 本身不需要关心记忆存储在什么地方,也不需要了解 Hindsight 的具体 API。后续如果需要接入其他记忆服务,只需要实现 MemoryProvider 即可。

3.  HindSight背后原理解析

3.1 长记忆效果测试

先看一个简单的例子。

Session A:

User:我叫 Frank,是一名软件工程师,在华为工作。

Session B:

User:Frank 的工作是什么?

Agent:根据记忆中的信息,Frank 是一名软件工程师,在华为工作。

两个问题发生在不同的 Session 中。Agent 能够回答,是因为 Hindsight 将 Session A 中的信息存储为长期记忆,并在 Session B 中将相关记忆召回。

那么,这些信息是如何存储和关联的?

3.2 背后原理解析

Hindsight 并不是简单地保存整段对话,而是将原始内容、提取出的事实、实体以及事实之间的关系组织起来。

可以通过几个核心概念理解它的工作方式:

  • documents:原始信息。 保存输入的原始内容,作为记忆的来源。

  • memory_units:事实。 从原始内容中提取出的独立事实,是后续 Recall 的重要依据。例如「Frank 是一名软件工程师」。

  • entities:实体。 事实中涉及的对象,例如人物、组织或概念。例如「Frank」「华为」和「软件工程师」。

  • memory_links:关系。 连接相关记忆,描述事实之间的关联。

以 Session A 为例:

User:
我叫 Frank,是一名软件工程师,在华为工作。

Hindsight 对这段对话进行处理,将原始内容保存到 documents,并提取出相关记忆。其过程如下:在这里插入图片描述这里需要区分两个概念:Entity 是「谁或什么」,Memory Unit 是「关于它的事实」。

例如:

Entity:
Frank
华为
软件工程师
Memory Unit:
Frank 是一名软件工程师
Frank 在华为工作

Entity 本身并不表达完整事实。只有将实体与 Memory Unit 关联起来,才能表达「Frank 是软件工程师」或「Frank 在华为工作」。

用户输入:

User:Frank 的工作是什么?

此时是一个新的 Session,Agent 本身可能没有 Session A 的上下文。

Hindsight 执行 recall,从已有记忆中检索出与 Frank 相关的事实。其过程如下:在这里插入图片描述由此可见,跨 Session 记忆的关键,不是 Agent 记住了 Session A 的聊天记录,而是 Hindsight 将 Session A 转化为持久化的结构化记忆,并在 Session B 中重新检索出来。

4. 总结

本文介绍了 Agent 长期 Memory 的价值,并参考 Hermes 的记忆机制,为 ZeroAgent 实现了一个通用的 Memory Provider。

通过 Extension,ZeroAgent 可以在请求开始前 Recall 相关记忆,并在对话结束后 Retain 新的信息。借助 Hindsight,我们进一步实现了跨 Session 的长期记忆。

Memory 让 Agent 不再局限于当前 Session,而是能够从过去的交互中提取、保存并重新利用信息。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter12 中获取本文的完整源码。

若觉得本文对你有帮助,请支持我的新书:《Harness 工程实战》。

跳转微信打开

从零构建Agent(十一):Extension扩展

2026年10月31日 17:36

原创 从码农到工匠 2026-10-31 17:36 上海

三层事件体系与 ExtensionAPI、ExtensionRunner 配合,实现了一个轻量级的扩展机制。

本文是「从零构建 Agent」系列的第 11 篇:Extension扩展。

本来我打算在这一篇实现跨 Session 的 Memory 功能。要实现 Memory,我们需要能够动态地向 Agent 注入上下文,而扩展点(Extension)正好可以提供这样的能力。不过,当前的 ZeroAgent 还不具备扩展机制,于是我决定先实现 Extension 功能,为后续 Memory 的实现打好基础。

所谓 Extension,就是允许外部代码参与 Agent 的运行过程:观察 Agent 的生命周期、动态注入上下文、注册工具和命令,而不需要修改 Agent 核心代码。

之前我分析过《DeepSeek Harness 的 Plugin 实现机制》。DeepSeek Harness(dsh)把扩展机制做得比较极致,甚至提出了一个理念:Everything is plugin。

不过,本文的Extension实现并没有采用dsh的思路,而是选择了类似于 pi agent extension的极简实现。

1. 模型解耦

在实现 Extension 之前,我们首先需要做一件事:模型解耦。

为什么 Extension 的实现需要先进行模型解耦?

原因在于,Extension 依赖 Agent 生命周期事件,而这些事件中的一部分来自模型端的流式响应。如果 Agent 直接依赖某个模型供应商的 SDK 和事件格式,那么模型供应商的差异就会传递到 Agent 核心,进而影响整个事件体系。

在此之前,openai-client.ts 中的 stream() 方法直接将 OpenAI SDK 返回的流式事件交给 Agent 处理。这意味着,如果要接入使用不同协议的 Provider(比如 Anthropic),就需要在 Agent 核心中增加针对不同 Provider 的处理逻辑。这显然不是我们想要的设计。

因此,我们需要引入一个统一的抽象层:屏蔽不同 Provider 的接口和流式事件差异,让 Agent 只依赖统一的模型客户端接口。

1.1 AiClient 接口

抽象层的核心是模型无关的 AiClient 接口,Agent 只依赖接口;具体实现(OpenAiClient)通过工厂函数创建后注入:

// src/ai/ai-client.ts
exportinterface AiClient {
    stream(request: AiRequest): AsyncGenerator<AiEvent>;
}

AiClient 只有一个方法 stream():接收模型请求,返回一个事件异步迭代器。

Agent 不关心底层使用的是 OpenAI SDK,还是其他模型供应商的 SDK。它只需要通过 for await...of 消费统一的 AiEvent 即可。

这样,Agent 核心就不再依赖具体的模型 SDK。

1.2 工厂函数

OpenAiClient 实现 AiClient 接口,内部根据 baseUrl + key 缓存 OpenAI 客户端实例,并通过 ProviderResolver 获取对应的连接凭据。

src/ai/index.ts 中的 createAiClient 工厂函数,根据 Provider 名称选择具体实现:

exportfunctioncreateAiClient(provider: string, options: AiClientFactoryOptions): AiClient{
if (!openAiCompatibleProviders.has(provider.toLowerCase())) {
thrownewError(`Unsupported AI provider "${provider}".`);
    }
returnnew OpenAiClient(options);
}

目前,ZeroAgent 接入的部分 Provider 可以通过 OpenAI 兼容接口复用 OpenAiClient,因此不需要为每个 Provider 单独实现客户端。

需要注意的是,OpenAI 兼容并不意味着所有供应商都完整实现了 OpenAI 的所有 API。具体能否复用 OpenAiClient,还取决于它所使用的 API 接口、请求格式和流式事件格式是否兼容。

未来接入不兼容协议的 Provider 时,只需要新增一个 AiClient 实现,并在工厂函数中增加对应的分支,Agent 核心逻辑不需要跟着修改。

1.3 AiEvent

AiEvent 是模型客户端向 Agent 输出的统一事件,也是屏蔽不同 Provider 流式事件差异的关键。

举个例子:工具调用(Tool Call)在不同模型供应商的协议中可能有不同的表达方式。在 OpenAI 的 Responses API 中,函数调用对应 function_call 类型的输出;在 Anthropic 的消息流中,则使用 tool_use 等事件表达工具调用。

但是经过中间层转换之后,在 ZeroAgent 内部,我们统一使用 toolcall 相关事件表达这一过程。

完整的模型响应流式事件定义如下:

// src/ai/ai-client.ts
exporttype AiEvent =
    | { type: 'start' }
    | { type: 'text_start' }
    | { type: 'text_delta'; delta: string }
    | { type: 'text_end'; content: string }
    | { type: 'thinking_start' }
    | { type: 'thinking_delta'; delta: string }
    | { type: 'thinking_end'; content: string }
    | { type: 'toolcall_start' }
    | { type: 'toolcall_delta'; delta: string }
    | { type: 'toolcall_end'; toolCall: ToolCall }
    | { type: 'done'; reason: string }
    | { type: 'error'; reason: string };

OpenAiClient 作为 AiClient 的具体实现,其主要职责就是将底层 API 返回的流式事件转换为统一的 AiEvent。

例如:

  • response.output_text.delta → text_delta

  • response.function_call_arguments.delta → toolcall_delta

其他事件也按照相同的思路进行转换。

这里需要强调:AiEvent 并不是 Provider 原始事件的简单转发,而是经过归一化之后的内部事件模型。它保留了 Agent 所需要的语义,同时屏蔽了底层协议的具体细节。

未来即使接入 Anthropic 等使用不同协议的 Provider,我们也只需要实现一个新的 AnthropicAiClient,将其流式响应转换为相同的 AiEvent 即可。

这样,Agent 核心就不需要关心底层究竟使用了哪一家模型供应商。

2. 事件分层

模型解耦之后,我们得到了模型无关的 AiEvent。

不过,AiEvent 主要关注的是 Agent Loop 过程中,模型返回的流式响应,包括文本、思考内容和工具调用等信息。

一个完整的 Agent 不仅仅是消费模型响应,还需要管理轮次(Turn)、消息(Message)、工具执行以及整个 Agent 的生命周期。

因此,仅仅依赖 AiEvent 是不够的。我们还需要在它的基础上建立更高层次的事件体系:AgentEvent 和 ExtensionEvent。

2.1 AgentEvent

AiEvent 表达的是模型层面的语义,并不能很好地表达 Agent 自身的运行过程。

例如,一次 Agent 执行可能包含多个 Turn,但这个概念在 AiEvent 中并不存在。

另外,AiEvent 中的 toolcall_end 表示模型已经生成完毕工具调用信息,并不代表工具已经执行完成。工具执行属于 Agent 层面的行为,需要由更高层次的事件来表达。

鉴于此,我们需要定义一个能够描述 Agent 运行时语义的事件类型:AgentEvent。

exporttype AgentEvent =
    | { type: 'agent_start' }
    | { type: 'agent_end'; message: AgentMessage; }
    | { type: 'turn_start' }
    | { type: 'turn_end'; message: AgentMessage; toolResults: ToolResultMessage[] }
    | { type: 'message_start'}
    | { type: 'message_update'; message?: AssistantMessage; aiEvent: AiEvent }
    | { type: 'message_end'; message?: AssistantMessage }
    | { type: 'tool_execution_start'; toolCallId: string; toolName: string; args: any }
    | { type: 'tool_execution_end';toolCallId: string;result: any;}

可以看到,AgentEvent 在 AiEvent 的基础上增加了 Agent 自身的运行语义。

例如:

  • agent_start / agent_end:表示一次完整的 Agent 执行开始和结束。

  • turn_start / turn_end:表示一次模型交互轮次的开始和结束。

  • message_start / message_update / message_end:表示消息的生命周期。

  • tool_execution_start / tool_execution_end:表示工具实际执行的开始和结束。

这里有一个值得注意的设计:message_update 事件同时携带了 aiEvent 字段,保留了原始的第一层事件。

这样做的好处是,不同消费者可以根据自己的需求选择事件粒度。

2.2 ExtensionEvent

AgentEvent 虽然从 Agent 的视角对 AiEvent 进行了封装,但它主要关注的还是 Agent Loop 内部的运行过程,无法覆盖完整的 Agent 生命周期。

从 Extension 的视角来看,我们需要的扩展点应该超出 Agent Loop 的范围。

例如,我们希望在 Agent 正式运行之前,就有一个扩展点(before_agent_start),让外部代码能够修改 System Prompt、注入上下文。

后续要实现的跨 Session Memory,就需要利用这样的扩展点,在 Agent 发起模型请求之前,将历史记忆动态注入当前上下文。

因此,我们还需要一个与扩展机制对应的事件体系:ExtensionEvent。

在类型定义上,我们可以利用 TypeScript 的联合类型,在 AgentEvent 的基础上增加 Extension 所需的事件:

ExtensionEvent = BeforeAgentStartEvent | AgentEvent

这里的 BeforeAgentStartEvent 就是一个典型的扩展层事件。它发生在 Agent 生命周期的起点,早于 agent_start 和 Agent Loop。

因此,ExtensionEvent 实际上是 AgentEvent 的超集,既包含 Agent 运行过程中的事件,也包含 Extension 自身需要的生命周期钩子。

2.3 三层事件体系

事件流的处理是 Agent 中比较复杂的逻辑之一。面对复杂问题,一个常见的设计思路就是分而治之。

这里的事件分层也是如此:每一层只关注自己需要的语义粒度,层与层之间通过明确的类型转换衔接。

每一层的消费者只需要关注自己关心的事件,不必直接处理其他层的实现细节。

层级

类型名

消费者

粒度

第一层:模型层

AiEventAgent.stream()

最细粒度:每个 SSE delta

第二层:Agent层

AgentEvent

界面、扩展器

Agent Loop 语义

第三层:扩展层

ExtensionEvent

Extension 钩子

AgentEvent 超集

说实话,事件体系是我目前在 ZeroAgent 上花费时间最多的部分。主要原因是很多设计一开始并不清晰,不知道什么样的抽象才是合理的。

最后参考了 Pi Agent 的实现,结合 ZeroAgent 当前的架构,才逐渐确定了这样的分层设计。![[Pasted image 20261030182346.png]]

3. Extension 实现

前面介绍了模型解耦和事件分层,接下来再来看本章真正要实现的功能:Extension。

ZeroAgent 的 Extension 设计比较简单,主要由三个部分组成:

  1. ExtensionAPI:提供给扩展使用的 API。

  2. ExtensionRunner:负责加载扩展、管理注册表和分发事件。

  3. Agent 生命周期钩子:在合适的时机触发扩展,让外部代码参与 Agent 的运行。

3.1 ExtensionAPI 与一个最小扩展

Extension 是一个 .ts 模块,default export 一个工厂函数,接收 ExtensionAPI:

exportinterface ExtensionAPI {
    on(type, handler): void;                 // 事件钩子
    registerCommand(name, command): void;    // 注册命令
    registerTool(definition, handler): void; // 注册工具
}

三个 API 覆盖 Extension 的全部能力。一个最小但完整的扩展:

// .zeroagent/extensions/demo.ts
exportdefaultfunction (zeroagent) {
    zeroagent.on('before_agent_start', (event) => {
        event.systemPromptOptions.sections['project_context'] = 'Project context.';
    });
    zeroagent.registerCommand('hello', {
        description: 'Show a greeting',
async handler(args) { console.log(`Hello, ${args || 'world'}!`); },
    });
    zeroagent.registerTool(
        { type: 'function', name: 'get_answer', description: 'Return the answer.',
          parameters: { type: 'object', properties: {} }, strict: true },
async () => '42',
    );
}

3.2 ExtensionRunner 与两层加载

ExtensionRunner 是整个扩展系统的核心。

它持有 handler、command、tool 三个注册表,负责扩展的加载、事件分发以及相关资源管理。

在事件分发上,ZeroAgent 将其分为两种方式:

  • emit(event):通用事件分发,用于通知型事件。Handler 的返回值会被忽略。

  • emitBeforeAgentStart(input, options):专门处理 before_agent_start 事件。Handler 除了可以修改传入的配置对象,还可以通过返回值注入消息。

为什么要将 before_agent_start 单独处理?

因为普通事件主要用于通知消费者,消费者监听事件后执行自己的逻辑即可,不需要改变 Agent 的执行流程。

但 before_agent_start 不一样,它需要允许 Extension 参与请求组装过程,修改 System Prompt,甚至注入额外的消息。因此,它需要一个专门的执行入口来处理 Handler 的返回值。

在扩展加载方面,与 Skills、Commands、SubAgents 一致,Extension 也采用「用户级 → 项目级」两层加载机制。

层级

路径

用户级

~/.zeroagent/extensions/*.ts

项目级

{workdir}/.zeroagent/extensions/*.ts

3.3 before_agent_start:修改 System Prompt

before_agent_start 是唯一能「塑造」行为的钩子,在请求组装前触发。它携带可变对象 systemPromptOptions:

exporttype SystemPromptOptions = {
    sections: Record<string, string>;  // 命名段落,按插入顺序渲染
    appendSystemPrompt: string;        // 追加在所有段落之后
};

Agent 在 #prepareRequest 里先创建初始 options(base 指令占首个 section),交给扩展修改,再渲染成最终 instructions:

const systemPromptOptions = createSystemPromptOptions(instructions);
if (this.#extensions) {
const before = awaitthis.#extensions.emitBeforeAgentStart(input, systemPromptOptions);
    injectedMessages = before.messages ?? [];
}
const finalInstructions = composeSystemPrompt(systemPromptOptions);

4.4 参考 Pi Agent 的 Extension

ZeroAgent 的 Extension 主要参考了 Pi Agent——一个极简、可扩展的 Agent Harness。

Pi 的扩展同样采用 default export function (pi) 的 .ts 模块形式。它的 ExtensionAPI 除了 on、registerCommand、registerTool 之外,还提供了 TUI、快捷键、命令行参数、Provider、MCP 等扩展能力,以及消息发送等接口。

ZeroAgent 当前并没有照搬 Pi 的全部能力,而是重点借鉴了两个设计:

  1. ExtensionRunner 的事件分发设计:普通事件使用 emit(),而 before_agent_start 这种具有特殊返回值语义的钩子,使用独立的 emitBeforeAgentStart()。

  2. 可变的systemPromptOptions:通过可变的 sections 对象管理 System Prompt,而不是要求 Extension 每次返回一份完整的新 Prompt。这样既能保留基础指令,也方便多个 Extension 在不同位置增加自己的上下文。

ZeroAgent 目前还是一个以学习和理解 Agent 架构为主的项目,没有必要一开始就实现 Pi 那样完整的扩展能力。

等后续实现 TUI 之后,再逐步增加 TUI 相关的扩展接口。

4. 总结

本章为了实现 Extension,实际上做了两项基础架构改造:模型解耦和事件分层。

整个实现过程可以归纳为以下几个步骤:

  1. 需要扩展点:为了让 Agent 支持运行时可插拔的能力,需要允许外部代码观察和塑造 Agent 的行为。

  2. 梳理 Agent 生命周期:Extension 必须依附于 Agent 的生命周期。我们梳理了一次 Agent 执行的完整流程,从 before_agent_start 到 agent_start,再到 ReAct 循环,最后以 agent_end 结束。

  3. 建立事件分层:不同阶段需要不同粒度的事件,因此设计了 AiEvent、AgentEvent 和 ExtensionEvent 三层事件体系。

  4. 实现模型解耦:为了避免第一层事件依赖具体 Provider,我们抽象出 AiClient 接口和 AiEvent 类型,将 Agent 核心与具体模型 SDK 解耦。

最终,三层事件体系与 ExtensionAPI、ExtensionRunner 配合,实现了一个轻量级的扩展机制。

Extension 可以监听 Agent 生命周期、修改 System Prompt、注入上下文、注册工具和命令,而不需要修改 Agent 核心代码。

至此,ZeroAgent 从一个主要依靠内置功能实现能力的 Agent,进一步演进为一个能够通过外部扩展塑造自身行为的 Agent 框架。

本章也为下一篇实现跨 Session Memory 做好了准备:Memory 可以作为一个独立的 Extension,在 Agent 启动之前检索历史记忆,并将其动态注入当前上下文。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter11 中获取本文的完整源码。

若觉得本文对你有帮助,请支持我的新书:《Harness 工程实战》。

跳转微信打开

从零构建Agent(十):Model管理

2026年10月27日 15:19

原创 从码农到工匠 2026-10-27 15:19 上海

本文实现一套完整的 Model 管理机制,包括 Provider 配置、模型注册、客户端路由、运行时切换。

本文是「从零构建 Agent」系列的第 10 篇。

在之前的实现中,我们通过 .env 保存 MaaS(Model as a Service)的 baseUrl 和 apiKey,并在构造 ResponsesClient 时固化成一个 OpenAI 实例。这种“焊死”的做法导致 Agent 启动后只能使用配置中的单个模型,无法在运行时切换。

通用 Agent 不应该被单一模型或供应商绑定。它应该能够统一管理不同供应商提供的模型,根据任务选择合适的模型,并在运行时切换模型。

本文将围绕这些目标,为 ZeroAgent 实现一套完整的 Model 管理机制,包括 Provider 配置、模型注册、客户端路由、运行时切换,以及 Session 中的模型状态持久化。

1. 什么是 Model 管理

Model 管理,简单来说,就是让 Agent 能够统一配置、查询、选择和切换不同的模型,并处理不同模型供应商之间的差异。

首先,我们需要区分两个概念:Provider 和 Model。

  • Provider:模型供应商,例如 DeepSeek、智谱。

  • Model:供应商提供的具体模型,例如 DeepSeek 的 deepseek-chat、deepseek-flash 和 deepseek-v4-pro。

一个 Provider 可以提供多个 Model,二者通常是一对多的关系。![[Pasted image 20261027084122.png]]

通常我们在开通一个MaaS服务的时候,都能从供应商那里获取的API Key来作为访问凭据。以deepseek为例,我们可以通过https://api.deepseek.com/v1/models 获取到其支持的所有模型,以及模型在推理时,支持的思考等级(Thinking Level)。在这里插入图片描述

如果是智普的话,我们可以通过https://open.bigmodel.cn/api/v1/models获取其支持的模型信息。在这里插入图片描述

对比不同供应商的接口可以发现,它们在模型命名、元数据结构和能力描述等方面可能存在差异。尤其需要注意的是,模型列表接口并不一定会返回模型支持的全部能力,也不一定会提供推理等级信息。如果需要了解模型是否支持推理、支持哪些推理档位,以及具体的参数格式,还需要结合供应商的 API 文档进行确认。

因此,Agent 在接入不同供应商时,不能简单地将各家的 API 响应原样暴露给上层,而应该建立一套统一的内部模型描述,并在必要时将其转换为供应商实际支持的参数。

Model 管理需要解决的核心问题包括:

  1. 统一配置:管理 Provider 的访问端点、鉴权信息,以及 Model 的元数据。

  2. 模型注册与校验:统一加载模型定义,检查配置之间的关联是否有效。

  3. 动态路由与切换:根据当前选中的 Model,找到对应的 Provider,并使用正确的客户端发送请求。

  4. 能力适配:处理不同模型在推理能力、参数格式和接口行为方面的差异。

  5. 状态持久化:保存当前使用的模型和推理档位,并在恢复 Session 时还原相关状态。

本章先完成这些能力的基础框架。更复杂的供应商协议差异,可以在后续章节中逐步完善。

2. 三个配置文件

章的设计参考了开源项目 Pi 的 Agent 实现。Pi 是一个设计相对克制、结构简洁的 Agent 项目,很适合作为 ZeroAgent 教程的参考对象。

参考其模型管理思路,我们在 ~/.zeroagent/ 下设计三个用户级配置文件,分别负责 Provider 鉴权、Model 定义和当前运行状态。

需要注意:这里采用的是适合 ZeroAgent 的配置划分,并不意味着文件名和字段结构与 Pi 完全一致。

文件

作用

auth.json

保存 Provider 的访问端点和鉴权信息

models-config.json

保存 Model 的元数据和个性化配置

settings.json

保存当前选中的 Model 和推理档位

前两个文件负责描述「如何访问模型」和「模型具备哪些配置」,第三个文件负责记录「当前使用哪个模型」。

2.1 auth.json:Provider 的鉴权与端点

auth.json 以 Provider ID 为键,保存对应的 API 端点和鉴权信息。

{
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"type": "api_key",
"key": "sk-..."
  },
"glm": {
"baseUrl": "https://open.bigmodel.cn/api/v1",
"type": "api_key",
"key": "..."
  }
}

这里的 deepseek 和 glm 是 Provider ID,后续 Model 定义会通过 provider 字段引用它们。

需要注意,baseUrl 应当填写与实际 API 协议匹配的服务端点。不同供应商的端点可能不同,不能仅通过替换域名来保证兼容。示例中的 URL 应以对应供应商当前的 API 文档为准。

2.2 models-config.json:Model 的定义

models-config.json 以 Model ID 为键,保存模型的元数据和个性化配置。

这里的 Model ID 同时也是发送给模型 API 的 model 参数值。

{
"deepseek-flash": {
"provider": "deepseek",
"name": "DeepSeek Flash",
"reasoning": true,
"thinkingLevelMap": {
"minimal": null,
"low": "low",
"medium": null,
"high": "high",
"max": "max"
    },
"maxTokens": 384000
  }
}

各字段的含义如下:

  • provider:所属 Provider,必须能够在 auth.json 中找到对应配置。

  • name:模型的显示名称,用于 CLI 展示。

  • reasoning:表示该模型是否启用本项目定义的推理能力标记。

  • thinkingLevelMap:将 Agent 内部统一的推理档位映射为模型实际使用的值。

  • maxTokens:模型输出长度的配置上限,具体含义应与实际请求参数保持一致。

这里需要特别说明两个设计决策。

第一,baseUrl只在auth.json中维护。 这样可以避免同一个 Provider 的端点在多个 Model 定义中重复出现,减少配置不一致的问题。

第二,thinkingLevelMap中的null表示该档位没有直接映射值,而不是一个可以原样发送给 API 的参数值。 例如,当请求 high 档位但对应值为 null 时,Agent 可以按照预先定义的回退规则选择其他可用档位。具体规则需要在实现和测试中保持一致。

2.3 settings.json:当前运行状态

settings.json 保存当前选中的 Model 和推理档位。

{
"currentModel": "deepseek-flash",
"currentThinkingLevel": "high"
}

与前两个文件不同,settings.json 不是模型定义,而是当前状态的持久化记录。

例如,用户通过 /model 切换模型,或者通过 /thinking 修改推理档位后,Agent 可以将新的选择写入该文件。下一次启动时,再读取这些设置作为默认运行状态。

这里需要区分两个概念:

  • 用户级默认状态:由 settings.json 保存,用于初始化新的运行环境或 Session。

  • Session 级状态:由 Session 持久化机制保存,用于恢复已有会话。

当两者发生冲突时,应该明确优先级。对于恢复已有 Session 的场景,通常应优先恢复该 Session 记录的模型状态,而不是无条件使用最新的全局设置。

三个文件各司其职:auth.json 管访问端点和凭据,models-config.json 管模型定义,settings.json 管默认运行状态。它们共同构成 Model 管理的基础。

本章暂不展开更完整的供应商兼容层,例如不同 API 的参数名称、请求结构和响应格式差异。这些问题需要在统一模型配置的基础上进一步处理。

3. 实现 Model 管理

3.1 类型定义

首先,新建 src/model/types.ts,定义统一的模型类型。

exportconst EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high', 'max'] asconst;
exporttype EffortLevel = (typeof EFFORT_LEVELS)[number];
exporttype ProviderAuth = {
    baseUrl: string;
type: 'api_key';
    key: string;
};
exporttype ThinkingLevelMap = Partial<Record<EffortLevel, string | null>>;
exporttype ModelDefinition = {
    id: string;              // 也是发给 API 的 model 值
    provider: string;        // 精确匹配 auth.json 的键
    name?: string;           // /models 的显示名
    reasoning?: boolean;     // 默认 false
    thinkingLevelMap?: ThinkingLevelMap;
    maxTokens?: number;      // → max_output_tokens
};
exporttype ProviderCredentials = {
    baseUrl: string;
    key: string;
};

这里使用 as const 将 EFFORT_LEVELS 定义为只读元组,再通过索引访问类型生成 EffortLevel。这样,推理档位的类型可以直接从常量中推导出来,避免在多个地方重复定义。

ThinkingLevelMap 使用 Partial<Record<EffortLevel, string | null>>,主要有两个原因:

  1. Record 表示每个标准档位都可以映射到一个字符串或 null。

  2. Partial 表示模型不必显式定义全部五个档位,因为不同模型支持的档位可能不同。

这里的 Partial 只是放宽了 TypeScript 类型约束,并不意味着运行时配置可以不经过校验。读取 JSON 后,仍然需要检查字段类型、档位名称和映射值是否合法。

3.2 客户端改造:按 model 路由

原来的 ResponsesClient 在构造阶段就创建了一个 OpenAI 客户端。这种方式适合只使用一个固定端点的场景,但无法满足多 Provider 的需求。

现在,我们改为根据请求中的 model 动态解析对应的 Provider,并按端点和凭据缓存客户端实例。

核心逻辑如下:

    #clientFor(model: string): OpenAI {
const credentials = this.#resolveProvider(model);
if (credentials === undefined) {
thrownewError(`No provider credentials configured for model "${model}" in ~/.zeroagent.`);
        }
const cacheKey = `${credentials.baseUrl}\u0000${credentials.key}`;
let client = this.#providerClients.get(cacheKey);
if (client === undefined) {
            client = new OpenAI({
                apiKey: credentials.key,
                baseURL: credentials.baseUrl,
                fetch: this.#fetch,
            });
this.#providerClients.set(cacheKey, client);
        }
return client;
    }

这里的关键变化是:客户端不再依赖构造阶段固定的 Provider,而是在请求时根据 Model 进行路由。

整个过程可以概括为:

  1. 从请求中获取 Model ID。

  2. 查询模型注册表,找到对应的 Model 定义。

  3. 根据 Model 定义中的 provider 字段,查询 auth.json 中的凭据。

  4. 根据端点和凭据获取缓存客户端;如果不存在,则创建新的客户端。

  5. 使用对应客户端发送请求。

3.3 Agent 改造:动态切换

完成客户端路由后,Agent 还需要支持修改当前模型。

我们为 Agent 新增 modelRegistry 选项、可变的 #model 字段,以及 setModel 方法。

核心代码如下:

get model(): string {
returnthis.#model;
}
setModel(model: string): void {
this.#model = model;
}

这里需要注意:setModel 只负责修改 Agent 当前持有的模型 ID,本身并不完成配置校验,也不负责 Session 持久化。因此,模型切换入口必须先验证目标模型是否存在,再执行切换和状态更新。

例如,在 CLI 层可以封装统一的切换逻辑:

exportfunctionswitchModel(agent: Agent, registry: ModelRegistry, manager: SessionManager | undefined, id: string): boolean{
if (registry.get(id) === undefined) returnfalse;
    agent.setModel(id);
const sessionId = agent.sessionId;
if (manager !== undefined && sessionId !== undefined) {
        manager.setSessionModel(sessionId, id);
    }
returntrue;
}

当用户输入 /model 命令时,CLI 调用 switchModel。如果目标模型不存在,则拒绝切换;如果模型存在,则更新 Agent 当前使用的模型,并在存在有效 Session 的情况下将其写回。

3.4 session 闭环补全

前面已经实现了运行时切换,但如果只修改 Agent 内存中的模型字段,当前 Session 的记录就不会自动更新。

这会产生一个问题:用户切换模型后退出,再通过 /resume 恢复会话,系统可能仍然使用旧模型。

因此,需要为 SessionStore 新增更新方法。

updateSessionModel(id: string, model: string): void {
const now = newDate().toISOString();
this.#db.prepare('UPDATE sessions SET model = ?, updated_at = ? WHERE id = ?').run(model, now, id);
}

随后,在 SessionManager 中封装 setSessionModel,由它调用 SessionStore 的更新方法。

这样,模型切换就形成了一个完整的状态链路:

  • /model 更新 Agent 当前模型。

  • SessionManager 将新模型写入 Session。

  • /resume 读取 Session 中保存的模型并恢复。 这一步补齐了之前「状态已经保存,却没有在恢复时真正使用」的问题。

3.5 CLI 命令

接下来,在 cli.ts 中加入模型管理相关命令,并将 /reload 和 /resume 接入新的配置体系。

  • /models — 列出所有 model,* 标记 active,显示 provider、reasoning 与可用档位。

  • /model <id> — 切换 active model 并写回当前 session。

  • /thinking <level> — 切换 thinking level 并写回 settings.json。

  • /reload — 同时重载 auth.json 与 models-config.json。

  • /resume — 恢复 session 时同时恢复其记录的 model。

4. 实际运行

4.1 配置

在 ~/.zeroagent/ 下准备好三个配置文件:

  • auth.json

  • models-config.json

  • settings.json

然后启动本章对应的项目:

pnpm --filter @zero-agent/chapter10 start

启动时,系统会加载模型注册表,并根据配置确定当前模型和推理档位。示例日志如下:

[workdir] /Users/frank/Desktop/code/ZeroAgent/chapter10
[models] Loaded 2 model(s): deepseek-flash, glm-5.3
[model] Using model: deepseek-v4-pro , thinking level: high
[skills] Loaded 1 skill(s): repo-tech-writer
[subagents] Loaded reviewer
[session] New session: a1b2c3d4-...
Interactive mode — type your prompt and press Enter. Ctrl+C to exit.

这里假设 models-config.json 中配置了两个模型,且 settings.json 中的 currentModel 为 deepseek-flash。实际日志应以当前配置和程序的真实输出为准。

4.2 列出与切换

启动后,输入 /models 可以查看当前可用的模型。

❯ /models
Models:
  * deepseek-flash  provider: deepseek  reasoning: on  levels: low,high,max
    glm-5.3         provider: glm       reasoning: off  levels: -
❯ /model glm-5.3
Active model: glm-5.3

其中,* 表示当前正在使用的模型;provider 表示模型所属的供应商;reasoning 表示配置中声明的推理能力标记;levels 列出当前模型可直接映射的推理档位。

切换到 glm-5.3 后,再次执行 /models,* 就会移动到对应的模型。

5. SDD驱动开发

本章的整个实现过程,我没有"打开编辑器直接开写",而是走了一条 Spec-Driven Development(SDD,规格驱动开发) 的流程,工具是 OpenSpec。

5.1 什么是 SDD

SDD 的核心思想可以概括为一句话:

先明确要做什么,再设计如何实现,最后验证实现是否符合规格,并持续维护规格与代码之间的一致性。

直接编码有一个常见风险:需求尚未澄清,就开始实现;当开发到一半才发现理解有误时,相关代码和测试往往都需要返工。

SDD 将需求理解和设计决策前置。开发者先产出可以评审的规格文档,明确系统应该具备哪些行为、有哪些边界条件,以及如何判断功能是否完成,再根据规格逐步实现。

在 AI 辅助开发中,这种方式尤其有价值。规格文档为人和 AI 提供共同的上下文,任务清单则将整体目标拆解为可执行、可检查的步骤。

需要注意的是,规格本身并不能自动保证实现正确。只有将规格落实为测试、校验和评审,才能有效降低遗漏需求或偏离设计的风险。

5.2 OpenSpec 的工作流

本章采用的 OpenSpec 工作流主要包含四个阶段。

  • explore(探索):澄清需求、讨论方案并分析问题。该阶段用于收敛方向,不要求立即产出代码或正式变更制品。

  • propose(提案):形成正式的变更提案,包括 proposal.md、design.md、specs/ 和 tasks.md。其中,提案说明为什么要做,设计文档说明如何实现及方案取舍,规格定义系统必须满足的行为,任务清单则按照依赖关系组织实现步骤。

  • apply(实现):按照 tasks.md 中的任务逐步实现功能,并跟踪任务完成情况。

  • archive(归档):将变更中新增或修改的规格增量同步到主规格目录 openspec/specs/,再归档已完成的变更记录。

5.3 本章的 OpenSpec 实践

Model 管理这个 change,最终产出了 6 个 capability 的规格——3 个新增、3 个修改:

Capability

类型

内容

model-registry

新增

auth/models 的加载、校验、查询

model-aware-agent

新增

provider 路由、reasoning映射 、可切换 model

model-cli

新增

/models

、/model、/reload

session-store

修改

新增 updateSessionModel

session-manager

修改

新增 setSessionModel

session-cli

修改

/resume

 恢复 model

一条规格的形态长这样(节选自 model-aware-agent):

### Requirement: reasoning effort translated through level map
When the active model has a `thinkingLevelMap`, the agent SHALL translate the
requested effort level (`high` by default) using the map...
#### Scenario: Requested level is null, fall back down
- **WHEN** the map has `low: "low"`, `max: "max"`, and `high: null`, and effort `high` is requested
- **THEN** the request SHALL send `reasoning.effort = "low"` (highest available not above `high`)

5.4 SDD 带来的三个好处

  1. 先想清楚再动手:design.md 强制我写下每个关键决策的备选方案与取舍——比如"客户端路由"是放在 client 层还是 CLI 层、"映射"是放在 agent 层还是 CLI 层。这些在动手前就辩清楚了。

  2. 规格即测试:WHEN/THEN 场景直接映射到测试用例,写完代码后"规格是否满足"是可验证的,不是感觉。

  3. AI 可执行:tasks.md 的 checkbox 格式可以被 apply 阶段解析、跟踪进度,AI 逐条实现、逐条勾选,不会漏也不会跑偏。

6. 总结

本章通过统一管理 Provider 鉴权、Model 配置、推理档位映射和客户端路由,实现了模型的动态切换、配置校验与 Session 状态持久化,并借助 SDD 流程提升了开发过程的可控性与可验证性。

在 SDD 实践中,发挥最大作用的是 explore 阶段。最初的「Model 管理」只是一个比较笼统的需求,涉及配置划分、Provider 路由、推理档位映射、Session 恢复等多个需要提前决策的问题。通过与 AI 反复讨论和迭代,才逐步收敛为可以实现和验证的规格。

从这个角度看,explore 与 Plan-Execute 模式中的 plan 有相通之处:二者都强调在执行之前先明确目标和方案。不过,它们并不是完全相同的机制——SDD 更强调规格的形成、验证与长期维护,而 plan 更侧重于组织一次具体任务的执行步骤。

因此,下一篇我会尝试使用更轻量的 plan 推进实现,与本章的 SDD 工作流进行对比,看看在不同复杂度的任务中,哪种方式更合适。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter10 中获取本文的完整源码。

若觉得本文对你有帮助,请支持我的新书:《Harness 工程实战》。

参考: 

PI Agent : https://pi.dev/ 

OpenSpec:https://github.com/Fission-AI/OpenSpec

跳转微信打开

从零构建Agent(九):SubAgent

2026年10月26日 11:00

原创 从码农到工匠 2026-10-26 11:00 上海

本文将拆解如何为 Agent 实现任务委派能力——SubAgent

本文是 从零构建Agent 系列第 9 篇。上一篇《从零构建Agent(八):Commands》中,我们用斜杠命令把高频 Prompt 固化为可复用的模板。本文将拆解如何为 Agent 实现任务委派能力——SubAgent。

试想一下:你让 Agent 审查一段代码,它需要先读懂文件、分析逻辑、查找潜在问题,再给出改进建议——这些步骤全挤在一个 Agent Loop 里跑,上下文越堆越长,模型注意力被稀释,最后给出的审查意见泛泛而谈。

又或者,你让 A 模型写完代码后,想再用 B 模型做一轮交叉 Review。交叉 Review 需要不同的 System Prompt(“你是资深代码审查专家,请独立判断,不要预设这段代码是对的”)、不同的工具集(只需要 read_file 和 file_search,不需要 write_file),需要用不同模型的不同“视角”互相校验,比同一个模型自查更容易发现盲区。

这些场景的共同诉求是:把一项子任务交给一个"专家"Agent 独立完成,再把结果带回来。 这就是 SubAgent。

1. 什么是 SubAgent

SubAgent 的核心思想是任务委派。就像一个团队负责人(父 Agent)把一项具体工作交给一位专业工程师(子 Agent),工程师独立完成后把结果汇报回来,负责人再综合结果做决策。

Claude Code 的 SubAgents 是这一模式的典型实现。每个 SubAgent 是一个 Markdown 定义文件,包含专属的 System Prompt、可选的模型覆盖和工具白名单。一个典型的Claude Code SubAgent配置示例如下:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grepmodel: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

1.1 SubAgent的触发方式

SubAgent 的触发方式可以整理为“隐式”与“显式”两大类,显式再细分为 prompt 点名和 @agent-name 两种。

1、隐式触发在处理较长或复杂的任务时,Agent 会根据当前上下文自动判断是否需要启用 Subagent。用户无需在提示词中指定代理名称。

例如: "请全面检查项目中的所有 API 路由,找到所有缺少的类型定义,并批量为它们补全类型声明和单元测试。"

2、显式触发显式触发即由用户显式介入,明确要求或指定 Subagent 来执行特定任务,主要分为以下两种形式:

  1. 通过 Prompt 明确指引在 Prompt 中主动建议主 Agent 将某部分独立任务交给“子任务/子 Agent”去完成,以维持主会话上下文的简洁。

例如:"请作为调度员重构认证模块,你可以启动一个 Subagent 专门扫描 src/auth/ 的依赖关系,主流程中只保留架构决策。

  1. 通过 @agent-name 语法指定在输入框中用 @ 选择或手写 @agent-<name>,确保该 SubAgent 为当前任务运行。如下图所示,在OpenCode Agent中可以通过@符号直接唤起特定的 Agent。在这里插入图片描述

1.2 SubAgent使用过程解析

我们还是以OpenCode Agent为例,当我们需要进行Code Review的时候,我们可以在OpenCode的控制台中输入:

@code-reviewer 帮我审查一下 chapter1 目录下的 Python 脚本。

主 Agent 接收到指令后,首先解析 @code-reviewer 这一显式声明,识别出目标 SubAgent 的角色与能力边界。随后,主 Agent 将当前任务上下文(包括目录路径、文件类型、审查目标)进行封装,并路由至对应的 code-reviewer SubAgent。

该 SubAgent 在隔离的上下文中执行专项任务——扫描指定目录、加载相关编码规范、逐文件分析代码质量,并生成结构化审查报告。若过程中需要额外信息(如依赖关系或历史变更记录),SubAgent 可向主 Agent 发起请求,由主 Agent 协调其他工具或 SubAgent 予以补充。

最终,审查结果返回至主 Agent,由其整合并呈现给用户。整个过程中,主 Agent 负责全局调度与异常处理,SubAgent 专注于领域任务,形成“你只管说目标,我来调度专家”的协作闭环。完整流程如下图所示:![[Pasted image 20261026094114.png]]

2. SubAgent和其他技术的区别

维度

Skills

Commands

SubAgent

核心作用

注入领域知识

复用 Prompt 模板

委派独立子任务

执行方式

在当前 Loop 中加载指令

在当前 Loop 中展开模板

启动独立的 Agent Loop

上下文

共享当前上下文

共享当前上下文

隔离的独立上下文

工具范围

不改变工具集

不改变工具集

可限定工具白名单

模型

使用当前模型

使用当前模型

可覆盖为不同模型

关键区别在于上下文隔离。Skills 和 Commands 都在当前 Agent Loop 内工作,共享对话历史。SubAgent 则启动一个全新的 Agent Loop——它看不到父 Agent 的对话历史,只接收一条任务描述,独立执行完毕后返回最终文本。这带来了三个好处:

  • 上下文洁净:子任务的中间步骤(读文件、搜索、试错)不会污染父 Agent 的上下文窗口。

  • 权限收敛:通过工具白名单,可以给子 Agent 最小权限——审查代码的子 Agent 不需要 write_file。

  • 成本可控:子 Agent 可以用更便宜的模型执行简单任务,贵模型只用在需要综合推理的父 Agent 上。

补充一点:SubAgent 与 MCP 工具并不冲突——run_subagent 本身就是一个工具,因此模型可以像调用其他工具一样调用它;而 MCP 工具是否对子 Agent 可见,同样受工具白名单约束。

3. 实现 SubAgent 功能

3.1 类型定义

实际上SubAgent也是Agent,其结构和功能都和已有的Agent有同构性,那为什么我们还要重新定义个新类型呢?主要是两点:

  1. SubAgent的定义来自于Markdown文档,我们需要一个和其完全匹配的结构

  2. SubAgent在有些逻辑上和Agent不同,区分开会让代码更加清晰

因此,我们在 src/subagent/types.ts 中定义了 SubAgent 的新数据结构:

exportinterface SubAgentDefinition {
/** Agent identifier, kebab-case. */
    name: string;
/** Human-readable description. */
    description: string;
/** Must be "subagent". */
    mode: 'subagent';
/** Optional model override, e.g. "deepseek/deepseek-chat". */
    model?: string;
/** Tool-name whitelist (tool name → enabled). */
    tools?: Record<string, boolean>;
/** System prompt body (Markdown content after front matter). */
    systemPrompt: string;
}
exporttype LoadedAgent = {
    definition: AgentDefinition;
    source: string;
};

字段解读:

  • name:kebab-case 唯一标识,也是 @name 调用时使用的名字。

  • description:描述,用于在加载时展示和未来可能的模型自动选择。

  • mode:固定为 'subagent',与未来可能的其他 Agent 类型区分。

  • model:可选。不指定则继承父 Agent 的模型。

  • tools:可选。工具白名单,只有值为 true 的工具才会注入子 Agent。不指定则继承全部工具。

  • systemPrompt:Markdown 正文,作为子 Agent 的 System Prompt 注入 instructions 字段。

3.2 Frontmatter 解析与两级加载

SubAgent 的定义文件与 Skill、Command 一样,使用 YAML frontmatter + Markdown 正文的格式:

---
name: reviewer
description: 代码审查专家
mode: subagent
tools:
  read_file: true  file_search: true
---
你是一名资深代码审查工程师。你擅长分析代码质量,提出最关键的两个问题。

加载路径与 Skills、Commands 完全同构——全局先加载,项目后覆盖:

~/.zeroagent/agents/*.md           # 全局 SubAgent 定义
{workdir}/.zeroagent/agents/*.md   # 项目级定义(覆盖同名全局定义)

3.3 Agent 类改造:createSubAgent

SubAgent 的核心是 Agent 类新增的 createSubAgent 方法。它创建一个子 Agent 实例,继承父 Agent 的客户端、工作目录和 Skills,但使用自己的 System Prompt、模型和工具白名单:

exportclass Agent {
    readonly #agentType: 'agent' | 'subagent';
    readonly #agentDefinition: AgentDefinition | undefined;
// ...
    createSubAgent(definition: AgentDefinition): Agent {
const child = new Agent(this.#client, {
            model: definition.model ?? this.#model,
            maxSteps: this.#maxSteps,
            workdir: this.#workdir,
        }, 'subagent', definition);
        child.#skills.copyFrom(this.#skills);
        child.#tools.copyFrom(this.#tools, definition);
return child;
    }
}

这里有几个设计决策值得展开:

模型继承与覆盖:definition.model ?? this.#model——子 Agent 定义中指定了 model 就用指定的,否则继承父 Agent 的。这让你可以为简单任务指定一个更便宜的模型。

Skills 继承:child.#skills.copyFrom(this.#skills) 把父 Agent 已加载的 Skills 复制给子 Agent。子 Agent 同样可以通过 load_skill 工具按需加载技能指令。

工具白名单:child.#tools.copyFrom(this.#tools, definition) 是关键——它不是全量复制,而是只复制 definition.tools 中值为 true 的工具:

copyFrom(source: ToolRegistry, agentDefinition: AgentDefinition): this {
for (const [name, handler] of source.#handlers) {
if (agentDefinition.tools?.[name] === true) this.register(name, handler);
    }
returnthis;
}

如果 definition.tools 未定义(undefined),则不会复制任何工具——这意味着未指定 tools 的 SubAgent 定义实际上没有工具可用。这是一个"最小权限"设计:子 Agent 默认无工具,必须显式声明需要的工具。

3.4 System Prompt 注入

在 Agent Loop 启动时,构建 instructions 字段的逻辑也做了调整:

const instructions = [this.#agentDefinition?.systemPrompt, this.#skills.buildPromptInstructions()]
    .filter((part) => part !== undefined && part.length > 0)
    .join('\n\n');
const requestBuilder = new PromptRequestBuilder(model)
    .addDeveloperMsg(`Working directory: ${this.#workdir}. Resolve relative paths from this directory.`)
    .setInstructions(instructions)
// ...

对于父 Agent(#agentDefinition 为 undefined),instructions 只有 Skills 目录。对于子 Agent,instructions 是 SubAgent System Prompt + Skills 目录 的组合。Skills 目录被保留是因为子 Agent 也继承了 Skills,需要知道有哪些技能可按需加载。

3.5 触发SubAgent执行

在ZeroAgent的实现中,我们对齐了OpenCode的SubAgent 触发方式,即可以用@符号显式调用SubAgent。关于@调用的实现,我们是这样实现的:

在 CLI 中输入 @ 开头的消息时,isSubAgentInput 会识别它:

exportfunctionisSubAgentInput(input: string): boolean{
return input.startsWith('@');
}

parseSubAgent 解析 @name task 格式,从 registry 中查找对应的 AgentDefinition:

exportfunctionparseSubAgent(
    input: string,
    registry: AgentRegistry,
): 
{ task: string; definition: AgentDefinition } {
const match = /^@(\S+)(?:\s+([\s\S]*))?$/.exec(input);
if (match === null) thrownewError('Expected @<agent-name> <task>.');
const name = match[1]!;
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
thrownewError(`Invalid agent name "${name}".`);
    }
const definition = registry.get(name);
if (definition === undefined) thrownewError(`Unknown agent: ${name}`);
const task = match[2]?.trim();
if (task === undefined || task.length === 0) thrownewError(`Usage: @${name} <task>`);
return { task, definition };
}

在 cli.ts 的 runPrompt 中,这个路径被接通:

asyncfunctionrunPrompt(agent: Agent, registry: AgentRegistry, prompt: string): Promise<void> {
if (!isSubAgentInput(prompt)) {
await runOnce(agent, prompt);
return;
    }
let invocation;
try {
        invocation = parseSubAgent(prompt, registry);
    } catch (error) {
console.error(`[subagent] ${error instanceofError ? error.message : String(error)}`);
return;
    }
console.log('\n[step 1]');
let result: string;
try {
        result = await runSubAgent(agent, invocation.task, invocation.definition);
    } catch {
return;
    }
const parentPrompt = buildSubagentParentPrompt(invocation.definition.name, invocation.task, result);
await runOnce(agent, parentPrompt, true);
}

注意最后一行——子 Agent 返回结果后,并不是直接输出给用户,而是用 buildSubagentParentPrompt 包装成一段新的 Prompt 发给父 Agent:

exportfunctionbuildSubagentParentPrompt(name: string, task: string, result: string): string{
return [
`The user invoked @${name} with this task:`,
        task,
'',
'Use the SubAgent result below to answer the user。',
'<subagent_result>',
        result,
'</subagent_result>',
    ].join('\n');
}

这个设计很重要:父 Agent 拿到子 Agent 的结果后,有机会做综合加工——比如用更强大的模型提炼要点、补充上下文、或者结合其他信息给出最终回答。子 Agent 负责"干活",父 Agent 负责"汇报"。

3.6 事件系统扩展

为了在终端中区分父 Agent 和子 Agent 的输出,新增了两个事件类型:

exportconst AgentEventType = {
// ... 原有事件 ...
    SubagentStart: 'subagent_start',
    SubagentEnd: 'subagent_end',
} asconst;

在 agent-event.ts 的 render 函数中:

case AgentEventType.SubagentStart:
console.log(`[${event.name} subagent]`);
break;
case AgentEventType.SubagentEnd:
console.log(`[${event.name} subagent end]`);
break;

这样在终端中,用户可以清晰地看到子 Agent 的起止边界:

[step 1]
[reviewer subagent]
[step 1]
[tool_call] read_file({"path":"src/agent-loop.ts"})
[step 2]
代码质量良好,建议关注以下两点:
1. shouldEndLooping 方法可以提前返回...
[reviewer subagent end]
[step 2]
审查完成。reviewer 子 Agent 发现了两个关键问题...
[run_end after 2 step(s)]

4. 实际运行

4.1 前置准备

确保已安装依赖,并在 chapter9 目录下启动:

pnpm install
pnpm --filter @zero-agent/chapter9 start

启动后,CLI 会扫描全局与项目级 agents 目录,并打印已加载的 SubAgent 列表:

$ pnpm --filter @zero-agent/chapter9 start
[workdir] /Users/frank/Desktop/code/ZeroAgent/chapter9
[skills] Loaded 1 skill(s): repo-tech-writer
[subagents] Loaded reviewer
[commands] Loaded 2 command(s): review, commit
[session] New session: a1b2c3d4-...
Interactive mode — type your prompt and press Enter. Ctrl+C to exit.

4.2 创建自定义 SubAgent

项目自带了一个示例定义 .zeroagent/agents/reviewer.md:

---
name: reviewer
description: 代码审查专家
mode: subagent
tools:
  read_file: true  file_search: true
---
你是一名资深代码审查工程师。你擅长分析代码质量,提出最关键的两个问题。

这个 SubAgent 只有 read_file 和 file_search 两个工具——它只能读和搜索,不能写文件、不能执行命令、不能委派子 Agent。最小权限。

你也可以在全局目录创建 SubAgent 定义供所有项目使用:

# 全局:所有项目可用
~/.zeroagent/agents/security-auditor.md
# 项目级:仅当前项目可用(同名覆盖全局)
{workdir}/.zeroagent/agents/security-auditor.md

4.3 使用 @ 调用

在交互模式中输入 @reviewer 审查 src/agent-loop.ts:

❯ @reviewer 审查 src/agent-loop.ts 的错误处理逻辑
[step 1]
[reviewer subagent]
[step 1]
[tool_call] read_file({"path":"src/agent-loop.ts"})
[step 2]
审查完成。代码中错误处理有以下两个关键问题:
1. stream() 方法的 catch 块在 signal.aborted 时直接 return,
   但未向上层调用者传递任何信息,调用方无法区分"正常结束"和"被中断"。
2. shouldEndLooping 在 step >= maxSteps 时返回 true,
   但后续会触发 "Reached maxSteps" 错误事件,
   调用者需要同时处理 RunEnd 和 Error 两种结束情况,语义不清晰。
[reviewer subagent end]
[step 2]
根据 reviewer 子 Agent 的审查结果,src/agent-loop.ts 的错误处理有两个值得关注的点:
第一,当用户通过 Ctrl+C 中断(signal aborted)时,stream() 会静默返回,
调用方无法感知中断发生了……
[run_end after 2 step(s)]

注意执行流程:

  1. @reviewer 触发 SubAgent,输出 [reviewer subagent] 标记。

  2. 子 Agent 独立运行两个 step:读文件 → 分析并输出结果。

  3. [reviewer subagent end] 标记子 Agent 结束。

  4. 父 Agent 拿到子 Agent 的结果,用自己的上下文做综合加工,输出最终回答。

4.4 热重载

与 Skills 和 Commands 一样,/reload 也支持重新加载 SubAgent 定义:

❯ /reload
[reload] 2 command(s), 1 skill(s), 1 subagent(s)

新增或修改 .zeroagent/agents/ 下的定义文件后,不需要重启 Agent。

5. 总结

本章我们为 Agent 实现了任务委派能力——SubAgent。核心可以概括为三点:

  1. 独立 Loop:SubAgent 不是“在当前对话里加指令”,而是启动一个全新的 Agent Loop,只接收一条任务描述,执行完返回最终文本。

  2. 上下文隔离:子任务的中间步骤不污染父 Agent 的上下文窗口,带来上下文洁净、权限收敛、成本可控三个好处。

  3. 可覆盖:通过 SubAgentDefinition 的 model 与 tools 字段,子 Agent 可使用不同模型、限定工具白名单,实现最小权限与成本优化。

SubAgent 的加入,标志着我们的 ZeroAgent 框架正式从单体 Agent 跨越到了多 Agent 协作系统(Multi-Agent System) 的门槛。下一篇文章中,我们将实现Model 管理,主要包括模型认证配置与动态模型切换。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter9 中获取本文的完整源码。

若觉得本文对你有帮助,请支持我的新书:《Harness 工程实战》。

参考: Claude Code SubAgents:https://docs.claude.com/en/docs/claude-code/sub-agents

跳转微信打开

从零构建Agent(八):Commands

2026年10月20日 10:37

原创 从码农到工匠 2026-10-20 10:37 上海

本文是 ZeroAgent 系列第 8 篇。将拆解如何为 Agent 实现一套可复用的斜杠命令系统

本文是 ZeroAgent 系列第 8 篇。上一篇《Session 管理》中,我们用 /resume 恢复会话,其实已经用到了 Command。本文将拆解如何为 Agent 实现一套可复用的斜杠命令系统。

斜杠命令是来自于Claude Code的经典设计,Command 除了可以控制Agent的行为外,还可以让用户自定义 Prompt 模板。

试想一下,每次想让 Agent "审查代码",你都得手打一遍完整指令:"请审查 xxx 文件,重点关注安全性、性能和代码风格,给出改进建议…"。每次想让 Agent "提交代码",又得输入:"请根据当前改动生成一条符合 Conventional Commits 规范的提交信息…"。

这些高频复用的 Prompt,能不能像 Shell 别名一样保存起来,用 /review 一个命令就自动展开呢?

1. 什么是 Slash Commands

经常使用Agent的同学,对于这个功能应该不陌生。下图是Hermes Agent的斜杠命令列表,我们可以用这些命令对Agent进行Session管理,上下文压缩等操作。在这里插入图片描述以下是PI Agent的斜杠命令列表,除了系统自定义的命令之外,opsx 开头的命令,是我们使用OpenSpec init 创建的SDD命令,属于是用户自定义命令,在PI Agent中也叫prompt template在这里插入图片描述Slash Commands 作为用户自定义的 Prompt 模板使用时。每个命令是一个 Markdown 文件,包含 YAML frontmatter(元数据)和正文(Prompt 模板)。在交互模式中输入 /命令名 参数1 参数2,CLI 会将参数展开到模板中,生成完整的 Prompt 发送给 Agent。

一个典型的命令文件:

---
name: reviewdescription: Review a file or diff
---
Review the following file and suggest improvements:
File: $1
Focus on: ${2:-correctness, style, and performance}

调用方式:

❯ /review src/cli.ts
# 展开后等价于直接发送:
# Review the following file and suggest improvements:
#
# File: src/cli.ts
#
# Focus on: correctness, style, and performance

与 Skills 的关键区别在于:Skills 是给模型看的指令(模型决定何时加载),Commands 是给用户用的快捷方式(用户决定何时触发)。Skills 影响模型何时、如何加载指令,Commands 影响用户如何发起任务。两者互补:你可以用一个 Command 快速发起任务,Agent 在执行过程中再按需加载 Skill。

维度

Skills

Commands

触发者

模型

用户

加载时机

模型按需加载

用户输入时展开

作用对象

模型推理过程

用户输入操作

复用方式

跨任务复用领域知识

跨会话复用 Prompt

需要注意的是,因为Skill本质上也是prompt,有些Agent,比如 Pi Agent,也支持通过 Command 触发 Skill。在这里插入图片描述

2.  实现Command功能

2.1 类型定义

在 src/command/types.ts 中定义命令的数据结构:

exporttype CommandDefinition = {
/** 命令名,调用时写作 /name */
    name: string;
/** 描述,列出可用命令时展示 */
    description: string;
/** Prompt 模板正文,支持 $1、${2:-default} 占位符 */
    template: string;
};

三个字段:name 是唯一标识,description 用于 /help 或错误提示时展示,template 是带占位符的 Prompt 模板。

占位符约定:$1、$2 表示第 1、2 个位置参数;${2:-default} 表示第 2 个参数缺省时使用 default。模板整体保存为字符串,展开时再做替换——这样命令文件可以原样落盘,便于阅读和版本管理。

2.2 Frontmatter 解析

鉴于命令文件使用与 Skill 文件相同的 frontmatter 格式,我们有必要把解析逻辑抽出来,以便两边可以复用(参考PI Agent也是这么做的),这类微重构可以交给 AI 完成,AI重构后在 src/util/frontmatter.ts 中的新实现如下:

exporttype Frontmatter = {
    name?: string;
    description?: string;
};/**
 * Split Markdown content into flat name/description frontmatter and body.
 */
exportfunctionsplitFrontmatter(content: string, source: string): { frontmatter: Frontmatter; body: string } {
const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
if (match === null) {
thrownewError(`File "${source}" is missing YAML frontmatter. Expected "---" delimited block at the start of the file.`);
    }
// ...省略
}

解析逻辑很直白:正则匹配 --- 分隔的 frontmatter 块,提取 name 和 description,frontmatter 之后的正文就是模板。缺失必填字段或模板为空都会抛出错误——错误要尽早暴露,不能等到用户调用时才发现命令文件有问题。

2.3  两级加载路径

与 Skills的加载机制一样,Command 支持全局和项目级两个加载路径:

~/.zeroagent/commands/*.md           # 全局命令,所有项目可用
{workdir}/.zeroagent/commands/*.md   # 项目命令,仅当前项目可用

项目级命令与全局命令同名时,项目级覆盖全局(后加载覆盖先加载)。这个设计让你可以为不同项目定制同名命令的行为——比如全局有个通用的 /review,某个项目可以定义一个更具体的 /review 覆盖它。

const dirs = [userCommandsDir(), projectCommandsDir(workdir)];
for (const dir of dirs) {
const commands = await loadCommandsFromDirectory(dir);
for (const entry of commands) {
        registry.register(entry.command);
    }
}

加载顺序:全局先、项目后。CommandRegistry 内部是 Map<string, CommandDefinition>,register() 对同名 key 直接覆盖,自然实现了"后写胜出"的优先级。

2.4 热重载

这个功能也是借鉴 PI Agent 的:交互模式中输入 /reload 可以重新加载命令和技能:

asyncfunctionhandleReloadCommand(agent: Agent, registry: CommandRegistry, workdir: string): Promise<void> {
const loadedCommands = await loadCommands(workdir, registry);
const loadedSkills = await loadSkills(workdir, agent.skills);
console.log(`[reload] ${loadedCommands.length} command(s), ${loadedSkills.length} skill(s)\n`);
}

loadCommands 会先 clear() 清空 registry,再从磁盘重新加载。这意味着你在运行中新增、修改、删除命令文件后,不需要重启 Agent——一个 /reload 即可生效。

3. 实际运行

3.1 前置准备

确保已安装依赖,并在 chapter8 目录下启动:

pnpm install
pnpm --filter @zero-agent/chapter8 start

启动后,CLI 会扫描全局与项目级命令目录,并打印已加载的命令列表。

3.2 创建命令

在项目目录下创建 .zeroagent/commands/review.md:

---
name: reviewdescription: Review a file and suggest improvements
---
Review the following file and suggest improvements:
File: $1
Focus on: ${2:-correctness, style, and performance}
Provide specific, actionable suggestions with code examples.

再创建 .zeroagent/commands/commit.md:

---
name: commitdescription: Generate a conventional commit message
---
Based on the current git diff, generate a commit message following the
Conventional Commits specification (type: scope: description).
Stage: $1

3.3 启动并使用

$ pnpm --filter @zero-agent/chapter8 start
[commands] Loaded 2 command(s): review, commit
[session] New session: a1b2c3d4-...
Interactive mode — type your prompt and press Enter. Ctrl+C to exit.
❯ /review src/cli.ts
[step 1]
[tool_call] read_file({"path":"src/cli.ts"})
[step 2]
Here are my suggestions for src/cli.ts:
1. Extract the session command handlers into a separate module...
[run_end after 2 step(s)]
❯ /commit src/
[step 1]
[tool_call] run_terminal_command({"command":"git diff --cached -- src/"})
[step 2]
feat(chapter8): add slash command support for CLI
[run_end after 2 step(s)]

3.4 热重载

❯ /reload
[reload] 3 command(s), 1 skill(s)

新增一个命令文件后,不需要重启 Agent,直接 /reload 即可。

3.5 未知命令

❯ /refactor
[error] Unknown command: /refactor
Available commands: /sessions, /resume, /clear, /reload, /review, /commit

列出所有可用命令(内置命令 + 用户定义命令),帮你快速发现是拼写错了还是命令没加载。内置命令(如 /sessions、/resume、/clear、/reload)在启动时注册,用户命令随后合并,同名时以用户命令为准。

4. 总结

本文为 ZeroAgent 构建了 Slash Commands 能力:定义了 CommandDefinition 结构,抽取了可复用的 frontmatter 解析,实现了全局/项目两级加载与同名覆盖,并支持 /reload 热重载。至此,高频 Prompt 可以像 Shell 别名一样被复用。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter8 中获取本文的完整源码。

参考: 

Claude code Command:  https://code.claude.com/docs/en/commands PIPrompt Template:https://pi.dev/docs/latest/prompt-templates

跳转微信打开

从零构建Agent(七):Session管理

2026年10月16日 17:22

原创 从码农到工匠 2026-10-16 17:22 上海

大模型本质上是无状态的数学函数。它不包含任何持久化的记忆机制。每一次发送 Prompt,对模型来说都是一次完全独立的"单次计算"。模型既不知道"你是谁",也不记得"1分钟前我们聊了什么"。

因为模型的无状态特性,所以Agent 的 Session 管理变得至关重要,它必须承担起 "外部记忆硬盘" 的角色。每次请求模型时,Agent 需要主动携带历史消息,并将它们塞进新的 Prompt 上下文里。

即一个完整的Prompt公式应该是:

当前Prompt = System Prompt + (历史Messages列表) + 当前User Question

1. 持久化选型

对于Agent场景,开源数据库SQLite是最佳选择,也是当前主流Agent的共同选择。SQLite 是嵌入式数据库,不需要像 MySQL/PostgreSQL 那样单独启动一个守护进程(Daemon)或容器。Agent 进程启动时直接读写 .db 文件,进程结束时释放。省去了网络连接池、认证鉴权等繁琐步骤,部署极其简单。

其内存占用极低,Agent 通常运行在用户的个人电脑(PC)或小型网关设备上,内存资源有限。SQLite 核心库仅占用 1MB 左右 内存,而 MySQL/Redis 动辄占用几百 MB。

此外,SQLite 是少数原生内置强大全文搜索FTS5(Full Text Search 5)的嵌入式数据库。对于 Agent 而言,用户经常提问:"之前关于那个 API 密钥的对话在哪?"。SQLite + FTS5 可以直接在本地 sessions.db 中毫秒级检索历史会话内容,而如果换成 MySQL,你还需要额外引入 Elasticsearch 或 Meilisearch,极大地增加了架构复杂度。

在 Node.js 22.5+ 中,node:sqlite 作为内置模块直接可用,无需 npm install 任何第三方依赖。这意味着我们的 Agent 项目依然保持零运行时依赖的核心优势。

2. 数据模型设计

Session 管理的核心是两张表:sessions 和 messages。一对多的关系——一个 Session 包含多条 Message。

2.1 表结构设计

一次对话是由Agent Loop的多轮Message组成的,所以Session和Message是显而易见的1对多的关系,其实体联系图如下:

2.2 类型定义

在 src/session/types.ts 中,我们定义了三个核心类型:

/** sessions 表的行结构 */
exporttype SessionRow = {
    id: string;
    title: string;
    model: string;
    workspace: string;
    parentSessionId: string | null;
    createdAt: string;
    updatedAt: string;
};
/** messages 表的行结构 */
exporttype MessageRow = {
    id: string;
    sessionId: string;
    role: string;
    content: string;
    createdAt: string;
};
/** 带消息数的 Session 元信息(list/get 操作使用) */
exporttype SessionMeta = SessionRow & {
    messageCount: number;
};

SessionRow 的各字段含义:

字段

用途

id

UUID v4,主键

title

会话标题,由第一条用户消息自动生成(截取前 50 字符)

model

创建会话时使用的模型名称

workspace

工作目录路径,用于按项目隔离会话

parentSessionId

父会话 ID(自关联),为未来"会话分支"功能预留

createdAt

 / updatedAt

ISO 8601 时间戳

MessageRow 则非常精简——role + content 就够了。注意,我们只持久化 user 和 assistant 的文本消息,不存 function_call 和 function_call_output。原因是:跨轮对话恢复只需要对话上下文(谁说了什么),工具调用是单次 stream() 内的临时行为,由 PromptRequestBuilder 在运行时管理,不需要跨会话持久化。

3.  Session操作

3.1 Session Store

SessionStore(src/session/store.ts)是纯粹的数据访问层,负责 SQLite 连接管理、Schema 迁移和 CRUD 操作。这个比较简单,就是CRUD的SQL操作,比如获取workspace下的所有session:

getSessionsByWorkspace(workspace: string): SessionRow[] {
const rows = this.#db.prepare(
'SELECT * FROM sessions WHERE workspace = ? ORDER BY updated_at DESC'
    ).all(workspace);
return rows.map(rowToSession);
}

3.2 Session Manager

SessionManager(src/session/manager.ts)包装 SessionStore,提供面向 Agent 和 CLI 的领域方法。这一层的存在让 Agent 循环和 CLI 不直接接触 SQL。

大部分的方法都比较直观,需要注意的是appendMessage ,如果是第一条message,需要有自动生成标题的能力,因为每一个session都需要有title,这样用户才能在后续根据title选择想要恢复的session,

appendMessage(sessionId: string, role: string, content: string): MessageRow {
const msg = this.#store.insertMessage({ sessionId, role, content });
this.#store.updateSessionTimestamp(sessionId);
// 第一条 user 消息自动设为会话标题
const session = this.#store.getSessionById(sessionId);
if (session !== undefined && session.title === '' && role === 'user') {
const title = content.length > 50 ? content.slice(0, 50) : content;
this.#store.updateSessionTitle(sessionId, title);
    }
return msg;
}

appendMessage 有两个副作用:一个是刷新 updated_at(让 getLatestSessionByWorkspace 能找到最近活跃的会话),以及从第一条用户消息自动生成标题——就像 ChatGPT 的会话列表一样,用户不需要手动命名。

4. 与Agent集成

为了让我们的Agent具备记忆外挂能力,我们需要把以上实现的Session管理能力和Agent进行集成。主要是两个方面,一个是在Agent Loop中使用持久化的Session,另一个是可以通过CLI管理Session。

4.1 让循环拥有记忆

这是最关键的一步——让 Agent 的 stream() 方法感知 Session。我们需要在Agent.stream() 的loop前进行session预备,在loop结束时进行session持久化:

async *stream(input: string, options: AgentOptions = {}): AsyncGenerator<AgentEvent> {
// ... 加载 skills ...
const sessionManager = options.sessionManager ?? this.#sessionManager;
const sessionId = options.sessionId ?? this.#sessionId;
const hasSession = sessionManager !== undefined && sessionId !== undefined;
const requestBuilder = new PromptRequestBuilder(model)
        .addDeveloperMsg(`Working directory: ${this.#workdir}.`)
        .setInstructions(this.#skills.buildPromptInstructions())
        .setParallelToolCalls(false)
        .setStore(false)
        .setReasoning(options.reasoning ?? { effort: 'low' });
// ① Session 模式:注入历史 + 持久化用户消息
if (hasSession) {
const history = sessionManager.getMessages(sessionId);
for (const msg of history) {
            requestBuilder.addInputItem({
                role: msg.role as InputMessage['role'],
                content: msg.content,
            });
        }
        sessionManager.appendMessage(sessionId, 'user', input);
    }
// ② 共同路径:添加当前用户消息
    requestBuilder.addUserMsg(input);
// ... agent loop(工具调用循环)...
// ③ 运行结束:持久化 assistant 回复
if (hasSession) {
        sessionManager.appendMessage(sessionId, 'assistant', responseText);
    }
yield { type: AgentEventType.RunEnd, steps: step, text: responseText };
}

与原来的逻辑相比,主要涉及三处关键修改:

时机

操作

目的

请求构建前

从 DB 加载历史消息,注入 builder

让模型看到完整对话上下文

请求构建前

appendMessage('user', input)

持久化用户消息

运行结束后

appendMessage('assistant', responseText)

持久化 assistant 回复

4.2 基于CLI的session管理

我们对session的要求不高,只需要能枚举、恢复、清除即可,对于我们当前的CLI Agent而言,通过斜杠命令实现这几个能力并不难:

// /sessions — 列出当前 workspace 的所有会话
if (prompt === '/sessions') {
const sessions = sessionManager.listSessions(workspace);
if (sessions.length === 0) {
console.log('No sessions found.');
    } else {
for (const s of sessions) {
console.log(`  ${s.id}${s.title || '(untitled)'}  [${s.messageCount} msgs]  ${s.updatedAt}`);
        }
    }
}
// /resume <id> — 切换到指定会话
if (prompt.startsWith('/resume ')) {
const id = prompt.slice('/resume '.length).trim();
const session = manager.getSession(id);
if (session === undefined) {
console.log(`Session not found: ${id}`);
    } else {
        agent.setSessionId(id);
console.log(`Resumed session ${id} — ${session.title} [${session.messageCount} messages]`);
    }
}
// /clear — 新建会话
if (prompt === '/clear') {
const session = manager.createSession(workspace, model);
    agent.setSessionId(session.id);
console.log(`New session: ${session.id}`);
}

5.  实际运行

1、创建新session

$ pnpm --filter @zero-agent/chapter7 start
[session] New session: a1b2c3d4-...
Interactive mode — type your prompt and press Enter. Ctrl+C to exit.
❯ 我叫 Frank
[step 1]
你好,Frank!有什么可以帮你的吗?
[run_end after 1 step(s)]
❯ 我叫什么名字?
[step 1]
你叫 Frank。
[run_end after 1 step(s)]

第二轮对话中,Agent 准确回答了"Frank"——Session 管理生效了。

2、恢复老session

$ pnpm --filter @zero-agent/chapter7 start
[session] Resumed: a1b2c3d4-... — 我叫 Frank [2 messages]
Interactive mode — type your prompt and press Enter. Ctrl+C to exit.
❯ 我刚才说了什么?
[step 1]
你刚才说你叫 Frank。
[run_end after 1 step(s)]

Agent 重启后自动加载了上次的会话,无需任何手动操作。注意:这个功能只是为了演示,真实的Agent不需要自动恢复会话,重启后都是全新的会话,用户可以选择手动恢复想要恢复的会话。

3、 查看与切换会话

❯ /sessions
Sessions (newest first):
  a1b2c3d4-...  我叫 Frank  [4 msgs]  2026-10-16T10:30:00.000Z
  e5f6g7h8-...  查询天气    [2 msgs]  2026-10-16T09:15:00.000Z
❯ /clear
New session: i9j0k1l2-...
❯ /resume e5f6g7h8-...
Resumed session e5f6g7h8-... — 查询天气 [2 messages]

6. 总结

本文为 ZeroAgent 构建了完整的 Session 管理能力,SQLite 嵌入式数据库是做Agent持久化的最佳选择。Session管理的代码逻辑不复杂,其操作可以从CLI发起,也很简单。但Session能力本身对于Agent而言却非常重要。

Session 管理是 Agent 从"单次问答工具"进化为"持续对话助手"的关键一步。没有记忆的 Agent 就像一个每 5 秒钟就会失忆的助手——能力再强也无法完成需要跨轮上下文的任务。

读者可以在 https://github.com/significantfrank/ZeroAgent 的 chapter7 中获取本文的完整源码。

跳转微信打开

从零构建Agent(六):Skills

2026年10月15日 16:33

原创 从码农到工匠 2026-10-15 16:33 上海

本文讲述了 Agent Skills 的构建与 渐进式披露 机制。

上一期我们为 Agent 接通了 MCP,让工具像 USB 设备一样即插即用。但很快大家就会发现一个现实问题:给了 Agent 一把锤子和一把锯子,它依然盖不出一栋漂亮的房子。

要把领域的“行医指南”或“施工图纸”教给 Agent,最土的办法就是把所有指南都写进 System Prompt。但这就好比让一个人把全科医学百科全书时刻背在脑子里去应诊——不仅脑容量(Token)受不了,脑子(LLM 推理)也容易被繁杂的信息搅混,信息过载和信息不足一样有害,所谓过犹不及是也。

Skills是上下文工程(Context Engineering)的重要创新,本文将带你拆解Agent如何构建完整的Skill是功能。

1. 什么是 Skill

和 MCP 一样,Skills 也是 Anthropic 制定的一个规范,它并不意味着一定要和 Claude Code 绑定。只要遵从 Skills 规范,其核心是关于Skills的文件系统结构:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

其中最重要的是SKILL.md,其中name和description是必选项,是为了把Skill能力暴露给大模型。

---
name:skill-name
description:Adescriptionofwhatthisskilldoesandwhentouseit.
---

完整内容请查阅官方网站,你会发现 Skills 规范的内容非常简洁,关键是定义 Skills 的文件结构和发现机制。

2. 为什么需要Skill

大模型主要依靠prompt工作,每次模型交互,模型接收到的prompt叫Context(上下文),在Agent Loop中,经常出现的问题不是Context内容不够,而是信息太多,导致。

  • 上下文过载(Context Bloat): 浪费极高的 Token 成本。

  • 注意力稀释(Attention Dilution): 模型被大量无用信息干扰,出现幻觉或忽略关键指令(即“信息过载导致推理质量下降”)

Skills(技能)就是解决这一难题的优雅答案。 Skills 的底层灵魂在于“渐进式披露(Progressive Disclosure)”:

就像一个优秀的图书馆员,平时只看图书检索目录(元数据);只有当读者明确要查某种资料时,才去书架上取出具体的操作手册(完整指令);如果书中提到某个附录,再翻开附录(辅助资源)。

借由这种设计,上下文窗口永远只保留当前任务最核心的信息。这种渐进式的披露过程可以分为三级:前言(Frontmatter)--> 全文(Body) --> 引用(Reference)。在这里插入图片描述接下来,我们将逐步为 Agent 构建完整的 Skills 系统,帮助Agent解决上下文膨胀问题!

3. 实现Skill功能

3.1 Skill类型定义

我们创建一个新的skills 包,将skill相关代码都放在这里,首先需要定义typesccript类型,其中skill的数据结构比较简单,被定义在src/skills/types.ts :

exporttype SkillDefinition = {
/** Unique name of the skill (kebab-case). */
    name: string;
/** Human-readable description of what the skill does. */
    description: string;
/** Instruction text injected into the system prompt when the skill is used. */
    instructions: string;
};

三个核心字段:name 是唯一标识,description 用于让模型判断"该不该用这个技能",instructions 是完整的指令正文。

3.2 Skill加载

在 Claude Code 中,它支持两种Skill来源:

  • 全局 Skills:~/.claude/skills/

  • 项目 Skills:{workdir}/.claude/skills/

为了实现类似的能力,我们首先要让我们的Agent支持,实现方式是在request中加入role为developer的item信息。

const requestBuilder = new PromptRequestBuilder(options.model ?? this.#model)
 .addDeveloperMsg(`Working directory: ${this.#workdir}`)
 .addUserMsg(input)
 .setInstructions(this.#skills.buildPromptInstructions())
 .setParallelToolCalls(true)
 .setStore(false)
 .setReasoning(options.reasoning ?? { effort: 'low' });

注意,在Responses API中,developer role和Instructions和传统的system prompt的作用类似。其效果就是,在每一次模型交互中,都会带上working directory的信息。为了区分user prompt,其role是developer。

"input": [
    {
"role": "developer",
"content": "Working directory: ~/ZeroAgent/chapter6"
    },
    {
"role": "user",
"content": "请问,当前有哪些可用的skill?"
    }
  ],

对于我们的Agent而言,参考Claude Code的实现,我们需要把 ~/.zeroagent/skills/ 作为全局目录、{workdir}/.zeroagent/skills/ 作为项目目录。其实现方式如下,具体是通过先后顺序来实现优先级的,后加载的优先级更高:

exportasyncfunctionloadAllSkills(workdir: string): Promise<{
    registry: SkillRegistry;
    loaded: LoadedSkill[];
}> {
const registry = new SkillRegistry();
const loaded: LoadedSkill[] = [];
const dirs = [userSkillsDir(), projectSkillsDir(workdir)];
for (const dir  of dirs) {
const skills = await loadSkillsFromDirectory(dir);
for (const entry of skills) {
            registry.register(entry.skill);
            loaded.push(entry);
        }
    }
return { registry, loaded };
}

3.3 渐进式披露:三级加载机制

前面提到,Skills 解决"上下文危机"的关键设计叫渐进式披露。这是上下文工程(Context Engineering)中的一项核心实践:不要一次性把所有信息塞给 LLM,而是根据任务进展分阶段注入。

如果没有 Skills,将多个专业领域的操作指南全部塞入 System Prompt 会导致上下文爆炸。Skills 通过三级加载机制优雅地解决了这一问题。

第一级——Skill发现

会话启动时,Agent 只加载所有可用 Skill 的 name 和 description,通常在几十到几百个 Token 内。这相当于在 Agent 的认知中建立一个"技能目录",让它知道有哪些能力可用,但不了解具体操作细节。

这正是 SkillRegistry.buildPromptInstructions() 的职责——只输出目录,这段目录被放入 Responses API 的 instructions 字段,作为全局指令注入给模型。几百 Token 的目录开销可控,模型也因此具备了"技能意识"。

第二级——Skill理解

当用户提出任务后,Agent 判断需要调用某个 Skill,此时才加载该 Skill 的完整 skill.md 指令。

例如用户要求"请从这个 PDF 中提取所有表格,并统计每个表格的行数和列数",Agent 识别匹配 pdf Skill,于是通过 load_skill 工具加载其完整指南(可能几千 Token),获取详细的操作方法论——包括如何定位 PDF 中的表格对象、如何解析表格结构、如何处理跨页表格等。

这个两步分离的设计——先看目录选择技能,再获取完整指令——是渐进式披露的核心。这样做的好处是:

  • 节省上下文:10 个技能的目录可能只有 200 Token,但 10 个技能的完整指令可能有 10000 Token

  • 按需注入:模型只获取与当前任务相关的技能指令,其他技能的指令不会干扰推理

  • 聚焦推理:上下文窗口只包含当前任务真正需要的信息,LLM 不会因信息过载而降低质量

第三级——资源按需加载

在执行 Skill 过程中,如果需要额外的资源(如脚本、模板、参考文档),Agent 再按需加载这些文件。

例如 PDF 处理 Skill 可能需要执行一个表格提取的 Python 脚本模板、一个处理加密 PDF 的解密工具、或一个针对扫描件 PDF 的 OCR 配置模板。这些资源存放在技能文件夹内,skill.md 的指令中会引用它们的相对路径:

~/.zeroagent/skills/pdf/
  skill.md              ← 第二层加载
  templates/
    extract-tables.py   ← 第三层按需加载
    ocr-config.json     ← 第三层按需加载
  scripts/
    decrypt.sh          ← 第三层按需加载

Agent 在执行指令时,通过Skill中Instructions的指引,决定加载哪些额外资源,执行哪些脚本命令,有一段时间鼓吹的推荐用CLI代替MCP,用到的就是Skill能力指引CLI执行。

4. 实际运行

完成以上实现之后,我们就可以在我们的Agent中使用Skill能力了。创建一个技能目录 ~/.zeroagent/skills/tech-writer/skill.md,Agent 启动时自动加载:

$ pnpm --filter @zero-agent/chapter6 start "分析当前代码仓,写一篇技术文章"
[skills] Loaded 1 skill(s): repo-tech-writer
[step 1]
[tool_call] load_skill({"name":"repo-tech-writer"})
[tool_result] ## Skill: repo-tech-writer
...
[step 2]
[tool_call] run_terminal_command({"command":"git clone --depth 1 ..."})
[tool_call] read_file({"path":"package.json"})
...
[run_end after 8 step(s)]

模型在第一步先调用 load_skill 获取完整指令,然后按照指令流程克隆代码仓、分析架构、撰写文章、保存到 Obsidian。

5. 总结

本文讲述了 Agent Skills 的构建与 渐进式披露 机制。Agent 光有 MCP 工具还不够,还需要领域知识和操作流程。把指南全塞进 System Prompt 会导致 Token 过载、推理混乱。Skills 是 Anthropic 提出的上下文工程规范,通过 SKILL.md 及配套文件(scripts、references、assets)来组织可复用技能,让 Agent 真正会做事。

读者可以在 https://github.com/significantfrank/ZeroAgent 的chapter6中,获取本文的Demo源码。

跳转微信打开

从零构建Agent(五):MCP

2026年10月13日 16:19

原创 从码农到工匠 2026-10-13 16:19 上海

“计算机科学中的所有问题都可以通过增加一个间接层来解决。” MCP就是这样的中间层

上一篇我们为 Agent 实现了一组本地 Function Calling 工具——文件读写、命令执行、代码搜索。这些工具让 Agent 从"只会聊天"变成了"能干活"的实干家。但所有工具都是硬编码在 Agent 内部的:加一个工具就要改代码、改 switch、加测试、重新部署。

如果工具能像 USB 设备一样即插即用呢? 你启动一个进程,Agent 自动发现它暴露的工具,注册到工具列表里,无需改一行代码。

这正是 MCP(Model Context Protocol) 试图解决的问题,但它要应对的远不止单个 Agent 的工具扩展。在 MCP 出现之前,每一个 AI 应用想要连接某一个外部工具,都需要单独编写一套集成代码。如果有 N 个 AI 应用和 M 个外部工具,理论上就需要 N × M 套定制适配器。数据被锁在信息孤岛和遗留系统里,每接入一个新数据源都要做一次定制实现,连接真正的外部系统变得难以规模化。MCP 要解决的,就是这种“N×M 集成噩梦”。

本文我们在Function Calling的基础上,为 Agent 增加 MCP 客户端支持,并实现一个 MCP Server,让 Agent 能够动态连接外部工具服务器。

1. 什么是 MCP

1.1 中间层解耦

我在《程序员的底层思维》一书中说过:“计算机科学中的所有问题都可以通过增加一个间接层来解决。”  这也是解耦的精髓,比如依赖倒置解耦,就是加入了新的抽象层。我当时还举了一个”我“作为中间层,解耦婆媳关系的例子:)

MCP也是中间层解耦。不要让 Agent 直接持有工具的实现,而是在 Agent 和工具之间插入一个中间层——Agent 只负责“描述我需要什么能力”,中间层负责“找到并提供这些能力”。这样,工具的增删改就不再牵动 Agent 的代码,Agent 也不用关心工具到底跑在本地、远程还是别人的服务器上。

这层中间层就是 MCP Client/Server 架构。Agent 通过 MCP Client 与外部 MCP Server 通信,工具的具体实现被隔离在 Server 一侧。加一个工具,只需要启动一个实现了对应能力的 MCP Server;Agent 侧无需改代码、无需重新部署,只需要在运行时发现并注册这个 Server 暴露的工具即可。

1.2 MCP协议

MCP协议是由 Anthropic 于 2024 年 11 月开源。它的定位可以用一个类比来概括:AI 领域的 USB-C。设备(Agent)和配件(工具/数据)各自实现标准接口,而不是每对组合都焊一根定制线。工具只需要实现一次 MCP Server,所有支持 MCP 的 AI 应用都可以直接连接使用,集成方程从 N×M 简化为 N+M。

MCP 的规范基于 JSON-RPC 2.0,采用客户端-服务器架构。Host(如 Claude Desktop、Cursor 等 AI 应用)管理多个 MCP Client,每个 Client 与一个 MCP Server 建立连接。MCP Server 可以向 Client 暴露三类核心能力:Tools(可供模型执行的函数)、Resources(可供读取的上下文数据)、Prompts(可复用的交互模板)。更多细节请参考我之前写的关于MCP的文章。

如下图所示,Agent(MCP Client) 不需要知道工具的具体实现,只需要知道:有哪些工具(listTools)、怎么调用(callTool)。工具的实际执行发生在 Server 侧,结果通过协议返回。

2. MCP Client实现

2.1 McpClientManager 设计

src/mcp-client.ts 中的 McpClientManager 是 Agent 侧的 MCP 客户端管理器,负责管理多个 MCP Server 连接:

    export class McpClientManager {
        readonly #clients = new Map<string, Client>();
        readonly #transports = new Map<string, Transport>();
        readonly #toolIndex = new Map<string, { serverName: string; originalName: string }>();
    }

    三个核心数据结构:

    • #clients

      :Server 名称 → MCP Client 实例的映射,每个连接对应一个 Client。

    • #transports

      :Server 名称 → Transport 的映射,管理传输层生命周期。

    • #toolIndex

      :Prefixed 工具名 → { serverName, originalName } 的反向索引,用于在 callTool 时路由到正确的 Server。

    2.2 连接 MCP Server

    MCP SDK 提供了两种传输方式:stdio(通过子进程通信)和 in-memory(同进程通信,用于测试)。connectTransport 是统一的连接入口:

      async connectTransport(serverName: string, transport: Transport): Promise<void> {
          if (this.#clients.has(serverName)) {
              throw new Error(`MCP server "{serverName}__{mcpTool.name}`,
                      parameters: mcpTool.inputSchema as Record<string, unknown>,
                      strict: false,
                  };
                  entries.push({ originalName: mcpTool.name, prefixedName, serverName, tool });
                  this.#toolIndex.set(prefixedName, { serverName, originalName: mcpTool.name });
              }
          }
          return entries;
      }

      命名空间隔离 是关键设计。如果两个 Server 都暴露了一个叫 echo 的工具,Agent 怎么区分?答案是加前缀:serverA__echo 和 serverB__echo。前缀格式是 serverName__toolName,用双下划线分隔(因为工具名本身不会包含双下划线)。

      MCP 工具的 inputSchema 是 JSON Schema 格式,和 FunctionTool.parameters 兼容,直接透传即可。但 strict 统一设为 false——MCP Server 的 schema 可能包含可选参数。

      2.4 工具调用

      当模型请求调用一个 MCP 工具时,callTool 通过 #toolIndex 找到对应的 Server 和原始工具名,然后转发调用:

        async callTool(prefixedName: string, args: Record<string, unknown>): Promise<McpCallResult> {
            const index = this.#toolIndex.get(prefixedName);
            if (index === undefined) {
                return { output: `Unknown MCP tool: {index.serverName}" is not connected`, error: 'server_disconnected' };
            }
            try {
                const result = await client.callTool({
                    name: index.originalName,
                    arguments: args,
                });
                // Extract text from content blocks
                // ...
                return { output, error };
            } catch (error) {
                return {
                    output: error instanceof Error ? error.message : String(error),
                    error: 'mcp_call_error',
                };
            }
        }

        任何异常都不会 crash Agent,而是转成 McpCallResult 传回模型。MCP 协议本身也有 isError 标志位——Server 可以正常返回 HTTP 200 但标记 isError: true,表示工具执行失败(区别于协议层面的错误)。

        3. MCP Server 实现

        3.1 Demo Server

        src/mcp/server.ts 实现了一个 demo MCP Server,暴露三个工具:echo、add、upper:

          export function createDemoServer(): McpServer {
              const server = new McpServer(
                  { name: 'zero-agent-demo', version: '0.1.0' },
                  { capabilities: { tools: {} } },
              );
              server.registerTool('echo', {
                  description: 'Echo back the provided text. Useful for testing MCP connectivity.',
                  inputSchema: { text: z.string().describe('The text to echo back') },
              }, async (args) => {
                  return {
                      content: [{ type: 'text' as const, text: args.text }],
                  };
              });
          // 省略add和upper
              return server;
          }

          McpServer 是 MCP SDK 提供的 Server 类,registerTool 接收三个参数:工具名、配置对象(含 description 和 inputSchema)、回调函数。inputSchema 使用 Zod schema 定义,SDK 自动将其转换为 JSON Schema 暴露给 Client。

          工具返回值是 { content: ContentBlock[] },其中 ContentBlock 的 type 必须用 as const 断言为字面量类型——这是 TypeScript 类型系统的要求,否则会推断为 string 导致类型不匹配。

          3.2 stdio 运行模式

          Demo Server 支持以独立进程运行,通过 stdio 与 Agent 通信:

            async function main(): Promise<void> {
                const server = createDemoServer();
                const transport = new StdioServerTransport();
                await server.connect(transport);
                process.stderr.write('[mcp-server] zero-agent-demo running on stdio\n');
            }

            StdioServerTransport 监听当前进程的 stdin,解析 JSON-RPC 消息,将响应写入 stdout。注意 Server 的日志输出到 stderr——stdout 是协议通道,任何非协议内容都会破坏 JSON-RPC 解析。

            启动方式:

              pnpm --filter @zero-agent/chapter5 mcp-server

              4. Agent 集成 MCP

              4.1 工具列表合并

              src/tools.ts 中新增了全局 mcpManager 实例和 getAllToolsWithMcp 函数:

                export const mcpManager = new McpClientManager();
                export async function getAllToolsWithMcp(): Promise<readonly FunctionTool[]> {
                    const mcpEntries = await mcpManager.listAllTools();
                    const mcpTools = mcpEntries.map((e) => e.tool);
                    return [...allTools, ...mcpTools];
                }

                每次 Agent Loop 请求模型前,都会调用 getAllToolsWithMcp() 获取完整的工具列表:本地工具 + 所有已连接 MCP Server 的工具。模型看到的是一个统一的工具列表,不需要知道哪个是本地的、哪个是远程的。

                4.2 工具调度

                executeTool 在原有的 switch 之前增加了一个 MCP 检查:

                  export async function executeTool(call: FunctionCallItem): Promise<ToolResult> {
                      // Check if this is an MCP tool
                      if (mcpManager.isMcpTool(call.name)) {
                          const args = parseArgs(call);
                          const mcpResult = await mcpManager.callTool(call.name, args);
                          return {
                              callId: call.call_id,
                              name: call.name,
                              output: mcpResult.output,
                              error: mcpResult.error,
                          };
                      }
                  }

                  调度逻辑是:先查 MCP,再查本地。mcpManager.isMcpTool(call.name) 通过检查 #toolIndex 判断工具名是否属于某个 MCP Server。如果是,解析参数后转发给 mcpManager.callTool。如果不是,进入原有的 switch 分派本地工具。

                  5. 测试策略

                  MCP 测试不需要启动子进程。MCP SDK 提供了 InMemoryTransport.createLinkedPair(),创建一对通过内存通信的 Transport:一端给 Server,一端给 Client,无需网络和进程间通信。

                    const [clientTransport, serverTransport] = createInMemoryTransportPair();
                    const server = createDemoServer();
                    await server.connect(serverTransport);
                    await manager.connectTransport('demo', clientTransport);

                    这种方式既快又可靠,适合单元测试和集成测试。

                    6. 总结

                    本文为 Agent 增加了 MCP 支持,让 Agent 能够动态连接外部工具服务器,实现了工具的即插即用。核心要点:

                    1. MCP 是工具的 USB 协议

                      :Server 暴露工具,Client 发现并调用,通过 JSON-RPC 通信。Agent 不需要知道工具实现,只需要知道有哪些工具、怎么调用。

                    2. 命名空间隔离

                      :通过 serverName__toolName 前缀避免不同 Server 的同名工具冲突。这是多 Server 共存的基础。

                    3. In-Memory 测试

                      :用 InMemoryTransport 创建同进程通信的 Server-Client 对,测试快且可靠,无需子进程和网络。

                    至此,我们的 Agent 已经具备了"大脑"(Agent Loop)、“双手”(本地工具)和"外接设备"(MCP Server)。下一篇文章我们讲解一下skills功能的实现。

                    微信读者请在 https://github.com/significantfrank/ZeroAgent/chapter5 获取Demo源码

                    跳转微信打开

                    ❌