企业官网建设流程全解析

3步把Text-to-SQL能力嵌入你的业务系统：Spring AI Alibaba DataAgent API Key调用完整参考

【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgent

Spring AI Alibaba DataAgent是基于 Spring AI Alibaba 构建的企业级智能数据分析师，核心能力包括Text-to-SQL（自然语言转 SQL）、Python 深度分析与智能报告生成。本文以DataAgent API Key为主线，用 3 步带你完成从生成 API Key到业务系统调用 Text-to-SQL 接口的完整接入，适合想在自己的产品里嵌入智能问数能力的新手开发者。

DataAgent 的 Text-to-SQL 能力长什么样？

DataAgent 基于 StateGraph 工作流编排了从意图识别 → 语义增强 → Schema 召回 → SQL 生成 → SQL 执行 → 报告生成的完整链路，支持多表查询、多轮对话，并通过 RAG 检索增强业务术语与表结构，显著提升 SQL 生成准确率。

对业务系统而言，你不需要关心这些内部细节：只需拿到一个API Key，调用几个 HTTP 接口，就能把"一句话查数"的能力搬进自己的后台、客服机器人或 BI 系统。

第1步：为智能体生成并管理 API Key

🔑 API Key 按智能体维度管理，一个 Key 对应一个已配置好数据源与知识的智能体。

操作路径：登录 DataAgent 前端 → 进入目标智能体详情页 → 左侧菜单点击"访问 API"：

1. 点击生成 Key创建你的第一个 API Key；
2. 通过开关启用/禁用，可一键切断外部调用；
3. 点击重置轮换密钥、删除吊销密钥、复制/显示查看完整 Key。

对应的后端能力由 AgentController.java 提供，涵盖完整的 Key 生命周期接口（api-key/generate、api-key/reset、api-key/delete、api-key/enable）。

两个值得了解的安全设计：

• Key 不落明文：服务端通过 ApiKeyCredentialService.java 对 Key 加密存储，页面上默认只展示掩码****abcd；
• 鉴权入口统一：请求头X-API-Key的解析逻辑见 AgentApiKeyServerAuthenticationConverter.java，同时也兼容Authorization: Bearer <key>形式。

⚠️ 建议：为每个接入方（不同业务系统）生成独立智能体与独立 Key，便于单独禁用与审计。

第2步：用 X-API-Key 调用数据问答接口

拿到 Key 后，核心调用分为三类：创建会话、发送消息、流式查询。

2.1 创建会话 & 发送消息

会话管理接口定义在 ChatController.java：

# 为指定智能体创建会话 curl -X POST "http://127.0.0.1:3000/api/agent/<agentId>/sessions" \ -H "Content-Type: application/json" \ -H "X-API-Key: <your_api_key>" \ -d '{"title":"demo"}' # 向会话中发送消息（用于记录对话、驱动多轮上下文） curl -X POST "http://127.0.0.1:3000/api/sessions/<sessionId>/messages" \ -H "Content-Type: application/json" \ -H "X-API-Key: <your_api_key>" \ -d '{"role":"user","content":"查询上月销售额TOP10产品","messageType":"text"}'

2.2 流式执行 Text-to-SQL 查询（核心）

真正触发 Text-to-SQL 工作流的是 SSE 流式接口 GraphController.java，它会按节点实时推送"计划 → SQL → 执行结果 → 报告"各阶段事件：

curl -N "http://127.0.0.1:3000/api/stream/search?agentId=<agentId>&query=查询上月销售额TOP10产品&nl2sqlOnly=true" \ -H "X-API-Key: <your_api_key>" \ -H "Accept: text/event-stream"

常用查询参数：

该接口已内置 API Key 校验：缺少X-API-Key或 Key 与agentId不匹配时直接返回401，规则见 WebFluxSecurityConfiguration.java。

2.3 查看与中止执行

执行过程与结果在问答页完整呈现——左侧是会话列表，底部可切换"仅NL2SQL、展示SQL结果"等模式：

SqlExecuteNode节点执行完毕后，会流式推送生成的 SQL 与结果集，可直接透传给你的前端渲染表格：

如果用户中途想取消长任务，调用中止接口即可：

curl -X POST "http://127.0.0.1:3000/api/stream/stop?conversationId=<conversationId>"

第3步：把调用封装进你的业务系统

接口跑通后，剩下的就是工程化。推荐的最小集成模式：

1. 后端代理：业务后端保存 API Key（绝不下发前端），业务侧只调用你的后端接口，由它转发到 DataAgent 的/api/stream/search并透传 SSE 事件；
2. 会话映射：把业务系统的"用户/工单"映射为 DataAgent 的sessionId+conversationId，天然获得多轮追问能力；
3. 结果分级展示：先用nl2sqlOnly=true快速返回 SQL 结果集；用户点击"深入分析"时再发起完整工作流（含 Python 分析与图表报告）。

常见坑速查 🛠

📌 生产环境建议：除流式接口内置校验外，可在网关或拦截器层对所有/api/**调用补充统一校验（参考 docs/ADVANCED_FEATURES.md 的鉴权说明），并对 Key 定期轮换。

参考资料

• 📖 官方文档：docs/ADVANCED_FEATURES.md（API Key 调用、MCP 服务器、逻辑外键）
• 📖 快速上手：docs/QUICK_START.md
• 🏗️ 架构设计：docs/ARCHITECTURE.md
• 💻 智能体管理源码：AgentController.java
• 💻 会话与消息源码：ChatController.java
• 💻 流式 Text-to-SQL 源码：GraphController.java
• 💻 鉴权配置源码：WebFluxSecurityConfiguration.java

【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgent