用 LangGraph 构建 AI Agents（2026 版）：保姆级指南

过去两年里，LangGraph 已成为我在 AI 领域构建各类应用的核心工具。无论是聊天机器人、MCP助手、语音机器人还是内部自动化智能体，只要涉及推理、工具调用或多步骤工作流，我几乎都会选择 LangGraph。它反复出现在我的客户项目、个人实验乃至日常的生产系统中。

去年我撰写了第一篇 LangGraph 教程，它很快成为我阅读量最高的文章。自那以后，LangGraph 本身持续演进，其生态日益成熟，我构建智能体的方法也发生了显著变化。因此，是时候推出一份更新的指南了——一份反映 LangGraph 当前面貌，而非一年前状态的指南。

在探讨新模式和更简洁的 2025 API 之前，让我们先回顾 LangGraph 的设计初衷。

什么是 LangGraph？

LangGraph 是一个构建在 LangChain 之上的库，其核心目标是为基于大语言模型的应用提供显式的控制流。与将应用组织成线性流水线不同，LangGraph 将其建模为一个图，使得执行过程可以分支、循环并重新访问早期步骤。

传统的 LangChain 工作流通常是有向无环图：它们只能单向推进直至终止。这对于许多场景已足够，但一旦你需要系统能够迭代、重新评估中间结果，或动态决定下一步行动，这种限制就会显现。许多现实世界的智能体需要循环、重试或根据结果调整行为，而非遵循固定序列。

LangGraph 通过允许图中存在循环来解决这个问题。节点可以被重复访问，决策可以反复做出，控制流被显式处理，而非隐藏在提示词逻辑中。因此，你可以构建能够“规划 → 执行 → 观察 → 继续”的智能体，直至满足停止条件。

Langraph: nodes, states, and edges.

在概念层面，LangGraph 围绕一组精炼的核心抽象构建。一个智能体被定义为一个图，其中所有步骤共享并更新一个共同的状态。

理解状态、节点和边，就基本掌握了 LangGraph 的工作方式。

状态 – 智能体的记忆

状态是在图中流动的共享数据结构。每个节点接收当前状态，并可以返回对其的更新。

你可以将状态视为智能体的累积上下文：消息、决策、工具输出、中间结果，以及任何需要跨步骤保留的信息。由于状态是显式传递的，每个节点都能访问到迄今为止发生的一切，而无需依赖隐式的提示历史。

节点 – 聚焦的行为单元

节点是图的可执行单元。每个节点代表一个单一且定义清晰的操作，例如：
* 调用一个大语言模型
* 调用某个工具或 API
* 转换或验证数据
* 进行路由决策

在实践中，当节点足够小且聚焦时，LangGraph 的效果最佳。只做一件事的节点更易于测试、推理和独立修改，随着智能体的演进也更容易维护。

边 – 控制流

边定义了执行如何从一个节点移动到下一个。它们编码了智能体的控制流，可以是：
* 顺序的（总是移动到下一个节点）
* 条件的（根据状态选择下一个节点）
* 循环的（返回到之前的节点）

通过显式定义边，LangGraph 使控制流以图的形式清晰可见，而不是隐藏在提示逻辑中。这使得理解智能体何时循环、何时分支、何时终止变得更加容易。

理清这些核心概念后，我们将从理论转向一个具体示例。接下来，我们将一步步构建一个基于 Strava 的训练智能体，使用状态、节点和边来建模一个能够根据真实训练数据自动调整的工作流。

分步指南

从你要自动化的流程开始

假设你要构建一个作为个人 Strava 动力训练规划师的 AI 智能体。你的目标明确（例如即将到来的比赛），训练约束清晰（例如每周3次），并且希望计划能根据你实际完成的训练自动调整。

这个智能体应该能够：
* 连接你的 Strava 账户并读取近期活动（跑步、越野跑等）
* 理解你的目标（比赛距离/日期、目标配速/完赛目标、海拔爬升）
* 生成简洁的一周训练计划，遵守进度提升上限与减负周规则
* 对比“计划与实际”以识别缺训、额外训练、过度训练以及过载风险
* 当出现风险信号时调整下一周计划，并解释更改了什么以及原因
* 通过 SMTP（若已配置）发送邮件交付计划；若未配置，则在日志/终端中预览

在 LangGraph 中实现一个智能体，通常遵循相同的五个步骤。

第一步：将工作流拆解为离散步骤

首先，将要自动化的流程拆解为清晰的离散步骤。每个步骤将成为一个节点：一个职责单一的小函数。识别出这些步骤后，我们再将其连接起来，描述智能体的整体流向。

