锦恢的 AI Agent 小白教程（七）PTC 设计原则与 Agent Harness 标准架构

前言

在前面几个章节，我们系统学习了 LLM 的基本原理（ChatML，System Prompt），LLM 是怎么转变到 Agent 的（也就是 ReAct 驱动的 Agent Loop 范式），更进一步的 Agent 封装（Loop Engineering，最典型的应用就是 goal 了），以及我们持久化 Agent 记忆的最佳工业实践 AGENTS.md 和 SKILL.md（这也被我们称为 Agent 基建）。

但是在这些章节中，关于 Agent Harness 的讲解略显碎片，且还没针对一个案例，告诉大家在这个案例下的 Agent Harness 具体要如何设计，也就是具体要设计哪些工具，怎么设计这些工具给 Agent 去用。这一章节中，我们会通过一个案例来讲出这件事。

这一章，我将拼凑完整 Agent 系统的最后一块拼图，并展示一个最小化的完整的现代的 Agent 系统到底是什么样子的，并配合一个我常用的 Agent 框架完成一个简单助手的快速设计与开发。

你能学到什么

通过本章学习，你将理解 codex，claude code，glm zcode 这些产品级 Agent 的 Harness 视角的完整蓝图，建立起对全套 Agent 系统自上而下的认知，初步拥有评估和判断 Harness 好坏的能力。并能学会利用成熟的 agent 框架快速搭建特定场景下助手机器人的能力。

PTC 设计原则

在之前的章节中，我们知道从 LLM 到 Agent 最主要的转变在于工具调用，在于 ReAct 范式。但是我们之前的章节中还没有讲到面对一个具体的业务场景和需求，要如何给 ReAct 组装对应的工具。

朴素的陷阱 —— 和拓展性说再见吧

在一年前，也就是 2025 年年初的时候，当时大部分人的一个直观想法是，业务上需要什么工具，我们就不断给 Agent 装配什么工具。比如我们需要设计一组工具给 Agent 来查询一个数据容量有 100 万条数据的外贸订单系统，设计这组工具的流程大概会是：

业务组说需要能让 Agent 查询状态为 pending 的订单 -> 我们设计 queryPending 工具。

业务组说需要能让 Agent 查询到负责业务板块 A 的全部业务员 -> 我们设计 queryCommissioner 工具。

…

你说为什么不能直接让 AI 读入全部订单信息，再回答，这样不就可以不需要设计工具了吗？你可真是一个小天才，注意呀，这 byd 是 100 万条数据，大模型上下文塞得下吗？就算塞得下，100 万条消息稀释的注意力能让大模型 100% 召回率地完成任务吗？

显然，从架构上，这样设计会引入巨大的拓展性风险——大模型的上下文是有限的，而通过 锦恢的 AI Agent 小白教程（三）提示词原理及其应用：ChatML、工具调用、提示词注入 的学习，你应该能明白，每一个工具的引入，都会增加大模型的系统提示词大小，这部分「大模型还没开始任务呢，就要计入上下文」的额外提示词，我们有时也会称为 prefill（预装填，infra 和 IC 工程师更喜欢这么说）。显然，每一个工具的引入都会增大 prefill，在我们这个例子中，N 个工具的引入会让 prefill 变成这样：

你是一个可以协助业务人员查询外贸订单的智能助手。以下是一些可以使用的工具：

## 可用工具

1. queryPending - 查询状态为 pending 的订单
   参数：
   - limit（整数，选填）：最多返回多少条订单，默认为 20。
   - offset（整数，选填）：从第几条记录开始返回，默认为 0。

2. queryCommissioner - 查询指定业务板块下的全部业务员
   参数：
   - businessUnit（字符串，必填）：需要查询的业务板块，例如 "A"。

3. ...

N. stopQuery - 停止已有的全部查询
   参数：
   - 无

当需要使用工具时，请将响应格式化为包含 "name" 和 "arguments" 字段的 JSON 对象。

显然，随着业务越来越大，Agent 能对接的能力越来越多，prefill 越来越大，就会导致一个很严重的问题——用户的 prompt 还没进来呢，光是 prefill 就已经把上下文的一大半给占据了。

