从零构建AI智能体：基于LangChain的Agent开发实战指南

在实际的大模型应用开发中，仅仅调用 API 生成文本已经无法满足复杂业务场景的需求。真正的挑战在于如何让大模型具备自主规划、使用工具、与环境交互并持续学习的能力，这正是 AI Agent（智能体）技术要解决的核心问题。许多开发者学习了基础的大模型调用后，在尝试构建能处理多步骤任务、具备记忆和决策能力的应用时，常常感到无从下手，面临工具集成、状态管理、流程控制等一系列工程难题。

本文旨在为希望从大模型基础应用迈向 Agent 开发的工程师提供一条清晰的实践路径。我们将从 Agent 的核心概念和工作机制讲起，逐步搭建一个具备基础能力的 Agent 项目，涵盖环境准备、框架选择、核心模块开发、运行验证以及生产环境下的关键考量。通过本文，你将能够理解 Agent 的架构设计，掌握使用主流框架（如 LangChain、LlamaIndex）或从零构建一个简易 Agent 的关键技术栈，并具备排查常见问题和进行工程化优化的能力。

1. 理解 AI Agent：从被动响应到主动规划

在深入代码之前，必须厘清 Agent 与传统大模型应用的本质区别。这决定了后续所有技术选型和架构设计的方向。

1.1 Agent 的核心定义与组件

一个 AI Agent 不是一个简单的“提问-回答”模型。它是一个能够感知环境、进行决策并执行动作以达成特定目标的自治系统。其核心思想是赋予大模型一个“大脑”和“手脚”。

一个典型的 Agent 系统通常包含以下几个关键组件：

• 大脑（核心模型）：通常是一个大型语言模型，负责理解任务、进行推理、制定计划并做出决策。
• 规划器：将复杂目标分解为可执行的子任务序列或步骤。
• 记忆模块：分为短期记忆（当前会话的上下文）和长期记忆（向量数据库等），用于存储和检索历史交互、知识、状态等信息。
• 工具集：Agent 可以调用的外部能力，如搜索 API、计算器、代码执行器、数据库操作等。这是 Agent 突破纯文本生成限制的关键。
• 执行器/动作器：负责调用工具，并将工具执行结果反馈给核心模型，以进行下一步决策。

1.2 Agent 的工作循环：ReAct 模式

理解 Agent 如何运作，最经典的范式是ReAct。它代表了Reasoning（推理）和Acting（行动）的循环。

1. 观察：Agent 接收用户输入和当前环境状态（包括记忆）。
2. 思考：核心模型基于观察进行推理，决定下一步是“继续思考”还是“采取某个行动”。如果是行动，则选择最合适的工具。
3. 行动：Agent 调用选定的工具，并传入必要的参数。
4. 观察：获取工具执行的结果（成功、失败或数据）。
5. 循环：将行动结果作为新的观察，再次进入“思考”步骤，直到模型认为任务完成或无法继续。

这个循环使得 Agent 能够处理“查询今天天气，如果是晴天就推荐户外活动，并计算活动时长”这类需要多步骤决策的任务。

1.3 主流 Agent 框架概览

对于开发者而言，完全从零构建所有组件成本很高。目前社区已有一些成熟的框架，它们封装了记忆、工具、规划等通用模块，让开发者能更专注于业务逻辑。

• LangChain / LangGraph：目前最流行的 Agent 开发框架之一。提供了丰富的工具集成、记忆管理和链式调用。LangGraph 特别擅长构建有状态的、多分支的复杂 Agent 工作流。
• LlamaIndex：最初专注于数据索引和检索，现已发展成为构建 RAG 和 Agent 应用的强大框架。它在知识管理和工具使用方面有独特优势。
• AutoGen：由微软推出，专注于多智能体对话和协作，适合需要多个 Agent 相互通信、协作完成任务的场景。
• Semantic Kernel：微软的另一个框架，强调将传统编程技能与 AI 模型能力“嫁接”起来。

在本文的实践部分，我们将以LangChain为例，因为它生态丰富、文档齐全，是大多数开发者入门 Agent 的首选。

2. 环境准备与项目初始化

