如果你正在学习 LangChain，却感觉概念太多、实战太少，这篇文章就是为你准备的。2026 年的 LangChain 1.3 已经不再是简单的“LLM 调用框架”，而是真正能帮你构建智能 Agent 的完整工具链。很多人学 LangChain 时最大的困惑就是：LLM 调用和 Agent 到底有什么区别？为什么需要 Deep Agent？这篇文章将用最直白的方式讲清楚这些核心问题。

传统的 LLM 调用就像让一个知识渊博但行动受限的专家回答问题，他只能基于已有知识给出建议。而 Agent 则是给这个专家配了一个执行团队，他可以主动使用工具、访问文件系统、调用 API，甚至创建子团队来并行处理复杂任务。这就是为什么 LangChain 1.3 的重点已经从简单的链式调用转向了 Deep Agent 架构。

本文将带你从零开始理解 LangChain 1.3 的核心变化，重点解析 LLM 调用与 Agent 的本质区别，并通过一个完整的 Deep Agent 项目实战，让你掌握构建真正智能应用的能力。无论你是想入门 LangChain，还是希望将现有项目升级到 Agent 架构，这篇文章都会提供清晰的路径。

1. 这篇文章真正要解决的问题

很多开发者学习 LangChain 时遇到的第一个瓶颈就是概念混淆。看到 LLM、Agent、Chain、Tool 这些术语，很容易陷入“每个词都认识，但组合起来不知道在说什么”的困境。更实际的问题是：我什么时候该用简单的 LLM 调用，什么时候需要构建 Agent？

核心判断：如果你的任务只需要一次性的问答或文本生成，直接调用 LLM 就足够了。但如果你需要系统能够自主执行多步骤任务、使用外部工具、管理长期记忆、或者处理超出单次上下文限制的复杂工作流，那么 Agent 架构就是必选项。

Deep Agent 不是 LangChain 中的一个新组件，而是 LangChain 1.3 推出的完整解决方案。它把之前需要手动组合的各种能力（任务规划、文件系统访问、子代理管理、上下文管理等）打包成了一个开箱即用的“智能体框架”。这意味着你现在可以用几行代码构建出之前需要几百行才能实现的复杂 Agent 系统。

本文将重点解决三个关键问题：

1. 概念澄清：用实际场景说明 LLM 调用与 Agent 的核心差异
2. 技术选型：什么情况下应该选择 Deep Agent 而不是传统方案
3. 实战落地：通过完整项目演示如何构建和部署真正的智能 Agent

2. LangChain 1.3 的核心变化与 Deep Agent 定位

LangChain 1.3 最大的变化是从“组件库”思维转向“解决方案”思维。之前的 LangChain 提供了丰富的构建块，但需要开发者自己组装。Deep Agent 则提供了预设的智能体框架，让开发者能快速构建生产可用的 Agent 系统。

2.1 LangChain、LangGraph、Deep Agent 的关系

理解这三者的关系对正确使用 LangChain 生态至关重要：

• LangChain：提供基础构建块，如模型封装、提示模板、记忆管理、工具调用等
• LangGraph：提供运行时环境，支持持久化执行、流式传输、人工干预等高级特性
• Deep Agent：基于前两者构建的完整 Agent 解决方案，内置了任务规划、文件系统、子代理等能力

简单来说，LangChain 是原材料，LangGraph 是厨房设备，Deep Agent 是已经配好的套餐。对于大多数应用场景，直接从 Deep Agent 开始是最有效率的选择。

2.2 Deep Agent 的核心能力矩阵

Deep Agent 之所以称为"Deep"，是因为它提供了四个层次的深度集成能力：

这种分层设计让 Deep Agent 既能处理简单任务，又能扩展到复杂的企业级应用场景。

3. 环境准备与 Deep Agent 安装

在开始实战之前，我们先确保环境准备就绪。Deep Agent 支持多种模型提供商，本文以 OpenAI 为例进行演示。

3.1 基础环境要求

# 确认 Python 版本（建议 3.9+） python --version # 创建虚拟环境（推荐） python -m venv langchain_env source langchain_env/bin/activate # Linux/Mac # 或 langchain_env\Scripts\activate # Windows # 安装核心依赖 pip install deepagents langchain-openai

3.2 模型 API 配置

Deep Agent 支持多种模型提供商，你需要根据选择的模型配置相应的 API 密钥：

# 方式1：设置环境变量（推荐） import os os.environ["OPENAI_API_KEY"] = "your-api-key-here" # 方式2：在代码中直接配置 from deepagents import create_deep_agent # 后续创建 Agent 时会指定模型