比如在 Introducing advanced tool use on the Claude Developer Platform 这篇 Anthropic 的工程博客里就提到了：Anthropic 的工程师们开发了一个含有 58 个工具的助手机器人 Agent，光是这 58 个工具就会让 prefill 增加 55K 的 token 消耗量，而他们使用大模型上下文也才只有 200K。光是工具的定义就已经占据了大模型 27.5% 的上下文。

大模型的上下文不会一直增长，因为底层显卡的显存总是有限的、HBM 的工艺迭代是缓慢的，因此这样的工具排布设计方案无疑非常不利于进行后期的拓展。

所以早期很多社区玩家设计的 harness 方案将全部工具的定义载入 prefill 这件事是没有拓展性（包括我早期设计的 atomic tool 思想），终将被历史抛弃的。

PTC —— 复杂度只会转移，不会消失，它转移到哪了呢？

这个问题的解决始于一场商业布局的意外之喜——为了从和 OpenAI 的竞争中取得优势，2024 年末开始，推出 Claude 的 Anthropic 公司开始进军 AI Coding 这个垂直领域，推出了 Claude Desktop，Claude CLI，Claude Cowork 等一系列桌面 Agent 产品。不同于当时热门的 ChatGPT 和 DeepSeek 这类只能在网页端做问题回答任务的 AI，Anthropic 推出的 Claude 系列产品更像是一个 Agent，它不仅仅能回答你的问题，还能实打实操作你电脑上的文件，帮你改文件改方案改代码。

在 2024 年，我们使用 ChatGPT 或者 DeepSeek 写代码的形式更多是把项目代码复制到 ChatGPT 的网页输入框，然后告诉它我们想要怎么做，然后再把 ChatGPT 的回答复制粘贴回我们的代码编辑器中。但是 Claude 可以做到直接帮你修改文件代码，你不需要复制，也不需要粘贴。不要小看了这节省了复制粘贴的步骤，从产品角度，这是非常 breakthrough 的——它革命了写代码的交互形式，让我们不必再操作代码，而是给出需求，review 结果即可，用户心智直接从代码移动到了更上层的需求和架构评估。

就算你不懂大模型训练，估计你也能看出来，当年的 Claude 模型之所以一骑绝尘，可以帮你改代码，是因为 Claude 的编码能力很厉害（我们称为 Coding 能力），Claude 能根据你的需求几乎 100% 地生成一段语法正确的 python，bash，javascript 等等代码。你要知道，2024 年的大部分模型，你把代码片段扔给它，它生成的代码甚至都做不到 100% 没有语法错误。AI 根据需求一轮就能生成一段语法完全正确，还能八九不离十满足需求的代码在 2024 年并不是一件理所当然的事情。

Anthropic 原本只想要做这样一个垂直领域来避免和 OpenAI 在问答聊天机器人这个主战场上正面交锋，但是没想到，大幅度提升 Claude 模型的 Coding 能力后得到了一个 harness 范式上的意外之喜 —— PTC（Programmatic Tool Calling）。

PTC 非常简单，它就讲了这么一件事——既然我们通过写代码就能操作数据库，完成 Excel 表格的增删改查，那为什么还需要为这些底层模型的上层提供一个又一个工具呢？直接让 Agent 自己编写并运行代码不就行了？这样只需要给 Agent 提供编写代码和运行代码这两个工具就行了。

任何基于这种思想设计的工具布局都可以称为 PTC。

所以这里需要纠正一下各位观众的思想，很多技术并非一两个天才一拍脑袋就想出来的，大量的前沿技术都是硬件，软件，算法，架构多方面升级后相互推动的。没有大模型在 Coding 能力上的显著提升，PTC 这个方案在 harness 上是不会凑效的，请记住这一点，我的朋友。

显然，通过上面的描述，你应该能看出来，想要实现基于 PTC 的工具布局设计，需要至少两样东西：

使用的基模的 Coding 能力和 Agentic 足够强，因为修改代码涉及到代码生成和多轮交互这两个任务。