开始构建 Agent 前，需要搭建一个稳定且可复现的开发环境。我们将创建一个独立的 Python 虚拟环境，并安装核心依赖。

2.1 基础环境配置

首先，确保你的系统已安装 Python（推荐 3.9 或更高版本）。然后，使用venv创建虚拟环境。

# 创建项目目录并进入 mkdir my_ai_agent && cd my_ai_agent # 创建 Python 虚拟环境 python -m venv venv # 激活虚拟环境 # 在 Windows 上： # venv\Scripts\activate # 在 macOS/Linux 上： source venv/bin/activate

激活后，命令行提示符前应显示(venv)，表示你已在虚拟环境中。

2.2 核心依赖安装

我们将安装 LangChain 及其相关组件。由于大模型是核心，我们还需要安装对应模型的 SDK。这里以 OpenAI 的 GPT 模型为例，同时安装用于网页搜索的工具包和用于记忆的向量数据库客户端。

# 升级 pip 确保安装顺利 pip install --upgrade pip # 安装 LangChain 核心包及 OpenAI 集成 pip install langchain langchain-openai # 安装用于调用搜索引擎的工具包（例如 Tavily，一个针对 AI 优化的搜索 API） # 注意：你需要注册并获取 API Key，后续会配置 pip install langchain-community tavily-python # 安装向量数据库客户端（以 Chroma 为例，轻量级，适合本地开发） pip install chromadb # 安装环境变量管理库，用于安全存储 API Key pip install python-dotenv

注意：生产环境中，chromadb可能被替换为pgvector（与 PostgreSQL 集成）或Weaviate、Qdrant等专业向量数据库。本地开发用 Chroma 足够。

2.3 项目结构与配置文件

创建一个清晰的项目结构，有助于管理代码、配置和资源。

my_ai_agent/ ├── .env # 存储敏感信息（API Keys），切勿提交到 Git ├── .gitignore # Git 忽略文件 ├── requirements.txt # 项目依赖清单 ├── config/ │ └── settings.py # 应用配置（从环境变量读取） ├── src/ │ ├── agents/ # Agent 定义目录 │ │ └── research_agent.py │ ├── tools/ # 自定义工具目录 │ │ └── custom_calculator.py │ ├── memory/ # 记忆管理模块 │ └── utils/ # 工具函数 └── main.py # 应用主入口

首先，创建.env文件来存储你的 API Key。务必确保此文件在.gitignore中。

# .env OPENAI_API_KEY=sk-your-openai-api-key-here TAVILY_API_KEY=tvly-your-tavily-api-key-here # 其他 API Key...

然后，创建config/settings.py来安全地加载这些配置。

# config/settings.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 class Settings: OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") TAVILY_API_KEY = os.getenv("TAVILY_API_KEY") # 可以添加其他配置，如模型名称、温度等 MODEL_NAME = "gpt-4o-mini" # 或 "gpt-3.5-turbo" MODEL_TEMPERATURE = 0.1 settings = Settings()

最后，生成requirements.txt文件，方便他人复现环境。

pip freeze > requirements.txt

3. 构建你的第一个智能体：研究助手 Agent

我们将构建一个“研究助手” Agent，它能根据用户的问题，自动使用搜索引擎查找信息，并整理成一份简洁的报告。这个例子涵盖了工具调用、记忆和简单规划。

3.1 定义可用的工具

工具是 Agent 能力的延伸。我们先定义一个搜索工具和一个计算器工具（示例）。

# src/tools/custom_calculator.py from langchain.tools import tool import math @tool def custom_calculator(expression: str) -> str: """ 执行一个数学表达式计算。支持加减乘除和乘方。 例如: “(3 + 5) * 2” 或 “2 ** 10”。 参数: expression: 一个字符串形式的数学表达式。 返回: 计算结果字符串，或错误信息。 """ try: # 警告：使用 eval 有安全风险，仅用于示例。生产环境应使用 ast.literal_eval 或专用库。 # 此处为简化演示，确保输入仅为数学表达式。 result = eval(expression, {"__builtins__": {}}, {“math”: math}) return f”计算 {expression} 的结果是：{result}” except Exception as e: return f”计算表达式 ‘{expression}’ 时出错：{e}” # 注意：实际项目中，应为工具提供更严格的输入验证和沙箱环境。

