构建智能API助手：从黑客松到测试版

一种LangGraph助手，可解释API、编写代码并执行只读查询：具备两种模式、自我修复的OData循环、工件内存、LLM评分机制以及自助访问功能。

发布者：REACTAPP.TOP加入本站 2026年10月23日阅读约 8 分钟1818 词

来源: From hackathon spark to production reality: building an agentic API assistant

一家为支付公司提供车队管理API的团队，将黑客松上的原型开发成了嵌入其开发者门户的测试版助手。其理念是：不再让集成商阅读参考文档并将其转化为代码，而是让对话式助手负责处理集成工作。本文将介绍这类助手的构建方式、它刻意避免的功能，以及质量评估标准。

该助手能够解释接口端点，用开发者使用的任何语言编写代码，规划多步骤工作流程，并对实时系统执行只读数据查询。它取代了那些仅指向页面的语言特定静态文档和搜索索引。

为何静态文档已不够用

车队与移动性管理软件需要处理海量数据：驾驶员活动记录、加油站信息、卡片交易数据以及车辆遥测数据。任何想要集成该系统的团队都必须学习复杂的REST接口、过滤语法、领域专用术语以及一系列相互关联的调用流程。这些繁琐的环节使得合作伙伴难以随平台一同发展。

开发人员依靠现成的文档工具来查看接口定义，同时使用测试工具手动进行调用测试。团队还保存着一些“标准操作流程”，即固定的调用序列，用以演示如何完成诸如创建账户、接纳驾驶员以及绑定卡片等多步骤任务。虽然这些方法有效，但仍然存在三个明显缺陷：

局限于特定编程语言。 若要用cURL、Python、.NET、Java和Go等不同语言展示每种工作流程，就需要编写人员和工程师持续投入大量手工工作。
边缘易碎。无法记录每种工作流的每一种可能情况，因此这些方案常常无法覆盖合作伙伴的具体场景。
持续的维护成本。一旦API架构发生变化，相关页面就会失效，这不仅会延长上手时间，还会增加支持团队的工作量。

从黑客松创意到两种模式

这个概念验证源于2025年12月的一次内部黑客松，核心问题只有一个：既然模型可以直接理解开发者的意图，为何还要让他们将文档转换为代码？最终诞生的产品更像是随时可用的集成顾问，而非简单的搜索框。

为确保运行安全，该设计将助手分为两条独立的处理路径。

顾问模式可处理单次操作的解释、文档深入分析以及任何框架的代码生成，包括POST、PUT和DELETE等修改型请求。它会生成代码但不会实际运行，因此当数据发生变化时仍需人工干预。

规划与执行模式能够处理复杂的多步骤读取请求，并通过只读的模型上下文协议（MCP）工具在真实平台上执行这些请求。

合作伙伴实际看到的内容

若向顾问模式请求用于创建驱动程序的Python代码片段，它会返回一个包含正确端点、请求头、请求体结构以及所需权限说明的requests调用代码。整个过程不会触及生产环境中的API。

请求“计划与执行”模式为名字为John的五名驾驶员进行处理，规划器会将多过滤器查询简化为单一任务：按名字筛选驾驶员。执行器会选择对应的MCP工具，构建OData参数（$filter=first_name eq 'John'、$top=5），执行只读GET请求，然后将完整响应存入工件存储库。模型仅能看到简化的摘要信息，如工件编号、数量5以及简短预览内容。随后，合成器会生成一份格式规范的五名匹配驾驶员的列表。

架构：协作代理的循环

该助手基于LangGraph构建，采用循环状态机设计。规划器、执行器、验证器以及合成器轮流负责规划、执行操作和检查各步骤，不断传递共享状态和内存信息，直至任务完成。其中有四项设计选择尤为突出。

1. 为安全考虑而设计的只读代理

安全性从一开始就决定了设计思路。该助手无法在其自身的运行时环境中执行会改变数据的操作。当用户说“为驾驶员X创建一张新卡片”时，路由器会将请求发送到顾问节点，该节点会返回结构化的代码片段，供开发者复制、审查并在本地运行。真正会被执行的操作仅限于GET请求。MCP服务器代码中虽存在具备写入功能的工具，但在模型看到它们之前就会被过滤掉。

2. 类监督器的协调机制

推理与执行位于不同的层级，由一个单一的监督器进行协调，它负责决定在一个全局循环中下一个该由哪个专用模块处理：

模式路由器负责对意图进行分类，并将相应消息发送给顾问模块或计划与执行模块。
规划者会将复杂的请求拆解为与目标参数相关的任务清单。
执行者为每项任务选择相应的MCP工具，整理参数（包括OData过滤器），并通过工具层反复处理，直到任务完成或重试次数用尽。
综合器会将所有任务的输出结果，无论是实时数据还是备用代码片段，整合为最终答案。

3. 用于修复自身OData问题的循环