3.3 验证安装

创建一个简单的验证脚本来测试环境是否正常：

# test_installation.py from deepagents import create_deep_agent def simple_tool(): """一个简单的测试工具""" return "工具调用成功！" try: agent = create_deep_agent( model="openai:gpt-4", # 根据你的可用模型调整 tools=[simple_tool], system_prompt="你是一个测试助手" ) print("✅ Deep Agent 环境配置成功") except Exception as e: print(f"❌ 配置失败: {e}")

运行这个脚本确认一切正常后再继续下一步。

4. LLM 调用 vs Agent：本质区别与适用场景

这是本文最重要的概念区分部分。很多人误以为 Agent 只是“能调用工具的 LLM”，实际上两者的架构思维有根本不同。

4.1 传统 LLM 调用模式

# 传统方式：直接调用 LLM from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4") # 单一问答任务 response = llm.invoke("请问今天北京的天气如何？") print(response.content)

这种模式的局限性：

• 只能基于训练数据回答，无法获取实时信息
• 无法执行实际操作（如查询数据库、调用 API）
• 复杂任务需要手动拆解和多次调用
• 无法保持跨会话的记忆一致性

4.2 Agent 工作模式

from deepagents import create_deep_agent def get_weather(city: str) -> str: """获取城市天气的真实工具函数""" # 这里应该是调用天气 API 的实际实现 return f"{city}的天气是晴朗，25°C" def search_flights(departure: str, destination: str) -> str: """搜索航班信息的工具""" return f"找到从{departure}到{destination}的航班：CA123, 10:00-12:00" # 创建具有多种能力的 Agent travel_agent = create_deep_agent( model="openai:gpt-4", tools=[get_weather, search_flights], system_prompt="你是一个专业的旅行规划助手", memory=True # 启用记忆功能 ) # Agent 可以自主规划并执行多步骤任务 result = travel_agent.invoke({ "messages": [{ "role": "user", "content": "帮我规划一个北京到上海的商务旅行，需要知道天气和航班信息" }] })

Agent 的核心优势：

• 自主规划：能拆解复杂任务并决定执行顺序
• 工具使用：可以调用外部函数和 API 获取实时信息
• 记忆持久化：跨会话保持上下文一致性
• 错误恢复：在执行失败时尝试替代方案

4.3 何时选择 LLM，何时选择 Agent

根据你的具体需求做技术选型：

选择简单 LLM 调用的场景：

• 一次性问答或文本生成
• 不需要外部数据或工具
• 任务在单次对话中完成
• 对响应延迟要求极高

选择 Agent 的场景：

• 需要多步骤任务规划
• 必须使用外部工具或 API
• 需要长期记忆和上下文管理
• 任务可能失败需要重试机制
• 需要人工干预或审批流程

5. Deep Agent 核心功能实战详解

现在我们来深入 Deep Agent 的各个核心功能，通过具体代码示例理解每个组件的作用。

5.1 工具系统与执行环境

工具是 Agent 与现实世界交互的桥梁。Deep Agent 支持多种类型的工具集成：

from deepagents import create_deep_agent import requests # 定义各种类型的工具 def get_stock_price(symbol: str) -> str: """获取股票价格""" # 模拟 API 调用 return f"{symbol} 当前价格: $150.75" def calculate_compound_interest(principal: float, rate: float, years: int) -> str: """计算复利""" amount = principal * (1 + rate/100) ** years return f"{years}年后，{principal}元将变成{amount:.2f}元" def search_web(query: str) -> str: """网络搜索工具""" # 实际项目中这里会调用搜索 API return f"找到关于'{query}'的搜索结果：..." # 创建多功能 Agent finance_agent = create_deep_agent( model="openai:gpt-4", tools=[get_stock_price, calculate_compound_interest, search_web], system_prompt="你是一个金融分析助手，擅长股票查询和财务计算" ) # Agent 会自主选择需要的工具 response = finance_agent.invoke({ "messages": [{ "role": "user", "content": "我想投资AAPL股票，请帮我查询当前价格，并计算如果投资10000元，5年后按年化8%收益会变成多少" }] })

5.2 虚拟文件系统操作

Deep Agent 内置了完整的文件系统操作能力，这是与传统 LLM 最大的区别之一：

from deepagents import create_deep_agent # 创建具有文件操作能力的 Agent file_agent = create_deep_agent( model="openai:gpt-4", system_prompt="你是一个文件管理助手" ) # Agent 可以执行的文件操作示例 file_operations = """ 请执行以下文件任务： 1. 创建一个名为 "project_notes.txt" 的文件 2. 写入项目的基本信息 3. 读取文件内容确认写入成功 4. 在文件中追加新的笔记 """ result = file_agent.invoke({ "messages": [{"role": "user", "content": file_operations}] })

