AI Agent开发入门：基于LangChain框架快速构建你的第一个智能助手-平芜编程栈

1. 从概念到实践：为什么你的第一个AI Agent不该从零开始

如果你最近关注AI领域，大概率已经被“AI Agent”这个词刷屏了。从OpenAI的GPTs到各种创业公司的新产品，似乎一夜之间，所有东西都想成为或集成一个Agent。但当你真正想动手构建一个属于自己的AI Agent时，面对海量的概念、框架和工具，是不是感觉无从下手？别急，这种感觉很正常。今天，我们不谈那些宏大的愿景和复杂的架构图，就从一个最实际的问题开始：如何用最小的代价，构建一个能真正跑起来、解决具体问题的AI Agent。

很多人一上来就想复现AutoGPT或者BabyAGI，结果卡在环境配置、API调用和无限循环里。这就像还没学会走路就想跑马拉松。我的建议是：你的第一个AI Agent，绝对不应该从零开始写核心调度逻辑。核心的推理循环（Reasoning Loop）、工具调用（Tool Calling）、记忆管理（Memory）这些基础设施，已经有非常成熟的框架帮你封装好了。你的首要任务不是成为算法专家，而是成为一个高效的“组装工程师”，理解现有积木，并用它们快速搭建出能解决你问题的原型。

那么，一个AI Agent到底由什么构成？抛开那些唬人的名词，我们可以把它简化理解为一个具备感知、规划、执行和反思能力的自动化程序。它通过大语言模型（LLM）作为“大脑”来理解目标、分解任务、选择工具；通过“工具”（可以是函数、API、甚至另一个程序）来执行具体操作；通过“记忆”来存储对话历史、执行结果，以便进行多轮规划和学习。而像Harness这样的基础设施层，就是把这些组件（LLM, Agent核心，工具，记忆，知识库-RAG）有机连接、管理和监控起来的“骨架”和“神经系统”。

所以，本篇的目标很明确：我会带你绕过初期最大的那些坑，选择一个当前（以当下技术视野来看）最友好、生态最活跃的框架，快速搭建一个能实际运行的AI Agent。我们将聚焦于一个具体场景：一个能自动处理简单文本任务的Agent，比如总结网页内容或整理会议纪要。通过这个实战，你将清晰掌握Agent的核心工作流、关键配置以及最重要的——调试心法。

2. 框架选型：为什么LangChain是新手的最佳起点

面对琳琅满目的AI Agent开发框架，选择困难是必然的。有基于Python的LangChain、LlamaIndex、AutoGen，也有面向企业级应用的Spring AI（Java），还有新兴的C#框架等。对于构建你的第一个Agent，我的核心选型建议是：优先选择生态最丰富、社区最活跃、文档和示例最多的框架。这能确保你在每一步遇到问题时，都能快速找到解决方案或参考代码。

基于这个原则，LangChain几乎是目前不二的选择。它不是性能最强或架构最优雅的那个，但它绝对是“群众基础”最广的。这意味着：

教程和示例海量：无论你想实现什么功能，几乎都能在LangChain的文档、Cookbook或社区论坛里找到相近的案例。
集成度极高：它原生支持数十种LLM（OpenAI, Anthropic, 本地模型等）、数百种工具（搜索引擎、API、数据库）、以及多种记忆和存储方案。你不需要自己写适配层。
抽象层次合理：它提供了从低级（LCEL链式表达式）到高级（AgentExecutor）的多种抽象，既能快速上手，也允许深入定制。
社区支持强大：遇到诡异的问题时，在GitHub Issues或Discord里很可能已经有人讨论过了。

为什么不选其他的？

从零开始：如前所述，时间成本太高，极易挫败。
AutoGPT/BabyAGI：它们更像是特定的Agent应用实现，而非通用的开发框架，不利于理解底层组件。
Spring AI：如果你和你的团队是坚定的Java生态开发者，Spring AI是优秀的选项。但它相对年轻，生态和工具丰富度目前不及LangChain。第一个Agent的目标是快速验证想法，而非纠结技术栈。
新兴C#框架：同理，生态尚在建设期，踩坑的概率大，不适合新手开荒。

