🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

在实际 AI 应用开发中，很多开发者都听说过 AI Agent 的概念，但往往停留在“知道它能自主完成任务”的层面，对于如何从零开始构建一个具备实际能力的 Agent 感到无从下手。LangChain 作为当前构建大模型应用最流行的框架之一，其核心价值正是为开发者提供了将大语言模型（LLM）与工具、记忆、逻辑流组合成智能体的标准化“积木”。本文将深入解析 LangChain 的核心工作机制，并带领你从环境搭建开始，一步步动手构建一个能理解指令、使用工具、并记住上下文的 AI Agent。无论你是希望将 AI 能力集成到现有业务系统，还是想探索智能体开发的更多可能性，理解 LangChain 的工作流都是关键的第一步。

1. 理解 AI Agent 与 LangChain 的核心概念

在动手之前，我们需要先厘清几个核心概念，这能帮助你在后续的编码和调试中，清楚地知道每一行代码在 Agent 系统中扮演的角色。

1.1 什么是 AI Agent？

AI Agent 不是一个单一的技术，而是一个由多个组件协同工作的系统。你可以把它想象成一个虚拟的“数字员工”。这个员工（Agent）拥有一个“大脑”（LLM），负责理解和规划任务；一个“备忘录”（Memory），用来记住之前的对话和结果；以及一个“工具箱”（Tools），里面装着各种它能调用的技能，比如搜索网络、查询数据库、执行代码等。Agent 的核心工作流是：接收用户指令 -> 大脑思考（可能调用工具）-> 执行动作 -> 观察结果 -> 再次思考 -> 直到任务完成并给出最终答案。

与简单的“一问一答”式聊天机器人不同，一个真正的 Agent 具备 自主性 （能拆解复杂任务）、 工具使用能力 （能调用外部 API 或函数）和 持续性 （能在多轮对话中保持上下文连贯）。例如，当你要求“帮我查一下北京明天的天气，然后根据天气推荐一个室内活动，最后把推荐结果总结成邮件草稿”时，一个合格的 Agent 应该能自动执行“查询天气”、“搜索活动推荐”、“撰写邮件”这三个步骤。

1.2 LangChain 扮演什么角色？

LangChain 是一个开源框架，它的目标不是提供一个现成的、开箱即用的超级 AI，而是提供一套标准化的组件和接口，让开发者能够像搭积木一样，快速、灵活地构建基于大语言模型的应用，尤其是 Agent。

LangChain 的核心抽象是 Chain（链） 。一个链就是将多个组件（如 LLM、提示词模板、工具、内存）按特定顺序连接起来的工作流。而 Agent 在 LangChain 中是一种特殊类型的链，它引入了一个关键组件： AgentExecutor 。这个执行器负责协调 LLM（负责决策）、工具（负责执行）和内存（负责记录）之间的循环交互。

简单来说，LangChain 帮你解决了以下工程难题：

  • 标准化接口 ：无论底层使用 OpenAI 的 GPT、Anthropic 的 Claude 还是开源的 Qwen，你都可以通过统一的 ChatModel 接口调用。
  • 工具抽象 ：将任何函数（如 google_search 、 sql_query ）包装成 Agent 可以理解和调用的标准化 Tool 。
  • 上下文管理 ：提供了多种 Memory 组件，方便地管理对话历史、缓存中间结果。
  • 工作流编排 ：通过 Chain 和 Agent 将上述组件串联成复杂的推理流程。

1.3 LangChain 与 LangGraph 的区别

在搜索热词中， langgraph 频繁出现。LangGraph 是 LangChain 团队推出的另一个库，它建立在 LangChain 之上，专注于构建 有状态、多参与者的复杂工作流 。

