在大语言模型应用开发中，智能体（Agent）框架已成为处理复杂任务的核心工具。我将深入解析一个基于LangGraph构建的Plan-and-Execute Agent开源项目，从理论架构到实际操作，全面展示如何利用该框架实现具备规划、执行和迭代优化能力的智能代理系统。

一、Plan-and-Execute架构解析

智能代理系统经历了从简单指令执行到复杂任务规划的发展历程。目前主流的Agent架构主要分为两类：

• ReAct架构：采用"思考-行动-观察"的循环模式，适用于单步或简单多步任务，但在处理需要长期规划的复杂任务时效率较低
• Plan-and-Execute架构：先制定完整计划，再分步执行并动态调整，特别适合需要多步骤协作的复杂任务

我要分享的项目正是基于Plan-and-Execute架构，通过将任务拆解为可执行的步骤序列，实现对复杂研究和报告生成任务的高效处理。

LangGraph作为LangChain生态的重要组成部分，为构建多智能体系统提供了关键支持，比如：

• 状态管理机制：允许Agent在执行过程中保存和更新状态，为多步骤任务提供上下文连续性
• 节点与边的拓扑结构：通过定义节点（功能单元）和边（流转规则），实现复杂的工作流编排
• 循环与条件分支：支持动态决策流程，使Agent能够根据执行结果调整后续行动
• 与LangChain工具生态无缝集成：可直接调用各类工具（如搜索、计算、数据库访问等）

这些特性使LangGraph成为构建Plan-and-Execute Agent的理想选择，能够轻松实现计划制定、任务执行和动态调整的闭环。

刚才聊了很多理论的东西，我们再来说说这个项目的架构情况吧，这个开源项目的架构设计体现了Plan-and-Execute模式的精髓，主要包含四个核心组件：

Plan-and-Execute Agent
├── Planner: 制定执行计划
├── Executor: 执行具体任务
├── Replanner: 分析结果并重新规划
└── State: 统一状态管理（包括文档跟踪）

具体说明：
Planner（规划器）根据用户输入来生成初始执行计划，具备时间感知和工具感知能力，能根据任务复杂度动态调整计划粒度。Executor（执行器）是负责执行计划中的具体步骤，集成搜索工具并能处理文档的创建与修改。而Replanner（重规划器）是分析执行结果，检测执行循环，判断任务是否完成，必要时生成新计划。最后是State（状态管理），它维护全局状态，包括当前计划、已执行步骤、文档草稿和时间信息等。

这种架构的优势在于将复杂任务分解为可管理的步骤，通过动态规划适应执行过程中的变化，同时保持全局任务视野，避免陷入局部最优。

二、环境搭建与核心配置

开发环境准备

这个项目对开发环境有明确要求，需要提前准备：

• Python 3.11+：确保语言特性兼容性
• uv包管理器：替代传统pip的高性能包管理工具
• LangGraph Studio：可视化开发与调试工具

具体安装步骤如下：

1. 克隆项目代码

git clone <repository-url>
cd plan-and-execute

2. 安装uv包管理器

# macOS/Linux系统
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows系统
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv作为新一代包管理器，相比pip具有更快的安装速度和更严格的依赖管理，特别适合复杂项目的环境一致性维护。

3. 安装项目依赖

# 创建虚拟环境并安装依赖
uv sync

# 或安装到现有环境
uv pip install -e .

4. 配置环境变量

cp .env.example .env

编辑.env文件，添加必要的API密钥：

# OpenAI API Key (必需)
OPENAI_API_KEY=sk-...

# Tavily API Key (用于搜索功能)
TAVILY_API_KEY=tvly-...

# LangSmith API Key (可选，用于追踪)
LANGSMITH_API_KEY=lsv2...
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=plan-and-execute

其中，OpenAI API用于模型调用，Tavily API提供搜索能力，LangSmith则用于任务执行的追踪与调试，推荐开启以方便开发过程中的问题排查。

5. 启动LangGraph Studio

# 在项目根目录执行
langgraph dev

# 或指定端口
langgraph dev --port 8123

启动后访问http://localhost:8123即可打开LangGraph Studio界面，该工具提供了可视化的图结构展示、节点调试和状态查看功能，是开发过程中的重要辅助工具。

接下来再说说这个项目的一些核心配置文件是做什么的，这个项目的核心配置集中在几个关键文件中，理解这些文件有助于后续的定制开发：
langgraph.json，这个文件定义了项目的基本结构，配置文件如下：

{
  "dependencies": ["."],
  "graphs": {
    "agent": "agent.graph:graph"
  },
  "env": ".env"
}

该文件指定了依赖关系、图入口点和环境变量文件位置，是LangGraph识别项目结构的关键。

pyproject.toml是项目元数据和依赖配置

[project]
name = "agent"
version = "0.0.1"
dependencies = [
    "langgraph>=0.2.6",
    "python-dotenv>=1.0.1",
]

