一文带你读懂 Google LangGraph 项目，快速入门 AI Agent 全栈开发

显示全部楼层

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;display: table;padding: 0.3em 1.2em;color: rgb(255, 255, 255);background: rgb(0, 152, 116);border-radius: 8px 24px;box-shadow: rgba(0, 0, 0, 0.06) 0px 2px 6px;">一、项目背景与目标

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;letter-spacing: 0.1em;color: rgb(63, 63, 63);">最近在带着同事一起做智能 Agent 相关的内部项目，发现很多人对 LangGraph 非常感兴趣，但又不太清楚如何从零开始搭建一个完整的 AI Agent，我于是在 github 上找，看看有没有好的开源项目给他们学习，偶然间发现了 google-gemini 开源的这个项目^[1]，正好拿来给他们讲讲，学习学习。发现整理的材料又正好可以出一期公众号文章，就作为我公众号的一篇番外，来讲讲。

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;font-style: italic;padding: 1em 1em 1em 2em;border-radius: 6px;color: rgba(0, 0, 0, 0.6);background: rgb(247, 247, 247);">
题外话：我十分不主张，一遇到新需求，就好像对应的知识就得全部掌握，得去花大力气看看基础教程，了解全貌之后，再开始行动。如果真是这样的话，这个项目大概率就得黄了。ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: inherit;color: rgb(0, 152, 116);">应该是要根据目标去找，去按需学习。
ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;color: rgb(63, 63, 63);">ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size:16px;margin:0.1em auto 0.5em;border-radius:8px;width:100%;"/>

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;letter-spacing: 0.1em;color: rgb(63, 63, 63);">你可能已经用过市面上的一些“低代码/零代码”智能体平台，比如 Coze、dify 这类产品。它们就像搭积木一样，让你拖拽组件、配置流程，快速拼出一个属于自己的 AI Agent。这种方式对于业务快速上线、简单场景非常友好。

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;letter-spacing: 0.1em;color: rgb(63, 63, 63);">但你有没有遇到过这样的问题：

ingFang SC", Cambria, Cochin, Georgia, Times, "Times New Roman", serif;font-size: 16px;text-indent: -1em;display: block;margin: 0.5em 8px;color: rgb(63, 63, 63);">
• 想要更深度的自定义，发现平台的“积木”不够用？
• 想搞懂 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 研究员”，自动帮你查资料、归纳、补充、引用，最后给你一份有理有据的答案。

三、如何启动和体验项目

在动手读代码前，我们先来体验一下项目的实际效果。

1. 环境准备

• Node.js 16+、npm
• Python 3.11+
• Google Gemini API Key（必需）

2. 安装依赖

在项目根目录下：

setup.batinstall

或分别：

setup.bat install-backend
setup.bat install-frontend

3. 运行开发环境

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”,即可获得该项目的完整代码和使用教程。