你可以这样理解它们的定位：

  • LangChain ：侧重于构建 单线程、线性或简单循环 的智能体。例如，一个根据用户问题决定调用哪个工具并返回答案的客服助手。
  • LangGraph ：使用图（Graph）的概念来建模工作流，节点代表步骤（如调用LLM、执行工具），边代表步骤间的流转条件。它擅长处理 具有分支、循环、并行和持久化状态 的复杂场景。例如，一个模拟多角色辩论的仿真系统，或者一个需要严格按步骤（创建工单 -> 分配人员 -> 处理 -> 复核）执行的审批流程。

对于入门和大多数常规 Agent 场景，LangChain 的 AgentExecutor 已经足够强大和易用。当你需要构建像流程图一样清晰、带有复杂状态转移逻辑的应用时，才需要考虑 LangGraph。本文将以 LangChain 的 Agent 为核心进行讲解。

2. 环境准备与依赖配置

我们将使用 Python 作为开发语言。请确保你的开发环境满足以下要求。

2.1 基础环境检查与搭建

首先，确认你的系统已安装 Python。建议使用 Python 3.8 至 3.11 版本，这些版本与主流 AI 库的兼容性最好。

打开终端（或命令提示符），执行以下命令检查 Python 和 pip 版本：

python --version
pip --version

接下来，为项目创建一个独立的虚拟环境。这是 Python 开发的最佳实践，可以避免不同项目间的依赖冲突。

# 使用 venv 创建虚拟环境（Windows）
python -m venv langchain_agent_env
# 激活虚拟环境（Windows）
langchain_agent_env\Scripts\activate

# 使用 venv 创建虚拟环境（macOS/Linux）
python3 -m venv langchain_agent_env
# 激活虚拟环境（macOS/Linux）
source langchain_agent_env/bin/activate

激活后，你的命令行提示符前通常会显示环境名称 (langchain_agent_env) 。

2.2 安装核心依赖

我们将安装 LangChain 及其相关依赖。这里我们选择使用 OpenAI 的模型作为 LLM 大脑，因为它接口稳定，易于演示。同时，我们也会安装一个用于构建 Web 接口的轻量级框架 FastAPI 和测试工具 requests 。

在激活的虚拟环境中，运行以下 pip 命令：

pip install langchain langchain-openai
pip install fastapi uvicorn requests
  • langchain : LangChain 核心框架。
  • langchain-openai : LangChain 官方维护的 OpenAI 集成包，包含了调用 GPT 系列模型的 ChatOpenAI 等组件。
  • fastapi & uvicorn : 用于快速创建 API 服务，方便我们通过 HTTP 调用 Agent。
  • requests : 通用的 HTTP 请求库。

注意：如果你计划使用开源模型（如 Qwen），则需要安装对应的集成包，例如 langchain-qianfan （用于百度千帆）、 langchain-community （社区集成）或直接通过 transformers 库加载本地模型。本文为简化流程，使用 OpenAI API 进行演示。

2.3 配置 API 密钥

要使用 OpenAI 的服务，你需要一个有效的 API Key。请前往 OpenAI 平台 注册并获取。

安全警告：永远不要将 API Key 硬编码在代码中或提交到版本控制系统（如 Git）。

推荐的做法是使用环境变量。在终端中临时设置（仅对当前会话有效）：

# macOS/Linux
export OPENAI_API_KEY='你的-api-key-here'

# Windows (Command Prompt)
set OPENAI_API_KEY=你的-api-key-here
# Windows (PowerShell)
$env:OPENAI_API_KEY='你的-api-key-here'

为了代码的可移植性，我们也可以在代码中通过 os.environ 读取，但前提是环境变量已提前设置好。在生产环境中，应使用 .env 文件配合 python-dotenv 库，或使用云服务提供的密钥管理服务。

3. 构建你的第一个 AI Agent：天气查询助手

现在，让我们开始动手构建一个具备实际功能的 Agent。这个 Agent 将能够理解用户关于天气的询问，并调用一个模拟的天气查询工具来回答问题。

3.1 项目结构设计

创建一个清晰的项目目录结构，有助于管理代码。