Deep Agent 支持的文件操作工具包括：

• ls：列出目录内容
• read_file：读取文件（支持大文件分页）
• write_file：创建或覆盖文件
• edit_file：编辑文件内容
• delete：删除文件或目录
• glob：模式匹配查找文件

5.3 权限管理与安全控制

在生产环境中，权限控制至关重要。Deep Agent 提供了声明式的权限管理系统：

from deepagents import create_deep_agent from deepagents.permissions import PermissionRule # 定义权限规则 permission_rules = [ PermissionRule( operations=["read", "write"], paths=["/workspace/*"], # 允许读写工作区 mode="allow" ), PermissionRule( operations=["write"], paths=["*.env", "config/secret*"], # 保护敏感文件 mode="deny" ) ] secure_agent = create_deep_agent( model="openai:gpt-4", permissions=permission_rules, system_prompt="你是一个有受限访问权限的助手" )

这种权限模型让你可以精确控制 Agent 能访问哪些文件，特别适合团队协作或处理敏感数据的场景。

6. 完整项目实战：构建智能文档分析 Agent

现在我们来构建一个完整的 Deep Agent 项目，这个 Agent 能够自动分析文档、提取关键信息并生成报告。

6.1 项目需求分析

我们要构建的文档分析 Agent 需要具备以下能力：

• 读取多种格式的文档（txt, pdf, docx）
• 提取关键信息（日期、人名、公司名等）
• 生成结构化摘要
• 保存分析结果到数据库
• 支持批量处理文档

6.2 工具函数定义

首先定义 Agent 需要的各种工具函数：

import os from pathlib import Path from typing import List, Dict import sqlite3 def read_document(file_path: str) -> str: """读取文档内容，支持多种格式""" path = Path(file_path) if not path.exists(): return f"错误：文件 {file_path} 不存在" if path.suffix == '.txt': return path.read_text(encoding='utf-8') elif path.suffix == '.pdf': # 实际项目中这里应该集成 PyPDF2 或类似库 return f"PDF 文件内容提取: {path.name}" else: return f"支持读取 {path.name} 的内容" def extract_entities(text: str) -> Dict: """从文本中提取实体信息""" # 简化版的实体提取，实际项目可用 NER 模型 entities = { "dates": [], "persons": [], "organizations": [], "key_topics": [] } # 简单的规则提取（实际应用应该用更复杂的方法） import re entities["dates"] = re.findall(r'\d{4}-\d{2}-\d{2}', text) return entities def save_to_database(analysis_result: Dict) -> str: """将分析结果保存到数据库""" conn = sqlite3.connect('document_analysis.db') cursor = conn.cursor() # 创建表（如果不存在） cursor.execute(''' CREATE TABLE IF NOT EXISTS analyses ( id INTEGER PRIMARY KEY AUTOINCREMENT, filename TEXT, entities TEXT, summary TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ''') # 插入数据 cursor.execute(''' INSERT INTO analyses (filename, entities, summary) VALUES (?, ?, ?) ''', ( analysis_result.get('filename', ''), str(analysis_result.get('entities', {})), analysis_result.get('summary', '') )) conn.commit() conn.close() return "分析结果已保存到数据库" def generate_report(analysis_data: Dict) -> str: """生成分析报告""" filename = analysis_data.get('filename', '未知文件') entities = analysis_data.get('entities', {}) report = f""" # 文档分析报告 - {filename} ## 提取的实体信息 - 日期: {len(entities.get('dates', []))} 个 - 人物: {len(entities.get('persons', []))} 个 - 组织: {len(entities.get('organizations', []))} 个 ## 关键主题 {chr(10).join(f'- {topic}' for topic in entities.get('key_topics', []))} ## 分析时间 {analysis_data.get('timestamp', '未知')} """ return report

6.3 创建文档分析 Agent

现在创建完整的文档分析 Agent：

from deepagents import create_deep_agent # 创建文档分析 Agent document_analyzer = create_deep_agent( model="openai:gpt-4", tools=[read_document, extract_entities, save_to_database, generate_report], system_prompt=""" 你是一个专业的文档分析助手。你的任务是： 1. 读取用户指定的文档文件 2. 提取关键实体信息（日期、人名、组织等） 3. 生成结构化分析报告 4. 将结果保存到数据库 请按照步骤执行，并在每个步骤后确认执行结果。 """, memory=True )

