codi-api-agent

技能简介

codi-api-agent 是一款只读的、自然语言驱动的 API 代理智能体。用户加载任意 API 规范文档（原生支持 OpenAPI/Swagger 和 GraphQL，支持自动转换 Postman Collection / RAML / API Blueprint，甚至可直接读取文字版 API 参考文档），然后用自然语言提问，智能体便会自动路由到相关接口、执行调用（严格只读），最终返回带有引用的结构化答案，以及多维度的可信度评估（grounding、sufficiency、responsiveness）。

核心能力

• 多格式规范支持：原生解析 OpenAPI/Swagger 和 GraphQL，自动转换 Postman Collection / RAML / API Blueprint
• 纯只读执行：严格限制为 GET 类操作，任何写入操作均被拦截，不会对目标系统产生副作用
• 引用标注：返回结果中每个数据点均标注来源接口和字段，便于核查和溯源
• 多信号评估：输出结果附带 grounding（引用充分性）、sufficiency（答案完整性）、responsiveness（响应性）三个维度的评估分数
• 流式输出：支持 Streamlit UI 实时展示推理步骤、流式返回答案，以及 token 和费用追踪
• 任意 LLM 提供者：对接任意 Chat Completions 兼容端点（本地部署或云端均可），模型配置与代码解耦
• 速率限制容错：支持多 Key 轮换和多后端池化，遇到 429 自动退避重试

安装配置

前置条件：

• Python 3.10+
• pip（包管理器）
• Chat Completions 兼容的 LLM API Key（如 OpenAI、Azure OpenAI、本地 Ollama 等）

安装步骤：

1. 创建虚拟环境并激活：python -m venv .venv && source .venv/bin/activate
2. 安装全功能包（含 UI 和 embeddings）：pip install "codi-api-agent[all]"
3. 配置环境变量：

   export LLM_BASE_URL=https://your-provider.example/v1
   export LLM_API_KEY=your-api-key

4. 启动 UI：api-agent（默认在 http://localhost:8501 打开）

高级配置（可选）：

• 设置 GENERATOR_MODEL / JUDGE_MODEL 指定不同用途的模型
• 设置 LLM_API_KEYS=key1,key2,… 实现多 Key 轮换
• 设置 LLM_POOL 配置多后端池化
• 设置 MAX_RESPONSE_TOKENS 控制每次响应的最大 token 数

使用步骤

1. 启动工具：运行 api-agent，在浏览器打开 http://localhost:8501
2. 加载 API 规范：在侧边栏输入 API 规范（URL、文件上传或直接粘贴），支持 OpenAPI/GraphQL/Postman 等格式
3. 自然语言提问：在主界面用自然语言描述你想查询的内容（如「获取最近一周华东地区销售订单数量」）
4. 查看推理过程：Streamlit UI 实时展示智能体的路由决策、调用的接口列表和中间推理结果
5. 获取带引用的答案：答案以结构化格式呈现，每个数据点均标注来自哪个接口和字段
6. 评估可信度：查看三个评估维度的分数，判断答案的可靠程度

适用场景

• API 探索与调试：无需阅读完整 API 文档，直接提问了解某个 API 的能力和返回格式
• 数据查询报表：用自然语言从多个 API 聚合数据，生成结构化报表（如「对比本月与上月各地区转化率」）
• 系统集成验证：验证目标 API 的实际行为是否符合规范文档描述
• 快速 POC 构建：在确定 API 接口可用性后再编写正式集成代码
• API 文档缺失场景：直接对着已运行的 API 实例进行自然语言查询，无需依赖文档
• 非技术团队数据访问：让产品、运营人员通过自然语言查询技术数据，无需写 SQL 或调用 API

适用人群

• 需要频繁与各类 API 打交道的后端和全栈工程师
• 希望快速探索陌生 API 的技术调研人员
• 产品经理和运营人员（数据查询场景）
• API 集成开发者（快速验证接口可用性）
• 测试工程师（API 行为验证和对比）

工作原理

codi-api-agent 的工作流分为以下几个阶段：

1. 规范解析：将输入的 API 规范（OpenAPI/GraphQL/Postman 等）解析为统一的操作目录（Catalog of Operations）
2. 意图路由：用户问题经过 LLM 推理，判断需要调用哪些具体接口（可能涉及多个接口的联合查询）
3. 只读执行：严格遵循只读约束调用目标接口，获取原始响应
4. 合成与引用：将多个接口返回的数据合成为统一答案，每个数据点标注来源接口和字段
5. 自审：生成答案后，LLM 再次审查答案是否忠实反映了接口返回内容（Faithfulness Check）
6. 评估：输出 grounding、sufficiency、responsiveness 三个评估信号，供用户判断可信度

官方链接

• PyPI：https://pypi.org/project/codi-api-agent/
• 教程文档：https://pypi.org/project/codi-api-agent/#tab-true
• 快速入门：https://github.com/（项目地址，需进一步获取）