接下来，在 Agent 主文件中，我们集成一个更实用的网络搜索工具。

# src/agents/research_agent.py from langchain_openai import ChatOpenAI from langchain_community.tools.tavily_search import TavilySearchResults from config.settings import settings from src.tools.custom_calculator import custom_calculator def create_research_agent(): """ 创建并返回一个配置好的研究助手 Agent。 """ # 1. 初始化大语言模型 llm = ChatOpenAI( model=settings.MODEL_NAME, temperature=settings.MODEL_TEMPERATURE, api_key=settings.OPENAI_API_KEY ) # 2. 初始化工具 # Tavily 搜索工具 search_tool = TavilySearchResults(api_key=settings.TAVILY_API_KEY, max_results=3) # 自定义计算器工具 calculator_tool = custom_calculator # 将所有工具放入一个列表 tools = [search_tool, calculator_tool] # 3. 为工具创建描述，帮助 LLM 理解何时使用它们 # LangChain 会自动从工具装饰器或文档字符串生成描述，这里我们显式检查 for tool in tools: print(f”工具名称：{tool.name}”) print(f”工具描述：{tool.description}”) print(“---”) # 4. 创建 Agent 执行器 # 使用 LangChain 的 create_react_agent 助手，它封装了 ReAct 逻辑 from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 从 LangChain Hub 拉取一个预设的 ReAct 提示词模板 # 这个模板会指导 LLM 按照“Thought/Action/Action Input/Observation”的格式进行推理 prompt = hub.pull(“hwchase17/react”) # 创建 Agent agent = create_react_agent(llm, tools, prompt) # 创建执行器，它负责运行 ReAct 循环 agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, # 打印详细的思考过程，调试时非常有用 handle_parsing_errors=True, # 处理模型输出格式解析错误 max_iterations=5, # 限制最大迭代次数，防止无限循环 early_stopping_method=”force” # 达到最大迭代时强制结束 ) return agent_executor

3.2 运行并测试 Agent

创建一个主程序来测试我们的研究助手。

# main.py import sys import os sys.path.append(os.path.dirname(os.path.abspath(__file__))) from src.agents.research_agent import create_research_agent def main(): print(“初始化研究助手 Agent...”) agent = create_research_agent() # 测试查询 queries = [ “2024年巴黎奥运会中国代表团获得了多少枚金牌？”， “计算一下这些金牌数加上 10 再除以 2 是多少？”， “什么是 AI Agent？用简短的几句话概括。” ] for query in queries: print(f”\n\n用户提问：{query}”) print(“=”*50) try: response = agent.invoke({“input”: query}) print(f”\nAgent 最终回答：{response[‘output’]}”) except Exception as e: print(f”执行过程中出现错误：{e}”) if __name__ == “__main__”: main()

运行这个程序：

python main.py

如果一切配置正确，你将看到类似以下的输出（verbose 模式）：

初始化研究助手 Agent... 工具名称：tavily_search_results_json 工具描述：一个搜索引擎。用于搜索互联网上的最新信息。... --- 工具名称：custom_calculator 工具描述：custom_calculator(expression: str) -> str - 执行一个数学表达式计算... --- 用户提问：2024年巴黎奥运会中国代表团获得了多少枚金牌？ ================================================== > 进入新的 Agent 执行链... 思考：我需要查找 2024 年巴黎奥运会中国代表团的金牌数。我应该使用搜索工具。 行动：tavily_search_results_json 行动输入：{“query”: “2024巴黎奥运会 中国 金牌 数”} 观察：[{“title”: “...”, “content”: “...中国代表团获得40枚金牌...”, “url”: “...”}, ...] 思考：根据搜索结果，中国代表团获得了40枚金牌。我可以直接给出答案。 行动：__结束__ Agent 最终回答：2024年巴黎奥运会中国代表团获得了40枚金牌。