下面的图示展示了这些节点如何在 Strava 训练智能体的工作流中协同工作。

Mermaid Graph

第二步：明确每个步骤要做什么

有了工作流轮廓后，我们需要确定图中每个节点的职责，以及它需要什么信息才能完成工作。

对于每个步骤，我们将决定：
* 它是什么类型的操作
* 它需要什么上下文（静态信息 vs 动态数据）
* 它应该输出什么

由于这个智能体完全自动运行，并且只发送每周邮件，因此我们不包含任何用户输入或人工干预步骤。

Types of nodes (LangGraph Tutorial)

数据步骤

当需要从外部系统检索信息时，使用数据步骤。

同步 Strava 活动

从拉取原始训练数据开始。
* 这个步骤做什么：获取最近约90天的 Strava 活动。
* 需要的上下文：通过访问令牌和客户端ID/密钥进行 Strava 认证。
* 期望结果：包含后续所需指标（日期、时长、距离、配速、海拔、活动类型）的近期活动列表。

LLM 步骤

当智能体需要分析数据、权衡取舍或生成可读输出时，使用 LLM 步骤。

总结近期训练

接下来，将原始活动日志转化为有意义的信号。
* 这个步骤做什么：将活动聚合为更高层次的训练指标，例如每周训练量、高强度训练次数、长距离跑时长以及训练一致性。
* 需要的上下文：来自 Strava 的近期活动、基本定义（什么算高强度训练、长距离跑、周窗口的界定）。
* 期望结果：可用于推理与决策的结构化近期训练摘要。

评估进展与目标

现在评估整体进展。

Generate Next Week Plan

此步骤负责生成实际的训练计划。

• 功能：基于用户目标与近期训练数据，在遵守每周训练次数和进度上限的前提下，生成以公里或时长为单位的一周训练安排。
• 所需上下文：目标（比赛日期、距离、海拔）、每周训练次数（sessions_per_week）以及近期训练摘要（训练量、强度信号）。
• 输出结果：一份结构化的下周计划，包含每次训练的日期、描述、时长和强度，并保留原始生成结果以便后续比较和调整。

Adjust Plan + Add Warnings

此步骤负责在检测到风险时调整计划并生成警示。

• 功能：根据风险评估结果，在必要时修改已生成的训练计划，并在出现过载或不一致时生成简明的警示或注意事项。
• 所需上下文：风险标记、草拟的训练计划。
• 输出结果：最终确定的训练计划，以及一个用户需要注意的简短警示列表。

Compose Weekly Email

此步骤负责将计划转化为可读的沟通内容。

• 功能：生成清晰的周报邮件，内容包含训练计划、简要原理说明，以及任何警示或风险提示。
• 所需上下文：最终训练计划、关键摘要信号、警示列表（如有）。
• 输出结果：可直接发送的周报邮件（包含主题和正文）。

Action Steps

当 Agent 需要与外部系统交互时，使用 Action Steps。

Send Email

此步骤通过交付结果来完成工作流闭环。

• 功能：将每周训练邮件发送给用户。
• 所需上下文：收件人邮箱、邮件主题与正文。
• 输出结果：邮件成功发送并记录日志。

至此，我们已经将所有步骤划分为 LLM、数据处理和动作执行三类，明确了图中每个节点的工作类型。

接下来需要解决一个同样重要的问题：这些节点之间如何共享信息？

为此，我们需要设计 Agent 的 State——这是一份共享内存，允许每个步骤在前一步的成果基础上继续构建。

Step 3: 设计你的 State

明确了每个步骤的功能后，接下来需要决定它们如何共享信息。State 是 Agent 的共享记忆：节点会将其检索、计算或决策的结果写入其中，供下游步骤使用。

决定哪些信息应放入 State 有两个简单原则：
1. 如果信息需要在多个步骤间持久存在，就将其放入 State。
2. 如果信息可以从现有数据中重新推导，则避免存储，在需要时计算即可。

对于我们的 Strava 训练 Agent，需要跟踪以下信息：

• 原始 Strava 活动数据：无法重建，且会被多个步骤复用。
• 训练摘要：如每周训练量、高强度训练次数、长跑时长等聚合信号。
• 目标与约束：静态输入，如比赛日期、距离、每周训练次数。
• 评估结果：对进展、置信度与风险标记的评估，用于驱动下游决策。
• 生成的训练计划：即将发送给用户的下一周计划。
• 执行元数据：用于调试与恢复的时间戳和标识。

以下是 State 的定义：