因此，我们接下来的实战将基于LangChain（Python版）和OpenAI的GPT模型（因其API稳定、能力全面）展开。请确保你的开发环境已安装Python（建议3.8以上），并且拥有一个可用的OpenAI API密钥。

注意：使用OpenAI API会产生费用，但用于学习和原型开发，成本极低（通常只需几美元）。请务必保管好你的API密钥，不要将其提交到公开的代码仓库。

3. 环境搭建与核心概念初探

在写第一行Agent代码之前，我们需要先把舞台搭好。这不仅仅是安装包，更是理解你即将使用的“积木”是什么。

3.1 基础环境配置

首先，创建一个干净的Python虚拟环境是个好习惯，这能避免包版本冲突。

# 创建并激活虚拟环境（以venv为例） python -m venv ai_agent_env source ai_agent_env/bin/activate # Linux/Mac # ai_agent_env\Scripts\activate # Windows # 安装核心依赖 pip install langchain langchain-openai

langchain是核心框架，langchain-openai是LangChain官方维护的OpenAI集成包，比之前通用的openai包封装了更多LangChain原生特性。

接下来，在代码中设置你的OpenAI API密钥。永远不要将密钥硬编码在代码中！最佳实践是使用环境变量。

# 在终端中设置环境变量（临时） export OPENAI_API_KEY='your-api-key-here'

或者在代码中通过os.environ设置（仅用于开发测试，生产环境务必用外部配置）：

import os os.environ["OPENAI_API_KEY"] = "your-api-key-here"

3.2 理解LangChain的核心“零件”

LangChain将Agent构建分解为几个核心组件，理解它们是你成功的关键：

LLM (大语言模型)：Agent的“大脑”。我们使用ChatOpenAI来调用GPT。
Tools (工具)：Agent的“手和脚”。一个工具本质上是一个可以被Agent调用的函数，它有一个名称、描述和具体的执行逻辑。例如，一个“搜索网络”的工具，或一个“执行Python计算”的工具。
Agent (代理)：这里的Agent是一个逻辑概念，它由LLM和一套Tools组成，并遵循某种决策逻辑（如ReAct框架）。在LangChain中，我们通常不直接实例化Agent，而是使用AgentExecutor。
AgentExecutor (代理执行器)：这是驱动Agent运行的实际“引擎”。它负责调用LLM进行思考、解析LLM的输出以决定调用哪个工具、执行工具、将结果返回给LLM进行下一轮思考，并处理可能出现的错误和循环。你可以把它想象成Agent的运行时容器和调度中心。
Memory (记忆)：用于存储对话历史或Agent执行过程中的状态，使Agent具备上下文感知能力。可以是简单的对话缓冲区，也可以是向量数据库存储的长期记忆。

第一个Agent，我们先从最简形态开始：一个拥有LLM大脑和几件简单工具的Agent，暂不使用复杂记忆。这能让你最清晰地看到信息流动的路径。

4. 实战：构建一个文本处理小助手Agent

现在，让我们动手构建一个具体的Agent。假设我们需要一个能帮我们处理文本的小助手：给定一个主题，它能去网上搜索相关信息，然后总结成一份简洁的报告。这个需求涉及两个关键动作：1. 搜索；2. 总结。正好对应两个工具。

4.1 创建并封装我们的工具

LangChain社区提供了大量预构建工具，我们直接使用两个最常用的：TavilySearchResults（一个专门为AI优化的搜索API）和ArxivQueryRun（搜索学术论文）。为了简化初次体验，我们也可以先用一个“模拟”的搜索工具。

首先，安装可能需要的额外包：

pip install langchain-community tavily-python

我们先实现一个模拟搜索工具和一个真实的总结工具（其实总结能力LLM本身就有，我们将其封装成工具是为了展示模式）：