你会看到 Agent 经历了“思考 -> 行动 -> 观察 -> 再思考”的过程，最终给出了答案。对于计算问题，它会调用计算器工具；对于概念性问题，它会调用搜索工具。

4. 为 Agent 添加记忆能力

上述 Agent 是无状态的，每次对话都是独立的。为了让 Agent 能进行连贯的多轮对话，我们需要为其添加记忆。这里我们实现一个简单的对话历史记忆。

4.1 使用 ConversationBufferMemory

LangChain 提供了多种记忆后端。ConversationBufferMemory会将完整的对话历史保存在内存中。

# src/agents/research_agent_with_memory.py from langchain_openai import ChatOpenAI from langchain_community.tools.tavily_search import TavilySearchResults from langchain.memory import ConversationBufferMemory from langchain.agents import create_react_agent, AgentExecutor from langchain import hub from config.settings import settings from src.tools.custom_calculator import custom_calculator def create_agent_with_memory(): llm = ChatOpenAI(model=settings.MODEL_NAME, temperature=settings.MODEL_TEMPERATURE, api_key=settings.OPENAI_API_KEY) tools = [TavilySearchResults(api_key=settings.TAVILY_API_KEY), custom_calculator] # 1. 创建记忆对象 memory = ConversationBufferMemory(memory_key=”chat_history”, return_messages=True) # 2. 拉取支持记忆的提示词模板（通常包含 `{chat_history}` 占位符） prompt = hub.pull(“hwchase17/react-chat”) # 或者，可以自定义提示词，确保其中包含 `chat_history` 变量。 # 3. 创建 Agent agent = create_react_agent(llm, tools, prompt) # 4. 创建执行器，并传入 memory agent_executor = AgentExecutor( agent=agent, tools=tools, memory=memory, # 关键：将记忆对象传入执行器 verbose=True, handle_parsing_errors=True, max_iterations=5 ) return agent_executor

4.2 测试多轮对话记忆

修改main.py进行测试。

# main.py (更新部分) from src.agents.research_agent_with_memory import create_agent_with_memory def main(): print(“初始化带记忆的研究助手 Agent...”) agent = create_agent_with_memory() queries = [ “我叫张三，记住我的名字。”, “我刚才让你记住什么了？”， “用搜索工具查一下 LangChain 是什么，然后总结给我。”, “根据你刚才查到的信息，LangChain 主要用来做什么？” ] for query in queries: print(f”\n\n[用户]：{query}”) print(“-”*30) try: response = agent.invoke({“input”: query}) print(f”\n[Agent]：{response[‘output’]}”) except Exception as e: print(f”错误：{e}”) # 打印当前记忆内容 print(f”\n\n当前对话历史：{agent.memory.buffer}”) if __name__ == “__main__”: main()

运行后，你会发现 Agent 在第二轮对话中能回忆起你的名字，并且在第四轮对话中，能基于第三轮搜索到的上下文进行回答，而不需要重新搜索。这就是记忆的作用。

5. 生产环境关键考量与常见问题排查

将 Agent 从开发环境推向生产，会面临一系列新的挑战。以下是必须关注的要点和常见问题的排查路径。

5.1 稳定性与错误处理

Agent 的自主性可能导致不可预知的错误，如工具调用失败、模型输出格式错误、陷入循环等。

常见问题 1：Agent 陷入无限循环或达到最大迭代次数

• 现象：Agent 反复执行相同或无效的“思考-行动”步骤，最终因max_iterations限制而停止，输出“Agent stopped due to iteration limit”。
• 原因：
  • 提示词不够清晰，未能引导模型正确判断任务完成。
  • 工具返回的结果无法让模型做出有效决策。
  • 任务本身过于模糊或复杂。
• 解决方案：
  • 优化提示词：在系统提示中明确给出任务完成的判断标准。例如：“当你认为已经收集到足够信息来回答用户问题时，请使用Final Answer:开头给出最终答案。”
  • 改进工具：确保工具返回结构化、清晰的信息。对于搜索工具，可以要求其返回更简洁的摘要。
  • 设置更严格的停止条件：除了max_iterations，可以监听特定输出（如包含“Final Answer”）来提前停止。
  • 任务分解：对于复杂任务，可以设计一个主管 Agent，将任务拆解后分发给多个子 Agent 执行。