被 PTC 描述的工具本身可以通过编程的方法来操作，比如你可以通过编程修改 Excel，但是你却不能通过编程的方法来稳定安全地操作和接受你微信上的消息。

回到上面那个订单管理系统的例子，使用 PTC 就会非常优雅了，假设我们的基模的 Coding 能力足够强，且我们通过一些手段拿到了我们这套外贸订单系统的 CLI 或者 SDK（在绝大部分 Agent 落地场景中，这是落地的主要阻碍），可以通过编程的方式来使用这套外贸系统。那么我们就不再需要定义和实现 queryPending，queryCommissioner 等等工具，我们只需要定义一组编程和执行代码的工具，并在系统提示词中如下交代即可：

你是一个可以协助业务人员查询外贸订单的智能助手。以下是一些可以使用的工具：

## 可用工具

1. write - 将代码或文本内容写入指定文件
   参数：
   - path（字符串，必填）：需要写入的文件路径，例如 `"/workspace/query.py"`。
   - content（字符串，必填）：需要写入文件的完整内容。

2. read - 读取指定文件的文本内容
   参数：
   - path（字符串，必填）：需要读取的文件路径，例如 `"/workspace/query.py"`。
   - offset（整数，选填）：从第几行开始读取，默认为 1。
   - limit（整数，选填）：最多读取多少行；不指定时读取到文件末尾。

3. edit - 对指定文件中的文本进行精确替换
   参数：
   - path（字符串，必填）：需要编辑的文件路径，例如 `"/workspace/query.py"`。
   - old_text（字符串，必填）：需要被替换的原始文本，必须与文件中的内容完全匹配。
   - new_text（字符串，必填）：用于替换原始文本的新内容。

4. bash - 在隔离的 Linux 环境中执行 Bash 命令
   参数：
   - command（字符串，必填）：需要执行的 Bash 命令，例如 `"python3 /workspace/query.py"`。

当需要使用工具时，请将响应格式化为包含 "name" 和 "arguments" 字段的 JSON 对象。

执行 bash 命令也能创建文件，这里为什么还需要一个单独的 write, read, edit 工具？这个问题留给读者了。

那么，当业务组说需要能让 Agent 查询状态为 pending 的订单时，Agent 就会先调用 write 工具先生成下面这样的一段代码并写入 ：

import excel

rows = excel.read_range({
    "sheet": "Orders",
    "range": "A1:Z10001"
})

pending = [row for row in rows if row["Status"] == "pending"]

print({
    "count": len(pending),
    "examples": pending[:5]
})

然后再调用 ，执行这段代码获取结果。

由于 python 编程语言本身是图灵完备的，而且我们本身就有了 excel 这样的库来访问贸易系统（部分传统贸易公司的数据都存储在 Excel 表格里），并自由操作。并且我们知道使用 python + Excel 库就能实现所有增删改查的行为。

这样通过编写代码 + 执行的方法就被我们称为 PTC。并且 PTC 还带来了非常多额外的好处——如果大模型本身被训练得非常擅长编写 python 代码，那么理论上，Agent 就获得了所有利用 python 完成的功能的能力。

比如我们可以在 python 里面使用 opencv 或者开源的深度学习模型来完成图像的读入和处理，那么我们的 Agent 自动也就学会了这个技能，当你和 Agent 说 “请帮我把这张图的雨进行 AI 擦除”，Agent 就会去搜索热门的 derain 开源 AI 项目，并通过 工具完成项目的安装初始化并帮你使用安装好的项目完成图像处理任务。

再比如你想要你的 Agent 帮你安装一下这份我的世界 mod，Agent 也类似，它会通过 工具调用命令行，不断发现你的《我的世界》游戏安装目录，并且再通过 把你的 mod 自动移动到该安装目录的文件夹里面，从而帮你完成 mod 的安装。在 PTC 之前，你可能还需要专门编写一个「我的世界服务器 MCP」来维护服务器启动，版本切换，MOD 安装，玩家管理等等一系列工具，但是现在你只需要一个 ，因为大模型本身会通过网络搜索找到使用命令行或者代码操作 MC 服务器的方法。

