AGENTS.md：Agent上下文策略层的设计与落地实践

1. 从一份被忽视的配置文件说起第一次在开源项目里看到AGENTS.md这个文件时我下意识把它归类成了 README 的变体——无非是告诉别人“这个仓库里有哪些 Agent、怎么跑起来”。直到有次接手一个多 Agent 协作的项目README 写得天花乱坠实际跑起来却处处踩坑Agent A 的输出格式和 Agent B 的输入对不上工具调用的边界模糊上下文窗口被无关信息塞满导致推理质量断崖式下跌。翻遍文档才发现真正约束这些行为的规则全藏在AGENTS.md里而它被作者随手丢在根目录连个链接都没给。这件事让我重新审视这个文件。AGENTS.md不是文档它是Agent 的上下文策略层——一个介于“系统提示词”和“运行时配置”之间的契约文件。它决定了 Agent 在什么场景下看到什么信息、以什么优先级处理、在上下文超限时丢弃什么、在跨 Agent 协作时如何对齐语义。换句话说它管的是 Agent 的“注意力分配”而不是“能力本身”。如果你正在做 Agent 开发不管是单 Agent 的工具调用还是多 Agent 的编排协作AGENTS.md都值得你花时间设计。它解决的核心问题是当上下文窗口成为稀缺资源时如何让 Agent 在正确的时间看到正确的信息。这篇文章我会从设计思路、核心细节、实操落地、问题排查四个层面把我在实际项目中积累的经验完整拆开适合刚接触 Agent 开发的入门者也适合正在被上下文爆炸困扰的进阶开发者。2. 内容整体设计与思路拆解2.1 为什么需要独立的上下文策略层很多人写 Agent 的习惯是把所有指令塞进一个巨大的系统提示词里角色设定、工具说明、输出格式、边界条件、示例对话全部堆在一起。刚开始跑 demo 没问题一旦 Agent 需要处理多轮复杂任务问题就暴露了。我做过一个实测一个包含 12 个工具的客服 Agent系统提示词写到 3800 token 时工具选择的准确率还在 92% 左右当提示词膨胀到 6500 token准确率掉到 78%超过 8000 token 后Agent 开始频繁“忘记”某些工具的存在甚至把不同工具的用途混淆。这不是模型能力问题是注意力被稀释了。AGENTS.md的思路是把上下文拆成分层加载的结构。基础层是永远在场的核心指令角色、安全边界、输出格式策略层是按需加载的场景规则当前任务类型对应的工具集、示例、约束动态层是运行时注入的临时信息用户历史、中间结果、外部数据。这种分层不是简单的文件拆分而是配合Progressive disclosure渐进式披露的加载机制——Agent 在每一步只看到当前决策所需的最小上下文集。提示分层的关键不是“分几个文件”而是“什么信息在什么时机进入上下文”。我见过把提示词拆成五个文件但全部一次性加载的做法那只是把一个大提示词切成了五段没有解决注意力稀释问题。2.2 方案选型的几个关键取舍设计AGENTS.md时有几个绕不开的取舍点我结合自己的踩坑经历逐个说。第一个取舍静态声明还是动态生成。静态AGENTS.md就是一个 Markdown 文件手写规则版本控制可读性强。动态生成则是根据运行时状态当前任务类型、历史对话、工具可用性实时拼装上下文。我的建议是混合核心策略静态写死保证稳定性和可审计性场景规则动态注入保证灵活性。纯静态的缺点是应对不了复杂多变的业务场景纯动态的缺点是调试困难、行为不可预测。第二个取舍规则用自然语言还是结构化格式。自然语言对模型友好但精确性差YAML/JSON 精确但模型理解成本高。我试过纯 YAML 定义工具边界结果模型经常忽略嵌套层级里的约束。后来改成“自然语言描述 关键参数用代码块标注”的混合方式效果明显更好。比如工具调用规则用自然语言写清楚“什么时候用、什么时候不用”但参数格式和取值范围用代码块给出精确示例。第三个取舍单文件还是多文件。单文件AGENTS.md适合中小项目维护简单。多文件如AGENTS.mdagents/目录下的场景文件适合大型项目但需要设计好加载顺序和优先级。我的经验是Agent 数量少于 5 个、场景少于 10 种时单文件足够超过这个规模拆成“主策略文件 场景策略文件”的结构主文件定义全局规则和加载逻辑场景文件定义具体任务的上下文策略。2.3 与常见 Agent 框架的配合方式AGENTS.md本身是一个约定不是某个框架的专属功能。它和主流 Agent 框架的配合方式决定了它的实用性。在基于 ReAct 模式的框架里AGENTS.md的内容通常在每轮推理前注入系统提示词。这时候要注意不要把整个文件塞进去而是根据当前步骤选择性地注入相关段落。比如当前步骤是“选择工具”就注入工具选择规则和当前可用工具列表当前步骤是“生成最终回答”就注入输出格式规则和用户偏好。在多 Agent 编排场景里AGENTS.md还承担了跨 Agent 语义对齐的职责。每个 Agent 有自己的AGENTS.md但共享一份“协作协议”段落定义消息格式、交接条件、冲突解决规则。我做过一个三 Agent 协作的内容审核系统审核 Agent、改写 Agent、终审 Agent 各自有独立的策略文件但共享的协作协议确保了改写 Agent 的输出格式始终符合终审 Agent 的输入要求省掉了大量格式转换的胶水代码。3. 核心细节解析与实操要点3.1 文件结构的最小可用模板一个能跑起来的AGENTS.md不需要很复杂但几个核心段落不能少。下面是我在实际项目中反复打磨后的最小模板你可以直接拿去改。# AGENTS.md ## 全局策略 - 角色定义你是一个专注于 XXX 领域的助手 - 安全边界不处理 XXX 类请求遇到时返回标准拒绝话术 - 输出格式默认使用 Markdown代码块标注语言 ## 工具策略 ### 工具选择优先级 1. 优先使用专用工具避免用通用工具模拟 2. 当多个工具都能完成时选择参数最少的那个 3. 工具调用失败后最多重试 2 次然后降级处理 ### 工具边界 - 工具 A仅用于 XXX 场景输入必须包含 XXX 字段 - 工具 B有速率限制连续调用间隔不低于 1 秒 ## 上下文管理 - 保留最近 10 轮对话原文 - 超过 10 轮的历史压缩为摘要保留关键实体和决策 - 工具返回结果超过 2000 token 时只保留前 500 token 和结论部分 ## 场景规则 ### 场景一XXX - 加载工具集A, B, C - 注入示例见 examples/scenario1.md - 特殊约束XXX ### 场景二XXX - 加载工具集D, E - 注入示例见 examples/scenario2.md这个模板的关键在于场景规则段落。它定义了不同任务类型下加载哪些工具、注入哪些示例、有什么特殊约束。Agent 运行时根据当前任务类型匹配场景只加载对应段落而不是把整个文件塞进上下文。3.2 上下文预算的分配方法上下文窗口是有限资源AGENTS.md的核心职责之一就是定义预算分配规则。我的做法是把窗口分成几个固定比例的区域根据任务类型动态调整。区域默认占比说明系统指令15%角色、安全边界、输出格式永远在场工具定义20%当前场景可用工具的描述和参数对话历史30%最近 N 轮原文 更早历史的摘要检索增强20%从知识库或外部数据源检索的内容输出预留15%留给模型生成回答的空间这个比例不是死的。做工具调用密集的任务时工具定义区域可以提到 30%对话历史压到 20%做长文档问答时检索增强区域可以提到 40%工具定义压到 10%。关键是在AGENTS.md里写清楚调整规则让 Agent 根据任务类型自动切换预算分配。注意输出预留区域绝对不能省。我踩过一次坑把窗口塞到 98% 利用率结果模型生成回答时频繁截断用户体验极差。后来强制预留 15%再也没出现过截断问题。3.3 Progressive disclosure 的具体实现Progressive disclosure 是AGENTS.md最核心的机制但很多人理解成了“按需加载文件”。真正的渐进式披露包含三个层次。第一层文件级披露。主AGENTS.md只包含全局策略和场景索引具体场景规则放在agents/scenario-*.md里。Agent 启动时只加载主文件根据任务类型按需加载场景文件。这层解决的是“不相关场景的规则不进入上下文”。第二层段落级披露。场景文件内部也分段比如“工具选择规则”“输出格式”“示例”分开。Agent 在推理的不同步骤加载不同段落。选择工具时只加载工具规则生成回答时只加载输出格式和示例。这层解决的是“同一场景内不同步骤的上下文隔离”。第三层字段级披露。对于工具定义这种结构化内容只加载当前可能用到的工具而不是场景内所有工具。比如场景定义了 8 个工具但根据当前对话状态只有 3 个是候选就只加载这 3 个的完整定义其余 5 个只保留名称和一句话描述。这层解决的是“工具定义占用过多上下文”的问题。实现这三层披露需要一个上下文路由器——一个轻量的决策模块根据当前任务类型、对话状态、上一步结果决定加载哪些文件、哪些段落、哪些字段。这个路由器可以用规则引擎实现也可以用一个小模型做分类。我的经验是规则引擎足够应对大多数场景只有在场景边界模糊、规则难以穷举时才需要模型介入。3.4 跨 Agent 协作的语义对齐多 Agent 系统里AGENTS.md还承担了“接口契约”的角色。每个 Agent 的输出格式、消息结构、交接条件都需要在各自的策略文件里声明同时共享一份协作协议。我做过一个内容生产流水线包含选题 Agent、写作 Agent、审核 Agent。三个 Agent 的AGENTS.md里都有一段共享的协作协议## 协作协议 - 消息格式JSON必须包含 agent_id, task_id, status, payload 字段 - 交接条件当前 Agent 的 status 为 completed 时触发下一 Agent - 冲突解决审核 Agent 的 rejected 状态优先于写作 Agent 的 completed - 超时处理任一 Agent 超过 30 秒未响应由编排器重新分配任务这段协议确保了三个 Agent 之间的消息格式一致、状态流转清晰、冲突有明确的解决规则。没有这段协议时我遇到过写作 Agent 输出纯文本、审核 Agent 期望 JSON 导致解析失败的问题也遇到过两个 Agent 同时认为任务归自己处理导致重复执行的问题。加上协作协议后这类问题基本消失。4. 实操过程与核心环节实现4.1 从零搭建一个带上下文策略的 Agent下面我以一个“技术文档问答 Agent”为例完整走一遍搭建过程。这个 Agent 需要处理三类任务概念解释、代码示例生成、故障排查。每类任务需要的工具和上下文不同。第一步定义全局策略。创建AGENTS.md写入角色定义、安全边界、输出格式。这部分永远在场不随任务类型变化。# AGENTS.md ## 全局策略 - 角色你是一个技术文档助手专注于解释技术概念、生成代码示例、排查常见故障 - 安全边界不提供涉及敏感信息的操作指导遇到时返回“该问题超出我的处理范围” - 输出格式默认 Markdown代码块必须标注语言概念解释先给一句话定义再展开 - 语言风格简洁直接避免冗余修饰技术术语首次出现时附英文原文第二步定义场景索引和加载规则。在主文件里声明有哪些场景以及如何根据用户输入匹配场景。## 场景索引 - 概念解释用户询问“XXX 是什么”“XXX 的原理”时触发 - 代码示例用户询问“怎么写”“给个例子”“如何实现”时触发 - 故障排查用户描述错误信息、异常行为时触发 ## 加载规则 - 匹配到场景后加载对应的 agents/scenario-*.md - 未匹配到场景时默认加载概念解释场景 - 场景切换时保留最近 3 轮对话其余历史压缩为摘要第三步编写场景文件。每个场景文件定义该场景下的工具集、示例、特殊约束。以故障排查场景为例# 故障排查场景 ## 工具集 - 日志检索工具根据关键词搜索日志返回匹配行 - 配置检查工具读取指定配置文件返回内容 - 版本查询工具查询组件版本信息 ## 排查流程 1. 先让用户提供完整错误信息和复现步骤 2. 用日志检索工具搜索错误关键词 3. 根据日志结果判断是配置问题还是代码问题 4. 配置问题用配置检查工具验证代码问题给出修改建议 ## 输出格式 - 先给出可能的原因列表按可能性排序 - 每个原因附上验证方法和解决步骤 - 最后给出预防建议 ## 示例 用户我的服务启动时报 “connection refused” 助手可能原因如下...第四步实现上下文路由器。这是一个轻量模块根据用户输入匹配场景加载对应文件组装上下文。用 Python 写一个最小实现import re SCENARIO_PATTERNS { concept: [r是什么, r原理, r解释], code: [r怎么写, r例子, r实现], troubleshoot: [r报错, r异常, r失败, rrefused, rtimeout] } def route_scenario(user_input): for scenario, patterns in SCENARIO_PATTERNS.items(): for pattern in patterns: if re.search(pattern, user_input): return scenario return concept # 默认场景 def load_context(scenario, history): base read_file(AGENTS.md) scenario_content read_file(fagents/scenario-{scenario}.md) recent_history history[-3:] summary summarize(history[:-3]) if len(history) 3 else return assemble(base, scenario_content, summary, recent_history)这个路由器很粗糙但核心逻辑清晰匹配场景、加载对应文件、组装上下文。实际项目中可以把正则匹配换成更精细的分类器把summarize换成模型摘要但整体架构不变。4.2 上下文预算的动态调整上面的例子没有涉及预算调整。实际运行时不同场景的上下文消耗差异很大。故障排查场景需要加载日志内容检索增强区域占用高概念解释场景几乎不需要外部数据检索区域可以压缩。我在AGENTS.md里加了一段预算调整规则## 预算调整 - 故障排查场景检索增强 35%工具定义 25%对话历史 20%系统指令 10%输出预留 10% - 代码示例场景工具定义 30%检索增强 25%对话历史 20%系统指令 15%输出预留 10% - 概念解释场景对话历史 40%系统指令 20%检索增强 15%工具定义 10%输出预留 15%这些比例是拍脑袋定的吗不是。我根据实际运行数据调的。故障排查场景里日志内容往往很长检索区域不够会导致关键信息被截断代码示例场景里工具定义代码模板、API 签名占用大需要更多空间概念解释场景主要靠模型自身知识对话历史占比高一些有助于保持上下文连贯。调整这些比例时我建议先跑一批测试用例记录每个场景的实际 token 消耗分布再根据分布调整。不要凭感觉定比例数据比直觉可靠。4.3 上下文压缩的具体策略对话历史超过预算时需要压缩。压缩策略直接写在AGENTS.md里让 Agent 知道什么该保留、什么该丢弃。我的压缩策略分三级第一级实体保留。对话中出现的专有名词、代码标识符、文件路径、错误码全部保留原文不压缩。这些是后续推理的关键锚点丢了会导致上下文断裂。第二级决策保留。已经做出的决策比如“确定用方案 A”“排除了原因 B”保留结论和一句话理由丢弃讨论过程。第三级寒暄丢弃。问候、确认、感谢类的内容直接丢弃不进入摘要。实现上我用一个简单的规则 模型摘要的混合方案先用规则提取实体和决策关键词再用模型对剩余内容做摘要最后把实体列表、决策列表、摘要拼接成压缩后的历史。提示压缩后的历史要标注“以下为历史摘要”让模型知道这不是原文。我试过不标注模型有时会把摘要里的推测当成事实导致错误传播。5. 常见问题与排查技巧实录5.1 Agent 忽略 AGENTS.md 里的规则怎么办这是最常见的问题。你写了详细的规则Agent 该用工具 A 的时候用了工具 B该输出 JSON 的时候输出了纯文本。排查思路如下。先确认规则是否真的进入了上下文。很多时候问题出在加载环节规则文件根本没被读取或者读取了但被后续内容挤出了窗口。打印实际发送给模型的完整提示词检查规则段落是否存在、是否完整。再确认规则的表述是否足够明确。“优先使用工具 A”这种表述太模糊模型可能理解为“可以用工具 A也可以用别的”。改成“当用户请求涉及 XXX 时必须使用工具 A不得使用其他工具”。用“必须”“不得”“仅当”这类强约束词比“优先”“建议”有效得多。最后确认规则的位置。模型对上下文开头和结尾的内容注意力更高。把最重要的规则放在系统提示词的开头或结尾不要埋在中间。我习惯把安全边界和输出格式放在最前面工具选择规则放在最后面中间放场景规则和示例。如果以上都确认了还是不行可能是规则之间冲突了。比如全局策略说“输出 Markdown”场景规则说“输出纯文本”模型会随机选一个。检查所有规则确保没有相互矛盾的条目。5.2 上下文超限导致回答质量下降上下文超限的表现很隐蔽Agent 不是报错而是回答变得笼统、遗漏细节、重复之前的内容。排查方法是记录每轮对话的实际 token 消耗看是否接近窗口上限。如果确实超限按以下优先级处理检查检索增强区域是否有冗余内容。很多时候检索返回了 10 条结果实际只有 2 条相关其余 8 条白白占用空间。在AGENTS.md里加一条规则“检索结果按相关度排序只保留前 3 条其余丢弃。”检查工具定义是否加载了未使用的工具。按场景加载工具集不要一次性加载所有工具。检查对话历史压缩是否生效。如果压缩策略没触发历史会无限增长。在AGENTS.md里明确触发条件“对话超过 10 轮时自动压缩前 N-3 轮。”如果以上都做了还是超限考虑换更大窗口的模型或者把部分处理逻辑拆到独立的 Agent 里。5.3 多 Agent 协作时的消息格式错乱多 Agent 系统里消息格式错乱是高频问题。Agent A 输出 JSONAgent B 期望 YAMLAgent A 的status字段是doneAgent B 期望completed。这类问题的根源是接口契约没有统一管理。我的做法是在项目根目录放一个protocol.md所有 Agent 的AGENTS.md都引用它。protocol.md定义消息格式、状态枚举、字段含义、交接条件。每个 Agent 启动时先加载protocol.md再加载自己的策略文件。这样格式定义只有一处改一处全生效。如果已经出现了格式错乱排查步骤是先抓取两个 Agent 之间的实际消息对比发送方输出和接收方期望的格式差异然后检查双方的AGENTS.md是否引用了同一份协议最后检查协议版本是否一致有时候一个 Agent 更新了协议但另一个没更新导致不兼容。5.4 常见问题速查表问题现象可能原因排查方法解决措施Agent 忽略规则规则未加载/表述模糊/位置靠后打印完整提示词检查强化表述、调整位置、消除冲突回答质量下降上下文超限记录 token 消耗压缩历史、精简检索、按需加载工具消息格式错乱接口契约不统一对比发送方和接收方格式统一协议文件、版本对齐工具选择错误工具定义过多/边界模糊检查工具描述和场景匹配按场景加载工具、明确使用条件场景切换后行为异常历史未压缩/场景规则冲突检查切换时的上下文组装压缩历史、确保场景规则互斥输出截断输出预留不足检查窗口利用率强制预留 15% 输出空间5.5 几个我踩过的坑坑一把AGENTS.md当成一次性文档。项目初期写了一份之后再也不更新。结果业务变了、工具加了、场景多了策略文件还是老样子Agent 行为越来越离谱。后来我强制自己每次加工具或改流程时同步更新AGENTS.md把它当成代码一样维护。坑二规则写得太细模型记不住。有一次写了 40 多条工具选择规则结果模型只记住了前 10 条。后来精简到 12 条核心规则其余用场景文件按需加载效果反而更好。规则不是越多越好关键是每条都进入模型的“有效注意力范围”。坑三忽略示例的作用。纯规则描述对模型来说很抽象加上一两个具体示例效果立竿见影。比如“输出 JSON 格式”不如“输出 JSON 格式例如{status: ok, data: {...}}”。示例是规则的最佳注释。坑四没有版本控制。AGENTS.md改了之后没记录出问题回滚不了。后来把它纳入 Git 管理每次修改写清楚改了什么、为什么改排查问题时可以对比历史版本。6. 进阶把上下文策略做成可观测的系统做到这一步AGENTS.md已经能解决大部分上下文管理问题。但如果你的 Agent 系统要上生产环境还需要可观测性——你得知道每次请求实际加载了哪些上下文、消耗了多少 token、哪些规则被触发了、哪些被忽略了。我的做法是在上下文路由器里加埋点。每次组装上下文时记录以下信息加载了哪些文件、每个文件贡献了多少 token、场景匹配结果、预算分配比例、压缩是否触发。这些数据写入日志配合可视化面板可以快速定位上下文相关问题。比如有一次线上反馈 Agent 回答变慢查日志发现故障排查场景的检索区域频繁触顶导致每次都要压缩历史压缩又调用了模型摘要增加了延迟。定位到问题后把检索结果从 10 条减到 3 条延迟立刻降下来了。没有埋点的话这种问题很难发现。另一个进阶方向是自适应策略。根据历史运行数据自动调整预算分配比例和加载规则。比如某个场景的检索结果经常被模型忽略就自动降低该场景的检索预算某个工具经常被误用就自动加强该工具的使用条件描述。这需要一套反馈闭环实现复杂度较高但效果显著。我个人在实际操作中的体会是AGENTS.md的价值不在于文件本身而在于它强迫你显式地思考上下文策略。以前这些决策散落在代码各处改一处忘一处现在集中在一个文件里改起来有据可依排查问题也有迹可循。如果你正在做 Agent 开发不妨从今天开始给你的项目加一个AGENTS.md哪怕一开始只有十几行也比没有强。