万字图文实战：我如何用 Claude Code + LangGraph，从零打造一个会“变脸”的天气智能体 Agent

AIBooter
557 阅读29分钟

万字图文实战：我如何用 Claude Code + LangGraph，从零打造一个会“变脸”的天气智能体 Agent

202508021455138.png

1 引言：AI 交互的下一步

在人工智能飞速发展的今天，我们已经习惯了与各种 AI Agent 通过对话框进行交流。无论是查询信息、生成文本还是控制智能家居，这种基于文本的交互模式虽然直接，却也逐渐暴露出其局限性——当 AI 需要呈现复杂、结构化的信息时，单纯的文字流往往显得力不从心，用户体验也因此大打折扣。

想象一下，当你询问天气时，AI 不再是返回一行冰冷的文字，而是直接为你生成一张包含温度、湿度、风速和动态图标的精美卡片。这，就是“生成式 UI”（Generative User Interface）的魅力。

image.png

image.png

生成式 UI 允许 AI Agent 突破文本的束缚，根据对话的上下文和自身的响应，动态地生成丰富、交互式的用户界面。这不仅是 AI 能力的延伸，更是用户体验的一次革命。它意味着我们的应用程序可以变得更加智能、更具情境感知能力。

本文将通过一个完整详尽的实战案例，手把手带你使用当前备受关注的两个前沿工具——用于构建状态化、多智能体应用的 Python 库 LangGraph，以及 AI 编程助手 Claude Code，从零开始，完整地构建一个具备生成式 UI 能力的智能天气 Agent。

整个开发过程全程通过 Claude Code 这一当下最火的 AI IDE 进行开发，充分展现了 Claude Code 辅助编程的强大能力：从需求分析、架构设计、开发规划、代码实现，到测试验证、问题修复。本文不仅是一个技术教程，更是对 AI 辅助软件开发新范式的深度探索和实践验证。

读完本文，你不仅能收获一个可运行的项目，更将掌握一套与 AI 高效协同的现代化开发方法论。

2 第一章：准备工作与环境配置

在正式开始编码之前，我们需要确保开发环境已经准备就绪，并了解我们所使用的核心技术框架。

2.1 技术框架说明 (LangGraph & Agent Chat UI & Claude Code)

  • LangGraph：它扩展自流行的 LangChain 框架，核心优势在于允许我们将 Agent 的工作流定义为一个“状态图”（State Graph）。这种方式非常适合处理需要持久化状态、循环和复杂流程控制的 Agent 应用，并且其对生成式 UI 提供了原生的支持。LangGraph 目前也是社区生态最好，技术成熟度最高，文档教程示例最完善的 AI Agent 开发框架之一。
  • LangGraph 模板应用 (Template Application) ：LangChain 团队提供的预构建的、可直接运行的开源项目。旨在帮助开发者快速上手，提供了常见代理工作流的示例，并且易于根据自身需求进行修改和部署。
  • New LangGraph Project ：是 LangGraph 模板应用中一个最简化的项目模版，相当于一个“空白画布”。它为开发者提供了最大的灵活性，可以从零开始完全自定义图的结构、状态和节点，适用于基于此项目来构建高度定制化的复杂应用。
  • Agent Chat UI：是一个基于 Next.js 的应用程序，为了与 LangGraph Agent 进行交互而设计，由 LangChain 开源。它提供了一个简洁的、基于聊天的界面，让开发者和高级用户可以与 LangGraph 的部署进行实时通信。
  • Claude Code：当前最强大的 AI 编程 IDE 。在本文中，它将扮演从项目经理、架构师到程序员、测试工程师的多种角色，我们将体验一种全新的、与 AI 深度协同的开发模式。

2.2 运行环境与前置条件

请确保你的本地环境满足以下要求：

  • Python：>= 3.11 版本。
  • UV：一个新兴的、速度极快的 Python 包安装和管理工具。

当然，你也可以使用 pip，但本文推荐使用 uv 以获得更好的体验。

2.3 开发环境说明

本文的开发环境如下：

  • MacOS：15.5
  • Python：3.11.5
  • UV：0.6.5
  • Claude Code：1.0.56

2.4 核心工具安装：LangGraph CLI

LangGraph 提供了一个强大的命令行工具（CLI），可以帮助我们快速启动开发服务器、打包应用等。我们使用 uvx（uv 的临时环境执行命令）来安装和运行它。