图片图片

当然，有时候大模型也不一定能搜到一些工具的或者 CLI 的使用方法，所以才有了 SKILL.md 的编写狂潮，这些事情本质上也都是大模型 Coding 能力提升、PTC 范式在 harness 设计中的普及等等事件释放出来的技术红利。对这部分内容感兴趣的朋友欢迎查看上一章的内容。

除此之外，PTC 结合上一章的内容（锦恢的 AI Agent 小白教程（六）Agent 项目基建：SKILL.md 和 AGENTS.md），还能自动实现一套 Agent 的记忆系统。AGENTS.md 带来的基础索引 + PTC 实现的完备的文件搜索，编辑，阅读等功能，Agent 可以基于文件完成记忆的更新和保存。

很多朋友可能会感叹：PTC 真 nb 呀，一下就优雅解决了问题，发明它的人一定是一个天才，但是请记住，我的朋友，复杂度不会消失，PTC 的范式只是把复杂度从「设计一个又一个工具」转移到了「大模型本身的 Coding 能力」上，这背后是对团队建设巨大的转变——之前做工具设计大概只需要对业务和工程比较了解的人来做就行了，但是转变为 PTC 范式后，意味着团队还需要一支熟悉大模型 Coding 能力训练和训练质量评估的相关人才，2026 年，这类人才的市场价年薪都在百万上下，如果养不起，那么就只能使用外部的大模型 API 了，但是这意味着安全性、成本、不可在私有数据 scaling 等等诸多问题。

所以，你能看到，工程就是基于已有的软件硬件条件的妥协和折中。天才是存在的，但是他们的故事并非和你在小说上看到的如出一辙。

为什么是 PTC，而不是 Computer Use

PTC 赋予了 Agent 几乎无限的能力。这是因为我们通过编程语言，就能够几乎百分百地操作我们的电脑，以及电脑上的多媒体与软件。 但是这件事并不直观，它并不和人类的语义对齐——绝大的普通人和计算机交互的方式都不是通过代码或者命令行，而是通过图形界面 GUI，也就是你已经习以为常的鼠标点点点，手机屏幕点点点就能完成操作。

所以，从两三年前开始，当时 Agent 的主流方案并不是 PTC，而是 computer use，也就是让 AI 学会直接使用鼠标和键盘操作电脑的图形界面， Mulerun，OpenAI 最早期的 Atlas 浏览器等产品都是在做这件事 。但是 computer use 因为如下的原因并没有成为主流技术：

训练大模型的稠密逻辑类数据更多，得到的结果就是大模型会更加擅长生成这类形式逻辑的语言。OpenAI Astra 大模型已经可以在数学家的安排下辅助解决菲尔兹奖级别的超级数学难题了，但是具身智能大模型目前连任意餐具的洗碗任务都做不到泛化。

对于有空间理解关系的任务，大模型则非常不擅长。比如使用鼠标点击图形画面，或者是使用手机来触碰，这些都是非常典型的含有空间理解关系的任务。这类任务目前大模型完成得非常差。

最终得到技术圈和市场认可的技术仍然是 PTC，这也证明了一件事，很多时候跟着直觉走并不能成功，如果这份直觉并非来自于底层技术研发的第一性原理。

这是银弹？不，PTC 引入了新的安全问题

工程的艺术就是妥协和折中，对于 PTC 而言也是如此。

我们在上文中讲到了，PTC 给我们的 Agent 设计带来了意外之喜，那就是 Agent 通过 PTC，让大模型可以直接编写编程语言并执行，这使得我们的 Agent 拥有了一些额外的能力，就像我们上面举的这些例子：它不仅可以实现贸易系统的订单查询，也能够帮我们自动安装《我的世界》游戏的 mod。

这件事情看起来非常美好啊，毕竟我们只花了一份力，就赋予了 Agent 几乎无限的能力。但事实上，这是一把双刃剑，它既是好事情，也是坏事情。