weather_agent_project/
├── tools/          # 存放自定义工具
│   └── weather_tool.py
├── agents/         # 存放 Agent 定义
│   └── weather_agent.py
├── main.py         # 主程序入口，启动 FastAPI
└── requirements.txt # 依赖列表

首先，在项目根目录下创建 requirements.txt 文件，内容为我们刚才安装的包：

langchain
langchain-openai
fastapi
uvicorn
requests

3.2 创建自定义工具（Tool）

Agent 的强大之处在于能使用工具。我们首先创建一个模拟的天气查询工具。在 tools/weather_tool.py 中：

# tools/weather_tool.py
from langchain.tools import tool
import requests
import json

@tool
def get_current_weather(city: str) -> str:
    """
    根据城市名称查询当前天气情况。
    这是一个模拟工具，实际开发中应接入真实的天气API（如和风天气、OpenWeatherMap）。

    Args:
        city (str): 城市名称，例如 “Beijing“ 或 ”上海”。

    Returns:
        str: 返回该城市的模拟天气信息字符串。
    """
    # 模拟数据 - 实际项目中替换为真实的API调用
    # 示例：response = requests.get(f“https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q={city}”)
    #        data = response.json()
    
    weather_data = {
        “Beijing”: “北京：晴，温度 25°C，湿度 40%，东南风 2级。”,
        “Shanghai”: “上海：多云，温度 28°C，湿度 65%，东风 3级。”,
        “Guangzhou”: “广州：阵雨，温度 30°C，湿度 80%，南风 1级。”,
        “Shenzhen”: “深圳：雷阵雨，温度 31°C，湿度 85%，西南风 2级。”,
    }
    
    # 简单匹配，实际应用需处理更复杂的地理编码
    for key in weather_data:
        if city.lower() in key.lower():
            return weather_data[key]
    
    return f“未找到城市 ‘{city}’ 的天气信息。已知城市：{‘， ’.join(weather_data.keys())}”

# 注意：@tool 装饰器会自动将函数转换为 LangChain 可识别的 Tool 对象。

关键点解释 ：

  1. @tool 装饰器 ：这是 LangChain 提供的便捷方式，能将任何函数包装成一个标准的 Tool 对象。这个对象包含了函数描述（ description ，来自文档字符串），Agent 的 LLM 大脑会根据这个描述来决定何时调用此工具。
  2. 函数签名 ： get_current_weather(city: str) -> str 。清晰的输入输出类型有助于 LangChain 进行类型校验和提示词生成。
  3. 文档字符串（Docstring） ：这部分至关重要！LLM 通过阅读工具的描述来理解它的功能。描述应简洁、准确地说明工具的作用、参数和返回值。
  4. 模拟实现 ：我们使用一个字典来模拟 API 返回。在真实项目中，这里应替换为对真实天气 API（如和风天气、OpenWeatherMap）的 HTTP 请求和响应解析。

3.3 定义 Agent 并集成工具

接下来，在 agents/weather_agent.py 中创建 Agent。我们将使用 LangChain 提供的 create_react_agent 函数，它实现了 ReAct 推理框架，能让 Agent 进行“思考-行动-观察”的循环。

# agents/weather_agent.py
import os
from langchain import hub
from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from tools.weather_tool import get_current_weather

