给 MyCodeAgent 添加新工具必须走完协议到测试五步

给 MyCodeAgent 添加新工具必须依次走完协议、实现、注册、提示词和测试五步。省略提示词更新或注册环节，即使代码写完，agent 也无法调用这个工具。

工具协议定义先于代码实现

在 MyCodeAgent 中，任何新工具的添加都从定义工具协议开始。这一步不是形式主义，而是整个扩展流程的约束起点。协议明确了工具必须具备的字段，包括名称、描述、参数 schema 和返回类型。这些字段直接决定了后续实现阶段的函数签名、注册时的元数据以及提示词中的描述文本。

协议通常采用 JSON Schema 风格或 Python 类型注解与 docstring 结合的形式。它强制要求开发者在写一行代码之前就想清楚这个工具要解决什么问题、接受什么输入、输出什么结果。这种先定义再实现的顺序避免了后期反复修改函数接口导致的连锁 bug。

协议还起到文档和校验的双重作用。agent 的决策模块会读取协议来判断当前任务是否需要调用该工具，如果协议描述模糊，模型就容易忽略或错误调用。信号中明确指出，这套协议是后续所有步骤的依据，省略它会导致整个链路无法对齐。

实际操作时，开发者需要创建一个包含 name、description、parameters 和 return_description 的字典或类。这种结构确保了工具在 agent 内部被统一管理，而不是散落在不同文件中。定义协议的过程本身就是在梳理业务逻辑：这个工具是查询数据库、调用外部 API 还是处理本地文件，都要在这一步说清楚。

这一步花费的时间往往比写代码本身还多，但它直接降低了后面调试成本。许多开发者跳过协议直接写函数，结果发现注册后 agent 完全不认识这个工具，原因就是缺少结构化的描述信息。协议定义先于代码实现，体现了工具扩展的工程化思维，而不是临时拼凑。

实现阶段需同时满足协议与 agent 调用格式

协议定义完成后进入工具函数的具体实现。这里的关键是函数必须同时满足两套要求：一是严格遵循前面定义的协议字段，二是符合 MyCodeAgent 的调用格式。

工具函数通常被包装成一个接收 dict 参数、返回 dict 的形式，而不是普通的 Python 函数直接接受多个参数。这种设计让 agent 可以统一通过 JSON 传递参数，避免了动态参数解析的复杂性。函数内部需要先从输入 dict 中提取参数，进行类型校验，然后执行核心逻辑，最后把结果包装成包含 success、data 或 error 的标准返回结构。

与普通函数的最大区别在于错误处理和日志记录。普通函数出错可以直接抛异常，但在 agent 工具中必须捕获所有异常并以结构化方式返回，这样 agent 才能根据返回内容决定下一步是重试还是切换工具。信号强调，实现阶段要同时满足协议与 agent 调用格式，否则即使函数能独立运行，放到 agent 环境中也会失败。

举例来说，如果要添加一个查询天气的工具，函数需要按照协议规定的参数 schema 接收城市名称，调用外部 API 后返回温度、湿度等字段的结构化数据。任何与协议不符的字段都会被注册环节拒绝。

这一步还涉及异步支持。如果工具需要调用网络服务，开发者必须决定是使用 async 还是 sync 版本，并确保与 agent 的执行器匹配。许多坑点出现在这里：开发者写了漂亮的业务逻辑，却忘记了返回结构的标准化，导致 agent 解析失败。

实现完成后，建议立即写单元测试验证输入输出是否严格符合协议。这能把问题控制在单个工具层面，而不是等到整个 agent 运行时才暴露。

注册机制把新工具暴露给 agent 决策层

工具函数写完后必须显式注册才能被 agent 发现。MyCodeAgent 的注册机制通常是在 agent 初始化或工具管理器中调用一个 register_tool 方法，把工具函数和它的协议元数据一起传入。

注册的代码位置一般放在 agent 的工具列表初始化部分，或者单独的 tools.py 文件末尾统一注册。这一设计让所有可用工具对决策层可见。注册时会把协议中的 name、description 和 parameters 存入一个内部字典或列表，agent 的规划模块每次思考时都会遍历这个列表。

这一步决定 agent 能否发现工具。如果忘记注册，即使协议和实现都完美，agent 的提示词和决策流程中也不会出现这个工具的名字，模型自然不会选择它。信号指出，注册机制是把新工具暴露给 agent 决策层的关键环节。

注册过程还会进行协议校验。如果协议字段缺失或类型错误，注册函数会直接抛出异常，强制开发者修正。这是一种防御性设计，避免了运行时才发现问题。

实际代码中，注册调用类似：agent.register_tool(weather_tool, weather_protocol)。完成注册后，工具就进入了 agent 的工具池，后续的提示词生成和决策都会自动包含它。

许多开发者在这一步踩坑：他们把注册写在了测试脚本里，而不是 agent 的主初始化流程，导致生产环境缺少工具。注册机制看似简单，却是连接实现层和决策层的桥梁。