[project.optional-dependencies]
dev = ["mypy>=1.11.1", "ruff>=0.6.1"]

这里定义了项目的核心依赖和开发依赖，确保了环境的一致性。

**状态定义（state.py）**是核心数据结构

class PlanExecute(TypedDict, total=False):
    input: str  # 用户输入
    plan: List[str]  # 计划步骤
    past_steps: Annotated[List[Tuple], operator.add]  # 已执行步骤
    response: str  # 最终响应
    # 时间上下文字段
    current_utc_date: str
    current_utc_time: str
    current_year: str
    # 文档草稿
    current_draft_report: Optional[str]

状态定义是整个Agent的"记忆"核心，包含了任务处理过程中需要保存的所有关键信息。

三、核心组件代码解析

1. 图结构定义（graph.py）

该文件定义了Agent的工作流程拓扑结构：

# 定义图
workflow = StateGraph(PlanExecute)

# 添加节点
workflow.add_node("planner", plan_step)
workflow.add_node("executor", execute_step)
workflow.add_node("replanner", replan_step)

# 设置入口点
workflow.set_entry_point("planner")

# 定义边
workflow.add_edge("planner", "executor")
workflow.add_edge("executor", "replanner")

# 定义重规划后的条件分支
def should_end(state: PlanExecute):
    if "response" in state and state["response"]:
        return END
    else:
        return "executor"  

workflow.add_conditional_edges(
    "replanner",
    should_end,
    {
        END: END,
        "executor": "executor", 
    }
)

# 编译图
graph = workflow.compile(name="Plan and Execute Agent")

这段代码清晰地定义了Agent的工作流程：
先从planner节点开始，生成初始计划，然后将计划传递给executor节点执行，接着将执行结果传递给replanner节点分析，replanner根据执行情况决定是结束任务还是继续执行新计划。

2. 规划器实现（planner.py）

规划器是生成初始计划的核心组件，其逻辑围绕一个结构化提示词展开：

planner_prompt_template_text = """You are a planning agent. Your primary function is to devise a concise, step-by-step plan..."""

# 构建提示词模板
planner_prompt = ChatPromptTemplate.from_messages(
    [
        ("system", planner_prompt_template_text),
        ("placeholder", "{messages}"),
    ]
)

# 绑定模型与输出结构
planner = planner_prompt | ChatOpenAI(
    model="gpt-4o", temperature=0
).with_structured_output(Plan)

# 规划步骤函数
async def plan_step(state: PlanExecute):
    current_state = get_default_state()
    current_state.update(state)
    
    plan = await planner.ainvoke({
        "messages": [HumanMessage(content=current_state["input"])],
        "current_utc_date": current_state["current_utc_date"],
        "current_utc_time": current_state["current_utc_time"],
        "current_year": current_state["current_year"],
    })
    return {"plan": plan.steps}

规划器的核心能力体现在：
理解工具能力（如TavilySearchResults），支持文档创建和迭代的工作流，根据任务复杂度动态调整计划粒度，考虑时间因素对任务的影响。

3. 执行器实现（executor.py）

执行器负责执行具体步骤，集成了工具调用能力：

# 创建ReAct代理作为执行器
agent_executor = create_react_agent(llm, tools, prompt=executor_system_prompt)

async def execute_step(state: PlanExecute):
    # 状态处理逻辑...
    
    # 执行当前任务
    agent_response_obj = await agent_executor.ainvoke(
        {"messages": [("user", task_input_for_agent_messages)]}
    )
    
    # 处理文档相关任务的结果
    new_draft_report_content = current_draft_content
    if task_is_document_related:
        new_draft_report_content = agent_final_output
    
    return {
        "past_steps": [(current_task_description, agent_final_output)],
        "current_draft_report": new_draft_report_content,
    }

执行器的关键特性是对文档任务的特殊处理，能够识别文档相关操作并更新current_draft_report状态，为报告的渐进式构建提供支持。

4. 重规划器实现（replanner.py）

重规划器是实现动态调整的核心，能够根据执行结果优化后续计划：

async def replan_step(state: PlanExecute):
    # 状态处理...
    
    output_act = await replanner.ainvoke(input_data_for_replanner)

    if isinstance(output_act.action, Response):
        return {
            "response": output_act.action.response,
            "plan": []
        }
    elif isinstance(output_act.action, Plan):
        return {
            "plan": output_act.action.steps,
            "response": ""
        }

重规划器的核心能力包括：
分析执行历史，识别失败步骤并调整策略，基于当前文档状态规划下一步操作，判断任务是否完成，决定终止或继续，避免执行循环，确保任务进展。

四、总结

基于LangGraph的Plan-and-Execute Agent框架为处理复杂任务提供了强大的解决方案。其核心优势在于将规划与执行分离，通过动态重规划机制适应任务过程中的变化，同时保持对全局目标的把握。

对于开发者而言，这个框架提供了一个灵活且强大的基础，可根据具体需求进行定制扩展，快速构建适应不同场景的智能体系统。