---

关于作者

• 深耕领域：大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调
• 技术栈：Python | RAG (LangChain / Dify + Milvus) | FastAPI + Docker
• 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让 AI 交互更智能，让技术落地更高效」
欢迎技术探讨与项目合作，解锁大模型与智能交互的无限可能！

---

摘要：本文将带领读者从零开始，使用LangChain 1.0搭建第一个Agent应用。涵盖环境搭建、模型配置、工具定义、ReAct循环详解等核心内容，帮助读者快速掌握Agent开发的基础技能。

一、环境准备与依赖安装

1.1 Python环境要求

LangChain 1.0要求Python 3.11或更高版本。在开始之前，请确保您的环境满足要求：

# 检查Python版本
python --version
# 输出: Python 3.11.14

1.2 核心依赖安装

LangChain 1.0采用模块化设计，根据需求安装相应的包：

# 核心依赖
pip install langchain==1.0.8
pip install langchain-core==1.0.7
pip install langchain-community==0.4.1

# 模型支持（按需选择）
pip install langchain-openai==1.0.2      # OpenAI模型
pip install langchain-deepseek==1.0.0    # DeepSeek模型
pip install langchain-ollama==1.0.0      # Ollama本地模型

# 工具扩展
pip install langchain-tavily==0.2.13     # Tavily搜索
pip install langchain-mcp-adapters==0.1.13  # MCP协议支持

# 记忆存储（生产环境）
pip install langgraph-checkpoint-postgres  # PostgreSQL持久化

1.3 环境变量配置

创建 .env文件管理API密钥：

# OpenAI配置
OPENAI_API_KEY=your_openai_api_key

# DeepSeek配置
DEEPSEEK_API_KEY=your_deepseek_api_key

# Tavily搜索配置
TAVILY_API_KEY=your_tavily_api_key

# 高德地图MCP配置
AMAP_MAPS_API_KEY=your_amap_api_key

加载环境变量：

from dotenv import load_dotenv

# 加载.env环境变量
load_dotenv(override=True)

1.4 模型初始化封装

为了统一管理和限速，建议封装模型初始化函数：

from langchain.chat_models import init_chat_model
from langchain_core.rate_limiters import InMemoryRateLimiter

# 配置速率限制器
rate_limiter = InMemoryRateLimiter(
    requests_per_second=5,       # 每秒最多5个请求
    check_every_n_seconds=1.0    # 每1秒检查一次
)

def load_chat_model(
    model: str,
    provider: str,
    temperature: float = 0.7,
    max_tokens: int | None = None,
    base_url: str | None = None,
):
    """
    统一模型加载函数
  
    Args:
        model: 模型名称，如"gpt-4o-mini"
        provider: 模型提供商，如"openai"
        temperature: 温度参数，控制随机性
        max_tokens: 最大生成token数
        base_url: 自定义API地址
  
    Returns:
        配置好的ChatModel实例
    """
    return init_chat_model(
        model=model,
        model_provider=provider,
        temperature=temperature,
        max_tokens=max_tokens,
        base_url=base_url,
        rate_limiter=rate_limiter  # 自动限速
    )

二、第一个Agent应用：天气查询助手

2.1 应用场景分析

我们将创建一个天气查询助手，它能够：

1. 理解用户查询天气的意图
2. 调用天气查询工具获取数据
3. 整合结果并生成自然语言回答

2.2 完整代码实现

from langchain.agents import create_agent
from langchain_core.tools import tool

# ============ 步骤1：定义工具 ============
@tool
def get_weather(city: str) -> str:
    """
    获取指定城市的天气信息
  
    Args:
        city: 城市名称，如"北京"、"上海"
  
    Returns:
        该城市的天气描述
    """
    # 模拟天气数据库
    weather_data = {
        "北京": "晴朗，气温25°C",
        "上海": "多云，气温28°C",
        "广州": "小雨，气温30°C",
        "深圳": "阴天，气温29°C"
    }
    return f"{city}的天气是：{weather_data.get(city, '未知')}"

# ============ 步骤2：初始化模型 ============
model = load_chat_model(
    model="gpt-4o-mini",
    provider="openai",
    temperature=0  # 天气查询需要确定性输出
)

# ============ 步骤3：创建Agent ============
agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="""
    你是一个专业的天气助手。
    当用户询问天气时，使用get_weather工具查询。
    回答要简洁明了，包含城市、天气状况和温度。
    """
)

# ============ 步骤4：运行Agent ============
result = agent.invoke({
    "messages": [{"role": "user", "content": "北京今天天气怎么样？"}]
})

