pi-mono 学习 07｜主 Agent 与 Tools：一套可迁移的设计方法

这篇写什么

把两份偏方法论的笔记（主 Agent 设计、Tools 设计）合并成一篇：给出一套可迁移、可施工的 agent 产品设计方法，不依赖编程场景。

主 Agent：先设计任务闭环，不要先写 prompt

主 agent 不是“一个大 prompt”，而是：任务边界、角色定义、行为规则与闭环运行方式的组合。

一个可用的主 agent，首先要回答：

• 核心目标是什么
• 完成标准是什么
• 默认怎么推进
• 何时继续、何时停止
• 遇到失败怎么处理

提示词只是这些设计的表达载体，不是起点。

主 Agent 的设计骨架（建议写清楚）

• 目标定义
• 输入定义（用户通常怎么提任务）
• 输出定义（你最终返回什么形态）
• 完成条件与停止条件
• 默认策略（模糊时问还是猜、失败时重试还是反馈）
• 边界与禁区

Tools：从任务闭环反推，不要从已有 API 正推

Tools 的本质是：模型可以请求执行的外部动作单元。

一个好的 tools 体系要做到：

1. 覆盖任务闭环中的关键动作
2. 以统一 schema 暴露给 agent
3. 让 runtime 能稳定调用、回灌、继续推进

Tool 设计的常见原则

• 工具表达动作，而不是泄漏内部系统结构
• 粒度适中：既不万能也不碎
• schema 骨架统一（名称/描述/参数），业务语义可自由
• 参数要“模型友好”（少、清晰、必填明确）
• 返回结果要有清晰语义（成功/失败/关键信息），避免噪音转储
• 错误要正式建模（是否可重试、失败原因）
• 写操作要强调幂等或可预测性，明确副作用
• 安全边界尽量设计进工具本身，而不是只靠 prompt

两者的边界

• tools 决定“能做什么动作”
• 主 agent 决定“什么时候做这个动作更合适、如何把动作串成闭环”
• runtime 决定“如何让动作与模型形成可控循环（执行、回灌、继续/停止）”

小结

如果你把 agent 当产品做，主 agent 与 tools 的设计不是写 prompt 的副产物，而是先有闭环、再有动作、再有约束，最后才编译成 prompt + schema + runtime 策略。