LangGraph Agent 开发指南（1~概述）

一、什么是 Agent（智能体）？

1.1 通俗解释

想象你有一个特别聪明的助手，它不仅能和你聊天，还能帮你干活：

• 你说"帮我查一下北京明天的天气"，它会调用天气 API 查询
• 你说"帮我订一张去上海的机票"，它会调用订票系统
• 你说"帮我写一段代码"，它会调用代码执行工具

这就是Agent（智能体）——一个能"动手干活"的 AI。

1.2 正式定义

一个 Agent 由三个核心组件构成：

┌─────────────────────────────────────────────────────────────┐ │ Agent 的组成 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 1. 大语言模型 (LLM) │ │ - 负责"思考"和决策 │ │ - 决定什么时候调用工具、调用哪个工具 │ │ │ │ 2. 工具集 (Tools) │ │ - Agent 可以使用的"技能" │ │ - 比如：搜索、计算、调用 API、执行代码等 │ │ │ │ 3. 提示词 (Prompt) │ │ - 给 Agent 的"指令" │ │ - 定义 Agent 的角色、行为规范等 │ │ │ └─────────────────────────────────────────────────────────────┘

1.3 Agent 的执行循环

Agent 不是"一次对话就结束"，而是在一个循环中持续运行：

┌─────────────────────────────────────────────────────────────┐ │ Agent 执行循环 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ │ │ │ 用户输入 │ │ │ └────┬─────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ ┌──────────┐ │ │ │ LLM 思考 │────▶│ 选择工具 │ │ │ └──────────┘ └────┬─────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ │ │ │ 执行工具 │ │ │ └────┬─────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ │ │ │ 获得结果 │ │ │ └────┬─────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ │ │ │ 任务完成？│ │ │ └────┬─────┘ │ │ 是 │ │ 否 │ │ │ └──────┐ │ │ ▼ │ │ │ ┌──────────┐ │ │ │ │ 返回结果 │ │ │ │ └──────────┘ │ │ │ │ │ │ └──────▶ 回到 LLM 思考 │ │ │ └─────────────────────────────────────────────────────────────┘

简单说：Agent 会不断"思考-行动-观察"，直到完成任务。

二、LangGraph 的核心功能

LangGraph 提供了构建生产级 Agent 系统所需的关键功能：

2.1 记忆管理（Memory）

Agent 需要"记住"之前的对话和状态：

# LangGraph 原生支持记忆 from langgraph.checkpoint.memory import MemorySaver memory = MemorySaver() graph = builder.compile(checkpointer=memory)

2.2 人工干预（Human-in-the-Loop）

Agent 执行过程中可以暂停，等待人工确认：

Agent: 我准备删除这个文件，确认吗？ 人工: 确认 Agent: 已删除

关键特点：

• 可以无限期暂停（不依赖实时连接）
• 支持异步审批
• 可在工作流任意节点干预

2.3 流式输出（Streaming）

实时输出 Agent 的执行过程：

# 流式输出 Agent 状态 for event in graph.stream(input, stream_mode="values"): print(event)

可以流式输出：

• Agent 状态变化
• LLM 生成的 token
• 工具执行结果

2.4 部署工具

LangGraph 提供完整的部署解决方案：

三、高级预构建组件

LangGraph 提供了一系列预构建组件，让你不用从零开始实现 Agent：

3.1 为什么需要预构建组件？

传统方式（从零开始）: - 自己实现状态管理 - 自己实现记忆存储 - 自己实现人工干预 - 自己实现错误处理 ...费时费力 使用预构建组件: - 调用 create_react_agent() 就能创建 Agent - 内置状态管理、记忆、干预等功能 ...快速上线

3.2 核心预构建组件

四、包生态系统

LangGraph 的功能分布在多个包中：

4.1 核心包

4.2 扩展包

五、创建 Agent 的基本方法

5.1 最简单的例子