from langchain.agents import tool from langchain.tools import Tool import requests # 方法一：使用@tool装饰器创建工具（最简洁） @tool def get_current_time(query: str) -> str: """当用户询问当前时间时调用此工具。输入应为空字符串或‘现在’。""" # 这是一个模拟工具，实际应该返回真实时间 return "当前时间是北京时间下午3点27分。（此为模拟数据）" # 方法二：从函数创建Tool对象（更灵活） def search_web(query: str) -> str: """使用DuckDuckGo即时答案进行简单网络搜索。""" # 注意：这是一个简单示例，实际生产环境应使用更稳定的API（如Serper、Tavily） try: # 这里使用一个免费的公共API示例，实际可能不稳定或有频率限制 url = f"https://api.duckduckgo.com/?q={requests.utils.quote(query)}&format=json&pretty=1" response = requests.get(url, timeout=10) data = response.json() # 提取摘要文本 abstract = data.get('AbstractText', '') if abstract: return f"关于'{query}'的摘要：{abstract}" else: return f"未找到关于'{query}'的简明摘要。相关结果标题：{', '.join([r['Text'] for r in data.get('Results', [])[:2]])}" except Exception as e: return f"网络搜索失败：{str(e)}" # 将函数封装成LangChain Tool对象 web_search_tool = Tool.from_function( func=search_web, name="WebSearch", description="当需要获取关于某个主题的最新、实时信息或事实时使用此工具。输入应是一个明确的搜索查询词。" ) # 再创建一个文本总结工具（实际上直接让LLM做就行，这里演示工具封装） @tool def summarize_text(text: str) -> str: """将长文本总结为简洁的要点。输入是需要总结的完整文本。""" # 这个工具本身也调用LLM，演示了工具的链式调用可能 from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) prompt = ChatPromptTemplate.from_template("请将以下文本总结为不超过3个要点的简洁版本：\n\n{text}") chain = prompt | llm result = chain.invoke({"text": text[:2000]}) # 防止文本过长 return result.content

关键点解析：

@tool装饰器：这是创建工具最快捷的方式。装饰器会自动根据函数名、文档字符串生成工具的name和description。描述（description）至关重要！LLM根据描述来决定是否以及何时调用该工具。描述必须清晰说明工具的用途和输入格式。
Tool.from_function方法：当你需要对工具有更多控制（比如错误处理、参数校验）时使用。
工具的功能：工具可以做任何事情，从简单的计算到调用复杂的API。它是Agent与外部世界交互的唯一途径。

4.2 初始化大脑（LLM）并组装Agent

有了工具，我们需要一个“大脑”来使用它们。我们选择GPT-3.5-turbo，它在成本、速度和能力上取得了很好的平衡，适合实验。

from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 1. 初始化LLM llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # temperature设置为0使输出更确定、可重复，适合Agent的决策过程。 # 2. 准备工具列表 tools = [get_current_time, web_search_tool, summarize_text] # 3. 获取一个预设的提示词（Prompt） # LangChain Hub 是一个提示词库，我们可以拉取一个为ReAct Agent设计好的标准提示词。 # 这个提示词会指导LLM按照“思考 -> 行动 -> 观察”的循环来工作。 prompt = hub.pull("hwchase17/react-chat") # 4. 创建Agent agent = create_react_agent(llm, tools, prompt) # 5. 创建Agent执行器 agent_executor = AgentExecutor.from_agent_and_tools( agent=agent, tools=tools, verbose=True, # 强烈建议打开！这将打印出Agent内部的思考过程，是调试和理解的关键。 handle_parsing_errors=True, # 自动处理LLM输出格式错误，避免程序崩溃 max_iterations=5, # 限制最大循环次数，防止无限循环或成本失控 early_stopping_method="generate" # 当Agent认为任务完成时，提前停止 )

代码解读：

create_react_agent：这里我们使用了ReAct（Reasoning + Acting）框架。这是目前最流行、最有效的Agent推理模式之一。它鼓励LLM将思考过程（Reasoning）和行动（Action）以文本形式交错输出，从而更可靠地调用工具。
hub.pull(“hwchase17/react-chat”)：这是一个社区共享的优秀提示词模板，它已经内置了ReAct的指令格式、工具描述列表的插入位置等。使用它能省去大量编写复杂提示词的时间。
AgentExecutor：这是核心。verbose=True是最重要的调试开关，打开后你能看到LLM的完整思考链（Chain of Thought），这对于理解Agent为何做出某个决策、为何失败至关重要。max_iterations是安全阀，必须设置。

4.3 运行与观察：让Agent开始工作

现在，让我们用一个简单的任务来测试我们的Agent。

# 运行Agent result = agent_executor.invoke({ "input": "请搜索一下‘LangChain框架的最新版本有什么新特性’，然后为我总结一下。", "chat_history": [] # 因为是新对话，历史为空 }) print("\n" + "="*50) print("最终答案：") print(result["output"])