打开你的终端，执行以下命令：

uvx --from "langgraph-cli[inmem]" langgraph dev --help

如果因为网络问题执行失败（如下图所示），可以尝试切换到国内的 PyPI 镜像源：

image.png

uvx --from "langgraph-cli[inmem]" --index-url https://mirrors.aliyun.com/pypi/simple/ langgraph dev --help

当你看到以下帮助信息输出时，代表 LangGraph CLI 已经准备就绪。

image.png

3 第二章：项目初始化与骨架搭建

我们基于 LangGraph 生态进行 Agent 快速开发，显然不是从零开始。LangGraph 官方为我们提供了一系列开箱即用的模板应用，可以大大加速我们的开发进程。

3.1 下载 LangGraph 官方模板

我们选择 New LangGraph Project 这个模板的 Python 版本作为起点（是的，它还提供了 TS 版本）。

New LangGraph Project 模板是一个使用 LangGraph 开发框架实现的简单应用程序，展示了如何开始使用 LangGraph Server 以及如何使用 LangGraph Studio（可视化调试集成开发环境）。

它包含了一个基本的 LangGraph Server 实现和一个简单的图定义，GitHub 仓库地址为： github.com/langchain-a… 。

image.png

使用 git 克隆模板仓库到本地：

git clone git@github.com:langchain-ai/new-langgraph-project.git

image.png

3.2 模板工程结构简介

这个模板的核心逻辑在 src/agent/graph.py 文件中，它定义了一个最简单的单节点图，无论输入什么，都只会返回一个固定的字符串。

image.png

接下来，我们会基于此图进行扩展，来编排更复杂的 Agent 工作流实现输出城市天气信息，并在 LangGraph Studio 中可视化展示这些工流，并进行调试。

3.3 本地化改造：重建 Git 仓库与修改项目名称

首先，我们断开与官方模板远程仓库的连接，让它成为我们自己的独立项目，作为自己的本地仓库进行版本管理。

# 进入项目目录
cd new-langgraph-project

# 断开与远程仓库的连接
git remote rm origin

# 验证，确保没有任何输出
git remote -v

然后，我们将项目重命名为一个更有意义的名称，例如 build-genui-agent-with-langgraph。

# 进入项目上级目录
cd ..
mv new-langgraph-project build-genui-agent-with-langgraph

image.png

由于项目使用 pyproject.toml 进行管理，我们还需要修改该文件中的项目名称和描述。

打开 pyproject.toml 文件，找到 [project] 部分，修改 name 字段及描述信息：

# pyproject.toml

# --- 修改前 ---
[project]
name = "agent"
version = "0.0.1"
description = "Starter template for making a new agent LangGraph."

# ...

# --- 修改后 ---
[project]
name = "build-genui-agent-with-langgraph"
version = "0.0.1"
description = "a simple generative ui agent built with LangGraph."
# ...

修改后的 pyproject.toml 文件如下所示：

image.png

3.4 准备参考资料：LangGraph 开发指南文档

LangGraph 官方提供了一篇关于实现生成式 UI 的详细指南： How to implement Generative User Interfaces with LangGraph。

image.png

上面的开发指南是一份在线文档，如果直接将链接给到 LLM，会出现理解偏差。为了方便 Claude Code 和 LLM 理解，我们从 LangGraph 的 GitHub 仓库中找到其源文档 generative_ui_react.md 并下载到本地，后续提供给 Claude Code 作为开发时的参考文档。

image.png

这是一个进行 vibe coding 的最佳实践，即提供明确的、结构化的参考文档，效果会优于一个网页链接。

4 第三章：与 AI 协同：Agent 的核心开发流程

环境和骨架准备就绪，接下来进入最核心的开发环节。我们将全程使用 Claude Code 作为编程工具，体验全新的 vibe coding 开发模式。

想要了解更多的 Claude Code 介绍和使用技巧，可以查看上一篇文章。

4.1 奠定基础：复制参考文档与生成 CLAUDE.md

首先，使用 IDE（如 Cursor）打开我们的项目目录 build-genui-agent-with-langgraph。

cd ~/projects

cursor build-genui-agent-with-langgraph/

Claude Code 本身是一个终端式 CLI，但是可以很好的集成在 VScode 和 Cursor 等界面 IDE 中，这里我们借用 Cursor 作为窗口 IDE。