from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI # 1. 创建 LLM model = ChatOpenAI(model="gpt-4") # 2. 定义工具 def get_weather(city: str) -> str: """查询城市天气""" return f"{city}今天晴天，温度25度" # 3. 创建 Agent agent = create_react_agent( model, tools=[get_weather], ) # 4. 运行 Agent result = agent.invoke({ "messages": [{"role": "user", "content": "北京今天天气怎么样？"}] }) print(result)

5.2 Agent 的内部结构

create_react_agent创建的 Agent 包含以下组件：

┌─────────────────────────────────────────────────────────────┐ │ Agent 内部结构 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ tools: 工具列表 │ │ - Agent 可以调用的函数或 API │ │ │ │ pre_model_hook: 模型调用前的钩子 │ │ - 可以修改消息、添加系统提示等 │ │ │ │ post_model_hook: 模型调用后的钩子 │ │ - 可以添加防护措施、人工干预等 │ │ │ │ response_format: 输出格式约束 │ │ - 可以指定输出为特定的数据结构 │ │ │ └─────────────────────────────────────────────────────────────┘

5.3 可视化 Agent 图

# 查看 Agent 的图结构 agent.get_graph().draw_ascii() # 保存为 PNG png_data = agent.get_graph().draw_mermaid_png() with open("agent_graph.png", "wb") as f: f.write(png_data)

六、Agent vs 传统程序

6.1 对比表

6.2 什么时候用 Agent？

适合用 Agent：

• 任务流程不确定，需要灵活应对
• 需要根据用户输入动态选择工具
• 需要处理开放性问题

不适合用 Agent：

• 流程固定、规则明确
• 不需要 LLM 决策
• 性能要求极高（Agent 有额外开销）

七、最佳实践

7.1 工具设计原则

# 好的工具设计：职责单一、描述清晰 def search_web(query: str) -> str: """搜索网络信息 Args: query: 搜索关键词 Returns: 搜索结果摘要 """ ... # 不好的工具设计：职责混乱 def do_everything(action: str, params: dict) -> dict: """万能工具""" ...

7.2 提示词设计

# 给 Agent 明确的角色和行为规范 system_prompt = """ 你是一个智能助手，负责帮助用户解决问题。 你的能力： 1. 可以搜索网络获取信息 2. 可以进行数学计算 3. 可以查询天气 你的行为规范： 1. 先思考再行动 2. 如果不确定，主动询问用户 3. 完成任务后总结结果 """

7.3 错误处理

# 工具内部做好错误处理 def risky_operation(param: str) -> str: try: result = do_something(param) return result except Exception as e: return f"操作失败: {str(e)}" # Agent 会根据错误信息决定下一步行动

八、常见问题

Q1: Agent 和 ChatBot 有什么区别？

Q2: Agent 会一直循环下去吗？

不会。Agent 有停止条件：

• LLM 认为任务完成
• 达到最大迭代次数
• 遇到错误

Q3: 如何控制 Agent 的成本？

• 限制工具数量
• 设置最大迭代次数
• 使用更便宜的模型
• 缓存常见查询结果

九、延伸阅读

• LangGraph 官方文档 - Agents
• LangGraph 教程 - 创建 Agent
• LangGraph 概念 - 多 Agent 系统

附录：快速开始

安装

pip install langgraph langchain-openai

最小示例

from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI model = ChatOpenAI(model="gpt-4") def calculator(a: int, b: int) -> int: """计算两个数的和""" return a + b agent = create_react_agent(model, tools=[calculator]) result = agent.invoke({ "messages": [{"role": "user", "content": "计算 3 + 5"}] }) print(result["messages"][-1].content)

总结

Agent = LLM + 工具 + 提示词

LangGraph 让你可以：

1. 快速创建 Agent（使用预构建组件）
2. 管理记忆和状态
3. 实现人工干预
4. 部署到生产环境

核心思想：让 AI 不仅能"说话"，还能"做事"。