摘要
1) 一句话总结
Agoda 开源了一款名为 API Agent 的零代码系统，通过动态架构自省与 DuckDB 数据过滤，使单个 MCP 服务器能够安全、高效地对接并查询任意内部 REST 或 GraphQL API。
2) 核心要点
- 零代码与低运维：无需为每个内部工具单独编写 MCP 服务器，只需在客户端配置目标 URL 与 API 类型即可完成接入。
- 共享部署架构：一次部署即可同时服务多个 API，新增 API 仅需更新配置，各 API 共享同一个实例。
- 动态架构自省：系统能自动检索 API 架构，支持解析 GraphQL（提取类型、字段和参数）与 REST API（基于 OpenAPI 规范或 JSON 响应示例），无需预建适配器。
- 现代技术栈：核心组件采用 FastMCP（MCP 服务器）、OpenAI Agents SDK（模型编排）以及 DuckDB（内存 SQL 后处理）。
- 突破上下文限制：利用 DuckDB 作为上下文管理层，在进程内对庞大的 API 响应进行 SQL 过滤与聚合，仅将精简结果发送给大模型。
- 默认安全机制：系统默认以只读模式运行，任何修改操作均需明确启用并加入内部工具白名单。
- 性能与查询优化：支持将重复查询参数化为“Recipe”以降低延迟，提供跳过大模型摘要的直接返回选项，并支持单会话跨端点关联查询。
- 全面的可观测性：集成了 OpenTelemetry、Jaeger、Zipkin、Grafana Tempo 及 Arize Phoenix 等监控与追踪工具。
3) 风险与不足（原文提及）
- 上下文截断风险：API 响应往往包含数千行数据，极易超出大语言模型（LLM）的上下文长度限制导致截断（系统通过引入 DuckDB 过滤来解决此痛点）。
- 任意代码执行风险：在处理数据转换时存在安全隐患（系统通过采用基于 SQL 的声明式后处理规避了此风险及相关的沙箱/网络隔离问题）。
- SQL 特性与错误处理：在实际运维中，需妥善处理 SQL 特性相关问题，并在响应截断或报错时向 LLM 暴露完整的错误信息，以便其进行自我修正。
正文
Agoda 工程师近期开发并开源了一款名为 API Agent 的系统。这是一个零代码、零部署的解决方案，能够让单个模型上下文协议（MCP）服务器直接对接内部的 REST 或 GraphQL API。该系统的核心目的在于降低管理多种架构和认证方式的 API 所带来的运维成本，使得团队无需为每个 API 单独搭建 MCP 服务器，AI 助手就能轻松查询相关服务。
Agoda 首席技术官 Idan Zalzberg 对此表示：“许多团队希望将内部工具开放给 AI 使用，但为每个工具单独编写 MCP 工作量极大。API Agent 采用创新的零代码方案实现这一能力，据我们所知，这一方案在业内属于首创。”
通用架构与动态自省
API Agent 可作为通用的 MCP 服务器使用。工程师只需在 MCP 客户端中配置目标 URL 与 API 类型，智能体便能自动对 API 架构进行自省，并根据自然语言输入生成查询。
- 一次部署，多 API 共享：一次部署即可同时服务多个 API。虽然每个 API 在客户端看来都是独立的 MCP 服务器，但实际上它们共享同一个实例。新增 API 仅需更新配置即可完成接入。
- 架构内省模块：配置目标 API 后，智能体会动态检索 API 架构。对于 GraphQL，它会提取类型、字段和输入参数；对于 REST API，它会基于 OpenAPI 规范或 JSON 响应示例进行解析。这使得智能体无需预先构建适配器，即可自动构造查询。
技术栈与核心功能
API Agent 整合了多项现代技术栈以保障其高效运行：
- 核心组件：使用 FastMCP 作为 MCP 服务器，OpenAI Agents SDK 用于语言模型编排，以及 DuckDB 用于内存 SQL 后处理。
- 扩展功能：支持动态工具命名、大型 API 的 Schema 搜索，以及多步骤查询的会话跟踪。
- 可观测性：集成了 OpenTelemetry、Jaeger、Zipkin、Grafana Tempo 以及 Arize Phoenix 等工具，实现全面的系统监控与追踪。
引入 DuckDB 突破上下文限制
在实际应用中，API 的响应往往包含数千行数据，极易超出大语言模型（LLM）的上下文长度限制，导致内容被截断。
为了解决这一痛点，API Agent 引入了 DuckDB，将其作为基于 SQL 的上下文管理层。完整的 API 响应会被存储在 DuckDB 中进行过滤与聚合，最终只将精简后的结果发送给大模型。
DuckDB 可以在进程内运行，原生支持 JSON 并能自动推断 Schema。通过使用 SQL 进行后处理，系统既避免了任意代码执行的安全风险，又能保持与 LLM 查询生成的良好兼容性。此外，基于 SQL 的后处理规避了沙箱、网络隔离和依赖问题，其声明式风格与大模型适配性极佳，实现了安全的 AI 辅助数据转换。
安全机制与运维经验
- 默认安全模式：API Agent 默认以只读模式运行。除非明确启用并加入内部工具白名单，否则系统不允许执行任何修改操作。
- 性能与查询优化：系统支持将重复查询作为参数化的“Recipe（配方）”，从而缩短推理耗时与延迟；同时提供直接返回选项，让过滤后的数据跳过大模型摘要步骤。此外，API Agent 还支持在单个会话中跨多个端点进行查询，完成复杂的数据关联与聚合操作。
- 最佳实践：Agoda 团队在实际运维中总结出多条经验，包括：在响应被截断时向 LLM 提供清晰提示；优先使用 Schema 而非样本数据；妥善处理 SQL 特性相关问题；以及向 LLM 暴露完整的错误信息，以便其进行自我修正。
目前，该项目已正式开源（项目地址为 api-agent），开发者可将其用于 REST 和 GraphQL 相关的 AI 实验与集成。