“`python
from typing import TypedDict, Literal, List, Dict

class TrainingEvaluation(TypedDict):
status: Literal[“on_track”, “behind”, “overloaded”]
confidence: float
risk_flags: List[str]
recommendation: Literal[“keep”, “adjust”, “deload”]

class TrainingSession(TypedDict):
day: str
description: str
duration_min: int
intensity: Literal[“easy”, “moderate”, “hard”]

class StravaTrainingAgentState(TypedDict):
# Raw Strava data
activities: List[Dict] | None
# Aggregated training signals
training_summary: Dict | None
# Goal and constraints
goal: Dict
sessions_per_week: int
# Evaluation output
evaluation: TrainingEvaluation | None
# Generated plan
next_week_plan: List[TrainingSession] | None
# Generated communication
weekly_email: str | None
# Execution metadata
run_id: str
last_sync_timestamp: str
“`

注意，State 仅包含原始或结构化数据。每个节点都从共享 State 中读取数据，完成其特定任务，然后将结果以结构化形式写回。

Step 4: 构建你的 Nodes

有了工作流和 State，我们就可以将每个步骤实现为代码。在 LangGraph 中，一个节点本质上就是一个 Python 函数：它以当前 State 作为输入，并返回其想要更新的字段。这种设计的简洁性是有意为之的——它将你的注意力集中在系统中的数据流上，而非框架的复杂性上。

所有节点的完整实现可在 GitHub 仓库中找到。在本文中，我们将重点剖析最关键的一个节点：Generate Next Week Plan。

为了让示例更清晰，我们使用一个极简的 ChatOpenAI 封装类。这个封装将 LLM 调用逻辑集中管理，以保持节点代码的简洁性。

“`python
from dataclasses import dataclass
from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage

@dataclass
class LLMService:
model: str = “gpt-4o-mini”
temperature: float = 0.1

def __post_init__(self) -> None:
    self.client = ChatOpenAI(model=self.model, temperature=self.temperature)

def structured_completion(self, system: str, user: str) -> str:
    return self.client.invoke(
        [SystemMessage(content=system), HumanMessage(content=user)]
    ).content

“`

generate_next_week_plan 节点是智能体“智能”决策的核心实现点。此前的所有步骤——同步 Strava 数据、汇总训练、评估进展——都是在为此节点准备输入数据。此后的步骤则是对其输出进行细化或传达。该节点的职责非常明确：根据当前状态，生成一份符合既定策略与约束条件的周度训练计划。

该节点完全由状态驱动。它读取运动员的目标、近期训练摘要、当前评估建议（保持、调整或减负）以及每周训练次数，无需额外的上下文信息。

系统提示词将模型角色定位为跑步教练，并设定了明确的规则：只返回结构化的 JSON 数据、严格遵守每周训练次数限制、在非减负场景下限制进度提升上限、描述保持简洁。用户提示词则注入了来自状态的实际上下文信息。

“`python
def generate_next_week_plan(state: StravaTrainingAgentState) -> dict:
“””LangGraph node: generate next week’s training plan.”””
llm: LLMService = _get_service(“llm”)
goal = state.get(“goal”, {})
summary = state.get(“training_summary”, {})
sessions = state.get(“sessions_per_week”, 3)
recommendation = (state.get(“evaluation”) or {}).get(“recommendation”, “adjust”)

system_prompt = (
    "You are a running coach. Return ONLY valid JSON: "
    "a list of sessions with fields: day (Mon-Sun), description, "
    "duration_min, intensity (easy|moderate|hard). "
    "Respect sessions_per_week exactly. Cap progression at +10% unless deloading (20–30% down)."
)

user_prompt = (
    f"Goal: {json.dumps(goal)}n"
    f"Recent summary: {json.dumps(summary)}n"
    f"Recommendation: {recommendation}n"
    f"Sessions per week: {sessions}"
)

plan = llm.structured_completion(system_prompt, user_prompt)
return {"next_week_plan": plan}

“`

Step 5: 构建工作流

实现所有节点后，最后一步是将它们连接成一个可运行的 LangGraph 工作流。至此，智能体的控制流程变得清晰可见：我们定义了节点的执行顺序、分支逻辑以及结束条件。

首先，使用状态模式创建一个 StateGraph，并注册所有节点：

“`python

初始化图

graph = StateGraph(StravaTrainingAgentState)

添加节点

graph.add_node(“sync_strava_activities”, sync_strava_activities)
graph.add_node(“summarize_recent_training”, summarize_recent_training)
graph.add_node(“evaluate_progress_vs_goal”, evaluate_progress_vs_goal)
graph.add_node(“generate_next_week_plan”, generate_next_week_plan)
graph.add_node(“adjust_plan_add_warnings”, adjust_plan_add_warnings)
graph.add_node(“compose_weekly_email”, compose_weekly_email)
graph.add_node(“send_email”, send_email)
“`