def create_weather_agent():
    """
    创建并返回一个配置好的天气查询 Agent 执行器。
    """
    # 1. 初始化 LLM（大脑）
    # 确保环境变量 OPENAI_API_KEY 已设置
    llm = ChatOpenAI(model=“gpt-3.5-turbo”, temperature=0)
    # temperature 控制创造性，0 表示更确定性的输出，适合工具调用。

    # 2. 准备工具列表
    tools = [get_current_weather]
    # 可以在这里添加更多工具，例如 get_weather_forecast, search_city_info 等。

    # 3. 获取预定义的提示词（Prompt）
    # LangChain Hub 是一个提示词库，我们从里面拉取一个为 ReAct 代理设计好的提示词。
    prompt = hub.pull(“hwchase17/react”)
    # 这个提示词模板已经包含了引导 LLM 按“Thought/Action/Action Input/Observation”格式思考的指令。

    # 4. 创建 Agent
    agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)

    # 5. 创建 Agent 执行器
    # 执行器负责运行 Agent，处理工具调用循环，并管理最大迭代次数以防死循环。
    agent_executor = AgentExecutor(
        agent=agent,
        tools=tools,
        verbose=True,  # 设为 True 可以在控制台看到详细的思考过程，调试时非常有用！
        handle_parsing_errors=True,  # 优雅地处理 LLM 输出解析错误
        max_iterations=5,  # 限制最大迭代次数，防止复杂任务陷入无限循环
        early_stopping_method=“generate”,  # 当 Agent 认为任务完成时，提前停止
    )
    return agent_executor

if __name__ == “__main__”:
    # 本地测试
    agent_executor = create_weather_agent()
    result = agent_executor.invoke({“input”: “上海今天天气怎么样？”})
    print(“Agent 回复：”, result[“output”])

关键点解释 ：

  1. ChatOpenAI ：这是 LangChain 对 OpenAI 聊天模型的封装。 temperature=0 使输出更稳定，减少工具调用时的随机性。
  2. hub.pull(“hwchase17/react”) ：从 LangChain Hub 拉取一个经过社区验证的、专为 ReAct Agent 设计的提示词模板。这避免了我们从零开始编写复杂的提示词。
  3. create_react_agent ：该函数将 LLM、工具和提示词组合成一个具备 ReAct 推理能力的 Agent 对象。
  4. AgentExecutor ：这是 Agent 的“发动机”。它驱动着整个“思考 -> 调用工具 -> 观察结果 -> 再思考”的循环。 verbose=True 是调试神器，它会打印出 LLM 的完整思考链。
  5. 安全参数 ： max_iterations 和 handle_parsing_errors 是生产级应用必须考虑的，它们能防止 Agent 因逻辑错误或意外输入而失控。

3.4 运行与测试 Agent

现在，让我们在本地测试这个 Agent。确保你的虚拟环境已激活，且 OPENAI_API_KEY 环境变量已设置。

在项目根目录下，运行：

python agents/weather_agent.py

你应该会在控制台看到类似以下的详细输出（因为设置了 verbose=True ）：

> Entering new AgentExecutor chain...
Thought: 用户想知道上海的天气。我有一个工具可以查询天气。
Action: get_current_weather
Action Input: {“city”: “Shanghai”}
Observation: 上海：多云，温度 28°C，湿度 65%，东风 3级。
Thought: 我已经通过工具获取了上海的天气信息，现在可以回答用户了。
Action: Final Answer
Action Input: 上海今天的天气是多云，气温 28°C，湿度 65%，东风 3级。

> Finished chain.
Agent 回复： 上海今天的天气是多云，气温 28°C，湿度 65%，东风 3级。

这个输出清晰地展示了 ReAct 框架的工作流程：

  1. Thought（思考） ：LLM 分析用户输入，决定下一步行动（调用工具）。
  2. Action（行动） ：LLM 选择要调用的工具 get_current_weather 。
  3. Action Input（行动输入） ：LLM 生成调用工具所需的参数 {“city”: “Shanghai”} 。
  4. Observation（观察） ：工具执行并返回结果。
  5. 循环 ：LLM 根据观察结果再次思考，发现任务已完成，于是生成最终答案。

尝试一些更复杂的问题，测试 Agent 的推理能力：

# 可以修改 agents/weather_agent.py 中的测试问题
test_questions = [
    “上海和北京的天气分别如何？”,
    “如果深圳下雨，我需要带伞吗？”, # Agent 需要理解“下雨”和“带伞”的关联
    “帮我比较一下北京和广州的天气。”,
]
for question in test_questions:
    print(f“\nQ: {question}”)
    result = agent_executor.invoke({“input”: question})
    print(f“A: {result[‘output’]}”)

