本项目是一个基于开源项目的学习型教程：在参考 spring-ai-alibaba/DataAgent 的基础上，结合个人理解进行拆解、复现与讲解。
目标是帮助开发者从 0 到 1 系统掌握 StateGraph 图编排、双重 RAG 检索、自我纠错、HITL 人机协同 等 Text2SQL Agent 关键能力。

项目仓库 · 参考项目

起凡 API 中转：Codex / Claude

提供 Codex 与 Claude API 中转服务，兼容 OpenAI 协议，可直接集成到项目中使用。注册即赠送 25 刀额度。

立即注册

• 项目介绍图
• 核心亮点
• 技术栈
• 系统架构
• 执行链路
• 效果预览
• 快速启动
• 教程导航

点击查看原图

这个教程不是“只看概念”的介绍，而是围绕一个可运行项目，带你把 Text2SQL Agent 的关键能力拆开学透：

• 🧩 从流程到代码的完整映射：用 StateGraph 把问题理解、知识召回、规划、执行、纠错、报告串成清晰链路，知道每一步该放什么能力。
• 📚 结构化 + 非结构化的双通道检索：同时利用关系图谱信息与业务知识库，理解 Text2SQL 在真实业务里如何减少歧义和幻觉。
• 🛠️ 可落地的执行与纠错机制：掌握 SQL 生成与执行、错误回溯修复、Python Docker 沙盒分析的协作方式，而不是停留在“生成 SQL”这一步。
• 🤝 面向生产的交互设计：通过 HITL 人工确认、A2A 协议、SSE 流式反馈，学习高风险场景下可控、可观测的人机协同模式。
• 📖 可复现的学习路径：基于开源项目进行拆解与复现，提供从骨架搭建到核心编排的章节化路线，适合边读边跑、逐步进阶。

• 后端：Kotlin + Spring Boot 3.x + Jimmer
• AI 与编排：Spring AI Alibaba Graph + Spring AI
• 向量与存储：PostgreSQL + pgvector
• 前端：Vue 3 + TypeScript + Vite + A2UI

点击查看原图

[用户自然语言提问]
   └── A2A 协议流式请求
        └── 路由意图识别
             ├── 知识召回（向量化业务词汇 + QA）
             ├── 关系图谱召回
             ├── 可行性评估与任务拆解（Planner）
             ├── 人工确认拦截（HITL）
             ├── SQL 生成与执行 + 自动纠错循环
             ├── Python Docker 沙盒执行与分析
             └── 报告整理（Report Generation）
                  └── 前端流式打字机效果呈现（A2UI）

点击查看原图（完整长图）

• 基础环境：Java 21+、Node.js 20+、pnpm
• 数据库：PostgreSQL（默认 localhost:5432/data_agent_tutorial）
• 必装扩展：pgvector

CREATE EXTENSION IF NOT EXISTS vector;

后端使用 Spring AI 的 OpenAI 兼容配置。没有可用的 API Key 时，可以前往 起凡 AI 中转站 注册，赠送25刀额度，支持 OpenAI 协议。

在 data-agent-backend/src/main/resources/application.yml 中配置：

• spring.ai.openai.base-url：填写 http://ai.jarcheng.top（不带 /v1）
• spring.ai.openai.api-key：填写中转站控制台创建的 API Key

首次初始化数据库（在项目根目录执行）：

psql -h localhost -p 5432 -U postgres -d data_agent_tutorial -f data-agent-backend/src/main/resources/database.sql

然后启动后端：

cd data-agent-backend
./gradlew bootRun

出现 Tomcat started on port(s): 9933 即启动成功。

cd data-agent-frontend
pnpm install
pnpm dev

默认地址：http://localhost:3500（自动代理 /api 到后端）。

打开浏览器输入自然语言问题，若看到前端卡片出现流式节点打字机效果，即最小 Agent 闭环已跑通。

本教程按章节组织，强烈建议切换到对应章节的 Git 分支对照阅读源码，效果翻倍！

• 🏗️ 00 项目骨架搭建
  后端 Kotlin + Jimmer 初始化，前端 Vue3 接入 API 自动生成。
• 🔌 01 A2A 协议实战
  跑通 Agent 服务发现与 JSON-RPC 流式事件。
• 🕸️ 02 Graph 编程基础
  从单节点走向多分支路由，实现 暂停 -> 人工确认 -> 续跑 的 HITL 工作流。
• 🧠 03 Bird SQL 知识库基建
  完成结构化表关联入库与 PGVector 向量化。
• 🔥 04 SQL Agent 核心编排（系列高潮）
  逐个击破：知识召回、关系图谱、任务拆解、SQL 自纠错、Python 高阶计算、商业报告生成。

付费远程运行/安装/定制开发联系微信：ljc666max

其他关于程序运行安装报错请加QQ群：

• 416765656（满）
• 632067985
• 1102705673