接着，添加定义执行流向的边。大多数边是简单的顺序执行：一个节点完成后总是进入下一个节点。

关键点在于 generate_next_week_plan 之后的条件边。此时智能体已生成计划，但后续处理方式并非总是一致。如果评估结果为“保持”，则可以直接发布计划；如果建议是“调整”或“减负”，则需要路由到额外的节点对计划进行适当缓和并附加警示。

在 LangGraph 中，添加条件边需要：
1. 指定分支的起始节点。
2. 定义一个返回路由键的路由函数。
3. 建立从路由键到目标节点的映射。

路由函数从状态中读取 recommendation 字段来决定后续流程：

“`python

添加边

graph.add_edge(START, “sync_strava_activities”)
graph.add_edge(“sync_strava_activities”, “summarize_recent_training”)
graph.add_edge(“summarize_recent_training”, “evaluate_progress_vs_goal”)
graph.add_edge(“evaluate_progress_vs_goal”, “generate_next_week_plan”)

graph.add_conditional_edges(
“generate_next_week_plan”,
lambda state: state.get(“evaluation”, {}).get(“recommendation”, “adjust”),
{
“keep”: “compose_weekly_email”,
“adjust”: “adjust_plan_add_warnings”,
“deload”: “adjust_plan_add_warnings”,
},
)

graph.add_edge(“adjust_plan_add_warnings”, “compose_weekly_email”)
graph.add_edge(“compose_weekly_email”, “send_email”)
graph.add_edge(“send_email”, END)

编译图

app = graph.compile()
“`

最后，连接剩余的节点并编译图，完成工作流的构建。

步骤 6：测试 Agent

要在本地测试整个 Agent，请克隆 GitHub 仓库并按照 README 中的步骤进行设置。创建（或激活）虚拟环境、安装依赖项，并在 .env 文件中配置所需的 Strava 和 OpenAI 凭据。之后，只需运行以下命令即可启动 Agent：

bash
python strava_training_agent.py

每次运行时，Agent 将拉取您近期的 Strava 活动、汇总训练情况、生成下周计划并撰写每周邮件。

SMTP 配置是可选的。如果未设置邮件相关的环境变量，Agent 将打印并记录邮件预览，而不是实际发送邮件。这使您能够在无需搭建邮件基础设施的情况下，端到端地测试完整工作流。

自动化运行

当 Agent 在本地运行良好后，下一步是考虑如何实现自动化运行。由于此工作流每周仅需执行一次，无需常驻基础设施。

对于个人项目和教程而言，GitHub Actions 通常是最简单的选择。仓库中包含一个 weekly-agent.yml 工作流文件，它通过 cron 定时触发，运行与本地相同的脚本。Strava 和 OpenAI（以及可选的 SMTP）凭据存储在加密的 GitHub Secrets 中，由 GitHub 负责执行和日志记录。此方案成本低、可靠，也便于他人复现。

总结

本教程的目标并非构建最复杂的训练系统，而是展示如何使用 LangGraph 以显式、可测试且易于推理的方式来组织智能体工作流。

通过将问题建模为一个图——包含共享状态、小而专注的节点以及清晰定义的控制流——您将得到一个行为可见且可预测的智能体，即使它能够根据输入变化进行自适应调整。这种模式不仅适用于 Strava 示例，还可广泛应用于客服智能体、数据分析助手、内部工具，或任何需要推理、行动与循环的系统。

当然，当前的 Agent 仍有明显的改进空间。在本教程中，我们有意简化了提示设计，以便将重点放在架构上。若在提示设计上投入更多精力——例如增加更丰富的教练语境、更清晰的进度规则、恢复启发式或特定运动的知识——无需修改图结构，即可显著提升训练计划的质量。工作流搭建完成后，提示工程往往是最高效的改进杠杆。

在此基础上，您可以进一步扩展用户反馈回路、引入跨训练周期的长期记忆、集成更多数据源（如睡眠或心率变异性），或增加更严格的安全检查，以便在风险信号累积时暂停进度。

关键在于，所有这些改进都是增量式的。只要您能够将问题拆解为节点、谨慎定义状态，并有意识地“布线”构建图，您就已经掌握了使用 LangGraph 构建稳健、自适应智能体的坚实基础。

关注“鲸栖”小程序，掌握最新AI资讯