我将pi-agent源码写成了一本书… Agent出demo只要一周，上线却要一年？ 差距就在这三个坑里。 这次我拿斩获70K Star的开源项目 pi-agent 当样本，拆解它怎么解决上线难题： 循环维护：一个trace有10个干预节点，无限循环、敏感词、危险工具全在这里拦 上下文工程：工具输出截断 + 阈值压缩，该给的给齐，不该给的别添乱 工具调用管理：参数验证、安全检查、错误回灌，让Agent自己纠错而不是崩掉 不堆技术细节，只讲框架。源码是TS的，我顺手做了Python版，配套还有一本书，在线版/PDF/Markdown都有，能直接扔进Claude Code边问边学。

Agent开发有个共识，出Demo只要一星期，但是上线要一年，为什么呢？出Demo很快，是因为只要选定靠谱的模型，设定了合适的系统提示词，再配上一些工具，那么在给定的测试场景下，这个Agent就能跑起来了。但是真的上线之后，脱离了测试场景，各种你想到或想不到的坑就都来了。有什么坑？要怎么解决呢？通常来说，这些坑我们可以走一步看一步慢慢解决，但是更好的建议是摸着别人的项目过河。那么这个已经斩获了70k Star的开源项目PeaAgent，就是一个不错的过河项目。它以极简著称，任何它看得上的功能，那自然是极其重要的，非常适合我们循序渐进地学习。 今天我们将聚焦三个问题，来看一下PeaAgent是怎么解决的。这三个问题是：如何维护Agent的循环，如何进行上下文管理，如何有效地进行工具调用。内容不少，但是全程通俗易懂，我会只说框架，技术细节我另外放在文档里。 先说第一个，我们之前说Agent的本质是一个不断调用模型的循环。根据用户输入的提示词，模型只会有两种决定：第一个是调用工具，第二个是不调用工具。如果是调用工具，那就执行工具，并将工具的执行结果告诉模型，由模型做下一步决定，不断地重复这个过程，直到模型最终不再调用工具，单纯返回纯文本，我们就认为可以终止循环了。 那么你可能有疑问，难道所有的Agent都只能这么循环吗？那还有什么好开发的？当然不是，这里面可以操作的空间多了去了。我们细拆一下这个流程，首先有两个概念你要了解，分别叫Trace和Turn。从你输入一个问题到模型最终给出答复，这叫一个Trace。在一个Trace中，模型会被不断地调用，每一次模型调用都称为一个Turn。注意，Turn是以模型调用为分界点的，如果在某次模型调用中需要调用工具，那么这次工具和上一次模型调用属于同一个Turn。那么在这种情况下，我们又可以把Turn拆解为两个环节，分别是模型调用环节和工具执行环节。 那么重点来了，在PeaAgent的设计中，一个Trace从开始到结束，总共有十个地方你可以对这个循环进行干预，分别是在Trace开始与结束的时候，每个Turn开始与结束的时候，以及模型调用前、调用时、调用后，工具执行前、执行时和执行后。简单来说，你可以在这十个环节插入代码，做任何你想做的事情。我举几个常见的例子，比如在Trace开始、结束的时候可以记录时间，那么就可以得到一次的响应时长，后续你可以拿来优化。再比如每个Turn开始的时候，就判断当前是在第几个Turn，如果达到了100轮以上，那就可以停下来，防止模型被无限调用。再比如在输出Message的时候，可以进行敏感词检测，防止模型说了不该说的。像那个豆包，有次我跟它边开车边聊，聊得意的时候，经常聊到一半，它动不动就说我们换个话题吧，也不知道触发了它什么机制。再比如工具调用前，要判断当前执行的工具是不是有害的，比如Data Agent场景中，万一模型想要DELETE甚至DROP，那就可以把它摁住。 总而言之，你能想到的需求，大部分可以通过在Agent循环的这十个节点进行相应的改造，实现相关的功能。这个就是你自己的Hooks，其实大部分Agent框架都有这个功能，只不过PeaAgent设计得很优雅，让你可以通过很简洁的代码来实现。这个我们后续在介绍以PeaAgent为基座进行二次开发的时候，会详细说明。 我们谈下一个话题，上下文工程。AI领域的名词很多，造概念的不少，但是上下文工程的确是我比较喜欢的一个，因为它一定程度上揭示了Agent是否有效的关键。你想，既然Agent的本质是循环调用模型，那么关键点就两个：第一个是模型本身的能力，另外一个就是在每一轮模型调用中，你提交给模型的提示词，这个就是上下文。上下文的核心可以归纳为两点：第一是该给的信息要给，第二是不用给的信息不要给。所谓该给的信息要给，是指针对给定的任务，任何完成这个任务所需的信息都要尽可能提供，不要跟模型打信息差。不用给的信息不给，是担心占用模型的上下文，分散模型的注意力。那具体什么信息要给，什么信息不要给，这就取决于你的判断力了。从这个角度讲，很多领导的上下文工程其实都不咋样，动不动给你转发一个消息，其余什么都不说，全靠你猜，做错了就全怪你没有悟性，所以领导是不会喜欢AI的，AI哪有牛马好用，AI没有足够的上下文就干不了活，而牛马会自动帮领导补齐上下文。 回归正题，我们继续说PeaAgent在上下文工程上做了哪些处理。我们简单说两点：第一点是对工具输出内容进行截断。有些工具的输出很长，如果不加以限制，可能一下子就把上下文撑爆了。比如说Read工具，读某个文档，或者某些Bash工具，返回一个命令的结果可能都会很长。这种情况下，我们会对返回的结果进行截断，完整的结果保存在本地文件，提供给模型的信息是截断后的文本和本地文件的路径，由模型自己评估要不要去读完整内容。这个方法看起来简单，但其实细节很多，比如说按字符截断，还是按字节截断，保留前面的，还是保留后面的，这些都是要根据不同的场景去具体分析的。这些细节我也整理成了文档，后面大家可以看一下。 第二点，非常常见，就是上下文压缩，这个几乎是开发Agent肯定要考虑的问题了。针对这个问题，我们就聚焦三点：分别是什么时候进行上下文压缩，压缩成什么样，以及压缩完了之后怎么用。首先为什么要对上下文进行压缩呢？有两点原因：第一点是模型的上下文有限，但是Agent在多轮循环过程中，它不断调用工具，上下文累积得非常快，很容易超过模型的上下文长度，当超过的时候就会报错。第二点是出于性能的考虑，随着上下文越来越长，模型会越来越笨，但是历史上下文中的有效信息其实是越来越少的，这时候我们也会考虑提前压缩。 那什么时候进行上下文压缩呢？通常会设定一个Token阈值，结合模型的上下文长度和当前上下文的长度，判断当前剩余Token的可用量，当剩余Token可用量低于某个阈值时，就主动发起压缩，防止模型报错。这里也给个建议，为了提升用户体验，上下文压缩可以提前进行，比如在模型完成上一轮任务之后，就判断是否要压缩。如果你是在下一轮任务开始时才开始压缩上下文，那么就会让用户陷入无聊的等待，体验就不好。 那要压缩成什么样子？压缩成什么样子其实没有确定的答案，PeaAgent给的建议是按照结构化的模板来压缩，比如说按照用户目标、约束条件、工作流程、关键决策、下一步计划来压缩历史上下文。但这个是Coding Agent的场景，具体到你自己的场景，比如说Data Agent场景，这个模板长什么样，还得你自己去思考。但说实话，有些时候我也懒得去想，