如何使用Google Gemini在Node.js中构建支持函数调用的AI代理
内容提要
本文介绍如何用Node.js和Gemini API构建AI代理，核心是函数调用循环：模型请求工具、执行并返回结果，直到生成答案。教程涵盖天气、汇率和计算三个免费工具，提供CLI和HTTP接口，并讨论并行执行、错误处理及扩展建议。
延伸解读
理解函数调用循环
文章强调，Gemini 并不会直接执行你的代码，而是返回一个结构化的函数调用请求。真正的循环是：模型请求工具 → 你的代码执行 → 将结果返回给模型 → 模型判断是否继续。这个循环是代理与普通聊天机器人的关键区别，它允许模型根据中间结果进行多步推理，例如先查天气再根据温度决定是否查询汇率。
并行执行与错误处理
当模型在一次响应中请求多个工具时，使用 Promise.allSettled 并行执行所有工具，可以显著减少等待时间。同时，每个工具调用都被单独捕获错误，避免一个失败影响其他调用。此外，设置最大迭代次数（如10次）可以防止模型陷入无限循环，这在工具持续返回错误时尤为重要。
工具描述的重要性
工具描述（description）是模型决定是否调用该工具的关键。模糊的描述可能导致模型在边缘情况下无法正确路由。文章建议在描述中明确说明“何时使用”，例如“当用户询问天气时使用”，这能显著提高路由准确性。调试时，如果模型不调用工具，首先检查描述是否足够具体。
安全与生产注意事项
文章指出，示例中的 calculate 函数通过正则过滤字符来降低注入风险，但并非真正的沙箱。如果通过 HTTP 暴露给匿名用户，应使用 mathjs 等专业解析器。此外，生产环境中应将日志输出到结构化日志系统，而非控制台。这些细节提醒开发者，教程代码用于演示，实际部署需加强安全与可观测性。
Q&A
如何在Node.js中使用Gemini API构建一个支持函数调用的AI代理？
构建过程包括：设置项目并安装依赖（@google/generative-ai、dotenv、express），定义工具模式（JSON schema），实现工具函数（如天气、汇率、计算），然后实现代理循环：发送消息和工具模式给Gemini，如果模型返回函数调用，则执行工具并将结果返回给模型，重复直到模型生成最终答案。
Gemini函数调用中，模型是如何调用工具的？
Gemini并不直接执行你的代码，而是返回一个结构化对象，指示调用哪个函数及参数。你的代码接收该对象，执行实际函数，并将结果发送回模型。模型根据结果决定是否继续调用其他工具或生成最终答案。
在Gemini函数调用中，如果模型同时请求多个工具，应该如何处理？
当模型在同一个响应中请求多个工具时，应该并行执行所有工具，并在一条消息中返回所有结果。如果逐个返回，会破坏模型的轮次跟踪，导致输出不可靠。
构建代理时，如何定义工具模式（tool schema）？
工具模式是JSON schema，包含name、description和parameters。description非常重要，它帮助模型决定何时调用该工具，应包含“当用户询问X时使用”之类的提示。参数定义需使用大写类型字符串，如'OBJECT'、'STRING'、'NUMBER'。
在代理循环中，如何防止无限循环？
设置最大迭代次数（如MAX_ITERATIONS = 10），当循环次数达到上限时强制退出。这可以防止模型因工具持续返回错误而陷入无限重试。
如何将代理集成到HTTP服务器中？
使用Express创建POST /agent端点，接收包含message字段的JSON请求，调用runAgent函数，并返回包含answer字段的JSON响应。启动服务器后，可通过curl发送请求测试。
如果遇到429错误（超出配额），有哪些解决方法？
三种方法：1) 在Google AI Studio创建新项目获取新API key；2) 启用计费以提高限额；3) 等待太平洋时间午夜重置。另外，可以通过设置GEMINI_MODEL环境变量切换到更轻量的模型（如gemini-2.0-flash-lite）来减少配额消耗。
如何扩展代理以支持更多工具？
添加新工具只需在tools.js中定义新的工具模式，在functions.js中实现对应函数，并在agent.js的toolHandlers中注册。代理循环无需修改，即可支持任意数量的工具。