6.4 测试 Agent 功能

创建一个测试文档并验证 Agent 功能：

# 创建测试文档 test_doc_content = """ 项目会议纪要 日期：2026-07-15 参会人员：张三、李四、王五 公司：某科技有限公司 会议内容： 1. 讨论了新产品的开发进度 2. 确定了2026-08-01的产品发布计划 3. 分配了各部门的任务职责 下一步行动： - 技术部完成核心功能开发（截止日期：2026-07-25） - 市场部准备推广材料 - 销售部制定销售策略 """ # 保存测试文档 with open("test_meeting.txt", "w", encoding="utf-8") as f: f.write(test_doc_content) # 使用 Agent 分析文档 result = document_analyzer.invoke({ "messages": [{ "role": "user", "content": "请分析 test_meeting.txt 文档，提取关键信息并生成报告" }] }) print("分析结果：") print(result)

6.5 添加批处理能力

扩展 Agent 以支持批量处理多个文档：

def batch_analyze_documents(file_pattern: str) -> str: """批量分析匹配模式的文件""" from glob import glob files = glob(file_pattern) if not files: return "未找到匹配的文件" results = [] for file_path in files: # 对每个文件执行分析 analysis_result = document_analyzer.invoke({ "messages": [{ "role": "user", "content": f"请分析 {file_path} 文档并保存结果" }] }) results.append(f"{file_path}: 分析完成") return f"批量分析完成，处理了 {len(files)} 个文件" # 将批处理工具添加到 Agent document_analyzer_with_batch = create_deep_agent( model="openai:gpt-4", tools=[read_document, extract_entities, save_to_database, generate_report, batch_analyze_documents], system_prompt="你是文档分析助手，支持单文件和批量分析", memory=True )

7. 高级特性：子代理与任务规划

Deep Agent 最强大的功能之一是能够创建子代理来处理复杂任务的分工协作。

7.1 子代理的工作原理

子代理让主 Agent 能够将复杂任务分解并并行处理：

from deepagents import create_deep_agent def research_topic(topic: str) -> str: """研究特定主题的子任务""" return f"{topic}的研究结果：这是一个重要主题，涉及多个方面..." def summarize_findings(details: str) -> str: """总结研究发现的子任务""" return f"总结：{details} 的关键要点是..." # 创建支持任务委托的主 Agent research_agent = create_deep_agent( model="openai:gpt-4", tools=[research_topic, summarize_findings], system_prompt=""" 你是一个研究助手，可以将复杂研究任务分解为子任务。 对于复杂主题，你可以创建子代理来并行研究不同方面。 """, # 启用子代理功能（默认开启） subagents=True ) # 复杂研究任务示例 complex_task = """ 请深入研究"人工智能在医疗领域的应用"这个主题，包括： 1. 医学影像诊断中的AI应用 2. 药物研发中的机器学习技术 3. 电子健康记录分析 4. 远程医疗和可穿戴设备 请分别研究每个子领域，然后汇总成完整报告。 """ result = research_agent.invoke({ "messages": [{"role": "user", "content": complex_task}] })

7.2 任务规划与进度跟踪

Deep Agent 内置了任务规划工具，让 Agent 能够管理复杂任务的工作流：

