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

一、项目背景与目标

最近在带着同事一起做智能 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. 1. 用户输入问题（网页或命令行）
2. 2. 代理自动生成搜索词 → Google 搜索 → Gemini 总结 → 反思知识盲区 → 迭代补充 → 合成带引用的答案

你可以把它想象成一个“AI 研究员”，自动帮你查资料、归纳、补充、引用，最后给你一份有理有据的答案。

三、如何启动和体验项目

1. 环境准备

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

2. 安装依赖

在项目根目录下：

setup.bat install

或分别：

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

3. 运行开发环境

setup.bat dev

• • 会自动弹出前端和后端窗口，前端访问 http://localhost:5173/app
• • 关闭服务只需关闭弹出的命令行窗口

4. 命令行体验

setup.bat cli-example "今天武汉的天气怎么样？"

• • 直接在终端输出带引用的答案

你可以先随便问一个问题，感受一下“processing...”之后，AI 是如何给你一份带引用的研究报告的。

四、端到端代码导读

接下来，让我们像课堂实战一样，带着问题、带着好奇心，一步步走进项目的核心实现。

1. 入口：命令行调用

我们先从最简单的命令行入口开始。

文件：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 "今天武汉的天气怎么样？"

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)})
    for idx, search_query 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 = 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 = [item for citation in citations for item in citation["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。
• • 关键代码：

if state["is_sufficient"] or state["research_loop_count"] >= max_research_loops:
    return "finalize_answer"
else:
    return [
        Send("web_research", {...})
        for idx, follow_up_query in enumerate(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)
# 替换短链为原始链接
for source in state["sources_gathered"]:
    if source["short_url"] in result.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. 1. 入口：cli_research.py 第36行 graph.invoke(state)
2. 2. 流程定义：graph.py 第269-291行（StateGraph 构建）
3. 3. 节点实现：graph.py 第36-265行（每个节点的具体逻辑）
4. 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”,即可获得该项目的完整代码和使用教程。