当你运行这段代码时，如果verbose=True，控制台会输出类似以下的内容（已简化）：

> Entering new AgentExecutor chain... 我需要找到LangChain最新版本的信息，然后进行总结。 思考：我应该使用WebSearch工具来搜索LangChain的最新版本信息。 行动： { "action": "WebSearch", "action_input": "LangChain latest version new features" } 观察：关于‘LangChain latest version new features’的摘要：LangChain 0.1.0 引入了...（模拟的搜索结果） 思考：我已经获得了信息，现在需要将其总结成简洁的要点。 行动： { "action": "summarize_text", "action_input": "LangChain 0.1.0 引入了..." } 观察：1. 引入了LCEL链式表达式语言... 2. 改进了Agent执行器的错误处理... 3. 新增了对Ollama本地模型的更好支持... 思考：我已经完成了用户要求的搜索和总结任务。 最终答案：根据搜索和总结，LangChain最新版本（例如0.1.0）的主要新特性包括：1. 引入LCEL...；2. 改进错误处理...；3. 增强本地模型支持... > Finished chain.

这个过程就是Agent的核心：

思考：LLM根据用户输入和当前上下文，决定下一步该做什么。
行动：LLM输出一个结构化的动作，指定要调用哪个工具以及输入是什么。
观察：AgentExecutor执行该工具，并将工具返回的结果作为“观察”反馈给LLM。
循环：LLM基于“观察”再次“思考”，决定是继续行动还是结束任务并给出最终答案。

你成功运行了第一个AI Agent！它自动完成了“规划（搜索）- 执行（调用搜索工具）- 再规划（总结）- 再执行（调用总结工具）- 输出”的全过程。

5. 避坑指南与效能提升：从“跑通”到“好用”

恭喜你完成了第一步！但让一个Agent“跑起来”和让它“稳定、可靠、高效地工作”之间，还有巨大的鸿沟。以下是你在后续开发中几乎一定会遇到的问题及解决思路。

5.1 工具描述：Agent能否正确决策的关键

LLM对工具的选择完全依赖于你提供的工具描述（description）。模糊或不准确的描述是导致Agent行为异常的最常见原因。

反面例子：

@tool def tool_a(data): """处理数据。""" # 太模糊！“处理”是什么？输入格式？

正面例子：

@tool def fetch_user_profile(user_id: str) -> str: """根据用户ID从数据库获取用户的姓名和邮箱地址。输入必须是一个有效的用户ID字符串。"""

经验法则：

明确用途：在什么场景下使用这个工具？
定义输入：输入参数是什么类型、格式、有何约束？
说明输出：工具返回的信息大致是什么？
差异化：当有多个相似工具时，描述要突出其独特之处，帮助LLM区分。

5.2 控制循环与成本：防止“失控的Agent”

Agent可能陷入死循环，或者为了一个简单问题调用多次昂贵的外部API。

设置max_iterations：如前所述，这是必须的保险丝。根据任务复杂度设置，简单任务3-5次，复杂任务可设10-15次。
使用early_stopping_method：设为“generate”，让LLM在认为自己完成后直接输出最终答案，而不是必须调用一个“完成”工具。
精细化工具设计：如果一个工具能一次返回更多信息，就避免让Agent多次调用它。例如，一个“搜索并总结”的复合工具，可能比先“搜索”再“总结”两个独立工具更高效、更可控。
监控Token使用：在AgentExecutor的回调（Callbacks）中集成token计数，对成本做到心中有数。

5.3 错误处理与鲁棒性

工具执行可能失败（网络超时、API限流、解析错误），LLM的输出也可能不符合预期格式（解析错误）。

利用框架能力：AgentExecutor的handle_parsing_errors=True参数能自动尝试修复格式错误的LLM输出。
在工具内部进行健壮性编码：工具函数内部应有完善的try-except，返回明确的错误信息，而不是抛出异常导致整个Agent崩溃。例如：

@tool def reliable_search(query: str) -> str: try: # ... 搜索逻辑 return result except requests.exceptions.Timeout: return “错误：搜索请求超时，请稍后重试。” except Exception as e: return f“搜索过程发生意外错误：{str(e)}”

