30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度最近在推进大模型应用落地时团队反复讨论一个核心问题如何让大模型从“被动问答”升级为“主动执行复杂任务”传统的提示工程Prompt Engineering在面对多步骤、需调用工具、有状态记忆的复杂场景时显得力不从心。这正是AI Agent智能体技术要解决的核心痛点。它不再是简单的聊天机器人而是能够感知环境、规划决策、调用工具并持续学习的“数字员工”。本文将为你系统拆解 AI Agent 的开发全貌。无论你是刚接触大模型的开发者还是希望将 Agent 能力集成到现有业务中的工程师都能通过本文掌握从核心概念、环境搭建、框架选型到项目实战的完整路径。我们将避开空洞的理论聚焦于可运行、可复现的代码示例并深入探讨工程落地中的常见陷阱与最佳实践。1. AI Agent 核心概念超越提示工程的智能体在深入代码之前我们必须厘清几个关键概念这有助于理解 Agent 为何是下一代 AI 应用的关键。1.1 什么是 AI Agent简单来说一个 AI Agent 是一个能够自主感知环境、做出决策并执行动作以实现特定目标的软件实体。它以大语言模型LLM为“大脑”但赋予了其“手脚”工具和“记忆”状态。与单一提示调用相比Agent 的核心特征在于自主性Autonomy在给定目标后能自行决定步骤无需每一步都人工干预。交互性Interactivity能够与外部环境如数据库、API、文件系统进行交互。持续性Persistence在单次会话或跨会话中保持状态和记忆。例如一个“数据分析Agent”的目标是“分析本月销售趋势并生成报告”。它会自主规划1. 连接数据库2. 查询数据3. 进行统计分析4. 调用图表生成工具5. 组装成报告文档。整个过程由 Agent 自主驱动。1.2 Agent 与普通大模型应用的区别很多初学者容易混淆。我们通过一个对比表格来明确特性普通大模型应用 (如Chat Completion)AI Agent 应用交互模式单轮或简单多轮对话一问一答。多轮、有状态的复杂工作流。决策核心依赖精心设计的提示词Prompt。依赖“推理框架”如ReAct, Plan-and-Execute进行规划。工具使用通常不具备或需要硬编码调用。核心能力能根据需求动态选择并调用工具。状态管理通常无状态或依赖简短上下文。有明确的记忆短期/长期和状态跟踪。目标导向响应式完成当前查询。主动式为实现一个复杂目标而持续行动。1.3 主流 Agent 框架与模式目前社区活跃着多种 Agent 框架它们封装了核心的推理、工具调用和记忆循环。了解它们有助于我们选择合适的技术栈LangChain / LangGraph生态最成熟提供了构建 Agent 所需的所有底层组件Models, Tools, Memory, Chains。LangGraph 特别擅长构建有环、有状态的复杂工作流。LlamaIndex最初专注于数据检索现在也提供了强大的 Agent 抽象尤其擅长与私有知识库结合构建检索增强生成RAG型 Agent。AutoGen (by Microsoft)支持多智能体对话多个 Agent 可以协作完成任务模拟团队工作模式。Semantic Kernel (by Microsoft)更偏向于将传统代码技能与 LLM 推理能力融合。CrewAI专注于角色扮演和多智能体协作概念清晰适合业务场景建模。对于初学者和大多数应用场景从 LangChain 入手是稳妥的选择其丰富的文档、社区和集成工具能极大降低开发门槛。2. 环境准备与核心工具栈工欲善其事必先利其器。一个稳定且版本兼容的开发环境是成功的第一步。2.1 基础环境配置我们以 Python 为主要开发语言。请确保你的环境满足以下要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)。本文示例在 Ubuntu 22.04 和 macOS 上测试通过。Python 版本强烈推荐使用Python 3.10或3.11。某些库在 Python 3.12 上可能存在兼容性问题。包管理工具使用pip或更推荐的poetry/conda来管理依赖避免环境冲突。首先创建一个干净的虚拟环境并安装基础包# 创建并激活虚拟环境 (以 conda 为例) conda create -n ai-agent python3.10 conda activate ai-agent # 或者使用 venv python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 升级 pip pip install --upgrade pip2.2 核心库安装我们将安装 LangChain 及其相关组件。注意版本兼容性以下版本组合经过测试较为稳定# 安装 LangChain 核心库及 OpenAI 集成 (我们将使用 OpenAI API 作为 LLM) pip install langchain0.1.0 langchain-community0.0.10 pip install langchain-openai0.0.5 # 安装用于解析 Agent 输出如工具调用的库 pip install langchain-core0.1.23 # 安装常用的工具库示例 pip install wikipedia # 维基百科查询工具 pip install requests # HTTP 请求工具 # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv重要提醒LangChain 版本迭代较快上述版本号在未来可能发生变化。如果遇到问题可以尝试安装最新版本但需注意 API 可能发生的变更。核心概念和架构是相通的。2.3 大模型 API 配置Agent 需要一个强大的“大脑”。你可以选择云端 API如 OpenAI GPT-4/GPT-3.5-Turbo Anthropic Claude 国内的通义千问、文心一言等。方便快捷性能稳定是入门和生产的首选。本地部署模型如通过 Ollama 运行 Llama 3、Qwen 等。数据隐私性好无网络延迟但对硬件有要求。本文主要使用OpenAI API进行演示因为它兼容性最好文档最全。你需要准备一个有效的 OpenAI API Key。访问 OpenAI Platform 注册并获取 API Key。在项目根目录创建.env文件将 Key 存入切勿提交到代码仓库。# .env 文件内容 OPENAI_API_KEY你的实际API密钥在代码中通过环境变量加载# config.py 或主程序开头 import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 openai_api_key os.getenv(OPENAI_API_KEY) if not openai_api_key: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)对于国内开发者如果需要使用国产大模型例如阿里的通义千问可以安装相应的 LangChain 集成包如langchain-community中通常包含相关集成或使用官方 SDK。配置方式类似需要替换模型名称和 API Base URL。3. Agent 核心组件深度拆解理解 LangChain 中 Agent 的构成就像理解一辆汽车的发动机、变速箱和车轮。我们将逐一拆解。3.1 大脑LLM (大语言模型)LLM 是 Agent 的推理核心。在 LangChain 中你需要初始化一个 LLM 实例。from langchain_openai import ChatOpenAI # 初始化 GPT-3.5-Turbo 性价比高适合开发和测试 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定减少随机性 api_keyopenai_api_key # 从环境变量传入 ) # 对于需要更强推理能力的复杂任务可以使用 GPT-4 # llm ChatOpenAI(modelgpt-4, temperature0, api_keyopenai_api_key)关键参数解释model: 指定使用的模型。temperature: 控制输出的随机性0-2。值越低输出越确定、一致值越高越有创造性。在 Agent 执行确定性任务时通常设为 0 或接近 0。api_key: 你的认证密钥。3.2 手脚Tools (工具)工具是 Agent 与外界交互的接口。一个工具本质上是一个函数有明确的名称、描述和参数。LangChain 内置了许多工具你也可以轻松自定义。示例1使用内置工具维基百科查询from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper # 创建 Wikipedia 工具 api_wrapper WikipediaAPIWrapper(top_k_results1, doc_content_chars_max200) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) # 打印工具信息 print(f工具名称: {wiki_tool.name}) print(f工具描述: {wiki_tool.description}) # 输出类似工具描述: A wrapper around Wikipedia. Useful for when you need to answer general questions about...示例2创建自定义工具获取天气这是你将来最常做的事情。我们需要用tool装饰器来定义。from langchain.tools import tool import requests tool def get_weather(city: str) - str: 根据城市名称获取当前天气情况。输入应为单个城市名称字符串。 # 这是一个模拟函数实际应用中应接入真实的天气API # 例如调用和风天气、OpenWeatherMap等 weather_data { 北京: 晴 15°C, 上海: 多云 18°C, 深圳: 阵雨 22°C } return weather_data.get(city, f未找到{city}的天气信息。) # 使用工具 print(get_weather.invoke(北京)) # 输出晴 15°C工具定义要点函数文档字符串Docstring至关重要LLM 完全依赖它来理解工具的用途和输入格式。描述要清晰、具体。使用类型注解如city: str帮助 LangChain 进行解析。tool装饰器会自动将函数包装成 LangChain 可识别的工具对象。3.3 记忆Memory (记忆)记忆让 Agent 拥有上下文。记忆分为多种类型ConversationBufferMemory简单存储整个对话历史。ConversationBufferWindowMemory只保留最近 K 轮对话。ConversationSummaryMemory对历史对话进行总结节省 Token。Vectorstore-Backed Memory将记忆存入向量数据库实现长期、可检索的记忆。from langchain.memory import ConversationBufferMemory # 创建一个会话缓冲记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # memory_key 指定在链中如何访问这段记忆 # return_messagesTrue 表示以消息列表格式存储更适合与ChatModel配合3.4 决策引擎Agent Executor (代理执行器)这是将 LLM、Tools、Memory 组装起来并运行推理循环的“总控制器”。它负责将用户输入和记忆传递给 LLM。解析 LLM 的输出是最终答案还是调用工具。如果调用工具则执行工具并获取结果。将工具结果和新的上下文再次传给 LLM直到 LLM 给出最终答案。4. 实战一构建你的第一个 Agent——多功能助手现在我们将把所有组件组合起来创建一个可以查询百科和天气的智能助手。4.1 项目结构my_first_agent/ ├── .env # 存储API密钥 ├── requirements.txt # 依赖列表 ├── agent_demo.py # 主程序 └── tools/ # 自定义工具目录可选requirements.txt内容langchain0.1.0 langchain-community0.0.10 langchain-openai0.0.5 langchain-core0.1.23 openai1.12.0 python-dotenv1.0.0 requests2.31.0 wikipedia1.4.04.2 编写核心代码# agent_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper from langchain.tools import tool from langchain.memory import ConversationBufferMemory from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder # 1. 加载环境变量 load_dotenv() openai_api_key os.getenv(OPENAI_API_KEY) # 2. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyopenai_api_key) # 3. 定义工具集 # 工具1: 维基百科 api_wrapper WikipediaAPIWrapper(top_k_results2, doc_content_chars_max500) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) # 工具2: 自定义天气工具 tool def get_weather(city: str) - str: 根据城市名称获取当前天气情况。输入应为单个城市名称字符串。 weather_data { 北京: 天气晴温度15°C湿度30%风向西北风2级。, 上海: 天气多云温度18°C湿度65%风向东风3级。, 深圳: 天气阵雨温度22°C湿度85%风向南风4级。, 杭州: 天气阴温度16°C湿度70%风向微风。 } return weather_data.get(city, f抱歉目前没有{city}的天气信息。) # 将工具放入列表 tools [wiki_tool, get_weather] # 4. 创建Prompt模板 # 这个模板定义了Agent的角色、可用工具和记忆的插入位置 prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的智能助手。你可以使用工具来获取信息。 请严格按照以下规则回答 1. 如果用户的问题需要实时或外部信息如天气、某概念解释请务必使用工具。 2. 使用工具时请清晰说明你正在查询什么。 3. 根据工具返回的信息组织成友好、完整的回答。 4. 如果你已经知道答案或无需工具请直接回答。), MessagesPlaceholder(variable_namechat_history), # 记忆将插入这里 (user, {input}), # 用户当前问题 MessagesPlaceholder(variable_nameagent_scratchpad), # Agent的思考过程暂存处 ]) # 5. 创建Memory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建Agent # create_openai_tools_agent 是LangChain提供的一个高级函数专门用于创建基于OpenAI函数调用格式的Agent。 agent create_openai_tools_agent(llm, tools, prompt) # 7. 创建Agent执行器 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 设为True可以打印详细的执行步骤便于调试 handle_parsing_errorsTrue, # 优雅地处理解析错误 max_iterations5, # 限制最大循环次数防止无限循环 ) # 8. 运行Agent print( 多功能AI助手已启动输入‘退出’或‘quit’结束对话 ) while True: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: print(助手: 再见) break try: # 调用执行器 response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f\n助手: 处理你的请求时出了点问题: {e})4.3 运行与验证在终端运行程序python agent_demo.py你将看到类似以下的交互过程verboseTrue会打印思考过程 多功能AI助手已启动输入‘退出’或‘quit’结束对话 你: 今天北京的天气怎么样 进入新的Agent执行链... 我可能需要查询北京的天气。用户问的是今天的天气我应该使用天气工具。 动作: get_weather 动作输入: {city: 北京} 观察: 天气晴温度15°C湿度30%风向西北风2级。 思考: 我已经获取了北京的天气信息现在可以回答用户了。 动作: Final Answer 今天北京天气晴朗气温15摄氏度湿度30%西北风2级。天气不错适合外出。 助手: 今天北京天气晴朗气温15摄氏度湿度30%西北风2级。天气不错适合外出。 你: 那上海呢 ... Agent会利用记忆知道你在继续问天气直接调用工具查询上海4.4 关键机制解析推理循环当用户提问后AgentExecutor启动。LLM 根据 Prompt、历史记忆和问题决定下一步是“调用工具”还是“直接回答”。工具调用如果 LLM 决定调用工具如get_weather它会输出一个符合特定格式OpenAI 函数调用的响应。AgentExecutor解析这个响应找到对应的工具函数并执行。结果整合工具执行的结果Observation被送回到 LLM 的上下文中。LLM 根据这个新信息再次决定是调用另一个工具还是整合所有信息给出最终答案Final Answer。记忆更新整个“用户输入-Agent思考-最终输出”的过程会被存入memory在下一轮对话中可用。5. 实战二构建具有复杂工作流的 Agent——自动研究助手单一问答的 Agent 能力有限。现实中的任务如“研究某个主题并撰写摘要”需要多个步骤的规划与执行。我们将使用LangGraph来构建一个更强大的、有明确状态的工作流。目标创建一个 Agent它能根据一个主题自动搜索网络信息阅读相关文章并整理成一份结构化的摘要报告。5.1 安装额外依赖pip install langgraph0.0.22 pip install duckduckgo-search # 用于网络搜索5.2 设计工作流与状态我们将工作流设计为以下几个节点规划节点根据主题规划需要搜索的关键问题。搜索节点并行执行多个搜索获取网页链接和摘要。提取节点从关键的网页中提取详细内容。撰写节点综合所有信息撰写最终报告。我们使用StateGraph来管理整个流程的状态。# research_agent.py import os from dotenv import load_dotenv from typing import TypedDict, List, Annotated import operator from langchain_openai import ChatOpenAI from langchain_community.tools import DuckDuckGoSearchRun from langchain.prompts import ChatPromptTemplate from langchain.schema import Document from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages from langgraph.checkpoint.memory import MemorySaver # 加载环境变量 load_dotenv() # 1. 定义状态结构 class ResearchState(TypedDict): 定义研究Agent的全局状态 topic: str # 研究主题 questions: List[str] # 规划出的搜索问题 search_results: List[str] # 原始搜索结果摘要 contents: List[str] # 提取的详细内容 report: str # 最终报告 messages: Annotated[list, add_messages] # 消息历史LangGraph内置 # 2. 初始化LLM和工具 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.1, api_keyos.getenv(OPENAI_API_KEY)) search_tool DuckDuckGoSearchRun() # 3. 定义各个节点函数 def plan_questions(state: ResearchState): 节点1规划搜索问题 prompt ChatPromptTemplate.from_messages([ (system, 你是一个研究规划专家。), (user, 针对以下研究主题请规划3-4个最关键的搜索问题以全面了解该主题。 主题{topic} 请以列表形式返回问题不要有其他解释。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic]}) questions response.content.strip().split(\n) # 清理问题格式 questions [q.strip(- ).strip() for q in questions if q.strip()] return {questions: questions} def execute_searches(state: ResearchState): 节点2执行并行搜索 questions state[questions] search_results [] for q in questions: # 这里可以优化为真正的并行为简化示例使用循环 result search_tool.run(q) search_results.append(f问题: {q}\n结果: {result[:500]}...) # 截取部分 return {search_results: search_results} def extract_key_contents(state: ResearchState): 节点3从搜索结果中提取关键内容 # 模拟从搜索结果中挑选最相关的2条进行“深度阅读” # 真实场景中这里可以调用网页抓取和内容解析工具 all_results \n.join(state[search_results]) prompt ChatPromptTemplate.from_messages([ (system, 你是一个信息提取专家。), (user, 以下是关于主题“{topic}”的搜索结果摘要 {all_results} 请从以上材料中提取出最核心、最相关的3-5个事实或观点用简洁的句子表述。 请直接输出提取的内容每条占一行。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic], all_results: all_results}) contents [c.strip() for c in response.content.strip().split(\n) if c.strip()] return {contents: contents} def write_report(state: ResearchState): 节点4撰写最终报告 contents state[contents] prompt ChatPromptTemplate.from_messages([ (system, 你是一名专业的报告撰写人。), (user, 研究主题{topic} 已收集的核心信息如下 {contents} 请基于以上信息撰写一份简短的研究摘要报告约300字。 报告应结构清晰包含主题概述、关键发现、简要总结。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic], contents: \n- .join(contents)}) return {report: response.content} # 4. 构建工作流图 workflow StateGraph(ResearchState) # 添加节点 workflow.add_node(planner, plan_questions) workflow.add_node(searcher, execute_searches) workflow.add_node(extractor, extract_key_contents) workflow.add_node(writer, write_report) # 设置边定义执行顺序 workflow.set_entry_point(planner) workflow.add_edge(planner, searcher) workflow.add_edge(searcher, extractor) workflow.add_edge(extractor, writer) workflow.add_edge(writer, END) # 5. 编译图并添加记忆用于更复杂的多轮交互场景 memory MemorySaver() app workflow.compile(checkpointermemory) # 6. 运行研究助手 if __name__ __main__: research_topic 大型语言模型LLM在软件开发中的应用与挑战 print(f开始研究主题: {research_topic}\n) # 初始化状态 initial_state {topic: research_topic, messages: []} # 执行工作流 final_state app.invoke(initial_state, config{configurable: {thread_id: research_thread_1}}) print(*50) print(【生成的研究报告】\n) print(final_state[report]) print(\n *50) print(【规划的研究问题】) for i, q in enumerate(final_state.get(questions, []), 1): print(f{i}. {q})5.3 运行与结果分析运行python research_agent.py。你会看到程序依次执行规划、搜索、提取、撰写四个步骤最终输出一份关于“LLM在软件开发中的应用与挑战”的简短报告。这个示例的价值在于展示了 Agent 的“规划-执行”能力可编排你可以通过修改StateGraph轻松调整工作流例如增加一个“验证”节点或让“搜索”和“提取”循环进行。有状态所有中间结果问题、搜索结果、内容都保存在state中并在节点间传递。可扩展每个节点都可以替换为更强大的工具例如用 Serper API 进行谷歌搜索用 Firecrawl 进行网页抓取和解析。6. 常见问题与排查指南 (FAQ)在开发 Agent 过程中你一定会遇到各种问题。以下是高频问题及解决方案。问题现象可能原因排查思路与解决方案Agent陷入循环不停调用同一个工具1. 工具描述不清晰LLM无法正确使用。2.max_iterations设置过高或未设置。3. LLMtemperature过高导致决策不稳定。1.优化工具描述确保工具的函数文档字符串清晰、无歧义明确输入格式。2.设置迭代限制在AgentExecutor中明确设置max_iterations5或更小。3.降低随机性设置temperature0。4.优化Prompt在系统提示中明确要求“在获得足够信息后请给出最终答案”。OpenAI API报错RateLimitError或AuthenticationError1. API Key 错误或失效。2. 达到速率限制或余额不足。3. 请求超时。1.检查.env文件确认OPENAI_API_KEY正确无误无多余空格。2.查看OpenAI控制台确认账户余额和用量限制。3.添加重试逻辑使用tenacity库或 LangChain 的Retry回调。4.使用代理在某些网络环境下需要配置代理但必须通过合法合规的企业网络解决方案进行。LangChain版本更新导致代码报错LangChain 版本迭代快API 常有变动。1.锁定版本在requirements.txt中指定已知可工作的版本号。2.查阅官方迁移指南关注 LangChain Release Notes 。3.使用兼容性导入如从langchain.agents导入create_react_agent可能已变需查找新写法。自定义工具无法被Agent识别或调用1. 工具函数缺少tool装饰器或描述。2. 工具没有正确添加到tools列表中。3. LLM 无法理解工具用途。1.确认装饰器函数上方必须有from langchain.tools import tool和tool。2.打印工具列表检查tools变量是否包含了你的自定义工具实例。3.简化描述让工具的描述 (docstring) 尽可能简单、直接。Agent在处理中文时效果不佳1. 底层 LLM 对中文支持参差不齐。2. Prompt 和工具描述均为英文。1.选用支持中文的模型如 GPT-4, Claude-3, 国产大模型。2.中文化Prompt和工具描述将系统提示和所有工具的函数描述改为中文能显著提升中文任务表现。3.进行指令微调对于复杂任务可以考虑用中文示例对模型进行少量提示微调 (Few-shot)。工作流 (LangGraph) 状态管理混乱1.State的TypedDict定义有误。2. 节点返回值与State键不匹配。3. 没有正确配置checkpointer。1.明确定义状态确保TypedDict中每个字段的类型注解正确。2.检查节点返回值每个节点函数必须返回一个字典其键是State的子集。3.从简单开始先构建两个节点的线性流程测试无误后再增加复杂度。7. 工程最佳实践与进阶建议当你掌握了基础开发后以下实践能帮助你将 Agent 应用到更严肃的生产环境中。7.1 设计原则构建可靠的 Agent工具设计精细化单一职责一个工具只做一件事。例如search_web和read_webpage应该分开。强类型输入在工具函数中使用 Pydantic 模型来定义和验证输入参数减少 LLM 调用错误。完备的错误处理工具内部要有try-except返回友好的错误信息避免因工具崩溃导致整个 Agent 失败。Prompt 工程系统化角色定义清晰在系统提示中明确 Agent 的角色、能力和约束。提供示例在 Prompt 中包含少量示例Few-shot能极大提升复杂任务的表现。分步思考鼓励 LLM “一步一步思考”对于规划型任务可以使用 Chain-of-Thought (CoT) 提示。控制流与安全保障设置超时与重试对工具调用和 LLM 请求设置超时并实现指数退避重试。权限控制对工具进行分级。高风险工具如删除文件、发送邮件需要额外的用户确认或权限校验逻辑。输入输出过滤对用户输入和 Agent 输出进行内容安全过滤防止注入攻击或不当内容。7.2 性能与成本优化缓存对频繁且结果不变的 LLM 请求或工具调用如查询静态知识实施缓存可以使用LangChain的Cache组件或外部 Redis。异步处理对于 I/O 密集型工具如网络请求、数据库查询使用异步函数 (async/await) 来提高 Agent 的并发处理能力。模型选择并非所有任务都需要 GPT-4。将任务分类简单分类/提取用小型模型复杂推理用大型模型。考虑使用国产大模型 API 作为成本更优的选择。Token 管理监控记忆和上下文消耗的 Token 数。对于长对话使用ConversationSummaryMemory或定期清理历史避免超出模型上下文长度导致失败或成本激增。7.3 监控与评估日志记录详细记录每个 Agent 运行的输入、输出、中间步骤、工具调用和耗时。这是调试和优化的基础。评估指标定义业务相关的评估指标如任务完成率、步骤数、用户满意度。可以构建一个简单的评估框架用 LLM 来自动评估生成结果的质量。可观测性将 Agent 的关键指标如调用次数、成功率、平均响应时间接入现有的监控系统如 Prometheus, Grafana。7.4 进阶学习路线深入框架精读LangChain和LangGraph的官方文档理解Chain,Runnable,State等核心抽象。多智能体系统学习AutoGen或CrewAI探索多个 Agent 如何通过分工、辩论、协作来解决超复杂问题。与业务系统集成学习如何将 Agent 封装成 API 服务如使用 FastAPI如何与企业的数据库、CRM、OA 系统对接。长期记忆与检索研究如何将向量数据库如 Pinecone, Weaviate, Chroma与 Agent 结合使其具备海量知识库的检索和记忆能力。智能体评估与对齐关注如何评估 Agent 的安全性、可靠性和有效性确保其行为与人类价值观对齐。从零构建一个能解决实际问题的 AI Agent 是一个充满挑战但回报丰厚的过程。它要求你不仅理解大模型的能力更要掌握软件工程的设计模式、系统架构的权衡取舍。建议从一个明确、具体的小场景开始例如“自动整理会议纪要并生成待办事项”的 Agent逐步迭代积累经验。记住强大的 Agent 不是一蹴而就的而是通过不断的设计、测试、反馈和优化循环构建出来的。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
AI Agent开发实战：从核心概念到复杂工作流构建指南
30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度最近在推进大模型应用落地时团队反复讨论一个核心问题如何让大模型从“被动问答”升级为“主动执行复杂任务”传统的提示工程Prompt Engineering在面对多步骤、需调用工具、有状态记忆的复杂场景时显得力不从心。这正是AI Agent智能体技术要解决的核心痛点。它不再是简单的聊天机器人而是能够感知环境、规划决策、调用工具并持续学习的“数字员工”。本文将为你系统拆解 AI Agent 的开发全貌。无论你是刚接触大模型的开发者还是希望将 Agent 能力集成到现有业务中的工程师都能通过本文掌握从核心概念、环境搭建、框架选型到项目实战的完整路径。我们将避开空洞的理论聚焦于可运行、可复现的代码示例并深入探讨工程落地中的常见陷阱与最佳实践。1. AI Agent 核心概念超越提示工程的智能体在深入代码之前我们必须厘清几个关键概念这有助于理解 Agent 为何是下一代 AI 应用的关键。1.1 什么是 AI Agent简单来说一个 AI Agent 是一个能够自主感知环境、做出决策并执行动作以实现特定目标的软件实体。它以大语言模型LLM为“大脑”但赋予了其“手脚”工具和“记忆”状态。与单一提示调用相比Agent 的核心特征在于自主性Autonomy在给定目标后能自行决定步骤无需每一步都人工干预。交互性Interactivity能够与外部环境如数据库、API、文件系统进行交互。持续性Persistence在单次会话或跨会话中保持状态和记忆。例如一个“数据分析Agent”的目标是“分析本月销售趋势并生成报告”。它会自主规划1. 连接数据库2. 查询数据3. 进行统计分析4. 调用图表生成工具5. 组装成报告文档。整个过程由 Agent 自主驱动。1.2 Agent 与普通大模型应用的区别很多初学者容易混淆。我们通过一个对比表格来明确特性普通大模型应用 (如Chat Completion)AI Agent 应用交互模式单轮或简单多轮对话一问一答。多轮、有状态的复杂工作流。决策核心依赖精心设计的提示词Prompt。依赖“推理框架”如ReAct, Plan-and-Execute进行规划。工具使用通常不具备或需要硬编码调用。核心能力能根据需求动态选择并调用工具。状态管理通常无状态或依赖简短上下文。有明确的记忆短期/长期和状态跟踪。目标导向响应式完成当前查询。主动式为实现一个复杂目标而持续行动。1.3 主流 Agent 框架与模式目前社区活跃着多种 Agent 框架它们封装了核心的推理、工具调用和记忆循环。了解它们有助于我们选择合适的技术栈LangChain / LangGraph生态最成熟提供了构建 Agent 所需的所有底层组件Models, Tools, Memory, Chains。LangGraph 特别擅长构建有环、有状态的复杂工作流。LlamaIndex最初专注于数据检索现在也提供了强大的 Agent 抽象尤其擅长与私有知识库结合构建检索增强生成RAG型 Agent。AutoGen (by Microsoft)支持多智能体对话多个 Agent 可以协作完成任务模拟团队工作模式。Semantic Kernel (by Microsoft)更偏向于将传统代码技能与 LLM 推理能力融合。CrewAI专注于角色扮演和多智能体协作概念清晰适合业务场景建模。对于初学者和大多数应用场景从 LangChain 入手是稳妥的选择其丰富的文档、社区和集成工具能极大降低开发门槛。2. 环境准备与核心工具栈工欲善其事必先利其器。一个稳定且版本兼容的开发环境是成功的第一步。2.1 基础环境配置我们以 Python 为主要开发语言。请确保你的环境满足以下要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)。本文示例在 Ubuntu 22.04 和 macOS 上测试通过。Python 版本强烈推荐使用Python 3.10或3.11。某些库在 Python 3.12 上可能存在兼容性问题。包管理工具使用pip或更推荐的poetry/conda来管理依赖避免环境冲突。首先创建一个干净的虚拟环境并安装基础包# 创建并激活虚拟环境 (以 conda 为例) conda create -n ai-agent python3.10 conda activate ai-agent # 或者使用 venv python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 升级 pip pip install --upgrade pip2.2 核心库安装我们将安装 LangChain 及其相关组件。注意版本兼容性以下版本组合经过测试较为稳定# 安装 LangChain 核心库及 OpenAI 集成 (我们将使用 OpenAI API 作为 LLM) pip install langchain0.1.0 langchain-community0.0.10 pip install langchain-openai0.0.5 # 安装用于解析 Agent 输出如工具调用的库 pip install langchain-core0.1.23 # 安装常用的工具库示例 pip install wikipedia # 维基百科查询工具 pip install requests # HTTP 请求工具 # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv重要提醒LangChain 版本迭代较快上述版本号在未来可能发生变化。如果遇到问题可以尝试安装最新版本但需注意 API 可能发生的变更。核心概念和架构是相通的。2.3 大模型 API 配置Agent 需要一个强大的“大脑”。你可以选择云端 API如 OpenAI GPT-4/GPT-3.5-Turbo Anthropic Claude 国内的通义千问、文心一言等。方便快捷性能稳定是入门和生产的首选。本地部署模型如通过 Ollama 运行 Llama 3、Qwen 等。数据隐私性好无网络延迟但对硬件有要求。本文主要使用OpenAI API进行演示因为它兼容性最好文档最全。你需要准备一个有效的 OpenAI API Key。访问 OpenAI Platform 注册并获取 API Key。在项目根目录创建.env文件将 Key 存入切勿提交到代码仓库。# .env 文件内容 OPENAI_API_KEY你的实际API密钥在代码中通过环境变量加载# config.py 或主程序开头 import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 openai_api_key os.getenv(OPENAI_API_KEY) if not openai_api_key: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)对于国内开发者如果需要使用国产大模型例如阿里的通义千问可以安装相应的 LangChain 集成包如langchain-community中通常包含相关集成或使用官方 SDK。配置方式类似需要替换模型名称和 API Base URL。3. Agent 核心组件深度拆解理解 LangChain 中 Agent 的构成就像理解一辆汽车的发动机、变速箱和车轮。我们将逐一拆解。3.1 大脑LLM (大语言模型)LLM 是 Agent 的推理核心。在 LangChain 中你需要初始化一个 LLM 实例。from langchain_openai import ChatOpenAI # 初始化 GPT-3.5-Turbo 性价比高适合开发和测试 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定减少随机性 api_keyopenai_api_key # 从环境变量传入 ) # 对于需要更强推理能力的复杂任务可以使用 GPT-4 # llm ChatOpenAI(modelgpt-4, temperature0, api_keyopenai_api_key)关键参数解释model: 指定使用的模型。temperature: 控制输出的随机性0-2。值越低输出越确定、一致值越高越有创造性。在 Agent 执行确定性任务时通常设为 0 或接近 0。api_key: 你的认证密钥。3.2 手脚Tools (工具)工具是 Agent 与外界交互的接口。一个工具本质上是一个函数有明确的名称、描述和参数。LangChain 内置了许多工具你也可以轻松自定义。示例1使用内置工具维基百科查询from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper # 创建 Wikipedia 工具 api_wrapper WikipediaAPIWrapper(top_k_results1, doc_content_chars_max200) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) # 打印工具信息 print(f工具名称: {wiki_tool.name}) print(f工具描述: {wiki_tool.description}) # 输出类似工具描述: A wrapper around Wikipedia. Useful for when you need to answer general questions about...示例2创建自定义工具获取天气这是你将来最常做的事情。我们需要用tool装饰器来定义。from langchain.tools import tool import requests tool def get_weather(city: str) - str: 根据城市名称获取当前天气情况。输入应为单个城市名称字符串。 # 这是一个模拟函数实际应用中应接入真实的天气API # 例如调用和风天气、OpenWeatherMap等 weather_data { 北京: 晴 15°C, 上海: 多云 18°C, 深圳: 阵雨 22°C } return weather_data.get(city, f未找到{city}的天气信息。) # 使用工具 print(get_weather.invoke(北京)) # 输出晴 15°C工具定义要点函数文档字符串Docstring至关重要LLM 完全依赖它来理解工具的用途和输入格式。描述要清晰、具体。使用类型注解如city: str帮助 LangChain 进行解析。tool装饰器会自动将函数包装成 LangChain 可识别的工具对象。3.3 记忆Memory (记忆)记忆让 Agent 拥有上下文。记忆分为多种类型ConversationBufferMemory简单存储整个对话历史。ConversationBufferWindowMemory只保留最近 K 轮对话。ConversationSummaryMemory对历史对话进行总结节省 Token。Vectorstore-Backed Memory将记忆存入向量数据库实现长期、可检索的记忆。from langchain.memory import ConversationBufferMemory # 创建一个会话缓冲记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # memory_key 指定在链中如何访问这段记忆 # return_messagesTrue 表示以消息列表格式存储更适合与ChatModel配合3.4 决策引擎Agent Executor (代理执行器)这是将 LLM、Tools、Memory 组装起来并运行推理循环的“总控制器”。它负责将用户输入和记忆传递给 LLM。解析 LLM 的输出是最终答案还是调用工具。如果调用工具则执行工具并获取结果。将工具结果和新的上下文再次传给 LLM直到 LLM 给出最终答案。4. 实战一构建你的第一个 Agent——多功能助手现在我们将把所有组件组合起来创建一个可以查询百科和天气的智能助手。4.1 项目结构my_first_agent/ ├── .env # 存储API密钥 ├── requirements.txt # 依赖列表 ├── agent_demo.py # 主程序 └── tools/ # 自定义工具目录可选requirements.txt内容langchain0.1.0 langchain-community0.0.10 langchain-openai0.0.5 langchain-core0.1.23 openai1.12.0 python-dotenv1.0.0 requests2.31.0 wikipedia1.4.04.2 编写核心代码# agent_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper from langchain.tools import tool from langchain.memory import ConversationBufferMemory from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder # 1. 加载环境变量 load_dotenv() openai_api_key os.getenv(OPENAI_API_KEY) # 2. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyopenai_api_key) # 3. 定义工具集 # 工具1: 维基百科 api_wrapper WikipediaAPIWrapper(top_k_results2, doc_content_chars_max500) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) # 工具2: 自定义天气工具 tool def get_weather(city: str) - str: 根据城市名称获取当前天气情况。输入应为单个城市名称字符串。 weather_data { 北京: 天气晴温度15°C湿度30%风向西北风2级。, 上海: 天气多云温度18°C湿度65%风向东风3级。, 深圳: 天气阵雨温度22°C湿度85%风向南风4级。, 杭州: 天气阴温度16°C湿度70%风向微风。 } return weather_data.get(city, f抱歉目前没有{city}的天气信息。) # 将工具放入列表 tools [wiki_tool, get_weather] # 4. 创建Prompt模板 # 这个模板定义了Agent的角色、可用工具和记忆的插入位置 prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的智能助手。你可以使用工具来获取信息。 请严格按照以下规则回答 1. 如果用户的问题需要实时或外部信息如天气、某概念解释请务必使用工具。 2. 使用工具时请清晰说明你正在查询什么。 3. 根据工具返回的信息组织成友好、完整的回答。 4. 如果你已经知道答案或无需工具请直接回答。), MessagesPlaceholder(variable_namechat_history), # 记忆将插入这里 (user, {input}), # 用户当前问题 MessagesPlaceholder(variable_nameagent_scratchpad), # Agent的思考过程暂存处 ]) # 5. 创建Memory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建Agent # create_openai_tools_agent 是LangChain提供的一个高级函数专门用于创建基于OpenAI函数调用格式的Agent。 agent create_openai_tools_agent(llm, tools, prompt) # 7. 创建Agent执行器 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 设为True可以打印详细的执行步骤便于调试 handle_parsing_errorsTrue, # 优雅地处理解析错误 max_iterations5, # 限制最大循环次数防止无限循环 ) # 8. 运行Agent print( 多功能AI助手已启动输入‘退出’或‘quit’结束对话 ) while True: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: print(助手: 再见) break try: # 调用执行器 response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f\n助手: 处理你的请求时出了点问题: {e})4.3 运行与验证在终端运行程序python agent_demo.py你将看到类似以下的交互过程verboseTrue会打印思考过程 多功能AI助手已启动输入‘退出’或‘quit’结束对话 你: 今天北京的天气怎么样 进入新的Agent执行链... 我可能需要查询北京的天气。用户问的是今天的天气我应该使用天气工具。 动作: get_weather 动作输入: {city: 北京} 观察: 天气晴温度15°C湿度30%风向西北风2级。 思考: 我已经获取了北京的天气信息现在可以回答用户了。 动作: Final Answer 今天北京天气晴朗气温15摄氏度湿度30%西北风2级。天气不错适合外出。 助手: 今天北京天气晴朗气温15摄氏度湿度30%西北风2级。天气不错适合外出。 你: 那上海呢 ... Agent会利用记忆知道你在继续问天气直接调用工具查询上海4.4 关键机制解析推理循环当用户提问后AgentExecutor启动。LLM 根据 Prompt、历史记忆和问题决定下一步是“调用工具”还是“直接回答”。工具调用如果 LLM 决定调用工具如get_weather它会输出一个符合特定格式OpenAI 函数调用的响应。AgentExecutor解析这个响应找到对应的工具函数并执行。结果整合工具执行的结果Observation被送回到 LLM 的上下文中。LLM 根据这个新信息再次决定是调用另一个工具还是整合所有信息给出最终答案Final Answer。记忆更新整个“用户输入-Agent思考-最终输出”的过程会被存入memory在下一轮对话中可用。5. 实战二构建具有复杂工作流的 Agent——自动研究助手单一问答的 Agent 能力有限。现实中的任务如“研究某个主题并撰写摘要”需要多个步骤的规划与执行。我们将使用LangGraph来构建一个更强大的、有明确状态的工作流。目标创建一个 Agent它能根据一个主题自动搜索网络信息阅读相关文章并整理成一份结构化的摘要报告。5.1 安装额外依赖pip install langgraph0.0.22 pip install duckduckgo-search # 用于网络搜索5.2 设计工作流与状态我们将工作流设计为以下几个节点规划节点根据主题规划需要搜索的关键问题。搜索节点并行执行多个搜索获取网页链接和摘要。提取节点从关键的网页中提取详细内容。撰写节点综合所有信息撰写最终报告。我们使用StateGraph来管理整个流程的状态。# research_agent.py import os from dotenv import load_dotenv from typing import TypedDict, List, Annotated import operator from langchain_openai import ChatOpenAI from langchain_community.tools import DuckDuckGoSearchRun from langchain.prompts import ChatPromptTemplate from langchain.schema import Document from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages from langgraph.checkpoint.memory import MemorySaver # 加载环境变量 load_dotenv() # 1. 定义状态结构 class ResearchState(TypedDict): 定义研究Agent的全局状态 topic: str # 研究主题 questions: List[str] # 规划出的搜索问题 search_results: List[str] # 原始搜索结果摘要 contents: List[str] # 提取的详细内容 report: str # 最终报告 messages: Annotated[list, add_messages] # 消息历史LangGraph内置 # 2. 初始化LLM和工具 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.1, api_keyos.getenv(OPENAI_API_KEY)) search_tool DuckDuckGoSearchRun() # 3. 定义各个节点函数 def plan_questions(state: ResearchState): 节点1规划搜索问题 prompt ChatPromptTemplate.from_messages([ (system, 你是一个研究规划专家。), (user, 针对以下研究主题请规划3-4个最关键的搜索问题以全面了解该主题。 主题{topic} 请以列表形式返回问题不要有其他解释。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic]}) questions response.content.strip().split(\n) # 清理问题格式 questions [q.strip(- ).strip() for q in questions if q.strip()] return {questions: questions} def execute_searches(state: ResearchState): 节点2执行并行搜索 questions state[questions] search_results [] for q in questions: # 这里可以优化为真正的并行为简化示例使用循环 result search_tool.run(q) search_results.append(f问题: {q}\n结果: {result[:500]}...) # 截取部分 return {search_results: search_results} def extract_key_contents(state: ResearchState): 节点3从搜索结果中提取关键内容 # 模拟从搜索结果中挑选最相关的2条进行“深度阅读” # 真实场景中这里可以调用网页抓取和内容解析工具 all_results \n.join(state[search_results]) prompt ChatPromptTemplate.from_messages([ (system, 你是一个信息提取专家。), (user, 以下是关于主题“{topic}”的搜索结果摘要 {all_results} 请从以上材料中提取出最核心、最相关的3-5个事实或观点用简洁的句子表述。 请直接输出提取的内容每条占一行。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic], all_results: all_results}) contents [c.strip() for c in response.content.strip().split(\n) if c.strip()] return {contents: contents} def write_report(state: ResearchState): 节点4撰写最终报告 contents state[contents] prompt ChatPromptTemplate.from_messages([ (system, 你是一名专业的报告撰写人。), (user, 研究主题{topic} 已收集的核心信息如下 {contents} 请基于以上信息撰写一份简短的研究摘要报告约300字。 报告应结构清晰包含主题概述、关键发现、简要总结。 ) ]) chain prompt | llm response chain.invoke({topic: state[topic], contents: \n- .join(contents)}) return {report: response.content} # 4. 构建工作流图 workflow StateGraph(ResearchState) # 添加节点 workflow.add_node(planner, plan_questions) workflow.add_node(searcher, execute_searches) workflow.add_node(extractor, extract_key_contents) workflow.add_node(writer, write_report) # 设置边定义执行顺序 workflow.set_entry_point(planner) workflow.add_edge(planner, searcher) workflow.add_edge(searcher, extractor) workflow.add_edge(extractor, writer) workflow.add_edge(writer, END) # 5. 编译图并添加记忆用于更复杂的多轮交互场景 memory MemorySaver() app workflow.compile(checkpointermemory) # 6. 运行研究助手 if __name__ __main__: research_topic 大型语言模型LLM在软件开发中的应用与挑战 print(f开始研究主题: {research_topic}\n) # 初始化状态 initial_state {topic: research_topic, messages: []} # 执行工作流 final_state app.invoke(initial_state, config{configurable: {thread_id: research_thread_1}}) print(*50) print(【生成的研究报告】\n) print(final_state[report]) print(\n *50) print(【规划的研究问题】) for i, q in enumerate(final_state.get(questions, []), 1): print(f{i}. {q})5.3 运行与结果分析运行python research_agent.py。你会看到程序依次执行规划、搜索、提取、撰写四个步骤最终输出一份关于“LLM在软件开发中的应用与挑战”的简短报告。这个示例的价值在于展示了 Agent 的“规划-执行”能力可编排你可以通过修改StateGraph轻松调整工作流例如增加一个“验证”节点或让“搜索”和“提取”循环进行。有状态所有中间结果问题、搜索结果、内容都保存在state中并在节点间传递。可扩展每个节点都可以替换为更强大的工具例如用 Serper API 进行谷歌搜索用 Firecrawl 进行网页抓取和解析。6. 常见问题与排查指南 (FAQ)在开发 Agent 过程中你一定会遇到各种问题。以下是高频问题及解决方案。问题现象可能原因排查思路与解决方案Agent陷入循环不停调用同一个工具1. 工具描述不清晰LLM无法正确使用。2.max_iterations设置过高或未设置。3. LLMtemperature过高导致决策不稳定。1.优化工具描述确保工具的函数文档字符串清晰、无歧义明确输入格式。2.设置迭代限制在AgentExecutor中明确设置max_iterations5或更小。3.降低随机性设置temperature0。4.优化Prompt在系统提示中明确要求“在获得足够信息后请给出最终答案”。OpenAI API报错RateLimitError或AuthenticationError1. API Key 错误或失效。2. 达到速率限制或余额不足。3. 请求超时。1.检查.env文件确认OPENAI_API_KEY正确无误无多余空格。2.查看OpenAI控制台确认账户余额和用量限制。3.添加重试逻辑使用tenacity库或 LangChain 的Retry回调。4.使用代理在某些网络环境下需要配置代理但必须通过合法合规的企业网络解决方案进行。LangChain版本更新导致代码报错LangChain 版本迭代快API 常有变动。1.锁定版本在requirements.txt中指定已知可工作的版本号。2.查阅官方迁移指南关注 LangChain Release Notes 。3.使用兼容性导入如从langchain.agents导入create_react_agent可能已变需查找新写法。自定义工具无法被Agent识别或调用1. 工具函数缺少tool装饰器或描述。2. 工具没有正确添加到tools列表中。3. LLM 无法理解工具用途。1.确认装饰器函数上方必须有from langchain.tools import tool和tool。2.打印工具列表检查tools变量是否包含了你的自定义工具实例。3.简化描述让工具的描述 (docstring) 尽可能简单、直接。Agent在处理中文时效果不佳1. 底层 LLM 对中文支持参差不齐。2. Prompt 和工具描述均为英文。1.选用支持中文的模型如 GPT-4, Claude-3, 国产大模型。2.中文化Prompt和工具描述将系统提示和所有工具的函数描述改为中文能显著提升中文任务表现。3.进行指令微调对于复杂任务可以考虑用中文示例对模型进行少量提示微调 (Few-shot)。工作流 (LangGraph) 状态管理混乱1.State的TypedDict定义有误。2. 节点返回值与State键不匹配。3. 没有正确配置checkpointer。1.明确定义状态确保TypedDict中每个字段的类型注解正确。2.检查节点返回值每个节点函数必须返回一个字典其键是State的子集。3.从简单开始先构建两个节点的线性流程测试无误后再增加复杂度。7. 工程最佳实践与进阶建议当你掌握了基础开发后以下实践能帮助你将 Agent 应用到更严肃的生产环境中。7.1 设计原则构建可靠的 Agent工具设计精细化单一职责一个工具只做一件事。例如search_web和read_webpage应该分开。强类型输入在工具函数中使用 Pydantic 模型来定义和验证输入参数减少 LLM 调用错误。完备的错误处理工具内部要有try-except返回友好的错误信息避免因工具崩溃导致整个 Agent 失败。Prompt 工程系统化角色定义清晰在系统提示中明确 Agent 的角色、能力和约束。提供示例在 Prompt 中包含少量示例Few-shot能极大提升复杂任务的表现。分步思考鼓励 LLM “一步一步思考”对于规划型任务可以使用 Chain-of-Thought (CoT) 提示。控制流与安全保障设置超时与重试对工具调用和 LLM 请求设置超时并实现指数退避重试。权限控制对工具进行分级。高风险工具如删除文件、发送邮件需要额外的用户确认或权限校验逻辑。输入输出过滤对用户输入和 Agent 输出进行内容安全过滤防止注入攻击或不当内容。7.2 性能与成本优化缓存对频繁且结果不变的 LLM 请求或工具调用如查询静态知识实施缓存可以使用LangChain的Cache组件或外部 Redis。异步处理对于 I/O 密集型工具如网络请求、数据库查询使用异步函数 (async/await) 来提高 Agent 的并发处理能力。模型选择并非所有任务都需要 GPT-4。将任务分类简单分类/提取用小型模型复杂推理用大型模型。考虑使用国产大模型 API 作为成本更优的选择。Token 管理监控记忆和上下文消耗的 Token 数。对于长对话使用ConversationSummaryMemory或定期清理历史避免超出模型上下文长度导致失败或成本激增。7.3 监控与评估日志记录详细记录每个 Agent 运行的输入、输出、中间步骤、工具调用和耗时。这是调试和优化的基础。评估指标定义业务相关的评估指标如任务完成率、步骤数、用户满意度。可以构建一个简单的评估框架用 LLM 来自动评估生成结果的质量。可观测性将 Agent 的关键指标如调用次数、成功率、平均响应时间接入现有的监控系统如 Prometheus, Grafana。7.4 进阶学习路线深入框架精读LangChain和LangGraph的官方文档理解Chain,Runnable,State等核心抽象。多智能体系统学习AutoGen或CrewAI探索多个 Agent 如何通过分工、辩论、协作来解决超复杂问题。与业务系统集成学习如何将 Agent 封装成 API 服务如使用 FastAPI如何与企业的数据库、CRM、OA 系统对接。长期记忆与检索研究如何将向量数据库如 Pinecone, Weaviate, Chroma与 Agent 结合使其具备海量知识库的检索和记忆能力。智能体评估与对齐关注如何评估 Agent 的安全性、可靠性和有效性确保其行为与人类价值观对齐。从零构建一个能解决实际问题的 AI Agent 是一个充满挑战但回报丰厚的过程。它要求你不仅理解大模型的能力更要掌握软件工程的设计模式、系统架构的权衡取舍。建议从一个明确、具体的小场景开始例如“自动整理会议纪要并生成待办事项”的 Agent逐步迭代积累经验。记住强大的 Agent 不是一蹴而就的而是通过不断的设计、测试、反馈和优化循环构建出来的。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
