# AI Agent 问渠 API 智能代理

**Repository Path**: north-dream-testing/Ask-Canal-API-Intelligent-Agent

## Basic Information

- **Project Name**: AI Agent 问渠 API 智能代理
- **Description**: 问渠 API 智能代理（API Agent）是一个基于 MCP（Model Context Protocol）协议的智能 API 网关服务。它将任意 GraphQL 或 REST API 转化为可通过自然语言查询的智能端点，用户无需了解 API 的具体结构，只需用自然语言描述需求，代理即可自动理解 API Schema、生成调用请求、返回结构化结果。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 问渠 API 智能代理

<p align="center">
  <strong>用自然语言查询任意 API</strong>
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#配置说明">配置说明</a> •
  <a href="#界面预览">界面预览</a> •
  <a href="#API 文档">API 文档</a> •
  <a href="#部署指南">部署指南</a>
</p>

---

## 项目简介

**问渠 API 智能代理**（API Agent）是一个基于 MCP（Model Context Protocol）协议的智能 API 网关服务。它将任意 GraphQL 或 REST API 转化为可通过自然语言查询的智能端点，用户无需了解 API 的具体结构，只需用自然语言描述需求，代理即可自动理解 API Schema、生成调用请求、返回结构化结果。

### 核心能力

- 🎯 **自然语言查询** - 用中文或英文提问，自动转换为 API 调用
- 🔌 **多协议支持** - 同时支持 GraphQL 和 REST/OpenAPI 接口
- 🧠 **智能 Schema 理解** - 自动读取并理解 API 结构，生成最优查询
-  **结构化输出** - 支持表格、CSV、JSON 等多种结果格式
-  **Recipe 学习** - 成功查询可保存为可复用工具，提升后续查询效率
- 🔐 **认证透传** - 支持 Bearer Token、API Key 等多种认证方式
- 🐳 **容器化部署** - 开箱即用的 Docker 部署方案

### 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | Python 3.11 + FastMCP |
| LLM 集成 | OpenAI Agents SDK（兼容 DeepSeek） |
| 数据处理 | DuckDB（SQL 后处理） |
| 协议 | MCP JSON-RPC 2.0 over Streamable HTTP |
| 前端 | 原生 HTML/CSS/JavaScript SPA |
| 部署 | Docker + Docker Compose |

---

## 功能特性

### 1. 自然语言 API 查询

用户只需用自然语言描述需求，代理自动完成：
- 解析用户意图
- 理解 API Schema
- 生成最优 API 调用
- 后处理返回结果

**示例：**
```
用户：列出前 5 个角色，包括名字和状态
代理：自动生成 GraphQL 查询 → 调用 API → 返回表格结果
```

### 2. GraphQL 支持

- 自动读取 GraphQL Schema
- 支持复杂查询、嵌套字段
- 智能字段选择和过滤

### 3. REST/OpenAPI 支持

- 自动解析 OpenAPI 3.x 规范
- 支持 GET/POST/PUT/DELETE 等方法
- 路径参数和查询参数自动处理

### 4. Recipe 学习机制

成功的查询模式会被采样保存为可复用的 `r_{slug}` 工具，后续相似查询可直接调用，大幅提升响应速度和准确性。

### 5. 多结果格式

- **文本摘要** - LLM 生成的自然语言回答
- **表格展示** - 结构化数据自动渲染为表格
- **CSV 导出** - 支持 `return_directly` 参数直接返回 CSV
- **调试模式** - 包含完整调用链和 trace_id

### 6. 认证与安全

- 支持 Bearer Token、API Key 等认证头透传
- 可选的 Passthrough Headers 机制
- 不安全路径（POST/PUT/DELETE）白名单控制

---

## 快速开始

### 环境要求

- Docker 20.10+
- Docker Compose v2+
- 有效的 LLM API Key（OpenAI 或 DeepSeek）

### 一键部署

```bash
# 1. 克隆项目
git clone <repository-url>
cd api-agent

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的 API Key

# 3. 启动服务
docker compose up -d

# 4. 访问前端
open http://localhost:8080
```

### 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| API Agent (MCP) | 3000 | MCP 协议端点 |
| Frontend (Web UI) | 8080 | 用户界面 |

### 健康检查

```bash
curl http://localhost:3000/health
# {"status":"ok"}
```

---

## 配置说明

### 环境变量（.env）

```env
# LLM 配置
OPENAI_API_KEY=sk-xxx          # LLM API 密钥
OPENAI_BASE_URL=https://...    # LLM API 地址（可选，用于 DeepSeek 等兼容服务）

# 服务配置
PORT=3000                      # MCP 服务端口
API_AGENT_HOST=0.0.0.0         # 绑定地址
API_AGENT_CORS_ALLOWED_ORIGINS=*  # CORS 允许的来源
```