print(result['messages'][-1].content)
# 输出: 北京今天天气晴朗，气温25°C。

2.3 代码解析

@tool装饰器

@tool是LangChain中最简单、最直观的工具创建方式：

@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    ...

核心特性：

• 自动参数推断：基于函数签名自动生成工具的参数schema
• 简化配置：只需提供工具名称和描述即可快速创建
• 同步执行：默认支持同步函数调用

技术概述：

• 代码简洁，一行装饰器即可完成工具注册
• 无需复杂的类继承和配置
• 与Python函数无缝集成，开发效率高

适用场景：

• 快速原型验证
• 简单工具实现
• 开发测试阶段

三、ReAct范式与执行循环详解

3.1 什么是ReAct

ReAct（Reasoning and Acting）是一种将推理（Reasoning）和行动（Acting）结合起来的Agent范式。它强调"推理—行动—观察"的闭环：

1. Thought（推理）：大模型基于当前输入和历史记录进行思考，决定下一步行动
2. Action（行动）：大模型选择一个工具并构造输入参数
3. Observation（观察）：工具被执行，其返回结果作为观察值
4. 循环决策：Agent将新的观察结果纳入上下文，进入下一轮循环

3.2 ReAct执行流程可视化

3.3 使用流式输出观察ReAct过程

from langchain.agents import create_agent
from langchain_core.tools import tool

# 定义工具
@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    weather_data = {
        "北京": "晴朗，气温25°C",
        "上海": "多云，气温28°C"
    }
    return f"{city}的天气是：{weather_data.get(city, '未知')}"

@tool
def calculate(expression: str) -> str:
    """计算数学表达式"""
    try:
        result = eval(expression)
        return f"计算结果是：{result}"
    except Exception as e:
        return f"计算出错：{str(e)}"

# 创建Agent
agent = create_agent(
    model=load_chat_model(model="gpt-4o-mini", provider="openai"),
    tools=[get_weather, calculate],
    system_prompt="你是一个多功能助手，可以查询天气和进行数学计算。"
)

# 流式输出观察执行过程
config = {"configurable": {"thread_id": "demo_001"}}

for step in agent.stream(
    {"messages": [{"role": "user", "content": "北京和上海气温差多少度？"}]},
    config=config,
    stream_mode="values"  # 返回每个步骤的完整状态
):
    message = step["messages"][-1]
    message.pretty_print()
    print("-" * 50)

输出示例：

================================ Human Message =================================

北京和上海气温差多少度？
--------------------------------------------------
================================== Ai Message ==================================
Tool Calls:
  get_weather (call_xxx)
 Call ID: call_xxx
  Args:
    city: 北京
  get_weather (call_yyy)
 Call ID: call_yyy
  Args:
    city: 上海
--------------------------------------------------
================================= Tool Message =================================
Name: get_weather

北京的天气是：晴朗，气温25°C
--------------------------------------------------
================================= Tool Message =================================
Name: get_weather

上海的天气是：多云，气温28°C
--------------------------------------------------
================================== Ai Message ==================================

北京气温25°C，上海气温28°C，两地相差3°C。
--------------------------------------------------

四、网络搜索工具实战

4.1 Tavily搜索集成

Tavily是一个专门为AI应用设计的搜索引擎，提供结构化、高质量的搜索结果。

from langchain.agents import create_agent
from langchain_community.tools.tavily_search import TavilySearchResults

# 初始化Tavily搜索工具
web_search = TavilySearchResults(max_results=2)

# 创建模型
model = load_chat_model(model="deepseek-chat", provider="deepseek")

# 创建Agent
agent = create_agent(
    model=model,
    tools=[web_search],
    system_prompt="你是一名多才多艺的智能助手，可以调用工具帮助用户解决问题。"
)

# 运行Agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "请帮我查询2024年诺贝尔物理学奖得主是谁？"}]
})

print(result['messages'][-1].content)

输出结果：

根据搜索结果，2024年诺贝尔物理学奖得主已经揭晓：

**2024年诺贝尔物理学奖得主：**

1. **约翰·霍普菲尔德 (John J. Hopfield)** - 美国科学家，普林斯顿大学教授
2. **杰弗里·欣顿 (Geoffrey E. Hinton)** - 英国裔加拿大科学家，多伦多大学教授

**获奖理由：**
他们因"为利用人工神经网络进行机器学习做出的基础性发现和发明"而获奖。
...

4.2 常用内置工具列表

LangChain提供了丰富的内置工具：