由于 Agent 可以通过 PTC 实现几乎任意的计算机操作，所以除非你是计算机专家，否则很多时候你无法预测 Agent 到底能做到什么，不能做到什么，这为如下的场景带来了非常严重的问题：

信息泄露：如果你用了不安全的中转站，当你让 Agent 执行一些敏感操作时，由于它拥有 read，bash 等工具，它有概率想法设法读取到存储在你电脑上的敏感信息（比如你的 Agent 读到了锦恢的 快速破解目标计算机的Chrome浏览器保存密码，那么它就能够读取到你电脑上的密码相关的信息），这些读取到的数据会通过 llm call 的方式流经中转站，造成严重的数据泄露。

意外操作：由于 Agent 可以通过 bash 等等工具实现几乎任意的操作，当你提供的上下文不足、模型能力不足、系统发生意外情况时，PTC 范式下的 Agent 会做出很多超出我们设计的意外操作，这些意外操作包括但不限于批准高风险操作（删除重要数字资产，见下图）、覆盖关键配置、为系统引入强耦合依赖让项目更容易变成屎山、修改测试文件或者绕开审查机制等等操作，这些操作都会引入巨大的安全问题。

图片图片

模型评估变得不再简单：在过去，深度学习模型的评估是一件非常简单的事情，它甚至可由算法工程师顺手解决，而模型评估是在复杂环境下验证训练结果最有力的证据之一。但是引入 PTC 后的模型评估不再简单，因为评估 PTC 范式下的 Agent 执行需要防范 Agent 作弊，比如我们让 Agent 在一个完整的评估数据环境中评估它的性能，它却通过 bash 等方法“越狱”，找到了 grader 的定义文件，找到了标准答案；再比如我们让 Agent 独立根据文档完成 ffmpeg 的编码器实现，Agent 却偷偷摸摸去网络上直接下载了 ffmpeg 源码对着抄完成了任务。PTC 的引入使得评测这件事变得非常棘手，同样一个 benchmark，你在不同的评测系统下的得分甚至有可能不一样。下一章，锦恢会展开讲讲 Agent 评测这件事，这件事值得花一到两个章节来讲讲。

但是 PTC 为我们在 harness 设计上节省的大量功夫值得我们去克服这些问题。这几年很火的 agent infra 和 sandbox 要解决的就是上面这几个问题，在 AI Infra 软核教程 系列教程的后面几个章节，会对这部分的技术原理展开讨论。

【选读】PTC 与现代大模型后训练流程

通过 AI Coding 的飞速普及和相关产品的能力得到了市场的验证，PTC 成为了目前一个 Agent Harness 的首要设计原则，并且极大影响了大模型的后训练流程。如果你经常关注科技新闻，就会发现各个大厂和 AI 初创在 2025 年年中统一调转了训练方向，把 Coding 作为目前最重要的能力之一进行训练，各个榜单也从 MCPMark 这类衡量普通工具调用的榜单变为了 Terminal 2.0，NL2Repo 这类和 Bash、Coding 有关的榜单。

锦恢会在后续带着我们的开源作品写一个 Agentic LLM 后训练的教程，在里面我会提到榜单的作用。在大模型后训练中，榜单是一个非常重要的训练权重质量评估指标，用什么榜单可以衡量 LLM 的某种能力，也可以窥探到当前这家公司训练模型的一个基本能力方向。

而时下各个大厂无论是训练通用大模型，还是业务上的大模型，只要是和 Agentic 能力相关的，优先强化 Coding 能力，再去强化业务理解能力都成为了越来越多被验证成功的后训练 pipeline。这一部分很清晰，但是在工程实现上有大量的坑，等我后续编写 dressage 教程的时候再详细展开吧。

Agent Harness 标准架构

如果阁下充分理解了 PTC，那么恭喜🎉，你已经完成了通用 Agent Harness 架构设计的最后一块拼图。

接下来，我们要开始搭积木，结合前面学过的知识点，描绘出完整的通用 Agent 的 Harness 蓝图了。

图片图片

拼图一：PTC 工具组