常见问题 2：工具调用参数解析错误

• 现象：日志中出现JSONDecodeError或类似解析错误，提示“Could not parse LLM output”。
• 原因：LLM 生成的“行动输入”不是合法的 JSON 字符串，或者与工具期望的参数格式不匹配。
• 解决方案：
  • 启用handle_parsing_errors=True：这是第一道防线，执行器会尝试修复或重试。
  • 提供更清晰的工具描述：在工具的描述中，明确写出参数名和类型，例如：“search(query: str)-query是搜索关键词字符串。”
  • 使用更强大的模型：GPT-4 系列在遵循输出格式指令上通常比 GPT-3.5 更稳定。
  • 输出解析器：使用 LangChain 的OutputFixingParser或RetryOutputParser来自动修正格式错误。

5.2 性能与成本优化

Agent 的每次“思考”和工具调用都产生延迟和成本。

• 减少不必要的迭代：通过优化提示词和工具设计，让 Agent 用更少的步骤完成任务。
• 缓存：对频繁且结果不变的查询（如“什么是 Python？”）实现缓存层，避免重复调用模型或工具。
• 模型选型：在非核心推理步骤使用更小、更快的模型（如gpt-4o-mini），仅在关键决策时使用大模型。
• 异步调用：如果 Agent 需要并行调用多个独立工具，使用异步接口（asyncio）可以显著降低总延迟。
• 监控与限流：记录每次调用的模型、工具、耗时和 Token 使用量，设置预算和速率限制。

5.3 安全与可控性

赋予模型调用工具的能力也带来了风险。

• 工具权限控制：不是所有工具都应对所有用户或所有问题开放。需要建立权限机制，例如，只有经过验证的请求才能调用“发送邮件”或“执行数据库写操作”的工具。
• 输入输出过滤与审查：对用户输入和模型输出进行安全检查，防止注入攻击、敏感信息泄露或生成有害内容。
• 人工审核回路：对于高风险操作（如支付、重要数据修改），设计流程让 Agent 生成方案，但最终执行需经人工确认。
• 可解释性与审计日志：完整记录 Agent 的思考过程、调用的工具及参数、工具返回结果。这对于调试、合规和事后分析至关重要。

5.4 部署与运维

• 配置外置化：所有 API Key、模型参数、工具端点等都应通过环境变量或配置中心管理，切勿硬编码。
• 健康检查与监控：为 Agent 服务添加健康检查端点，并监控其响应时间、错误率和资源使用情况。
• 版本化管理：对 Agent 的提示词、工具集、模型版本进行版本控制，便于回滚和 A/B 测试。
• 容器化部署：使用 Docker 容器打包应用及其依赖，确保环境一致性。

6. 进阶方向与学习路径

掌握了基础 Agent 构建后，你可以向以下几个方向深入探索：

1. 复杂工作流与多智能体：使用LangGraph构建有状态、带循环和条件分支的复杂工作流。探索AutoGen框架，构建多个各司其职的 Agent 进行协作（如一个负责规划，一个负责编码，一个负责审查）。
2. 高级记忆与检索：超越简单的对话缓冲区，集成向量数据库实现长期记忆和语义检索，让 Agent 能从历史交互和知识库中学习。
3. 工具学习：研究如何让 Agent 自动发现、描述和学习使用新工具，而无需为每个工具手动编写描述和接口。
4. 强化学习与自我改进：设计奖励机制，让 Agent 根据任务完成效果自我优化其决策策略。
5. 领域特定 Agent：将 Agent 技术应用于垂直领域，如客服、代码生成、数据分析、游戏 NPC 等，需要深入理解领域知识并构建专用工具集。

构建可靠的 AI Agent 是一个系统工程，它考验的不仅是对大模型的理解，更是对软件架构、异常处理、安全设计和运维能力的综合运用。从本文的最小可行案例出发，逐步增加复杂度，并在每个环节都思考其稳定性、性能和安全性，是迈向 Agent 开发高手的务实路径。