让LLM处理错误：当工具返回错误信息时，良好的提示词（如ReAct提示词）会指导LLM理解这个错误，并尝试其他方案（例如换一个查询词重试）。

5.4 为Agent注入记忆与上下文

我们之前的Agent是无状态的，每轮对话都是独立的。要让Agent进行多轮对话，需要记忆（Memory）。

LangChain提供了多种记忆方案。最简单的是ConversationBufferMemory，它就像一块白板，记录完整的对话历史。

from langchain.memory import ConversationBufferMemory memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True) # 在创建AgentExecutor时传入memory agent_executor = AgentExecutor.from_agent_and_tools( agent=agent, tools=tools, memory=memory, # 关键！ verbose=True, # ... 其他参数 ) # 调用时不再需要手动传入chat_history result = agent_executor.invoke({"input": “上一轮我们讨论了什么？”}) # Agent能记得

记忆的引入让Agent能处理更复杂的、依赖上下文的交互，但同时也带来了新的挑战：历史记录可能过长，消耗大量Token并干扰当前决策。这时需要考虑更高级的记忆管理，如ConversationSummaryMemory（总结历史）或ConversationEntityMemory（记住关键实体）。

6. 超越Demo：规划你的AI Agent进阶之路

当你成功运行了第一个Agent，并解决了上述常见问题后，你可以朝着以下几个方向深化你的理解和技能：

6.1 探索更强大的Agent类型

ReAct只是众多Agent架构中的一种。LangChain还内置了其他类型：

Plan-and-Execute（规划与执行）：让一个“规划者”LLM先制定一个高级计划，再由一个“执行者”LLM（或同一个LLM）按步骤调用工具完成。适合复杂、多步骤任务。
OpenAI Functions Agent：利用OpenAI模型原生的函数调用（Function Calling）能力来驱动Agent，格式更规范，可靠性可能更高。
Custom Agent（自定义）：你可以完全定义自己的推理循环逻辑，实现更特殊的控制流。

6.2 集成RAG（检索增强生成）

这是当前让Agent“更懂你”的核心技术。当你的Agent需要基于特定领域知识（如公司内部文档、产品手册）进行回答时，仅靠通用LLM和网络搜索是不够的。你需要RAG：

将你的知识文档切块、嵌入（Embedding），存入向量数据库（如Chroma, Pinecone）。
当用户提问时，Agent先调用一个“检索”工具，从向量库中找到最相关的文档片段。
将这些片段作为上下文，连同问题一起交给LLM生成最终答案。

这相当于为Agent配备了一个专属的、可实时更新的知识库。LlamaIndex框架在此领域非常专业，它可以与LangChain无缝集成。

6.3 拥抱多模态与更复杂的工具

工具不限于文本API。你可以为Agent集成：

图像生成工具：如调用DALL-E或Stable Diffusion API，让Agent能“画”出它想象中的东西。
代码执行工具：在一个安全的沙箱中运行Python代码，让Agent进行复杂计算或数据分析。
软件操作工具：通过自动化框架（如Playwright, Selenium）让Agent操作浏览器或桌面应用。

6.4 关注工程化与部署

一个实验成功的Agent要变成可持续的服务，需要考虑：

测试：如何对Agent的行为进行单元测试和集成测试？其输出具有非确定性，这是一大挑战。
评估：如何衡量Agent任务完成的“好坏”？需要设计评估指标（Evaluation Metrics）和基准测试（Benchmark）。
监控与可观测性：记录每一次Agent运行的完整思考链（Chain of Thought）、工具调用记录、Token消耗、耗时。这对于调试和优化不可或缺。
部署：使用FastAPI等框架将Agent封装成API服务，或集成到现有的应用流水线中。

构建第一个AI Agent就像学习骑自行车，最初需要辅助轮（成熟的框架）。一旦你找到了平衡，理解了核心组件（LLM, Tools, Memory, Executor）是如何协同工作的，你就能卸下辅助轮，去探索更复杂、更定制化的场景。记住，最好的学习方式是在解决一个实际问题的过程中进行。所以，别再观望，从今天这个能搜索和总结的小助手开始，尝试为它添加一个新工具，解决一个你工作中真实存在的、小而具体的自动化需求吧。那个过程，才是你真正理解AI Agent的开始。