基于LangGraph+Elasticsearch 9.x 构建人机协同（HITL）AI Agent
一、概念，先懂逻辑再动手
1. 什么是人机协同（HITL）？
可以把它理解成「AI的精准求助机制」：
-
不是让人工全程盯着AI干活，而是AI只有搞不定的时候，才会停下来叫人，其余时间全自动运行
-
核心原则：只在「信息缺失、意图模糊、高风险决策」3种场景触发人工干预，避免无效打断
-
举个例子：AI从法律库里找了5个相似案例，但不知道你要用哪个，就停下来问你；AI写分析时发现缺合同细节，就停下来让你补充，而不是瞎编内容。
2. 为什么必须用LangGraph，不能用普通LangChain？
普通LangChain是「单线程流水线」：一条道走到黑，一旦启动就没法中途暂停、没法回退、没法分叉。
而LangGraph是「带存档的流程图+状态机」，也是实现HITL的核心：
-
它能让工作流精准暂停，完整保存当前所有进度，等你输入后，从暂停的地方继续跑，不用从头再来
-
支持条件分支（比如你确认案例选错了，能直接退回选择步骤）
-
自带「共享记事本（State）」：所有步骤都能读写同一个全局状态，数据不会乱
3. Elasticsearch 9.x在这里干什么？
它是「AI的精准检索放大镜」，核心解决2个痛点：
-
如果你有10000条法律案例，直接全丢给LLM，不仅费钱，还会让LLM混乱、幻觉
-
ES先做第一层过滤：把你的问题转成向量，从海量案例里精准捞出最相关的5条，再交给LLM和你选择，兼顾效率、成本和准确性
-
9.x版本专属优势：向量检索速度更快、本地部署安全配置更简单、对LangChain兼容性更好，完全向下兼容8.x的语法
二、环境
前置必装工具
Node.js 18+ ：https://nodejs.cn/ （装LTS版本，装完用 node -v 验证）
Docker Desktop ：https://www.docker.com/ （Windows用户必须开启WSL2引擎，Linux直接装）
能正常调用的OpenAI API Key
步骤1：1条命令部署Elasticsearch 9.x本地单节点
直接用Docker部署，不用管复杂的环境配置
打开终端（Windows用CMD/PowerShell，Mac/Linux用终端），先创建Docker网络：
docker network create es-net
执行下面的命令启动ES 9.x容器（直接复制全段运行）：
docker run -d \\
–name es01 \\
–net es-net \\
-p 9200:9200 \\
-p 9300:9300 \\
-e \”discovery.type=single-node\” \\
-e \”ES_JAVA_OPTS=-Xms2g -Xmx2g\” \\
-e \”xpack.security.enabled=true\” \\
-e \”xpack.security.enrollment.enabled=true\” \\
docker.elastic.co/elasticsearch/elasticsearch:9.3.0
关键参数解释：
-
discovery.type=single-node：单节点模式，不用配置集群，本地开发专用
-
ES_JAVA_OPTS=-Xms2g -Xmx2g：给ES分配2G内存，低于1G会启动失败
-
xpack.security.enabled=true：开启安全认证，才能生成API Key连接代码
验证ES是否启动成功：
执行 docker ps，能看到es01容器的状态是Up（健康运行），就成功了。如果启动失败，大概率是内存不够，把2g改成1g再试。
步骤2：配置ES安全，生成连接用的API Key
这一步是新手踩坑重灾区，严格跟着执行，每一步都有验证
重置elastic超级用户的密码：
docker exec -it es01 bin/elasticsearch-reset-password -u elastic -i
执行后会提示你输入新密码，自己设一个好记的（比如Es@123456），输完回车，提示Password updated successfully就成功了，这个密码一定要记好。
生成代码连接用的API Key：
# 把<elastic的密码>换成你上一步设的密码，比如Es@123456，然后全段复制运行
docker exec -it es01 curl -u elastic:<elastic的密码> -X POST \”https://localhost:9200/_security/api_key?pretty\” -H \”Content-Type: application/json\” -d\’
{
\”name\”: \”hitl-legal-agent-key\”,
\”expiration\”: \”30d\”
}
\’
保存API Key：
运行后会输出一段JSON，里面的api_key字段（一串随机字符串）就是你要的，完整复制下来，后面要用，示例如下：
{
\”id\” : \”xxx\”,
\”name\” : \”hitl-legal-agent-key\”,
\”api_key\” : \”abc123def456xxx\” // 就复制这个值！
}
浏览器打开 https://localhost:9200，账号输入elastic，密码输入你刚才设的，能看到ES的版本信息（9.3.0），就说明环境完全没问题了。
步骤3：初始化项目，安装依赖
新建一个空文件夹（比如es-hitl-legal-agent），用VS Code打开，在终端里执行：
# 初始化Node项目，一路回车就行
npm init -y
安装固定版本的依赖（避免版本兼容问题，直接复制运行）：
# 安装核心依赖
npm install @elastic/elasticsearch@8.15.0 @langchain/community@0.3.10 @langchain/core@0.3.15 @langchain/langgraph@0.2.18 @langchain/openai@0.3.11 dotenv@16.4.5 –legacy-peer-deps
# 安装开发依赖（TypeScript运行工具）
npm install –save-dev tsx@4.19.1 typescript@5.6.3
新建TypeScript配置文件tsconfig.json，直接复制下面的内容：
{
\”compilerOptions\”: {
\”target\”: \”ES2020\”,
\”module\”: \”ESNext\”,
\”moduleResolution\”: \”node\”,
\”esModuleInterop\”: true,
\”strict\”: true,
\”skipLibCheck\”: true,
\”outDir\”: \”./dist\”
},
\”include\”: [\”*.ts\”],
\”exclude\”: [\”node_modules\”]
}
新建环境变量文件.env，复制下面的内容，替换成你自己的信息：
# ES连接地址，本地Docker部署就是这个固定值
ELASTICSEARCH_ENDPOINT=https://localhost:9200
# 刚才生成的ES API Key
ELASTICSEARCH_API_KEY=你复制的api_key值
# 你的OpenAI API Key
OPENAI_API_KEY=你的OpenAI API Key
三、全流程逻辑：先看全貌，再写代码
整个HITL系统的工作流，就像下面的流程图，一共9步，2次核心人工干预，1次校验回退，你先在脑子里有个全貌，后面写代码就不会乱：
用户输入法律问题 → 1.ES检索相关案例 → 【HITL1：暂停，让用户选案例】
→ 2.LLM解析用户选择，锁定案例 → 【HITL1.5：暂停，让用户确认案例是否正确】
→ 3.校验结果：不对→退回HITL1重选；对了→往下走
→ 4.LLM生成分析草稿，检查有没有缺信息
→ 5.分支判断：没缺信息→直接生成最终分析；缺信息→【HITL2：暂停，让用户补充信息】
→ 6.拿到补充信息，生成最终分析 → 结束
核心原理提醒：所有的「暂停等用户输入」，都是靠LangGraph的interrupt()实现的，它会把当前所有数据都存档，等用户输入后，从暂停的地方继续跑，这就是HITL的核心。