我们将前面下载的开发指南文档 generative_ui_react.md 复制到项目下的 refs 目录中（如果目录不存在，可以手动创建）。

image.png

然后，在 Claude Code 的命令窗口中，使用 /init 命令，它会自动分析整个项目结构和代码，生成一个 CLAUDE.md 文件。

CLAUDE.md 文件是 Claude Code 的项目核心文件（类似 cursorrules），能帮助它在后续的开发中提供更精准的上下文参考，通常在使用 Claude Code 开发时，应该首先生成项目的该文件。

image.png

image.png

生成的 CLAUDE.md 如下所示：

image.png

为了方便阅读，也可以使用类似如下的提示词，让 Claude Code 帮助生成一份中文版的 CLAUDE_ZH.md 文档：请参考 CLAUDE 文档生成一份 CLAUDE_ZH.md 文档。

4.2 AI 辅助规划：使用 Plan Mode 制定开发计划

另一个使用 Claude Code 等 AI 编程 IDE 进行开发的最佳实践是：在让 AI 开始写代码之前，先让其进行规划。

在 Claude Code 下，通过双击 Shift + Tab 进入 Plan Mode，这是一个专门用于需求沟通和计划制定的模式。

image.png

我们向它下达第一个指令：

参考 @refs/generative_ui_react.md，在后台创建一个天气示例节点和 UI 组件来支持 generative UI 效果，注意不要使用 LLM，不需要开发前端组件。

image.png

Claude Code 会给出一个初步的开发计划。plan mode 有点类似 Cursor 的 ask 模式，我们可以像和同事讨论一样，继续与它沟通，对计划进行完善。

比如，我们可以要求它增加创建节点、更新依赖的步骤，并细化实现细节，从而得到更完整的开发实施计划。

非常好,尤其是在结尾总结了文件变更清单,不过有几个点需要完善:1.目前计划中的 1234 点属于"关键变更", 需要增加"创建 Weather 节点实现"和"更新依赖"两个计划事项;2. 需要增加"实现细节(Implementation Details)",包括"Weather Node Features","UI Component Features"和"State Management";3.可以使用 Tailwind css ,但是需要注意在 ui.tsx中即可,不需要使用独立的 styles 文件

image.png

我们需要对 AI 的输出结果保持关注，并持续 review：

移除配置节点版本：设置 "node_version": "20" 支持 React 组件,因为我们使用 python env

image.png

如果需要添加新的依赖项，需要更新 pyproject.toml 文件

image.png

经过几轮沟通，我们会得到一个非常详尽且靠谱的实施计划，它将作为我们和 AI 共同遵守的开发蓝图。

4.3 AI 编码实现：生成后端图、UI 组件与配置文件

计划确认后，双击 Shift + Tab 退出 Plan 模式进入编辑模式，告诉 Claude Code 开始执行：

按照上述实施计划，开始开发

image.png

接下来，就是见证奇迹的时刻。Claude Code 会开始逐一执行计划中的任务：

  • 重构后端图 (graph.py): 它会修改 graph.py，定义新的状态（State）、添加 weather_node 节点，并重新构建图的逻辑。

    image.png

  • 创建 UI 组件 (ui.tsx): 它会创建一个 ui.tsx 文件，并在其中编写一个 React 组件，用于前端展示天气信息。

    image.png

  • 更新配置文件: 同时，它还会修改 langgraph.json 和 pyproject.toml 等文件，以注册新的 UI 组件和添加必要的依赖。

    image.png

4.4 AI 自动化测试：执行冒烟测试与智能自修复

完成初步编码后，Claude Code 不会立即停止，而是会主动进行简单的冒烟测试，比如语法检查和 lint 检查。

在这个过程中，它可能会发现自己写下的代码存在问题，然后根据测试结果自动进行纠正。

image.png

image.png

同样的，我们在这整个过程中，也需要保持关注，并在 AI 发生偏离时进行干预（Claude Code 的中断操作为 ESC 键）。

例如，它在一个测试步骤中尝试使用 pip 命令，但我们项目推荐使用 uv，我们只需要提醒它：

我们使用的是 uv 而不是 pip

image.png

Claude Code 会立刻理解并进行修正，重新使用正确的命令重新执行测试，并根据测试结果修复它自己刚刚编写的代码。这种“自我纠错”的能力，正是 AI 协同开发的巨大优势。

