这时候，你就需要跳出“应用端拼装”，进入“代码层级的自定义”。本项目就是为此而生——它不仅让你看到一个完整的“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 研究员”，自动帮你查资料、归纳、补充、引用，最后给你一份有理有据的答案。
三、如何启动和体验项目
在动手读代码前，我们先来体验一下项目的实际效果。
1. 环境准备
• Node.js 16+、npm • Python 3.11+ • Google Gemini API Key（必需）
2. 安装依赖
在项目根目录下：
setup.batinstall
或分别：
setup.bat install-backend
setup.bat install-frontend3. 运行开发环境
setup.batdev
• 会自动弹出前端和后端窗口，前端访问 http://localhost:5173/app • 关闭服务只需关闭弹出的命令行窗口
4. 命令行体验
setup.batcli-example"今天武汉的天气怎么样？"
• 直接在终端输出带引用的答案
你可以先随便问一个问题，感受一下“processing...”之后，AI 是如何给你一份带引用的研究报告的。
四、端到端代码导读
接下来，让我们像课堂实战一样，带着问题、带着好奇心，一步步走进项目的核心实现。
1. 入口：命令行调用
我们先从最简单的命令行入口开始。
文件：backend/examples/cli_research.py
•入口： if __name__ == "__main__": main()（第42行）•主函数： main()（第5行）
你可以打开这个文件，看到如下关键代码：
fromagent.graphimportgraph # 第3行
...
result = graph.invoke(state) # 第36行这里的graph.invoke(state)，就是整个“AI 研究员”流程的起点。你输入一个问题，所有的自动研究、搜索、推理、引用，都是从这里开始的。
小贴士：如果你想快速体验后端的效果，可以直接在命令行运行：
pythonbackend/examples/cli_research.py"今天武汉的天气怎么样？"
2. 跳转到核心代理定义
接下来，我们顺着from agent.graph import graph跳到核心代理的定义。
文件：backend/src/agent/graph.py
•graph 定义： graph = builder.compile(name="pro-search-agent")（第293行）•StateGraph 构建：第269行起
你会看到一段类似“流程图”的代码：
builder.add_node("generate_query", generate_query) # 第272行
builder.add_node("web_research", web_research) # 第273行
builder.add_node("reflection", reflection) # 第274行
builder.add_node("finalize_answer", finalize_answer) # 第275行
...
builder.add_edge(START,"generate_query") # 第279行
builder.add_conditional_edges("generate_query", continue_to_web_research, ["web_research"])# 第281行
builder.add_edge("web_research","reflection") # 第285行
builder.add_conditional_edges("reflection", evaluate_research, ["web_research","finalize_answer"])# 第287行
builder.add_edge("finalize_answer", END) # 第291行林生点评：
• 这就是 LangGraph 的“流程编排”能力。每个节点（Node）就是一个处理环节，节点之间的连线（Edge）决定了流程怎么走、是否循环。 • 你可以把它想象成“AI 研究员的工作流”：先生成搜索词，再查资料，再反思，再查补充，最后合成答案。
3. 节点实现详解
现在我们带着“AI 研究员”的视角，逐个节点来看它们都做了什么。
3.1.generate_query节点
•定义： def generate_query(state: OverallState, config: RunnableConfig) -> QueryGenerationState:（第44行）•作用：用 Gemini LLM 生成适合搜索的关键词。 •关注点：prompt 构造、LLM 调用、输出结构。 •关键代码：
llm = ChatGoogleGenerativeAI(...)
structured_llm = llm.with_structured_output(SearchQueryList)
formatted_prompt = query_writer_instructions.format(...)
result = structured_llm.invoke(formatted_prompt)
return{"search_query": result.query}•林生提示：这里的 SearchQueryList是在 tools_and_schemas.py 里定义的结构，专门用来描述“搜索词列表+理由”。
3.2.continue_to_web_research节点
•定义： def continue_to_web_research(state: QueryGenerationState):（第84行）•作用：把每个搜索词分发到 web_research 节点。 •关键代码：
return[
Send("web_research", {"search_query": search_query,"id":int(idx)})
foridx, search_queryinenumerate(state["search_query"])
]•林生提示：这里用到了 LangGraph 的“并行分发”能力，每个搜索词都可以独立查资料。
3.3.web_research节点
•定义： def web_research(state: WebSearchState, config: RunnableConfig) -> OverallState:（第95行）•作用：用 Google Search API + Gemini LLM 查找并总结网页内容。 •关注点：API 调用、引用提取、结果格式。 •关键代码：
response = genai_client.models.generate_content(...)
resolved_urls = resolve_urls(...)
citations = get_citations(response, resolved_urls)
modified_text = insert_citation_markers(response.text, citations)
sources_gathered = [itemforcitationincitationsforitemincitation["segments"]]
return{
"sources_gathered": sources_gathered,
"search_query": [state["search_query"]],
"web_research_result": [modified_text],
}•林生提示：这里的“查资料”其实是 Gemini LLM 通过 Google Search 工具能力，自动抓取网页、提取引用、生成带引用的总结。
3.4.reflection节点
•定义： def reflection(state: OverallState, config: RunnableConfig) -> ReflectionState:（第139行）•作用：用 Gemini LLM 反思当前资料是否足够，生成补充查询词。 •关键代码：
formatted_prompt = reflection_instructions.format(...)
llm = ChatGoogleGenerativeAI(...)
result = llm.with_structured_output(Reflection).invoke(formatted_prompt)
return{
"is_sufficient": result.is_sufficient,
"knowledge_gap": result.knowledge_gap,
"follow_up_queries": result.follow_up_queries,
...
}•林生提示：这里的 Reflection结构体也是在 tools_and_schemas.py 里定义的，描述“是否足够、知识盲区、补充查询”。
3.5.evaluate_research节点
•定义： def evaluate_research(state: ReflectionState, config: RunnableConfig) -> OverallState:（第183行）•作用：判断是否继续 web_research 还是进入 finalize_answer。 •关键代码：
ifstate["is_sufficient"]orstate["research_loop_count"] >= max_research_loops:
return"finalize_answer"
else:
return[
Send("web_research", {...})
foridx, follow_up_queryinenumerate(state["follow_up_queries"])
]•林生提示：这里就是“AI 研究员”决定要不要继续查补充资料的地方。
3.6.finalize_answer节点
•定义： def finalize_answer(state: OverallState, config: RunnableConfig):（第220行）•作用：用 Gemini LLM 合成最终答案，整理引用。 •关键代码：
formatted_prompt = answer_instructions.format(...)
llm = ChatGoogleGenerativeAI(...)
result = llm.invoke(formatted_prompt)
# 替换短链为原始链接
forsourceinstate["sources_gathered"]:
ifsource["short_url"]inresult.content:
result.content = result.content.replace(
source["short_url"], source["value"]
)
unique_sources.append(source)
return{
"messages": [AIMessage(content=result.content)],
"sources_gathered": unique_sources,
}•林生提示：最终输出就是带引用的完整答案，前端和命令行都会显示。
4. 数据结构与工具定义
在读节点实现时，你可能会好奇：SearchQueryList、Reflection这些结构体是怎么定义的？
文件：backend/src/agent/tools_and_schemas.py
• SearchQueryList（第5行）：定义了搜索词列表和 rationale。• Reflection（第14行）：定义了反思节点的输出结构。
你可以随时跳到这个文件，看看每个字段的含义和注释。
5. 总结跳转链路
到这里，我们已经带着“AI 研究员”的视角，完整走了一遍从命令行输入到最终答案输出的全链路。
1.入口： cli_research.py第36行graph.invoke(state)2.流程定义： graph.py第269-291行（StateGraph 构建）3.节点实现： graph.py第36-265行（每个节点的具体逻辑）4.数据结构： tools_and_schemas.py（第5-24行）
你可以跟着这些跳转，边看边实验，体会每一步的数据流转和设计巧思。
6. 建议的学习方式
最后，给大家一些实战建议：
• 跟着每个“文件+行号+关注点”定位代码，边看边在本地加 print/log，体会数据流转。 • 遇到不懂的类型（如 SearchQueryList、Reflection），可跳到tools_and_schemas.py查看定义。• 如果想看“Google Search API”具体怎么调用的，可进一步跳到 tools_and_schemas.py或utils.py。• 多用命令行和前端实际提问，结合日志和代码理解每一步。
本文章可作为写作、讲解、二次开发的基础材料，欢迎补充和完善！希望你能像带着学员实战一样，真正掌握 LangGraph 应用开发的精髓。
原先的 google-gemini 该项目的地址如下，大家可以跳转去看：https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart
我在这个项目的基础上进行了部分修改，有完整的中文使用教程，以及本地 Windows 部署脚本调整，方便大家直接运行和二次开发。如果对这块感兴趣，可以关注我的微信公众号，直接发消息“langgraph”,即可获得该项目的完整代码和使用教程。