4. 为 Agent 添加记忆与持久化 API 服务

基础的 Agent 已经能工作，但它没有记忆，每次对话都是独立的。同时，我们需要一个更易用的接口。接下来，我们为其添加对话记忆，并用 FastAPI 将其包装成 Web 服务。

4.1 集成对话记忆（Memory）

LangChain 提供了多种 Memory 组件。这里我们使用 ConversationBufferMemory ，它会在内存中保存完整的对话历史。

修改 agents/weather_agent.py ，创建一个新的、带记忆的 Agent 构建函数：

# agents/weather_agent.py (新增函数)
from langchain.agents import AgentExecutor, create_react_agent
from langchain.memory import ConversationBufferMemory
from langchain_openai import ChatOpenAI
from langchain import hub
from tools.weather_tool import get_current_weather

def create_weather_agent_with_memory():
    """
    创建并返回一个带有对话记忆的天气查询 Agent 执行器。
    """
    llm = ChatOpenAI(model=“gpt-3.5-turbo”, temperature=0)
    tools = [get_current_weather]
    prompt = hub.pull(“hwchase17/react”)
    
    # 1. 创建记忆组件
    memory = ConversationBufferMemory(memory_key=“chat_history”, return_messages=True)
    # memory_key 是提示词模板中用于引用历史消息的变量名。
    # return_messages=True 表示以消息列表格式返回，适用于聊天模型。

    # 2. 创建 Agent（这一步不变）
    agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)
    
    # 3. 创建 Agent 执行器，并传入 memory
    agent_executor = AgentExecutor(
        agent=agent,
        tools=tools,
        memory=memory,  # 关键：将 memory 对象传递给执行器
        verbose=True,
        handle_parsing_errors=True,
        max_iterations=5,
    )
    return agent_executor

if __name__ == “__main__”:
    # 测试带记忆的 Agent
    agent_executor = create_weather_agent_with_memory()
    
    # 第一轮对话
    result1 = agent_executor.invoke({“input”: “我来自北京。”})
    print(“Round 1 - User: 我来自北京。”)
    print(“Round 1 - Agent:”, result1[“output”])
    print(“Chat History:”, agent_executor.memory.chat_memory.messages) # 查看记忆
    
    # 第二轮对话，Agent 应能引用之前的上下文
    result2 = agent_executor.invoke({“input”: “我家乡的天气怎么样？”})
    print(“\nRound 2 - User: 我家乡的天气怎么样？”)
    print(“Round 2 - Agent:”, result2[“output”])

运行测试，你会发现 Agent 在第二轮对话中，能正确地将“我家乡”关联到第一轮提到的“北京”，从而调用 get_current_weather(“Beijing”) 。这就是记忆的作用。

4.2 使用 FastAPI 创建 Web 服务

为了让其他应用或前端能调用我们的 Agent，我们将其封装成 RESTful API。创建 main.py ：

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from agents.weather_agent import create_weather_agent_with_memory
from langchain.memory import ConversationBufferMemory
import uuid

app = FastAPI(title=“Weather AI Agent API”, description=“一个具备记忆功能的天气查询智能体”)

# 用于存储不同会话的 Agent 执行器实例
session_agents = {}

class ChatRequest(BaseModel):
    message: str
    session_id: str = None  # 客户端可传入 session_id 以维持会话

class ChatResponse(BaseModel):
    response: str
    session_id: str