我们前面提到的 PTC 已经成为了强基模下的一个基本的设计原则，所以 write, read, edit, bash 这四个工具都是必须的。

我们得到了 write, read, edit, bash

拼图二：子智能体与规划模式

通过 锦恢的 AI Agent 小白教程（四）智能体基本原理：Agent Loop，规划模式与子智能体 的学习，子智能体和规划模式也是需要支持的。子智能体一般就叫 subagent 或者 task 这个工具，我个人更喜欢用 task 这个说法。

这里有一个细节，task 工具一般会被设计成含有 prompt, subagent_type, subagent_mode 等参数，比如：

task(
    prompt="分析这个代码仓库的架构并返回总结",
    subagent_type="explorer",
	subagent_mode="sync"
)

prompt 很好理解，也就是启动子智能体后发送的问题；subagent_type 用于指定派生的子智能体的类型，harness 系统代码中需要根据 subagent_type 来赋予派生的智能体不同的权限，比如在 锦恢的 AI Agent 小白教程（四）智能体基本原理：Agent Loop，规划模式与子智能体 中，讲到 Explorer 时，我们就提到了，explorer 这种子智能体只具备读权限，具体实现就是通过 task 的 subagent_type 字段指定 + harness 代码实现实现的；subagent_mode 用于指定当前的子智能体执行是同步的还是异步的。这三个属于一个 task 工具最最基本的参数了，我觉得还是有必要提前和你说一下的。

规划模式我们在第四章也讲了，主要就是 enter_plan 和 exit_plan 这两个工具，并且为了克服目标漂移的问题并允许智能体原地恢复任务执行上下文，我们还引入了 todo_write 这样一个工具。

我们得到了 task, enter_plan, exit_plan, todo_write

拼图三：上下文管理

第四章的学习还引入了 ask_user 这个工具，它的作用是让 Agent 可以主动向用户询问信息，这样设计的目的是防止大模型因为缺失必要的上下文而产生幻觉。避免产生幻觉的核心方法就是引入额外的有效信息，对于人类来说，引入额外信息的手段就三种：问朋友、查本地文档、上网搜索。

问朋友已经通过 ask_user 实现了。

查阅本地文档可以通过 grep（负责从一个文件里搜索指定文本模式的文本片段） 和 glob（负责从文件系统中搜索指定路径模式的文件和文件夹） 实现。这里需要注意，如果是 MacOS 或者 Linux，grep 和 glob 是原本系统就有的工具。但是 Windows 没有，得另外实现。

就剩一个上网搜索了，所以我们还需要增加 web_search 工具用于让 Agent 可以上网查东西，web_fetch 工具用于将搜到的网页转化为利于大模型读懂的文本形式，避免因信息不足而产生幻觉。web_search 也是全部原生工具中，唯一会产生费用的工具，工业级 web_search 工具往往都是要收费的。如果只是自己用，推荐可以试试 duckduckgo 的逆向 API，QPS 很低时没问题。逆向 API 的蓝图 SKILL 在这里：duckduckgo-websearch-api。

我们得到了 ask_user, grep, glob, web_search, web_fetch

拼图四：循环工程

锦恢的 AI Agent 小白教程（五）Loop Engineering 与 goal 的学习让我们了解到了 goal 这个新特性，所以我们还需要提供 get_goal 和 set_goal 这两个工具。不过 goal 相对于其他工具属于非常低频的工具了，可以作为一个可选项出现。

我们得到了 get_goal, set_goal

拼图五：记忆持久化系统

锦恢的 AI Agent 小白教程（六）Agent 项目基建：SKILL.md 和 AGENTS.md 的学习让我们了解到了 SKILL.md 和 AGENTS.md 这两个特性，所以我们不仅需要提供一个 read_skill 工具负责加载指定的 SKILL，我们还需要在 agent 初始化时实现自动的 SKILL 发现与 AGNETS.md 发现功能。需要注意，SKILL 发现与 AGNETS.md 发现功能 会被设计为一次系统事件，它在用户开启一个新的 session 时自动触发，并根据运行结果计算出 system prompt，它并不是一个工具。

