在 OpenRouter 上构建可靠的工具调用 Agent 循环

工具调用 Agent 循环的核心逻辑并不复杂：初始化任务、工具列表与消息历史后，反复执行「调用模型 → 解析工具请求 → 执行工具 → 追加结果」这一流程。循环在两种情况下终止：模型返回不含工具调用的纯文本答复，或应用层定义的停止条件触发。关键在于，模型只负责决定调用哪个工具及传入什么参数，实际执行函数、解析参数、判断何时停止，全部由应用代码掌控。

在工具定义阶段，开发者需要在 TypeScript 项目中安装 OpenRouter SDK，并通过环境变量注入 API 密钥。工具以 JSON Schema 格式描述函数签名，description 字段应尽量具体，例如明确列出支持的城市名称，帮助模型生成合法参数。模型列表（models 参数）支持有序回退：当首选模型不可用时，SDK 自动切换到列表中的下一个模型，Auto Exacto 机制还会针对工具调用请求默认对提供商重新排序。

单轮请求封装在 sendTurn 函数中完成。SDK 接受驼峰命名字段（如 toolChoice、maxCompletionTokens），内部自动转换为 API 要求的下划线格式。首次迭代将 toolChoice 设为 required，确保示例必然走工具调用路径；后续迭代改为 auto，允许模型在收到工具结果后直接返回文本答复。每次请求都必须携带完整的工具定义，包括工具结果返回后的跟进请求，模型需要这些定义来判断是否还需要调用其他工具。

工具执行层通过 executeToolCall 函数处理单次调用，并将结果封装为 role 为 tool 的消息返回给模型。工具参数以 JSON 字符串形式到达，JSON.parse() 应置于 try 块内；无效 JSON、未知函数名或处理器异常均转换为包含 error 字段的工具结果，而非直接抛出异常中断循环。这种设计让模型有机会感知错误并调整策略，而不是让整个 Agent 崩溃。

主循环需要设置硬性迭代上限。模型可能因调用失败而反复重试，或持续搜索更优答案，若无上限保护，循环将一直运行直到系统其他部分介入。除迭代上限外，还应检测重复调用：若同一工具以相同参数被调用超过阈值次数，应提前终止循环。历史记录长度同样需要管控，过长的上下文会增加延迟与成本，可通过滑动窗口或摘要策略限制传入模型的消息数量。

指南最后指出，这套轻量实现适合在迁移到更高层 Agent SDK 之前使用，也是理解 Agent 控制流底层机制的最佳方式。对于需要接入 MCP 工具的场景，OpenRouter 同样支持在循环中集成 MCP 协议工具，扩展工具生态。开发者掌握这套基础循环后，无论是自行维护还是迁移到框架，都能对系统行为保持清晰的掌控。

要点

• 工具定义必须在每次请求中携带，包括工具结果返回后的后续请求，模型需要它们来决定是否继续调用工具
• 迭代上限与重复调用检测是防止 Agent 无限循环的必要保障，不能依赖模型自行停止
• models 参数支持有序模型回退，Auto Exacto 机制会针对工具调用请求自动优化提供商顺序
• 工具执行层应将所有异常转换为结构化错误结果返回给模型，避免单次工具失败中断整个循环
• 这套无框架依赖的轻量实现有助于开发者深入理解 Agent 控制流，为后续迁移到更高层库打下基础