### TOML 配置（api-agent.toml）

```toml
[model]
api = "chat_completions"       # API 类型：chat_completions 或 responses
name = "deepseek-chat"         # 模型名称
openai_base_url = "https://api.deepseek.com/v1"
reasoning_effort = "low"       # 推理努力程度

[description]
model_name = "deepseek-chat"   # Schema 描述模型
timeout_seconds = 15           # 描述生成超时
```

> **注意**：只有 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`PORT` 可通过环境变量覆盖，其他配置必须通过 TOML 文件设置。

---

## 界面预览

### 整体架构

```
┌─────────────┐     MCP Protocol     ┌──────────────┐     HTTP     ┌─────────────┐
│   前端 UI   │  ─────────────────► │  API Agent   │ ◄──────────► │  Target API │
│  (Port 8080)│   JSON-RPC 2.0       │  (Port 3000) │  GraphQL/REST│  (External) │
└─────────────┘                      └──────────────┘              └─────────────┘
                                            │
                                            ▼
                                     ┌──────────────┐
                                     │   LLM API    │
                                     │ (DeepSeek等) │
                                     └──────────────┘
```

### 功能界面截图

#### 1. 欢迎页面

首次访问时显示的欢迎界面，左侧为 API 配置面板，右侧为对话区域。

![欢迎页面](docs/screenshots/01-welcome-page.png)

**界面元素说明：**
- **服务地址**：MCP 服务endpoint，默认 `http://localhost:3000/mcp`
- **目标 API 地址**：GraphQL 端点或 OpenAPI 规范 URL
- **接口类型**：GraphQL 或 REST/OpenAPI 切换
- **认证请求头**：JSON 格式的认证信息（可选）
- **工具名前缀**：自定义工具名称前缀（可选）

#### 2. API 连接成功

配置目标 API 后，点击回车或切换字段自动触发连接。连接成功后状态栏显示绿色圆点和工具名称。

![连接成功](docs/screenshots/02-connected.png)

**连接流程：**
1. 前端发送 `initialize` 请求到 MCP 服务
2. MCP 服务加载目标 API Schema
3. 动态生成 `{prefix}_query` 工具
4. 前端显示连接状态和可用工具

#### 3. GraphQL 查询结果

输入自然语言问题，代理自动理解 GraphQL Schema 并生成查询，结果以表格形式展示。

![GraphQL 查询结果](docs/screenshots/03-graphql-query-result.png)

**查询示例：**
- "列出前 5 个角色，包括名字和状态"
- "找出所有存活的角色，按名字排序"
- "统计每个状态的角色数量"

#### 4. REST API 查询结果

切换到 REST 模式，输入 OpenAPI 规范 URL，即可对 REST API 进行自然语言查询。

![REST 查询结果](docs/screenshots/04-rest-query-result.png)

**支持特性：**
- 自动解析 OpenAPI 3.x 规范
- 智能选择 HTTP 方法和路径
- 自动处理路径参数和查询参数
- 结果自动格式化为表格或文本

#### 5. 错误处理

当 API 地址无效或连接失败时，界面显示清晰的错误提示。

![错误处理](docs/screenshots/05-error-handling.png)

**错误类型：**
- 网络连接失败
- Schema 加载失败
- 认证失败
- 查询执行错误

#### 6. 认证头配置

支持配置认证请求头，用于访问需要认证的 API。

![认证头配置](docs/screenshots/06-auth-headers.png)

**配置示例：**
```json
{
  "Authorization": "Bearer your-token-here",
  "X-API-Key": "your-api-key"
}
```

---

## API 文档

### MCP 协议端点

**URL**: `POST /mcp`

**协议**: JSON-RPC 2.0 over Streamable HTTP

### 必需请求头

| 请求头 | 说明 | 示例 |
|--------|------|------|
| `X-Target-URL` | 目标 API 地址 | `https://api.example.com/graphql` |
| `X-API-Type` | API 类型 | `graphql` 或 `rest` |

### 可选请求头

| 请求头 | 说明 | 默认值 |
|--------|------|--------|
| `X-Target-Headers` | 发送给目标 API 的认证头 | `{}` |
| `X-Passthrough-Headers` | 从当前请求透传的头名称 | `[]` |
| `X-Allow-Unsafe-Paths` | 允许的不安全路径模式 | `[]` |
| `X-Base-URL` | REST API 基础 URL 覆盖 | - |
| `X-Include-Result` | 是否在输出中包含完整结果 | `false` |
| `X-Poll-Paths` | 需要轮询的路径 | `[]` |
| `X-Recipe-Learn-Rate` | Recipe 采样率 (0-1) | - |
| `X-Debug` | 调试模式，包含调用链 | `false` |
| `X-API-Name` | 自定义工具名前缀 | 自动从 URL 生成 |