当模型遇到像OData这样的结构化过滤语言时，很容易自行生成查询选项或破坏语法结构。团队选择OData是因为它能够在无需手动编写所有组合的情况下，对复杂的移动性对象进行灵活的部分匹配查询，但这种灵活性也会带来错误，因此加入了多层修复循环。

如果预检解析器检测到语法问题，或者实时调用返回 API 错误，系统会捕获该事件，增加对应任务的重试计数器，并将具体的错误信息反馈给模型上下文。执行器会读取自身的失败信息并生成修正后的调用请求。当重试次数用尽后，任务会切换回建议模式，以确保用户仍能获得有用的结果。

4. 内存划分为独立资源

将大量 JSON 数据，比如数千条资产记录，放入对话中会耗尽令牌预算，降低推理精度并增加成本。因此，原始响应会存储在独立的后端资源库中，模型仅能看到指向这些资源编号的简短摘要元数据。后续问题可通过在应用层查询这些编号来定位具体内容，从而保持模型上下文的简洁与聚焦。

质量评估

若要修改提示词或模型且不导致性能下降，就需要自动化基准测试。该团队的流程会利用大型语言模型作为评判标准，针对每次修改回答一个问题：其表现比之前更好还是更差？

该数据集是由人工构建的测试用例集合，涵盖代码生成、事实知识、推理能力及安全性四个类别。每个测试用例都配有明确的评分标准而不仅仅是问题，因此评分者会根据答案的内容进行评估，而非仅比对预设的固定字符串。评分模型始终与被测试模型不同，评分采用10分（正确）、5分（部分正确）和0分（错误）的三分制。每次测试都会在历史文件中新增一行记录，其中包含git提交信息、被测试模型、评分模型、OpenAPI哈希值、数据集哈希值以及提示词版本，从而让任何评分结果都能追溯到其背后的具体代码、规范和提示词。

据团队介绍，该助手在多次测试中的平均得分约为9.4分（满分10分），这一数值在功能更新前可作为性能基准。不过，准确性并非唯一的评估标准——每次测试还会记录延迟时间以确保响应速度，以及令牌使用量，后者直接反映模型消耗情况。任何可能恶化上述任一指标的改动都将在发布前被标记出来。

保障预算与资源容量

由于该助手需要持续访问生产环境中的API，因此必须设置限制来保护模型预算及上游服务。目前采取了三层防护机制：

用户配额限制。演示账户每天可发送10条消息，这样有兴趣的合作伙伴可以先进行试用，避免无限制地消耗模型资源；当他们需要正式使用时，再转为合作伙伴账户。
可追溯且范围明确的调用。合作伙伴的流量使用其自身的凭证进行传输，因此每次调用都会计入其配额，并显示在其自身的审计记录中。助手从不伪装成共享服务账户，这正是实现使用情况追溯和滥用检测的基础。
能识别故障的重试机制。当请求失败时，包括出现临时性限流响应时，修复循环会将错误信息传回模型，同时增加重试次数，直至达到预设的最大值。若重试次数用尽，则会切换到顾问模式。

简化访问流程

构建助手只是其中一半的工作，安全且便捷的访问方式同样重要。

该平台的 API 传统上使用标准的客户端凭证，这意味着需要为每位新客户手动配置。对于面向外部合作伙伴的助手而言，“提交请求并等待工程团队审批”的方式是不可接受的。要求开发人员在聊天中粘贴令牌同样不可行，因为这会导致无法区分助手发起的调用与手动发起的调用，进而使使用情况归因和安全监控变得复杂。团队需要一种能够同时服务于两类用户的策略：一类是希望获得无障碍测试环境的合作伙伴，另一类则是希望直接使用实时数据且无需手动处理配置请求的用户。

解决方案是在常规开发者登录界面之外采用两级自助服务模式。

演示模式为默认模式。新用户无需任何配置、等待或提交请求，即可立即通过合成数据与助手进行交互。
合作伙伴模式会在开发者需要实时集成时启用。认证信息来自与开发者自身账户及权限相关的一次性自助授权流程。连接之后，每个请求都会绑定到该身份，并可完整追溯来源，从而明确是哪一方通过哪条路径发起请求。

这解决了主要的入门障碍。从“只是好奇”到“开始集成”的过程不再需要经过工程团队排队处理。

未来发展方向

该项目最初是作为内部实验启动的，现已发展为可缩短企业开发者团队集成时间的测试版本。它在开发者门户中运行，目前已吸引了首批合作伙伴加入。

该架构工具能够解析标准的 OpenAPI 模式，因此其设计具备横向扩展能力。目前的研发工作主要集中在移动业务领域的深度验证上，但路由核心则被刻意设计为通用型。未来的发展计划包括将相同的对话层应用到企业支付和福利平台等其他业务部门，增加更完善的确定性 OData 验证机制，以便在查询离开助手之前拦截更多无效请求；同时还会探索在写操作中加入人工确认环节，从而使助手最终也能安全地协助处理工作流变更。