from deepagents import create_deep_agent def collect_data(source: str) -> str: """数据收集工具""" return f"从{source}收集到的数据" def analyze_data(data: str) -> str: """数据分析工具""" return f"分析结果：{data}的模式和趋势" def generate_insights(analysis: str) -> str: """生成洞察工具""" return f"基于分析的业务洞察：{analysis}" planning_agent = create_deep_agent( model="openai:gpt-4", tools=[collect_data, analyze_data, generate_insights], system_prompt=""" 你是一个数据分析专家，擅长使用任务规划来管理复杂分析项目。 对于多步骤任务，请先制定计划，然后按步骤执行。 """, # 启用任务规划能力 task_planning=True ) # 使用任务规划处理复杂分析 analysis_request = """ 我们需要分析公司上个季度的销售数据，包括： 1. 从数据库和CRM系统收集数据 2. 分析销售趋势和客户行为 3. 生成业务洞察和改进建议 请制定详细计划并执行。 """

8. 部署与生产环境注意事项

将 Deep Agent 部署到生产环境需要考虑多个重要因素。

8.1 配置管理最佳实践

使用环境变量和配置文件管理敏感信息：

# config.py import os from dataclasses import dataclass @dataclass class AgentConfig: model_provider: str model_name: str api_key: str max_tokens: int = 4000 temperature: float = 0.1 def load_config() -> AgentConfig: """从环境变量加载配置""" return AgentConfig( model_provider=os.getenv("MODEL_PROVIDER", "openai"), model_name=os.getenv("MODEL_NAME", "gpt-4"), api_key=os.getenv("API_KEY"), max_tokens=int(os.getenv("MAX_TOKENS", "4000")), temperature=float(os.getenv("TEMPERATURE", "0.1")) ) # 使用配置创建 Agent config = load_config() production_agent = create_deep_agent( model=f"{config.model_provider}:{config.model_name}", system_prompt="生产环境助手", # 其他生产环境配置... )

8.2 错误处理与重试机制

在生产环境中，健壮的错误处理至关重要：

import logging from tenacity import retry, stop_after_attempt, wait_exponential # 配置日志 logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) @retry( stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10) ) def safe_agent_invoke(agent, message, max_retries=3): """带重试机制的 Agent 调用""" try: response = agent.invoke({ "messages": [{"role": "user", "content": message}] }) return response except Exception as e: logger.error(f"Agent 调用失败: {e}") if max_retries > 0: logger.info(f"重试中... 剩余重试次数: {max_retries}") return safe_agent_invoke(agent, message, max_retries-1) else: raise # 在生产代码中使用安全调用 try: result = safe_agent_invoke(production_agent, "用户请求") print("执行成功:", result) except Exception as e: logger.error("所有重试均失败，需要人工干预") # 触发告警或人工处理流程

8.3 性能监控与优化

监控 Agent 的性能指标以便优化：

import time from functools import wraps def monitor_agent_performance(func): """Agent 性能监控装饰器""" @wraps(func) def wrapper(agent, *args, **kwargs): start_time = time.time() try: result = func(agent, *args, **kwargs) execution_time = time.time() - start_time # 记录性能指标 logger.info(f"Agent 执行时间: {execution_time:.2f}秒") # 这里可以添加更多监控逻辑 # 如 token 使用量、工具调用次数等 return result except Exception as e: logger.error(f"Agent 执行失败: {e}") raise return wrapper # 应用监控 @monitor_agent_performance def monitored_agent_call(agent, message): return agent.invoke({ "messages": [{"role": "user", "content": message}] })

9. 常见问题与解决方案

在实际使用 Deep Agent 过程中，你可能会遇到以下常见问题：

9.1 配置与安装问题

9.2 运行时问题

9.3 性能优化问题

9.4 安全与权限问题

# 安全最佳实践示例 from deepagents import create_deep_agent from deepagents.permissions import PermissionRule # 严格的权限控制 security_rules = [ PermissionRule(operations=["read", "write"], paths=["/workspace/*"], mode="allow"), PermissionRule(operations=["write"], paths=["/system/*", "*.env"], mode="deny"), PermissionRule(operations=["execute"], paths=["*"], mode="deny") # 禁止代码执行 ] secure_agent = create_deep_agent( model="openai:gpt-4", permissions=security_rules, interrupt_on={"delete": True, "write_file": True}, # 关键操作需要人工审批 system_prompt="安全限制下的助手" )

10. 最佳实践总结

通过本文的完整实践，我们总结了以下 Deep Agent 最佳实践：

10.1 架构设计原则

1. 渐进式复杂度：从简单任务开始，逐步增加 Agent 能力
2. 工具模块化：每个工具函数职责单一，便于测试和重用
3. 权限最小化：按需授予权限，保护系统安全
4. 错误隔离：使用子代理隔离可能失败的任务

10.2 开发工作流

1. 本地测试优先：在本地充分测试后再部署到生产环境
2. 版本控制：对 Agent 配置、工具函数和提示模板进行版本管理
3. 监控告警：建立完整的监控体系，及时发现和处理问题
4. 持续优化：基于使用数据不断优化提示词和工具设计

10.3 性能调优要点

1. 模型选择：根据任务复杂度选择合适的模型规格
2. 提示优化：精简有效的提示词能显著提升性能
3. 上下文管理：合理使用记忆和总结功能控制 token 使用
4. 并行处理：对独立任务使用子代理并行执行

Deep Agent 代表了 LangChain 发展的新方向，它将之前分散的 AI 能力整合成了完整的智能体解决方案。通过本文的实践指南，你应该能够开始构建自己的智能 Agent 应用，并在实际项目中体会这种新架构带来的效率提升。

真正的价值不在于掌握某个具体工具，而在于理解 LLM 与 Agent 的本质区别，从而在合适的场景选择合适的技术方案。随着 AI 技术的快速发展，这种架构思维将比任何具体实现都更加重要。