提示词更新直接影响工具被调用的概率

注册完成后，必须更新 agent 的系统提示词，把新工具的描述写入其中。这一步直接影响工具被大模型调用的概率。

提示词中通常需要为每个工具提供自然语言描述，包括工具名称、用途、参数含义和调用示例。描述粒度非常关键：太粗糙模型不知道什么时候该用，太详细又会占用过多 token 导致上下文超限。信号中特别提到，提示词更新是完整链路中容易被省略却至关重要的一环。

常见遗漏是只更新了工具列表却没有调整示例对话。模型在 few-shot 学习模式下非常依赖示例，如果示例中没有出现类似工具的调用场景，新工具的调用成功率会显著下降。

更新提示词时还需要控制整体长度。开发者常常把所有工具描述堆在一起，导致提示词过长，模型注意力分散。更好的做法是按任务类型分组，只在特定场景加载相关工具的详细描述。

描述的撰写也需要技巧。不能简单复制协议里的 technical description，而要用模型容易理解的业务语言重述，比如“当用户询问某个城市天气时，使用 get_weather 工具，传入 city 参数”。这种调整能明显提高调用准确率。

如果提示词没有更新，即使前面所有步骤都完成，agent 仍然不会主动调用新工具。这一步的缺失是很多扩展失败的隐形原因。

测试环节验证工具调用的完整闭环

最后一步是端到端测试。只有跑通从用户查询到工具调用、再到结果返回的完整闭环，才能确认工具真正可用。

测试方法通常包括两种：一是直接调用 agent 的 chat 方法输入包含工具使用场景的查询，观察是否生成正确的 tool call；二是使用专门的工具测试模式，绕过规划模块直接验证工具执行结果。

典型失败案例有三种：协议不匹配导致解析错误、注册缺失导致工具不可见、提示词描述不清晰导致模型不选择工具。定位问题需要逐步排查：先检查注册列表里是否有该工具，再看提示词中描述是否出现，最后验证函数返回结构是否标准。

信号强调，测试环节要能区分问题是出在协议、注册还是提示词。一种有效方式是打印 agent 每次决策时的 tool pool 内容和最终生成的 prompt，快速定位缺失环节。

测试还应该覆盖错误场景，比如网络失败时工具是否能优雅返回错误信息，agent 是否能根据错误继续执行其他工具。这些测试确保工具在真实复杂环境中稳定。

完整的测试用例通常包含 5-10 种不同查询，覆盖正常路径、边界条件和多工具协作场景。只有全部通过，才能认为新工具添加成功。

主流框架工具扩展路径的共性与差异

MyCodeAgent 的五步链路与主流框架存在明显共性，也有一些差异。对比 LangChain 和 AutoGen 可以看出工具扩展的核心逻辑高度一致。

LangChain 中添加工具同样需要先定义 tool 对象（包含 name、description、func），然后通过 initialize_agent 注册，最后确保 prompt 中包含工具描述。它的 Tool 类本质上就是协议的体现，实现阶段也要求函数返回字符串或结构化输出，与 MyCodeAgent 的返回结构要求类似。

AutoGen 的工具扩展则更侧重于 function calling 能力。开发者需要定义 function schema（类似协议），然后在 assistant agent 的 function_map 中注册实现函数，最后通过 system message 更新提示词。它的流程同样包含定义、实现、注册、提示词几个关键环节，只是名称和实现细节不同。

共性在于：所有框架都强调工具描述必须进入模型上下文，注册必须让决策模块可见，实现必须符合统一的调用协议。这些共性说明 MyCodeAgent 的链路具有通用价值。

差异主要体现在抽象层次。LangChain 提供了更多开箱即用的工具和集成，开发者有时可以跳过部分协议定义；AutoGen 更依赖大模型的原生 function calling，对提示词工程要求更高。MyCodeAgent 的链路相对底层，把每一步都显式拆开，更适合开发者理解底层机制。

对中文开发者落地 AI 应用而言，这套链路提供了清晰的参考路径。很多团队在引入 LangChain 或 LlamaIndex 后遇到工具扩展困难，根本原因就是没有搞清楚背后的协议-注册-提示词逻辑。掌握 MyCodeAgent 的完整流程后，开发者可以更快地在任何框架中添加自定义工具，比如企业内部的知识库查询、特定业务系统的 API 调用等。

这种从零扩展的思路还能帮助团队建立自己的工具库，避免重复造轮子。中文社区中关于 agent 落地的讨论常常停留在模型选择层面，而工具扩展能力才是决定应用能否真正解决业务问题的关键。MyCodeAgent 的案例为开发者提供了一条可复制的路径：先定义清晰协议，再严格实现和注册，精心维护提示词，最后通过系统化测试闭环。

理解这些共性与差异后，开发者可以根据项目复杂度选择合适框架，同时保持对核心扩展逻辑的掌握。这正是这套五步链路最大的参考价值。

参考来源