### 工具列表

#### `_query` - 自然语言查询

**描述**: 用自然语言提问关于配置 API 的问题

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `question` | string | 是 | 自然语言问题 |
| `return_directly` | boolean | 否 | 直接返回 CSV（默认 false） |

**响应格式**:
```json
{
  "ok": true,
  "data": "自然语言回答",
  "result": [...],
  "queries": [...],
  "error": null
}
```

### 响应结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `ok` | boolean | 请求是否成功 |
| `data` | string | 自然语言回答 |
| `result` | array | 结构化结果数据 |
| `queries` / `api_calls` | array | API 调用记录 |
| `error` | string | 错误信息（失败时） |
| `debug` | object | 调试信息（X-Debug=true 时） |

---

## 部署指南

### Docker Compose 部署（推荐）

```yaml
services:
  api-agent:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      - API_AGENT_HOST=0.0.0.0
      - API_AGENT_PORT=3000
      - API_AGENT_CORS_ALLOWED_ORIGINS=*
    volumes:
      - ./data:/app/data
      - ./api-agent.toml:/app/api-agent.toml:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:3000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

  frontend:
    image: python:3.11-slim
    ports:
      - "8080:8080"
    volumes:
      - ./frontend:/app/frontend:ro
    working_dir: /app/frontend
    command: python server.py 8080
    restart: unless-stopped
    depends_on:
      - api-agent
```

### 生产环境建议

1. **安全配置**
   - 设置具体的 `API_AGENT_CORS_ALLOWED_ORIGINS`，避免使用 `*`
   - 使用 HTTPS 反向代理（Nginx/Caddy）
   - 配置防火墙规则

2. **性能优化**
   - 调整 LLM 超时配置
   - 启用 Recipe 学习提升缓存命中率
   - 配置适当的并发限制

3. **监控告警**
   - 监控 `/health` 端点
   - 记录 API 调用日志
   - 设置 LLM API 用量告警

---

## 开发指南

### 项目结构

```
api-agent/
├── api_agent/              # 核心后端代码
│   ├── agent/             # GraphQL/REST 代理逻辑
│   ├── tools/             # MCP 工具定义
│   ├── recipe/            # Recipe 学习机制
│   ├── utils/             # 工具函数
│   ├── config.py          # 配置管理
│   ├── context.py         # 请求上下文
│   ├── middleware.py       # 中间件
│   └── query_response.py  # 响应封装
├── frontend/              # 前端界面
│   ├── index.html         # 单页应用
│   └── server.py          # 静态文件服务
├── docs/                  # 文档
│   └── screenshots/       # 界面截图
├── tests/                 # 测试用例
├── api-agent.toml         # 应用配置
├── docker-compose.yml     # 容器编排
├── Dockerfile             # 容器镜像
└── pyproject.toml         # Python 项目配置
```

### 本地开发

```bash
# 1. 安装依赖
uv sync

# 2. 配置环境变量
cp .env.example .env

# 3. 启动后端（开发模式）
uv run python -m api_agent

# 4. 启动前端（另一个终端）
cd frontend
python server.py 8080
```

### 运行测试

```bash
uv run pytest tests/ -v
```

---

## 常见问题

### Q: 支持哪些 LLM 服务？

A: 支持所有兼容 OpenAI API 格式的服务，包括：
- OpenAI GPT-4/GPT-3.5
- DeepSeek
- Azure OpenAI
- 其他兼容服务（通过 `OPENAI_BASE_URL` 配置）

### Q: 如何配置 DeepSeek？

A: 修改 `api-agent.toml` 和 `.env`：

```toml
# api-agent.toml
[model]
api = "chat_completions"
name = "deepseek-chat"
openai_base_url = "https://api.deepseek.com/v1"
```

```env
# .env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.deepseek.com/v1
```

### Q: REST API 的 X-Target-URL 应该填什么？

A: 应该填写 OpenAPI 规范 JSON 的 URL，例如：
- `https://petstore3.swagger.io/api/v3/openapi.json`
- `https://api.example.com/openapi.json`

### Q: 如何调试 API 调用？

A: 添加 `X-Debug: true` 请求头，响应中会包含完整的调用链和 trace_id：

```json
{
  "ok": true,
  "data": "...",
  "debug": {
    "queries": [...],
    "trace_id": "abc123"
  }
}
```

### Q: Recipe 学习是什么？

A: Recipe 学习机制会自动采样成功的查询模式，保存为可复用的工具。后续相似查询可直接调用已保存的 Recipe，提升响应速度和准确性。可通过 `X-Recipe-Learn-Rate` 控制采样率。

---

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

<p align="center">
  <strong>问渠那得清如许？为有源头活水来。</strong>
</p>