一、项目背景与目标
最近在带着同事一起做智能 Agent 相关的内部项目，发现很多人对 LangGraph 非常感兴趣，但又不太清楚如何从零开始搭建一个完整的 AI Agent，我于是在 github 上找，看看有没有好的开源项目给他们学习，偶然间发现了 google-gemini 开源的这个 项目[1]，正好拿来给他们讲讲，学习学习。发现整理的材料又正好可以出一期公众号文章，就作为我公众号的一篇番外，来讲讲。
题外话：我十分不主张，一遇到新需求，就好像对应的知识就得全部掌握，得去花大力气看看基础教程，了解全貌之后，再开始行动。如果真是这样的话，这个项目大概率就得黄了。应该是要根据目标去找，去按需学习。
你可能已经用过市面上的一些“低代码/零代码”智能体平台，比如 Coze、dify 这类产品。它们就像搭积木一样，让你拖拽组件、配置流程，快速拼出一个属于自己的 AI Agent。这种方式对于业务快速上线、简单场景非常友好。
但你有没有遇到过这样的问题：
• 想要更深度的自定义，发现平台的“积木”不够用？
• 想搞懂 Agent 内部到底是怎么一步步推理、搜索、反思、合成答案的？
• 希望做私有化部署、对接企业内网、或者实现一些平台不支持的高级功能？
这时候，你就需要跳出“应用端拼装”，进入“代码层级的自定义”。本项目就是为此而生——它不仅让你看到一个完整的“AI 研究员”是怎么从零到一搭建起来的，还能让你随时插拔、扩展、魔改每一个环节。
它适合：
• 希望了解 LangGraph 实践的开发者
• 想要构建带有“智能搜索+推理+引用”功能的对话/问答系统的团队
• 需要端到端范例、可直接二次开发的工程师
核心亮点：
• 通过 LangGraph 低代码方式编排“生成-搜索-反思-合成”AI 代理流程
• 支持 Google Search API 实时查找资料，答案带引用
• 前端 React + Vite，后端 Python + FastAPI + LangGraph
在接下来的内容中，我会像一位带你实战的讲师，带你从全局到细节，逐步拆解这个项目的每一处关键实现。
二、项目组成与架构
在正式读代码前，我们先快速了解一下项目的整体结构和技术选型。
目录结构简述：
•frontend/：React 前端，负责 UI 展示、与后端 API 通信
•backend/：Python 后端，核心为 LangGraph 代理
•src/agent/：代理主流程、工具、状态定义
•examples/cli_research.py：命令行调用代理的最小示例
技术栈：
• 前端：React、Vite、Tailwind CSS
• 后端：Python 3.11+、LangGraph、Google Gemini、FastAPI
核心流程：
1. 用户输入问题（网页或命令行）
2. 代理自动生成搜索词 → Google 搜索 → Gemini 总结 → 反思知识盲区 → 迭代补充 → 合成带引用的答案
你可以把它想象成一个“AI 研究员”，自动帮你查资料、归纳、补充、引用，最后给你一份有理有据的答案。
三、如何启动和体验项目
在动手读代码前，我们先来体验一下项目的实际效果。
环境准备
• Node.js 16+、npm
• Python 3.11+
• Google Gemini API Key（必需）
安装依赖
在项目根目录下：
setup.bat install
或分别：
setup.bat install-backendsetup.bat install-frontend
运行开发环境
setup.bat dev
• 会自动弹出前端和后端窗口，前端访问 http://localhost:5173/app
• 关闭服务只需关闭弹出的命令行窗口
命令行体验
setup.bat cli-example "今天武汉的天气怎么样？"
• 直接在终端输出带引用的答案
你可以先随便问一个问题，感受一下“processing…”之后，AI 是如何给你一份带引用的研究报告的。
四、端到端代码导读
接下来，让我们像课堂实战一样，带着问题、带着好奇心，一步步走进项目的核心实现。
入口：命令行调用
我们先从最简单的命令行入口开始。
文件：backend/examples/cli_research.py
•入口：if _name == "main_": main()（第42行）
•主函数：main()（第5行）
你可以打开这个文件，看到如下关键代码：
from agent.graph import graph # 第3行…result = graph.invoke(state) # 第36行
这里的graph.invoke(state)，就是整个“AI 研究员”流程的起点。你输入一个问题，所有的自动研究、搜索、推理、引用，都是从这里开始的。
小贴士：如果你想快速体验后端的效果，可以直接在命令行运行：
python backend/examples/cli_research.py "今天武汉的天气怎么样？"
跳转到核心代理定义
接下来，我们顺着from agent.graph import graph跳到核心代理的定义。
文件：backend/src/agent/graph.py
•graph 定义：graph = builder.compile(name="pro-search-agent")（第293行）
•StateGraph 构建：第269行起
你会看到一段类似“流程图”的代码：
builder.addnode("generatequery", generatequery) # 第272行builder.addnode("webresearch", webresearch) # 第273行builder.addnode("reflection", reflection) # 第274行builder.addnode("finalizeanswer", finalizeanswer) # 第275行…builder.addedge(START, "generatequery") # 第279行builder.addconditionaledges("generatequery", continuetowebresearch, ["webresearch"]) # 第281行builder.addedge("webresearch", "reflection") # 第285行builder.addconditionaledges("reflection", evaluateresearch, ["webresearch", "finalizeanswer"]) # 第287行builder.addedge("finalizeanswer", END) # 第291行
林生点评：
• 这就是 LangGraph 的“流程编排”能力。每个节点（Node）就是一个处理环节，节点之间的连线（Edge）决定了流程怎么走、是否循环。
• 你可以把它想象成“AI 研究员的工作流”：先生成搜索词，再查资料，再反思，再查补充，最后合成答案。
节点实现详解
现在我们带着“AI 研究员”的视角，逐个节点来看它们都做了什么。
3.1.generate_query节点
•定义：def generate_query(state: OverallState, config: RunnableConfig) -> QueryGenerationState:（第44行）
•作用：用 Gemini LLM 生成适合搜索的关键词。
•关注点：prompt 构造、LLM 调用、输出结构。
•关键代码：
llm = ChatGoogleGenerativeAI(…)structuredllm = llm.withstructuredoutput(SearchQueryList)formattedprompt = querywriterinstructions.format(…)result = structuredllm.invoke(formattedprompt)return {"search_query": result.query}
•林生提示：这里的SearchQueryList是在 toolsandschemas.py 里定义的结构，专门用来描述“搜索词列表+理由”。
3.2.continuetoweb_research节点
•定义：def continuetoweb_research(state: QueryGenerationState):（第84行）
•作用：把每个搜索词分发到 web_research 节点。
•关键代码：
return [ Send("webresearch", {"searchquery": searchquery, "id": int(idx)}) for idx, searchquery in enumerate(state["search_query"])]
•林生提示：这里用到了 LangGraph 的“并行分发”能力，每个搜索词都可以独立查资料。
3.3.web_research节点
•定义：def web_research(state: WebSearchState, config: RunnableConfig) -> OverallState:（第95行）
•作用：用 Google Search API + Gemini LLM 查找并总结网页内容。
•关注点：API 调用、引用提取、结果格式。
•关键代码：
response = genaiclient.models.generatecontent(…)resolvedurls = resolveurls(…)citations = getcitations(response, resolvedurls)modifiedtext = insertcitationmarkers(response.text, citations)sourcesgathered = [item for citation in citations for item in citation["segments"]]return { "sourcesgathered": sourcesgathered, "searchquery": [state["searchquery"]], "webresearchresult": [modified_text],}
•林生提示：这里的“查资料”其实是 Gemini LLM 通过 Google Search 工具能力，自动抓取网页、提取引用、生成带引用的总结。
3.4.reflection节点
•定义：def reflection(state: OverallState, config: RunnableConfig) -> ReflectionState:（第139行）
•作用：用 Gemini LLM 反思当前资料是否足够，生成补充查询词。
•关键代码：
formattedprompt = reflectioninstructions.format(…)llm = ChatGoogleGenerativeAI(…)result = llm.withstructuredoutput(Reflection).invoke(formattedprompt)return { "issufficient": result.issufficient, "knowledgegap": result.knowledgegap, "followupqueries": result.followup_queries, …}
•林生提示：这里的Reflection结构体也是在 toolsandschemas.py 里定义的，描述“是否足够、知识盲区、补充查询”。
3.5.evaluate_research节点
•定义：def evaluate_research(state: ReflectionState, config: RunnableConfig) -> OverallState:（第183行）
•作用：判断是否继续 webresearch 还是进入 finalizeanswer。
•关键代码：
if state["issufficient"] or state["researchloopcount"] >= maxresearchloops: return "finalizeanswer"else: return [ Send("webresearch", {…}) for idx, followupquery in enumerate(state["followup_queries"]) ]
•林生提示：这里就是“AI 研究员”决定要不要继续查补充资料的地方。
3.6.finalize_answer节点
•定义：def finalize_answer(state: OverallState, config: RunnableConfig):（第220行）
•作用：用 Gemini LLM 合成最终答案，整理引用。
•关键代码：
formattedprompt = answerinstructions.format(…)llm = ChatGoogleGenerativeAI(…)result = llm.invoke(formattedprompt)# 替换短链为原始链接for source in state["sourcesgathered"]: if source["shorturl"] in result.content: result.content = result.content.replace( source["shorturl"], source["value"] ) uniquesources.append(source)return { "messages": [AIMessage(content=result.content)], "sourcesgathered": unique_sources,}
•林生提示：最终输出就是带引用的完整答案，前端和命令行都会显示。
数据结构与工具定义
在读节点实现时，你可能会好奇：SearchQueryList、Reflection这些结构体是怎么定义的？
文件：backend/src/agent/toolsandschemas.py
•SearchQueryList（第5行）：定义了搜索词列表和 rationale。
•Reflection（第14行）：定义了反思节点的输出结构。
你可以随时跳到这个文件，看看每个字段的含义和注释。
总结跳转链路
到这里，我们已经带着“AI 研究员”的视角，完整走了一遍从命令行输入到最终答案输出的全链路。
1.入口：cli_research.py第36行graph.invoke(state)
2.流程定义：graph.py第269-291行（StateGraph 构建）
3.节点实现：graph.py第36-265行（每个节点的具体逻辑）
4.数据结构：toolsandschemas.py（第5-24行）
你可以跟着这些跳转，边看边实验，体会每一步的数据流转和设计巧思。
建议的学习方式
最后，给大家一些实战建议：
• 跟着每个“文件+行号+关注点”定位代码，边看边在本地加 print/log，体会数据流转。
• 遇到不懂的类型（如SearchQueryList、Reflection），可跳到toolsandschemas.py查看定义。
• 如果想看“Google Search API”具体怎么调用的，可进一步跳到toolsandschemas.py或utils.py。
• 多用命令行和前端实际提问，结合日志和代码理解每一步。
* *
本文章可作为写作、讲解、二次开发的基础材料，欢迎补充和完善！希望你能像带着学员实战一样，真正掌握 LangGraph 应用开发的精髓。
原先的 google-gemini 该项目的地址如下，大家可以跳转去看：https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart
我在这个项目的基础上进行了部分修改，有完整的中文使用教程，以及本地 Windows 部署脚本调整，方便大家直接运行和二次开发。如果对这块感兴趣，可以关注我的微信公众号，直接发消息“langgraph”,即可获得该项目的完整代码和使用教程。