image.png

image.png

image.png

4.5 阶段性整理：开发工作总结与测试脚本归档

当所有开发和初步测试任务完成后，Claude Code 会生成一份工作总结，创建为 README.md 文档，非常智能。

image.png

另外，因为模板工程本身就提供了一些单元测试和集成测试的脚本，我们让 Claude Code 将上述开发过程中生成的测试脚本也整理到对应的目录下，保持良好的工程规范。

根据 @tests/ 目录下的结构,将上述测试脚本调整或者整理到合适的目录及脚本中

image.png

可以看到，Claude Code 不但完成了测试脚本的重构，还自动进行了重构之后的脚本测试：

image.png

4.6 亲自上阵：单元测试及运行演示脚本

我们也可以手动在项目目录下执行脚本，来进行单元测试和功能演示，终端输入以下命令：

python3 -m pytest tests/unit_tests/ -v

image.png

以及以下命令：

python3 examples/weather_demo.py

image.png

image.png

5 第四章：迭代与重构：从可用到好用的演进之路

初版 Agent 代码开发已经完成，但它还远没完成。接下来，我们将进入一个不断测试、发现问题、修复问题的迭代重构阶段，整个过程我们仍然交给 Claude Code 来完成。

5.1 核心逻辑修正：实现从用户输入中动态提取城市

通过对核心逻辑 graph.py 的代码进行 review，我们发现一个核心问题：我们的期望是通过 chatUI 页面输入一个城市，agent 返回该城市对应的天气信息，而当前代码中城市是从配置文件读取的，而不是从用户的输入消息中动态获取。这显然不符合一个“智能”Agent 的要求。

对应代码如下：

image.png

我们向 Claude Code 提出修正要求：

@src/agent/graph.py 应该从用户输入中获取城市,而不是从配置文件中读取

Claude Code 迅速理解了问题，并制定了新的更新计划，包括修改 weather_node 的逻辑，增加 extract_city_from_message 的工具函数，并同步更新相关的测试用例。在执行过程中，它再次展现了编码、测试、自修复的完整闭环。

image.png

image.png

并且还总结了测试报告，保持到 TEST_REORGANIZATION_SUMMARY.md 文档中，主要目录结构如下图：

image.png

5.2 阶段性整理：文档整理和脚本整理

使用 Claude Code 等 AI IDE 开发，另一重要的最佳实践是，在一个开发任务完成后，进行总结。这样做会有效的避免上下文窗口导致的 LLM 幻觉或者失控。

我们可以在每次执行最后，整理归档 Claude Code 给出的总结或者文档：

把相关总结文档也调整到合适的对应目录下

image.png

最终得到项目结构和文档结构如下：

image.png

image.png

同样，我们也可以根据每轮对话的测试情况进行整理：

上述历史对话中的测试是否涉及 make 测试?

所有测试脚本等执行命令,以及 BASH 工具执行命令应该优先尽可能使用 uv。

image.png

执行 make test 并自我修复：

image.png

5.3 服务端联调：在 LangGraph Studio 中测试与修复 Bug

代码逻辑修正后，我们启动 LangGraph Studio 服务器进行联调。启动前会安装项目所需的依赖包，需要一些时间，请耐心等待。

uv run langgraph dev

启动完成后，会自动打开一个新的浏览器窗口，展示 LangGraph Studio 的页面。

在 Studio 的 UI 界面中，选中我们定义的 agent ，并切换到 Graph 模式，可以看到我们定义的天气 Weather 节点已经正确显示在页面上：

image.png

在 Graph 模式下输入 " 查询北京的天气 "，点击提交：

image.png

结果报错，我们将完整的报错堆栈信息直接复制给 Claude Code，它会像一个经验丰富的开发者一样，分析日志、定位问题，并给出解决方案，一步步引导我们修复 Bug。

image.png

image.png

image.png

image.png

image.png

最终得到解决方案，原因是在 LangGraph Studio 的 Graph 页面中需要输入标准的 JSON 格式：

image.png

再次启动服务，在 LangGraph Studio 输入框中使用以下 JSON 格式：：

{
    "messages": [
      {
        "role": "user",
        "content": "北京的天气怎么样？"
      }
    ]
}

# 或者：

{
    "messages": [
      {
        "role": "human",
        "content": "北京的天气怎么样？"
      }
    ]
}