我们得到了 read_skill

拼图六：上下文压缩

锦恢的 AI Agent 小白教程（二）关于大模型，小白必须知道的一些通识知识 的学习让我们了解到了大模型的上下文是有限的，锦恢的 AI Agent 小白教程（三）提示词原理及其应用：ChatML、工具调用、提示词注入 又让我们学到了大模型调用和工具调用是如何被编码成具体的token进入上下文的。

但是在 agent loop 中，Agent 实现完成的一条轨迹对应的编码成的token，最终总是会撑破上下文的，为了避免这个问题，我们还需要实现一个上下文压缩的工具 compact，但是需要注意的是，这个工具不应该被 Agent 主动调用，因为我们必须 100% 保证，当上下文即将撑满时，必须采用 compact 进行压缩。因此，在绝大部分 harness 中，compact 会被设计为一次系统事件。每次大模型调用结束后，harness 系统都会检查一次当前上下文的占用情况，当上下文达到 80% 时（举个例子，也可以是75%，但是 80% 用得比较多），自动压缩上下文并替换下一次开始时发送给LLM的轨迹。

在很多的 agent 产品中，compact 也会成为和 create-skill 一样的系统内置 skill 方便用户直接手动触发上下文压缩。比如在 codex 中，输入 /compact 就会主动触发上下文压缩。

最终的胶水——system prompt 的设计

除此之外，我们还需要一套系统提示词作为胶水，黏连起整套系统，让这些架构信息真正流入大模型的上下文。

图片图片

根据上文的内容，我们一共需要准备这几层胶水：

Agent 身份信息：让 Agent 知道自己的身份和基础信息。

基础行为准则：告诉 Agent 你应该做什么，不应该做什么，默认的回答话术和语气等。

操作边界：针对 PTC，根据初始化参数，告诉 Agent 它能访问的系统资源、文件路径、命令行工具有哪些。（比如在 ~/project/pytorch 启动的 Agent 默认就只能访问 ~/project/pytorch 里面工具，如果访问外面的工具则需要调用 ask_user 或别的方法征询用户意见）

Tool Schema：各个工具的描述，参数的数据结构和描述。

SKILL：SKILL 发现结束后，写入的各个 Skill 的名称、描述和加载方式。

AGENTS.md：AGENTS.md 发现结束后，AGENTS.md 的内容。

记忆管理：告诉 Agent，当前管理长期记忆的公共文件夹，局部文件夹在哪里、每次回答用户的问题是否要从中做上下文召回、是什么情况下要更新记忆文件，什么是需要被更新的，哪些信息是禁止被更新的。

通过编程来完成这七层提示词的生成，就可以拼凑出足以驱动整个 Agent 的 system prompt 了。

Agent Harness 最小蓝图

所以，我们得到了实现一个基础 Agent 的 Harness 最小蓝图。

这个 harness 采用 ReAct Agent Loop 作为基础的调度模型。实现原理参考 锦恢的 AI Agent 小白教程（四）智能体基本原理：Agent Loop，规划模式与子智能体。

设计的工具为：

工具必选描述✅将代码或文本完整写入指定文件。✅读取指定文件的内容。✅对现有文件进行局部、精确修改。✅执行 Bash 命令，调用 CLI、运行代码并操作系统环境。✅创建子智能体并委派任务，支持指定任务内容、子智能体类型和同步或异步执行模式。✅进入规划模式，在执行任务前制定计划。✅退出规划模式，开始按照计划执行任务。✅记录并更新任务状态，缓解目标漂移，并帮助 Agent 恢复执行上下文。✅主动向用户询问缺失信息，避免因上下文不足而产生幻觉。✅在文件内容中搜索符合指定文本模式的片段。✅根据路径模式搜索文件和文件夹。✅搜索互联网信息。工业级搜索服务通常会产生调用费用。✅获取指定网页，并将其转换成适合大模型阅读的文本。❌获取当前任务的长期目标。❌设置或修正当前任务的长期目标。✅加载指定的 ，向 Agent 注入相应的知识、流程或操作规范。

