User Input: pi 帮我改个 bug ↓ cli.ts (Parse CLI args) ↓ main.ts (Create session, select run mode) ↓ AgentSession (Load tools extensions) ↓ Agent (Manage state logic) ↓ agentLoop() (Core execution loop)Agent 出 demo 只要一周上线却要一年Demo选定靠谱的模型 设定系统提示词 配上工具上线会出现各种意想不到的坑70K Star 的开源项目pi-agent以极简著称可以借助其来进行工程化学习如何维护 Agent 的循环如何进行上下文管理如何有效地管理工具调用二、Loop Maintenance2.1 Agent 的本质循环调用模型Agent 的本质是一个不断调用模型的循环用户输入 → 模型决策 ├─ 调用工具 → 执行工具 → 将结果告诉模型 → 回到模型决策 └─ 不调用工具 → 直接返回文本 → 终止循环模型只有两种决定调用工具或不调用工具。不断重复直到模型单纯返回文本循环终止。2.2 Trace TurnTrace从用户输入一个问题到模型最终答复的完整过程Turn在一个 Trace 中每一次模型调用称为一个 Turn每个 Turn 又可拆解为两个环节模型调用环节工具执行环节2.3 pi-agent 的 10 个干预节点设计一个 Trace 从开始到结束有 10 个地方可以干预循环Trace 开始记录开始时间Turn 开始判断当前轮数达到上限如 100 轮则停止防止无线循环模型调用前准备上下文模型调用时实际发起 API 请求模型调用后敏感词检测防止模型输出违规内容工具执行前判断工具是否危险如 delete/drop危险操作直接拦截工具执行时实际执行工具逻辑工具执行后对返回结果做脱敏等后处理Turn 结束记录本轮运行结果Trace 结束记录整体响应耗时支撑后续性能优化这 10 个干预节点的设计极其优雅——大部分 Agent 框架都有这个功能三、Context Engineering3.1 为什么上下文工程是关键Agent 效果取决于两点模型本身的能力每一轮提交给模型的提示词即上下文上下文工程该给的信息要给齐不用给的信息不要给占用上下文会分散模型注意力员工的作用或许是帮领导补充上下文如果领导转发消息时什么都不说全靠员工猜测做错了就说是没悟性——这样的领导大概是不会喜欢 AI 的。AI 没有足够上下文就干不了活而员工会自动帮领导补齐上下文。pi-agent 的上下文处理工具输出截断有些工具输出很长如read读文档、bash执行命令可能一下子撑爆上下文处理方法完整结果保存在本地文件提供给模型的只有**截断后的文本 本地文件路径**由模型自己评估要不要去读完整内容tips按字符截断还是按字节截断保留前面还是保留后面需要根据不同场景具体分析上下文压缩为什么压缩防止超限模型上下文有限Agent 多轮循环中上下文累积很快容易超限报错性能上下文越长模型越笨但历史信息密度越来越低什么时候压缩pi-agent 会设定一个token 阈值结合模型上下文长度与当前上下文长度计算剩余可用量当剩余可用量低于阈值时主动发起压缩tips实际上下文压缩应**提前进行**——在模型完成上一轮任务后就判断是否压缩。如果等到下一轮任务开始时才压缩用户会陷入无聊的等待。压缩成什么样子pi-agent 的建议是按结构化模板压缩以 coding agent 为例1. 用户目标 2. 约束条件 3. 工作流程 4. 关键决策 5. 下一步计划不同场景的模板需要自己思考如 data agent 场景。或者直接给模型一个方向让它自由发挥效果也不错。压缩后怎么用在下一轮对话中将压缩后的结果替代被压缩的那部分上下文完成上下文重组Context Caching合理编排来提升 prompt cache 命中率系统提示词的分区什么信息放前面什么信息放后面尽量避免提示词的**前缀变化**Claude Code 在这一点上做得很好花了很多心思处理。四、Tool Calling Management4.2 基础技巧写清楚工具的 schema—— 降低模型的理解负担选一个靠谱的模型—— 至少具备 function calling 能力的模型经过这两步模型依然传回错误的工具指令就要进入 pi-agent 的工具调用管理流程。4.3 工具调用参数验证调用前安全检查调用时错误处理调用后结果调整参数验证pi-agent 做两种参数验证JSON 格式修复有些模型返回调用指令时会把 JSON 序列化成字符串pi-agent 检测到后会自动转化为正确的 JSON 格式Schema 验证参数要求传数字型却返回文本型时pi-agent 帮忙直接转化原则尽量给模型兜底能解决的问题就都给解决掉。调用前安全检查对应工具执行前干预节点判断是否有危险指令是否访问了不该访问的文件egdata agent 场景中模型想delete甚至drop就把它reject。调用时错误处理原则工具执行失败时把报错信息当成结果返回给模型而不是终止循环。这样 Agent 循环不会被中断模型根据报错信息重新生成准确的调用指令。egdata agent 场景中模型用 SQL 查了不存在的字段把报错信息返回给模型模型会意识到要重新读表结构生成准确的 SQL。实践根据不同工具**预定义可能的错误信息**说明这是什么错误、要怎么处理穷举不了就返回一条通用的报错信息给模型**继续纠错的机会**Agent 才会更稳定和智能调用后结果调整对应工具执行后干预节点对返回的结果进行后处理例data agent 场景中校验返回结果中有无敏感信息必要时脱敏下篇预告参考:https://github.com/earendil-works/pihttps://dg-ai-notes.pages.dev
pi-agent
User Input: pi 帮我改个 bug ↓ cli.ts (Parse CLI args) ↓ main.ts (Create session, select run mode) ↓ AgentSession (Load tools extensions) ↓ Agent (Manage state logic) ↓ agentLoop() (Core execution loop)Agent 出 demo 只要一周上线却要一年Demo选定靠谱的模型 设定系统提示词 配上工具上线会出现各种意想不到的坑70K Star 的开源项目pi-agent以极简著称可以借助其来进行工程化学习如何维护 Agent 的循环如何进行上下文管理如何有效地管理工具调用二、Loop Maintenance2.1 Agent 的本质循环调用模型Agent 的本质是一个不断调用模型的循环用户输入 → 模型决策 ├─ 调用工具 → 执行工具 → 将结果告诉模型 → 回到模型决策 └─ 不调用工具 → 直接返回文本 → 终止循环模型只有两种决定调用工具或不调用工具。不断重复直到模型单纯返回文本循环终止。2.2 Trace TurnTrace从用户输入一个问题到模型最终答复的完整过程Turn在一个 Trace 中每一次模型调用称为一个 Turn每个 Turn 又可拆解为两个环节模型调用环节工具执行环节2.3 pi-agent 的 10 个干预节点设计一个 Trace 从开始到结束有 10 个地方可以干预循环Trace 开始记录开始时间Turn 开始判断当前轮数达到上限如 100 轮则停止防止无线循环模型调用前准备上下文模型调用时实际发起 API 请求模型调用后敏感词检测防止模型输出违规内容工具执行前判断工具是否危险如 delete/drop危险操作直接拦截工具执行时实际执行工具逻辑工具执行后对返回结果做脱敏等后处理Turn 结束记录本轮运行结果Trace 结束记录整体响应耗时支撑后续性能优化这 10 个干预节点的设计极其优雅——大部分 Agent 框架都有这个功能三、Context Engineering3.1 为什么上下文工程是关键Agent 效果取决于两点模型本身的能力每一轮提交给模型的提示词即上下文上下文工程该给的信息要给齐不用给的信息不要给占用上下文会分散模型注意力员工的作用或许是帮领导补充上下文如果领导转发消息时什么都不说全靠员工猜测做错了就说是没悟性——这样的领导大概是不会喜欢 AI 的。AI 没有足够上下文就干不了活而员工会自动帮领导补齐上下文。pi-agent 的上下文处理工具输出截断有些工具输出很长如read读文档、bash执行命令可能一下子撑爆上下文处理方法完整结果保存在本地文件提供给模型的只有**截断后的文本 本地文件路径**由模型自己评估要不要去读完整内容tips按字符截断还是按字节截断保留前面还是保留后面需要根据不同场景具体分析上下文压缩为什么压缩防止超限模型上下文有限Agent 多轮循环中上下文累积很快容易超限报错性能上下文越长模型越笨但历史信息密度越来越低什么时候压缩pi-agent 会设定一个token 阈值结合模型上下文长度与当前上下文长度计算剩余可用量当剩余可用量低于阈值时主动发起压缩tips实际上下文压缩应**提前进行**——在模型完成上一轮任务后就判断是否压缩。如果等到下一轮任务开始时才压缩用户会陷入无聊的等待。压缩成什么样子pi-agent 的建议是按结构化模板压缩以 coding agent 为例1. 用户目标 2. 约束条件 3. 工作流程 4. 关键决策 5. 下一步计划不同场景的模板需要自己思考如 data agent 场景。或者直接给模型一个方向让它自由发挥效果也不错。压缩后怎么用在下一轮对话中将压缩后的结果替代被压缩的那部分上下文完成上下文重组Context Caching合理编排来提升 prompt cache 命中率系统提示词的分区什么信息放前面什么信息放后面尽量避免提示词的**前缀变化**Claude Code 在这一点上做得很好花了很多心思处理。四、Tool Calling Management4.2 基础技巧写清楚工具的 schema—— 降低模型的理解负担选一个靠谱的模型—— 至少具备 function calling 能力的模型经过这两步模型依然传回错误的工具指令就要进入 pi-agent 的工具调用管理流程。4.3 工具调用参数验证调用前安全检查调用时错误处理调用后结果调整参数验证pi-agent 做两种参数验证JSON 格式修复有些模型返回调用指令时会把 JSON 序列化成字符串pi-agent 检测到后会自动转化为正确的 JSON 格式Schema 验证参数要求传数字型却返回文本型时pi-agent 帮忙直接转化原则尽量给模型兜底能解决的问题就都给解决掉。调用前安全检查对应工具执行前干预节点判断是否有危险指令是否访问了不该访问的文件egdata agent 场景中模型想delete甚至drop就把它reject。调用时错误处理原则工具执行失败时把报错信息当成结果返回给模型而不是终止循环。这样 Agent 循环不会被中断模型根据报错信息重新生成准确的调用指令。egdata agent 场景中模型用 SQL 查了不存在的字段把报错信息返回给模型模型会意识到要重新读表结构生成准确的 SQL。实践根据不同工具**预定义可能的错误信息**说明这是什么错误、要怎么处理穷举不了就返回一条通用的报错信息给模型**继续纠错的机会**Agent 才会更稳定和智能调用后结果调整对应工具执行后干预节点对返回的结果进行后处理例data agent 场景中校验返回结果中有无敏感信息必要时脱敏下篇预告参考:https://github.com/earendil-works/pihttps://dg-ai-notes.pages.dev