可以看到正确的输出：

image.png

5.4 前端联调：在 Agent Chat UI 中测试与修复 Bug

前面我们是通过启动 LangGraph Studio UI 服务器运行 Weather Agent 的。

接下来，我们使用在线的 Agent Chat UI ( agentchat.vercel.app/ ) 与本地服务进行联调。

我们使用 LangGraph 已经在线上预构建好的 Agent Chat UI 界面与本机的 LangGraph Agent 通过 Agent Chat UI 界面进行交互。

在 UI 界面中运行 Agent 的步骤非常简单。

首先，在本地启动 LangGraph API 服务器，前面我们已经启动过了（langgraph run dev）。

image.png

然后，在浏览器中打开 Agent Chat UI 界面链接，链接地址为 agentchat.vercel.app/ 。在打开的页面，填入本地 LangGraph 服务地址和端口（默认为 http://localhost:2024 ），并输入 Agent Graph ID 和 LangSmith API Key（前面工程中的 .env 文件中填入的）：

image.png

点击 Continue 按钮，就跳转到 Chat 聊天页面：

image.png

在聊天框输入“上海天气如何？”，页面再次报错。

image.png

image.png

同样的，我们将 LangGraph Server 控制台的报错日志提供给 Claude Code。它分析出错误原因是 user_message.content 的类型问题（期望是字符串，实际是列表），并迅速对 graph.py 进行了修复。

image.png

image.png

修复过程如下：

image.png

修复后，无需重启服务，我们再次在 Agent Chat UI 中提问，终于看到了正确的文本回答。

image.png

5.5 人在环路：代码 review 与优化

我们发现，虽然页面返回了正确的天气信息，但是页面并没有渲染出我们期望的天气卡片效果，而只是简单的文字描述，这个问题我们将在后面进行优化。

现在我们需要进行一个在 AI Assitant 开发过程中非常重要的工作，人需要在环路中保持 review。在当前阶段，我们即使将 coding 工作交给了 AI，但是我们仍然需要对 AI 的思考和输出保持关注，并进行 review 然后及时反馈给 AI ，避免随着时间推移出现新的“AI 味道”的屎山代码。

下面是开发过程中 review 的几个问题及修复。

5.5.1 问题 1 ：函数规范性写法（运用 Claude Code 思考模式）

在之前的 coding 过程中，我们注意到，在修复 Agent Chat UI 的输入参数类型时，Claude Code 的修复方式为：

image.png

我们可以给出建议，让 Claude Code 进入思考模式，对比更规范的写法：

仔细思考 def extract_city_from_message(message_content) -> str: 和 def extract_city_from_message(message_content: str | list) -> str: 两种写法的优劣

image.png

image.png

image.png

image.png

image.png

image.png

通过思考模式，可以非常清晰的对比两种写法的优劣势，得到更规范的代码写法。另一个隐藏的意义在于，开发过程中类似场景的使用，也是在加强 Claude Code 及背后的 LLM 对开发规范的训练，从而让其在后续的开发过程中更加受约束。

5.5.2 问题 2：前端样式问题（LangGraph pull 机制）

回到 Agent Chat UI ，我们注意到，我们期望的回答应该是一个天气卡片，但是现在样式明显不够美观。

打开 F12 查看回答区域页面元素，可以看到的确是一个卡片 DIV ，但是需要美化样式：

image.png

我们尝试描述问题，并引导 Claude Code 从 LangGraph Server 、 Agent Chat UI 集成以及消息推送机制的角度进行分析排查。

因为这个问题比较复杂，且涉及多个系统交互，链路较长，所以经过多轮会话后，才得到解决：