def get_or_create_agent(session_id: str):
    """根据 session_id 获取或创建一个新的 Agent 执行器。"""
    if session_id not in session_agents:
        # 为每个新会话创建独立的记忆
        memory = ConversationBufferMemory(memory_key=“chat_history”, return_messages=True)
        llm = ChatOpenAI(model=“gpt-3.5-turbo”, temperature=0)
        tools = [get_current_weather] # 需要从 tools 模块导入
        prompt = hub.pull(“hwchase17/react”)
        agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)
        agent_executor = AgentExecutor(
            agent=agent,
            tools=tools,
            memory=memory,
            verbose=True,  # 生产环境可设为 False
            handle_parsing_errors=True,
            max_iterations=5,
        )
        session_agents[session_id] = agent_executor
    return session_agents[session_id]

@app.post(“/chat”, response_model=ChatResponse)
async def chat_with_agent(request: ChatRequest):
    """
    与天气 Agent 对话。
    首次请求可不传 session_id，服务端会生成一个。
    """
    try:
        session_id = request.session_id or str(uuid.uuid4())
        agent_executor = get_or_create_agent(session_id)
        
        # 调用 Agent
        result = agent_executor.invoke({“input”: request.message})
        
        return ChatResponse(response=result[“output”], session_id=session_id)
    except Exception as e:
        raise HTTPException(status_code=500, detail=f“Agent 处理失败: {str(e)}”)

@app.get(“/health”)
async def health_check():
    return {“status”: “healthy”}

if __name__ == “__main__”:
    import uvicorn
    uvicorn.run(app, host=“0.0.0.0”, port=8000)

关键点解释 ：

  1. 会话管理 ：我们使用一个字典 session_agents 来管理不同用户的会话。每个 session_id 对应一个独立的 AgentExecutor 实例，从而拥有独立的对话记忆。这是实现多用户并发对话的基础。
  2. API 设计 ： /chat 端点接收用户消息和可选的 session_id 。如果未提供 session_id ，则生成一个新的。这模拟了 Web 聊天中的会话保持。
  3. 错误处理 ：使用 try...except 捕获 Agent 执行过程中的异常，并通过 FastAPI 的 HTTPException 返回友好的错误信息，避免服务崩溃。
  4. 启动服务 ：使用 uvicorn 作为 ASGI 服务器来运行 FastAPI 应用。

4.3 启动并测试 API 服务

在项目根目录下，运行：

python main.py

服务将在 http://127.0.0.1:8000 启动。你可以使用浏览器访问 http://127.0.0.1:8000/docs 查看自动生成的交互式 API 文档（Swagger UI），并直接在那里测试。

也可以使用 curl 命令或 Python 的 requests 库进行测试：

# test_api.py
import requests
import json

base_url = “http://127.0.0.1:8000“

# 第一轮对话，不提供 session_id
payload = {“message”: “我来自深圳。”}
response = requests.post(f“{base_url}/chat”, json=payload)
data = response.json()
print(“Round 1 Response:”, data[“response”])
session_id = data[“session_id”]
print(“Session ID:”, session_id)

# 第二轮对话，使用上一轮返回的 session_id
payload2 = {“message”: “我家乡的天气适合出门吗？”, “session_id”: session_id}
response2 = requests.post(f“{base_url}/chat”, json=payload2)
data2 = response2.json()
print(“\nRound 2 Response:”, data2[“response”])

运行这个测试脚本，你将看到 Agent 能够跨 API 调用保持对话记忆。

5. 核心工作机制深度解析与高级配置

通过前面的实战，我们已经搭建了一个可运行的 Agent。现在，让我们深入 LangChain Agent 的内部，理解其核心工作机制，并探讨一些高级配置和优化点。

5.1 LangChain Agent 的核心工作流

一个标准的 LangChain Agent（以 AgentExecutor 为例）工作流如下图所示（概念性描述）：

用户输入
    |
    v
[提示词模板 + 记忆 + 工具描述] -> 组装成完整提示词
    |
    v
大语言模型 (LLM)
    |
    v
解析 LLM 输出 -> [Thought, Action, Action Input] 或 [Final Answer]
    |                             |
    | (如果是 Action)             | (如果是 Final Answer)
    v                             v
