3步把Text-to-SQL能力嵌入你的业务系统Spring AI Alibaba DataAgent API Key调用完整参考【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgentSpring 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点击生成 Key创建你的第一个 API Key通过开关启用/禁用可一键切断外部调用点击重置轮换密钥、删除吊销密钥、复制/显示查看完整 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?agentIdagentIdquery查询上月销售额TOP10产品nl2sqlOnlytrue \ -H X-API-Key: your_api_key \ -H Accept: text/event-stream常用查询参数参数说明agentId智能体 ID必填也是 API Key 鉴权的依据query自然语言问题必填nl2sqlOnlytrue时只返回 SQL 查询结果不做 Python 深度分析更快适合嵌入式场景conversationId/threadId多轮对话时传入保持上下文humanFeedback/rejectedPlan人工反馈模式干预或否决执行计划该接口已内置 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?conversationIdconversationId第3步把调用封装进你的业务系统接口跑通后剩下的就是工程化。推荐的最小集成模式后端代理业务后端保存 API Key绝不下发前端业务侧只调用你的后端接口由它转发到 DataAgent 的/api/stream/search并透传 SSE 事件会话映射把业务系统的用户/工单映射为 DataAgent 的sessionIdconversationId天然获得多轮追问能力结果分级展示先用nl2sqlOnlytrue快速返回 SQL 结果集用户点击深入分析时再发起完整工作流含 Python 分析与图表报告。常见坑速查 现象排查方向请求返回 401检查X-API-Key请求头、Key 是否被禁用、agentId与 Key 是否匹配流式接口长时间无输出复杂问题会经历多个工作流节点建议前端做加载态确认数据源与模型配置正常多轮追问答非所问确保连续请求传入相同的conversationId/threadId结果里 SQL 正确但数据不对到数据源管理页核对表结构、检查 docs/ADVANCED_FEATURES.md 中的逻辑外键配置 生产环境建议除流式接口内置校验外可在网关或拦截器层对所有/api/**调用补充统一校验参考 docs/ADVANCED_FEATURES.md 的鉴权说明并对 Key 定期轮换。参考资料 官方文档docs/ADVANCED_FEATURES.mdAPI 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考