工具名	Python类	作用
python_repl	PythonREPLTool	执行Python代码
shell	ShellTool	执行命令行
requests_get	RequestsGetTool	HTTP GET请求
requests_post	RequestsPostTool	HTTP POST请求
bing_search	BingSearchRun	Bing搜索
serper	GoogleSerperRun	Google搜索
tavily_search	TavilySearchResults	Tavily搜索
sql_db_query	QuerySQLDatabaseTool	SQL查询
retriever	VectorStoreTool	RAG检索

五、create_agent核心参数详解

5.1 参数配置最佳实践

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

# 创建内存检查点（短期记忆）
checkpointer = InMemorySaver()

agent = create_agent(
    # ========== 三要素（必需）==========
    model=model,                          # 推理引擎
    tools=[tool1, tool2],                 # 执行能力
  
    # ========== 行为准则 ==========
    system_prompt="""
    你是一个专业的AI助手。
    规则：
    1. 严格根据工具描述选择工具
    2. 没有合适工具时回答"无合适工具"
    3. 回答要简洁准确
    """,
  
    # ========== 扩展配置 ==========
    middleware=[logging_middleware],      # 功能扩展
    checkpointer=checkpointer,            # 短期记忆
  
    # ========== 运行限制 ==========
    recursion_limit=10                    # 最大迭代次数
)

# 配置会话
config = {
    "configurable": {"thread_id": "user_123"},
    "recursion_limit": 5  # 最多5次迭代
}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "查询内容"}]},
    config=config
)

5.2 递归限制说明

recursion_limit用于控制Agent的最大迭代次数，防止无限循环：

# 限制最大3次循环
config = {
    "configurable": {"thread_id": "limit_demo"},
    "recursion_limit": 3  # 最多3次迭代
}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "LangChain 1.0发布日期"}]},
    config=config
)

注意事项：

• 迭代次数包括所有Thought-Action-Observation循环
• 达到限制后Agent会返回当前最佳结果
• 生产环境建议设置合理的限制值（通常5-10次）

六、流式输出模式详解

6.1 stream_mode参数对比

模式	输出内容	使用场景	优点	缺点
values	每步后的完整状态	调试Agent执行流程	状态完整，可追溯	数据量大
updates	仅状态变更部分	前端增量更新UI	数据量小，传输快	需手动维护状态
messages	LLM生成的token流	实时显示打字效果	响应即时	不包含工具调用信息
custom	工具函数自定义输出	插入业务日志	灵活控制	需手动调用stream writer

6.2 values模式实战

# 流式输出，实时观察推理过程
for step in agent.stream(
    {"messages": [{"role": "user", "content": "北京和上海的天气怎么样？"}]},
    config=config,
    stream_mode="values"    # 返回每个step步骤的完整消息列表
):
    # 获取最新消息并格式化打印
    message = step["messages"][-1]
    message.pretty_print()
    print("-" * 50)

6.3 监控Agent执行时间

import time

start = time.time()
steps = 0

for chunk in agent.stream(..., stream_mode="values"):
    steps += 1
    elapsed = time.time() - start
    print(f"步骤 {steps} 耗时：{elapsed:.2f}s")

print(f"总耗时：{time.time() - start:.2f}s，总步骤：{steps}")

七、常见问题与解决方案

7.1 工具不被调用

问题现象：Agent直接回答，没有调用工具

解决方案：

1. 检查工具描述是否清晰
2. 在system_prompt中强制要求使用工具
3. 使用支持Function Calling的模型（如GPT-4o）

agent = create_agent(
    model=model,
    tools=tools,
    system_prompt="""
    你必须使用工具来回答用户问题。
    严禁直接回答，必须通过工具获取信息。
    """
)

7.2 工具调用错误

问题现象：Agent选择了错误的工具或参数

解决方案：

1. 优化工具描述，明确使用场景
2. 使用StructuredTool进行参数校验
3. 添加工具路由机制

7.3 循环次数过多

问题现象：Agent陷入无限循环

解决方案：

1. 设置 recursion_limit限制
2. 优化system_prompt，明确终止条件
3. 使用中间件监控循环次数

八、总结

本文详细介绍了LangChain 1.0 Agent的基础实战：

主题	核心内容
环境搭建	Python 3.11+、核心依赖安装、模型初始化封装
第一个Agent	天气查询助手的完整实现
ReAct范式	推理-行动-观察循环详解
网络搜索	Tavily搜索工具集成
核心参数	create_agent参数配置与最佳实践
流式输出	不同stream_mode的使用场景

在下一篇文章中，我们将深入探讨工具集成的高级用法，包括三种工具定义方式对比、多工具协同使用以及MCP协议接入。