调用对应工具(Tool)           返回最终答案给用户
    |                             |
    | 获取工具执行结果(Observation) |
    v                             |
重新组装提示词（包含历史）<-------|
    |
    v
进入下一轮循环...

关键组件解析 ：

  1. 提示词模板（Prompt Template） ：这是驱动 LLM 按特定格式（如 ReAct）思考的“剧本”。它通常包含：
    • 给 LLM 的角色设定（“你是一个有帮助的助手…”）。
    • 工具列表及其描述。
    • 对话历史（如果配置了 Memory）。
    • 当前用户输入。
    • 输出格式指令（“请以 Thought/Action/Action Input/Observation 格式回应”）。
  2. 输出解析器（Output Parser） ：负责将 LLM 的文本输出（如 Thought: ... Action: ... ）解析成结构化的数据（如 AgentAction 或 AgentFinish 对象）。 AgentExecutor 依赖解析器来判断下一步是调用工具还是结束。
  3. 工具执行（Tool Execution） ：根据解析出的 Action 和 Action Input ，找到对应的 Tool 对象并执行其函数。
  4. 循环控制 ： AgentExecutor 管理着整个循环，包括检查停止条件（如达到 max_iterations 、解析到 Final Answer 、发生错误等）。

5.2 关键参数调优与问题排查

在实际使用中，你可能会遇到各种问题。下表总结了一些常见问题及其解决方案：

问题现象 可能原因 检查与解决思路
Agent 不调用工具，直接猜测答案 1. 工具描述不清，LLM 不理解何时调用。
2. 提示词模板未有效引导工具使用。
3. LLM 的 temperature 过高，导致输出随机。		 1. 优化工具描述 ：确保工具函数的文档字符串清晰、具体，说明输入输出。
2. 检查提示词 ：使用 hub.pull(“hwchase17/react”) 这类经过验证的模板。
3. 降低 temperature ：尝试设为 0 或 0.1，增加确定性。
4. 开启 verbose 模式 ：查看 LLM 的完整思考链，判断问题出在思考还是解析环节。
Agent 陷入无限循环或重复调用同一工具 1. 任务过于复杂，超出 LLM 规划能力。
2. 工具返回的结果未能提供有效信息，导致 LLM 困惑。
3. max_iterations 设置过高或未设置。		 1. 设置 max_iterations ：务必设置一个合理的上限（如 5-10）。
2. 优化工具输出 ：确保工具返回的信息是结构化、明确的。如果工具失败，应返回清晰的错误信息。
3. 简化任务 ：考虑将复杂任务拆分成多个子 Agent，或使用 LangGraph 编排更可控的工作流。
解析错误： ValueError: Could not parse LLM output: ... LLM 的输出不符合 Output Parser 预期的格式。 1. 启用 handle_parsing_errors=True ：让执行器能优雅处理，尝试让 LLM 重新生成格式正确的输出。
2. 检查提示词 ：确保提示词中关于输出格式的指令足够清晰、强硬。
3. 使用更强大的模型 ：GPT-3.5-turbo 有时会“不听话”，可尝试 GPT-4 系列模型，其遵循指令能力更强。
记忆不生效或混乱 1. memory_key 与提示词模板中的变量名不匹配。
2. 记忆组件类型选择不当（如 ConversationBufferMemory 可能过长导致 token 超限）。		 1. 核对 memory_key ：确保在初始化 memory 和构建提示词时使用相同的 key。
2. 选择合适的内存 ：对话长用 ConversationBufferWindowMemory （只保留最近 N 轮）；需要总结用 ConversationSummaryMemory ；需要存储实体信息用 ConversationEntityMemory 。
3. 检查 token 数 ：过长的记忆会被 LLM 上下文窗口截断，需监控 token 使用量。

5.3 生产环境最佳实践