系统事件为：

系统事件触发点操作SKILL 自动发现创建新 Session 时搜索当前环境中可用的 ，将 Skill 的名称、描述和加载方式写入系统提示词。AGENTS.md 发现创建新 Session 时搜索项目目录中的 ，读取项目级规则并将其写入系统提示词。上下文压缩上下文占用达到约 80% 时压缩历史对话与执行轨迹，并使用压缩后的上下文替换下一轮发送给大模型的原始轨迹。

系统提示词为：

模块注入 System Prompt 的内容Agent 身份信息Agent 的身份、角色和基础信息基础行为准则应该做什么、不应该做什么，以及默认的回答话术和语气操作边界可访问的系统资源、文件路径和命令行工具；越界访问时需要调用 征求许可Tool Schema各个工具的功能描述、参数数据结构及参数说明SKILLSkill 发现后获得的 Skill 名称、功能描述和加载方式AGENTS.md文件发现后读取的项目级约定、开发规范和操作指令记忆管理公共与局部记忆的位置、上下文召回条件、记忆更新时机，以及允许和禁止写入的信息

如此，我们变得到了一个 Agent Harness，稍加测试与迭代，便可制作出工业级的 Agent。这些「稍加测试与迭代」过于琐碎，便留给大家日后自行注意和总结了，比如 MCP 的 defer loading，比如历史数据的 append only 设计等等，这些都太琐碎了，养成写博客，看优秀工程师的博客在 AI 时代仍然是成长的必由之路。

这里给大家推荐推荐锦恢经常看的一些和 agent harness 相关的前沿技术博客：

Anthropic 工程博客：Anthropic 公司的工程博客，MCP 优化，多智能体架构设计，LLM 全自动评估的大量一线工程师产出的技术博客都在里面，虽然有一些是广告性质的，但是大部分博客都强烈推荐。

OpenAI 研究员翁荔的博客：业内极具名誉的 AI 研究员，在她的个人博客 Lil’Log 中记录了一些很重要的技术脉络，她的文章同时具备学术的严谨和工程的实事求是，她的团队对 Agent 的大量架构技术做过极其早期的探索和验证，她的文章是建立 Agent 前沿认知的重要手段。

OpenAI 开发者博客：OpenAI 面向开发者的技术博客，除了在一些无聊的小广告外，OpenAI 经常会写一些机制和功能的设计原理，为什么这么设计，会引入什么结构风险。比如 goal 的设计原理就在这个开发者博客里面。

师傅领进门，修行靠个人嘛！各位，加油吧。

图片图片

课后作业Q1. PTC 适合所有场景吗？

想要在某个业务场景上使用 PTC 原则设计 Harness，需要满足哪几个基本的条件。

Q2. 多此一举的设计？

为什么要单独设计 write，read，edit 这几个工具，而不让 bash 工具取代它们？

Q3. 参考同行作品

下载 codex，claude code 或者别的 agent 产品或者 agent sdk，查看它们默认的系统事件、工具设计、系统提示词设计分别是什么样子的，和本文列举的这个 demo harness 相比，成熟的 agent 产品的 harness 有何异同？

结语

这一章，我们结合前几章的全部知识，给大家呈现了完整的 Agent Harness 的一个基础架构长什么样子，嗯，如果可以为你增加一点点 Agent 相关的 insight，就再好不过了。

这一章我想也是一个 milestone，它预示着读到这里的朋友们都具备了独立进行 Harness 设计的能力或者大概知道所谓 agent harness 到底在指什么了。

okey dokey，这里是 00 后全栈工程师锦恢，一个正在尝试撰写全网最小白最全面最系统的AI Agent系列教程的学徒。同时我的《AI Infra 软核教程》系列教程已经开始更新了：https://kirigaya.cn/blog/article?seq=384，欢迎想要了解和学习大模型底层技术的相关朋友来阅读讨论。

想要获取一手信息或者不错过我的文章更新，欢迎加入我的社群，进入我的 wx 公众号输入“微信群聊”，即可加入。

图片图片