目前 Agent Chat UI 页面的回答样式十分简陋,参见截图 [Image #1], 我们预期的样式类似截图 [Image #2] ，请修复显示的样式。  

提供一个示例供其参考：

image.png

目前样式仍然不对,只输出了"🌤️ 上海今天多云转阴，温度稍凉，建议增添衣物。", 对应的 html 元素为:xxx . 请仔细思考 push_ui_message 的调用方式, 可以搜索 LangGraph 的UI消息推送的正确用法, 以及 ui.tsx 的作用和机制，来分析这个问题.先给出方案,等我确认后再编写代码.

image.png

image.png

image.png

image.png

image.png

我的另一个工程运行正常(我已经复制该工程源代码到 example 目录下),请参考该工程的相关 graph.py, ui.tsx ,langgraph.json ,pyproject.toml 等关键文件,深入分析思考当前项目的问题原因,先给出分析结果而不开始代码.

我们现在尝试解决,先使用正常项目的 ui.tsx写法,然后参考正常项目的push_ui_message调用格式调整AgentState等.注意 Don't write code unrelated to the current task.

image.png

image.png

整个过程经过了大概 10 次会话，期间一直在各种尝试日志输出和测试，都没有效果，直到最后一次明确让其从 LangGraph Server 、 Agent Chat UI 集成以及消息推送机制的角度进行分析排查后，才真正解决。

最终发现，UI 组件不渲染的问题，经过多轮排查，最终定位到是 push_ui_message 的调用方式和状态定义有问题。修复后得到了正确的页面天气组件渲染：

image.png

这也是在实际开发过程中，遇到复杂问题时 LLM 可能会不停绕圈子的情况。此时人为的介入和判断以及给 AI 提出明确的参考意见非常重要。

5.6 代码重构（一）：实现天气数据前后端分离

5.6.1 问题分析

UI 组件不渲染的问题，经过 Claude Code 的多轮排查，最终成功定位并解决。但是在修复过程中，我们发现一个更深层次的架构问题：为了临时解决问题，天气的数据被硬编码在了前端的 ui.tsx 文件中，而后端只推送了一个简单的文本消息。

这个问题也可以从 LangGraph Studio 的 Graph 模式得到验证：通过上述方式，虽然修复了 Agent Chat UI 页面的天气组件展示样式问题，但是在 LangGraph Studio 的 Graph 模式下，可以看到 AI 返回的信息只包括了文字内容，而并没有返回对应城市的天气信息。

image.png

切换到 Chat 模式下，也可以直观的看到缺失了天气信息数据：

image.png

基于现在的代码实现，这个逻辑也很好理解：因为当前的 graph.py 代码实现中，push_ui_message 推送的信息只包含了上面返回的文字信息，而城市天气信息的数据，是在前端 ui.tsx 中 mock 定义的：

graph.py 代码如下：

image.png

ui.tsx 代码如下：

image.png

image.png

很明显，这违背了“关注点分离”的原则，也不符合实际生产应用的需求。一个更健壮的架构应该是：后端负责提供完整的天气数据，前端只负责根据数据进行渲染。

5.6.2 制定计划

我们再次与 Claude Code 的 Plan Mode 沟通，制定了代码重构计划：将天气数据定义移回后端 graph.py，并通过 push_ui_message 将完整的数据对象推送给前端。

通过上述方式，虽然修复了 Agent Chat UI 页面的天气组件展示样式问题，但是在 LangGraph Studio 的 Graph 模式下，可以看到 AI 返回的信息只包括了文字内容 "这是北京的天气信息"。

基于现在的代码实现，这个逻辑是正确的：因为当前的 `graph.py` 代码实现中，push_ui_message 推送的信息只包含了上面返回的文字信息，而城市天气信息的数据，是在前端 `ui.tsx` 中 mock 定义的。但是最合理的工程化实践（基于**关注点分离原则**）应该是：城市的天气数据信息，应该仍然是定义在后端 `graph.py` 中，和 message 信息一起推送给前端，前端 `ui.tsx` 的 `WeatherComponent` 组件基于推送过来的数据，然后加上样式组装，从而呈现页面的效果。

请根据上述方案，参考 `graph.bak.py` 和 `ui.bak.tsx` 代码（虽然并不能正确渲染，但是实现思路更接近上述表达），制定一个最小化的开发计划，来尽量保证当前正确渲染天气组件样式的前提下，通过尽量小的代码改动实现。注意先规划计划，而不要写代码。

image.png

image.png

f7b51783c7bf78f8de8135f14bd3f209.png

在计划的过程中，我们仍然可以进行补充，得到最终的实施计划：

补充说明一点，后端的 WeatherOutput ，对应的其实就是 graph.py.bak 中的天气信息的定义，在保留前端 ui.tsx 的样式前提下，可能需要参考其 mock 数据的定义增加 icon，gradient（？思考是否合适放在后端）以及对齐前后端的 windSpeed 和 wind的属性名

image.png

image.png

image.png

5.6.3 实施计划

然后切换成 Edit 模式，Claude Code 开始构建 TODO LIST，并完美地执行了这个计划，在保证 UI 正常渲染的前提下，优化了项目的整体架构。

image.png

image.png

image.png

5.6.4 运行验证

Claude Code 完成代码改造后，我们再次运行服务：

首先是 LangGraph Studio 的 Graph 模式，如预期一样正确返回了 message 和天气信息：

image.png

重新打开 Agent Chat UI ，运行正确：

image.png

5.7 代码重构（二）：优化城市名称提取算法

最后，我们还需要对从用户消息中提取城市名称的 extract_city_from_message 函数进行重构。通过对比分析，我们实现了一个更高效、更鲁棒的两层提取算法，并用规范的单元测试覆盖了各种自然语言表达方式。

5.7.1 问题分析

仍然先切换到 Claude Code 的 plan mode，输入以下提示词，来先制定一个开发计划：

经过测试, Agent Chat UI 仍然能够正常显示带动画的天气卡片组件. 继续对比 graph.py.bak的 实现从用户消息中提取城市名称的 extract_city_from_message 和当前的实现, 给出更优的方法，然后制定一个最小化的开发计划，来尽量保证当前正确渲染天气组件样式的前提下，通过尽量小的代码改动实现。注意先不要写代码。  

image.png

image.png

5.7.2 制定计划

整体实施计划如下，符合预期：

image.png

5.7.3 实施计划

image.png

5.7.4 运行验证

完成代码后，运行服务正常：

image.png

6 第五章：成果展示与深度解析

经过多轮开发与重构，我们的智能天气 Agent 终于达到了一个稳定且功能完善的状态。

6.1 最终成果运行展示

  • LangGraph Studio: 在 Studio 中，可以看到 AI 的响应同时包含了 messages（文本消息）和 ui（UI 组件及其数据）两部分，这证明了我们前后端数据分离的重构是成功的。

    image.png

  • Agent Chat UI: 在最终的聊天界面中，当用户提问时，会动态渲染出一张带有动画效果的精美天气卡片，完美实现了生成式 UI 的效果。

    image.png

6.2 项目特性小结

这个看似简单的天气 Agent，在我们的精心打磨下，具备了一个简单的 Agent 应用雏形：

  • 核心特性:
    • ✅ 简单自然语言处理: 两层城市提取算法，支持复杂自然语言表达。
    • ✅ 动态 UI 生成: 后端动态生成带动画效果的 React 天气卡片组件。
    • ✅ 无 LLM 依赖: 使用静态数据和正则表达式，响应速度快，成本低。
    • ✅ 完整测试覆盖: 包含 34 个单元测试，100% 通过率。
  • 基于 Chat 页面支持的自然语言查询方式:
    • 查询模式: " 查询北京的天气 ", " 查看上海天气 "
    • 询问模式: " 北京的天气怎么样？", " 上海天气如何？"
    • 时间表达模式: " 今天北京天气 ", " 现在深圳天气 "
    • 复杂自然语言表达: " 我想知道北京今天的天气情况 ", " 请告诉我上海的天气预报 "
  • UI 组件特性与数据结构:
    • UI 组件包含城市名称、温度、天气状况（带动态图标）、湿度、风速和描述等完整信息。
    • 具备卡片入场动画、图标弹跳、根据天气状况动态调整背景渐变色等视觉效果。
    • 拥有完整的 TypeScript 接口定义，保证了类型安全。
  • 支持的城市列表与容错处理:
    • 当前支持北京、上海、深圳、广州、杭州五个城市。
    • 当用户查询不支持的城市或未指定城市时，会自动回退到默认城市（北京）。
    • 当消息中出现多个城市时，会返回最先被识别到的城市。
  • 数据流与状态管理:
    • 整个应用的数据流是单向且清晰的：用户输入 -> 城市提取 -> 数据查询 -> 状态更新 (包含 AI 消息和 UI 组件) -> 前端渲染。我们使用 LangGraph 的状态管理机制，通过一个严格定义的 AgentState 来确保数据在图的流转过程中的一致性和可追溯性。
  • 测试架构与工具链设计:
    • 我们遵循了“测试金字塔”的原则，以大量的单元测试为基础，覆盖了消息解析、节点功能、UI 数据结构等各个方面。同时，通过在 Makefile 中设计智能命令（PYTHON_CMD := $(shell command -v uv >/dev/null 2>&1 && echo "uv run" || echo "python -m")），实现了开发工具的自动选择，优先使用性能更好的 uv，提升了开发效率。

7 第六章：项目开发管理与总结

在使用 Claude Code 这类 AI Coding 工具的过程中，尤其需要通过规范来约束 AI 的开发过程。

7.1 版本控制：Git 分支管理与代码提交策略

在整个开发过程中，我们遵循了良好的 Git 实践。例如，在进行大的功能修改或重构前，会创建新的特性分支。

建立一个代码基线版本及分支版本，帮我创建

image.png

image.png

image.png

在完成阶段性工作后，我们通过 Claude Code 自定义的 /gitcommit 命令，让 AI 自动总结修改内容并生成规范的 commit message，然后合并分支，推送到远程仓库。

请总结本次修改内容,简单扼要的总结后提交git, git commit message 不超过 200 字 (user)

image.png

然后将当前开发分支同步到主分支：

合并当前分支到主分支

以及推送到远程仓库：

推送到远程仓库 https://github.com/flanliulf/build-genui-agent-with-langgraph-and-claudecode

7.2 文档体系：项目文档的整理与归属

在 Claude Code 的帮助下，通过多次提示词引导，我们为项目建立了清晰的文档体系，包括顶层的 README.md、开发文档 ARCHITECTURE.md、功能文档以及测试文档等，确保了项目的可维护性和可理解性。

过程中涉及的提示词如下：

非常好,现在可以总结一下目前的项目工程。

据上述总结内容,更新相关的文档,注意需要避免错误的信息表达。

技术架构文档 ARCHITECTURE.md 是否应该放到development 目录下?

docs 文档下的 README 和 项目根目录下的 README 的作用有什么不同？

image.png

image.png

8 结尾：开启你的生成式 UI 之旅

至此，我们完整地经历了从项目规划、AI 协同开发、多轮测试、迭代重构到最终部署的全过程。我们收获的不仅仅是一个功能完备的智能天气 Agent，更重要的是，我们亲身体验并掌握了一套与 AI 深度协作的现代化开发工作流。

我们学会了如何将一个模糊的需求，通过与 AI 对话，拆解成清晰的开发计划；

我们看到了 AI 如何根据计划生成代码，并在我们的指导下进行测试和自我修复；

我们也学会运用 Claude Code 的自定义命令、plan 模式、截图定位等一系列开发过程中非常有效的交互技巧；

我们还实践了如何通过不断重构，让项目架构变得更加优雅和健壮。

这种“人与 AI 协同编程”的范式，正在深刻地改变着软件开发的生态。它不再是关于某个特定的工具或框架，而是一种全新的思维方式——将人类的创造力、架构能力与机器强大的执行力、纠错能力完美结合。

希望这篇文章能成为你探索生成式 UI 和 AI 协同开发领域的起点。现在，不妨亲自动手，尝试对这个项目进行扩展，比如为它接入一个真实的天气 API，或者为它设计一个全新的 UI 组件。当你真正开始时，你会发现，未来的软件开发，充满了无限可能。

本文是基于 LangGraph 开发 AI Agent 系列教程的第一篇文章，接下来，会基于该项目进行持续迭代，将 MCP，RAG 等 AI Agent 开发领域的最新技术引入到本项目中，进一步展开讲解如何基于 LangGraph 框架开发智能体应用 Agent。

9 参考资料

  • LangGraph开发指南
  • LangGraph 开发平台
  • LangGraph 应用模板
  • 使用 LangGraph 实现生成式用户界面
  • 基于预构建聊天界面与 LangGraph Agent 交互
  • LangGraph 构建生成式 UI 界面开发演示

10 项目源码

本项目源码已开源到 GitHub： github.com/flanliulf/b… 。

欢迎指正、分享、Star 以及提交 Issue。

鉴于 Claude Code 在国内的使用难度，推荐使用国内的中转平台 GAC。

通过中转平台使用 Claude Code ，简单来说流程如下：

  1. 1. 注册中转平台账号: gaccode.com/signup?ref=… ；
  2. 2. TB 购买天卡或者月卡：
  3. 3. 登录 GAC 中转平台，激活订阅，开始使用 Claude Code 。

本文使用 文章同步助手 同步

avatar
文章
阅读
粉丝