将原型转化为稳定可靠的生产服务，还需要考虑以下几点：

  1. 配置管理 ：

    • 将 API Key、模型名称、温度等参数抽取到配置文件（如 config.yaml ）或环境变量中。
    • 使用 python-dotenv 管理 .env 文件。

  2. 错误处理与监控 ：

    • 在 FastAPI 应用中实现全局异常处理中间件。
    • 为 Agent 调用添加详细的日志记录，包括输入、输出、工具调用详情和 token 消耗。这有助于问题排查和成本分析。
    • 考虑设置 API 调用的超时和重试机制。

  3. 性能与成本 ：

    • 缓存 ：对频繁且结果不变的查询（如城市基本信息）引入缓存（如 redis ），减少不必要的 LLM 调用和工具调用。
    • 异步 ：如果工具调用涉及网络 I/O（如调用外部 API），考虑使用异步工具和异步 Agent 执行器（ langchain.agents.agent_toolkits 中有相关示例），以提高并发性能。
    • Token 管理 ：监控记忆增长，避免因历史对话过长导致 token 开销剧增和上下文被截断。定期清理或总结记忆。

  4. 扩展性 ：

    • 更多工具 ：根据业务需求，轻松添加新的 @tool 装饰函数，如查询股票、搜索知识库、操作数据库等。
    • 复杂编排 ：当单个 Agent 逻辑过于复杂时，考虑使用 LangGraph 来构建有状态、多分支的工作流。
    • RAG 集成 ：结合 langchain 的 RetrievalQA 链或相关组件，让 Agent 能够从你的私有文档库（向量数据库）中检索信息，增强其知识储备。

6. 从入门到进阶：下一步学习路线

你已经成功构建并理解了一个基础 AI Agent。要将其应用于更复杂的商业场景，可以沿着以下路径深入学习：

  1. 掌握更多工具类型 ：学习使用 StructuredTool 处理复杂参数，使用 Toolkit 组织相关工具集，探索社区已有的工具库（如 langchain-community.tools ）。
  2. 深入提示词工程 ：不满足于 Hub 中的模板时，学习如何从头编写和调试高效的 Agent 提示词。理解 SystemMessage 、 HumanMessage 、 ToolMessage 等在对话中的角色。
  3. 集成向量数据库与 RAG ：学习使用 Chroma 、 Pinecone 或 Weaviate 等向量数据库，结合 langchain 的文本分割器、嵌入模型和检索器，构建能够回答私有领域知识的“专家 Agent”。
  4. 探索 LangGraph ：当你的任务流程需要严格的状态控制、并行执行或复杂循环时，开始学习 LangGraph。从官方教程中的“旅行规划 Agent”或“客服工单处理”案例入手。
  5. 模型微调与优化 ：对于特定领域，如果通用 LLM 表现不佳，可以研究使用 LoRA 、 SFT 等技术对开源模型（如 Qwen）进行高效微调，或使用 PPO 、 DPO 等算法进行对齐优化。
  6. 部署与运维 ：学习使用 Docker 容器化你的 Agent 应用，并部署到云服务器或 Kubernetes 集群。建立 CI/CD 流程、监控告警和性能指标收集体系。

构建 AI Agent 是一个持续迭代的过程，从理解用户需求、设计工具、调试提示词到优化性能，每一步都需要细致的工程化思维。LangChain 提供的模块化设计，让这个过程的每一步都变得清晰可控。现在，你已经拥有了一个可以运行和扩展的起点，接下来就是根据你的具体场景，为其注入更强大的工具和更智能的逻辑。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

从试点到规模化复制，AI Agent如何安全可控的在企业落地应用

avatar AI Agent技术社区
cover

活动回顾｜支付的下一个十年圆满落幕，BlockSec 携手 Interlace 共探支付新秩序

avatar AI Agent技术社区
cover

从“能说会道”到“使命必达”：AI智能体如何真正进入企业工作流

avatar AI Agent技术社区