在实际项目里AI Agent智能体已经从一个前沿概念变成了解决复杂任务、串联工作流、提升人机交互效率的工程化组件。很多开发者对它的理解还停留在“调用API”的层面但一个真正可用的智能体需要处理意图理解、工具调用、记忆管理、幻觉抑制和状态流转等一系列工程问题。本文将从零开始带你搭建一个具备实际功能的AI Agent重点不是复现某个热门项目而是理解其核心架构、掌握开发流程、并能在自己的业务场景中落地。我们将以一个“技术文档查询与总结Agent”为例它需要完成理解用户关于某个技术组件的模糊提问自动检索相关文档提取关键信息并生成结构化的总结报告。这个过程会涉及大模型调用、工具函数设计、工作流编排和结果验证。通过这个案例你会掌握从环境准备、架构设计、代码实现到部署测试的完整链路并理解每个环节的工程考量。1. 理解AI Agent的核心架构与工作流在动手写代码之前必须厘清AI Agent不是什么。它不是一个简单的大模型包装器而是一个具备感知、规划、行动和反思能力的自治系统。一个典型的任务型Agent其工作流可以抽象为“感知-规划-执行-观察”的循环。1.1 Agent的核心组成模块一个功能完备的Agent通常包含以下几个核心模块理解它们的关系是后续开发的基础大脑Brain/Core LLM负责理解用户意图、进行逻辑推理、制定行动计划Plan和生成最终响应。通常由一个大语言模型LLM担任如GPT-4、Claude 3或开源的Llama 3、Qwen等。工具ToolsAgent的“手”和“脚”。它们是Agent可以调用的具体函数或API用于执行模型自身无法完成的操作如计算、搜索、查询数据库、调用第三方服务等。工具的定义需要清晰描述其功能、输入参数和输出格式。记忆Memory分为短期记忆会话历史和长期记忆向量数据库等。短期记忆让Agent能理解上下文对话长期记忆则存储知识供Agent在需要时检索这是克服模型“幻觉”和知识截止日期限制的关键。规划器Planner在复杂任务中Agent需要将目标分解为一系列子任务Steps并决定执行顺序。规划器负责这个分解和调度过程。简单的Agent可能由LLM直接进行规划复杂的则需要专门的规划算法或模块。执行器Executor负责调用规划好的工具管理工具的执行顺序和依赖并处理执行过程中产生的异常。反思Reflection高级Agent具备对自身行动和结果进行评估的能力。如果结果不理想或出现错误它能分析原因调整计划并重新尝试。对于我们的“技术文档查询Agent”其模块映射如下大脑使用一个能够理解技术术语和进行总结的LLM。工具至少需要两个工具一个用于搜索技术文档如调用Elasticsearch API或网络搜索另一个用于从网页或文档中提取正文内容。记忆使用向量数据库存储历史查询和总结结果实现相似问题的快速回答和避免重复工作。规划器与执行器我们将使用LangChain这样的框架来简化这部分工作它提供了标准的Agent执行循环。反思在我们的初级版本中暂不实现但会预留接口并讨论其实现思路。1.2 典型工作流以查询文档为例当用户提问“Spring Boot如何配置多数据源”时一个设计良好的Agent会按以下流程工作意图理解与规划LLM分析问题判断需要“搜索”和“总结”两个动作。它生成一个计划[调用搜索工具查找“Spring Boot 多数据源配置官方文档”] - [调用内容提取工具获取文档正文] - [分析正文并生成总结]。工具执行执行器依次调用搜索工具和内容提取工具获取到相关的文档内容。信息合成与响应LLM接收到工具返回的原始文档内容对其进行阅读、分析和总结生成结构化的回答例如分点列出配置步骤、核心依赖、常见坑点。记忆更新将本次的查询问题、使用的工具、获取的文档片段以及最终的回答以向量化的形式存入长期记忆向量数据库。下次用户问“Boot多数据源怎么配”时Agent可以先从记忆库中检索相似历史直接给出答案无需再次搜索提升效率并节省API成本。这个流程的稳定性高度依赖于每个环节的设计尤其是工具描述的准确性和LLM提示词Prompt的质量。2. 环境准备与核心依赖选择搭建Agent的第一步是准备好开发环境并选择适合的技术栈。我们将以Python生态为主因为它拥有最丰富的AI开源库和工具链。2.1 基础环境与Python包管理确保你的开发机满足以下条件操作系统Linux (Ubuntu 20.04)、macOS或Windows Subsystem for Linux (WSL2)。生产环境推荐Linux。Python版本3.9 或 3.10。避免使用3.11的某些早期版本可能与部分库存在兼容性问题。包管理强烈建议使用conda或venv创建独立的虚拟环境避免包冲突。# 使用conda创建环境如果已安装Anaconda/Miniconda conda create -n ai-agent python3.10 conda activate ai-agent # 或者使用venv python -m venv venv # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate2.2 核心框架与库的选择我们将使用LangChain作为Agent开发的核心框架它抽象了记忆、链、工具和Agent等概念能极大减少重复代码。同时需要大模型API、向量数据库等组件。组件类别推荐选项作用说明安装命令 (pip)核心框架LangChainAgent和链的编排框架pip install langchain langchain-community大模型接入OpenAI / Azure OpenAI使用GPT系列作为“大脑”pip install openai或 LangChain集成其他模型如通义千问、DeepSeek等参考对应模型SDK向量数据库Chroma (本地轻量)存储和检索记忆文档片段pip install chromadbPinecone / Weaviate (云服务)生产级向量数据库参考官方文档文档处理LangChain Document Loaders加载PDF、HTML、Markdown等pip install pypdf beautifulsoup4工具与工具调用LangChain Tools定义和调用工具pip install langchain-experimental(部分工具)自定义工具封装业务API-开发辅助Jupyter / IPython交互式实验pip install ipythonPython-dotenv管理环境变量API密钥pip install python-dotenv关键版本说明LangChain版本迭代较快API可能有变动。建议在项目初期锁定版本例如pip install langchain0.1.0 openai1.3.0。本文示例基于LangChain 0.1.x 和 OpenAI 1.x 版本编写。2.3 项目结构初始化创建一个清晰的项目目录有利于后续维护和扩展。tech_doc_agent/ ├── .env # 存储敏感信息如API密钥切勿提交到Git ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖清单 ├── config/ # 配置文件目录 │ └── settings.py # 应用配置模型类型、温度等 ├── core/ # 核心逻辑 │ ├── __init__.py │ ├── agent.py # Agent构建与执行逻辑 │ ├── tools.py # 自定义工具定义 │ └── memory.py # 记忆管理向量存储 ├── models/ # 数据模型可选 │ └── schemas.py # Pydantic模型用于结构化输出 ├── utils/ # 工具函数 │ ├── document_loader.py # 文档加载器 │ └── text_processor.py # 文本处理函数 ├── tests/ # 单元测试 │ └── test_agent.py └── main.py # 应用入口或FastAPI启动文件现在在项目根目录下创建requirements.txt文件并填入核心依赖langchain0.1.0 langchain-community0.0.10 openai1.3.0 chromadb0.4.18 pypdf3.17.0 beautifulsoup44.12.2 python-dotenv1.0.0 fastapi0.104.1 # 如需提供Web API uvicorn[standard]0.24.0 # ASGI服务器运行pip install -r requirements.txt安装所有依赖。3. 构建技术文档查询Agent从工具定义到完整运行我们将分步构建Agent。首先从最基础的“大脑”和“工具”开始。3.1 配置大模型连接与基础Prompt在config/settings.py中配置模型参数。使用.env文件管理你的OpenAI API密钥。.env文件OPENAI_API_KEYsk-your-openai-api-key-here OPENAI_API_BASEhttps://api.openai.com/v1 # 如果使用Azure或代理需修改 MODEL_NAMEgpt-4-turbo-preview # 或 gpt-3.5-turboconfig/settings.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() # 加载.env文件中的环境变量 class Settings: openai_api_key os.getenv(OPENAI_API_KEY) openai_api_base os.getenv(OPENAI_API_BASE, https://api.openai.com/v1) model_name os.getenv(MODEL_NAME, gpt-3.5-turbo) # LLM实例化参数 llm_temperature 0.1 # 低温度使输出更确定适合总结性任务 llm_max_tokens 2000 settings Settings() def get_llm(): 创建并返回配置好的LLM实例 return ChatOpenAI( modelsettings.model_name, temperaturesettings.llm_temperature, max_tokenssettings.llm_max_tokens, api_keysettings.openai_api_key, base_urlsettings.openai_api_base, )接下来在core/agent.py中我们先构建一个最简单的链测试模型连接。# core/agent.py (初步) from langchain_core.prompts import ChatPromptTemplate from config.settings import get_llm def test_llm_connection(): 测试LLM连接和基础对话 llm get_llm() prompt ChatPromptTemplate.from_template(请用一句话解释什么是{concept}) chain prompt | llm # LangChain 0.1.x 使用管道操作符 response chain.invoke({concept: 微服务}) print(f测试响应: {response.content}) return response if __name__ __main__: test_llm_connection()运行python core/agent.py如果看到关于“微服务”的一句解释说明模型连接成功。3.2 创建自定义工具搜索与内容提取工具是Agent能力的扩展。我们将创建两个工具一个模拟网络搜索一个从URL提取正文。在实际项目中你需要替换为真实的搜索引擎API如Serper、Google Custom Search和HTML解析库。core/tools.pyimport json from typing import Type, Optional from langchain_core.tools import BaseTool, Tool from pydantic import BaseModel, Field import requests from bs4 import BeautifulSoup # --- 工具1模拟网络搜索工具 --- class SearchInput(BaseModel): 搜索工具的输入参数模型 query: str Field(description用于搜索技术文档的查询关键词) class SearchTool(BaseTool): name web_search description 根据查询词搜索互联网上的技术文档、博客或官方教程。输入应为搜索关键词。 args_schema: Type[BaseModel] SearchInput return_direct: bool False # 工具返回结果后是否直接结束Agent运行 def _run(self, query: str) - str: 模拟搜索过程。实际应调用Serper/Google Search API。 print(f[工具调用] 正在搜索: {query}) # 这里模拟返回一些固定的搜索结果链接和摘要 # 真实场景response requests.get(fhttps://serper.dev/search?q{query}, headers...) mock_results [ { title: Spring Boot官方文档 - 数据访问, link: https://docs.spring.io/spring-boot/docs/current/reference/html/data.html, snippet: Spring Boot为SQL和NoSQL数据库提供了强大的支持... }, { title: Baeldung教程 - Spring Boot多数据源配置, link: https://www.baeldung.com/spring-boot-multiple-datasources, snippet: 本教程详细介绍了如何在Spring Boot应用中配置多个DataSource... } ] return json.dumps(mock_results, ensure_asciiFalse) # --- 工具2网页内容提取工具 --- class ExtractInput(BaseModel): 内容提取工具的输入参数模型 url: str Field(description需要提取正文内容的网页URL) class ExtractTool(BaseTool): name extract_web_content description 从给定的URL中提取主要的文本内容过滤掉导航栏、广告等无关信息。 args_schema: Type[BaseModel] ExtractInput def _run(self, url: str) - str: 从URL提取正文 print(f[工具调用] 正在提取内容 from: {url}) try: # 注意实际生产环境需处理超时、重试、反爬等问题 headers {User-Agent: Mozilla/5.0} response requests.get(url, headersheaders, timeout10) response.raise_for_status() soup BeautifulSoup(response.text, html.parser) # 简单的正文提取移除script, style标签获取所有段落文本 for script in soup([script, style]): script.decompose() text soup.get_text() lines (line.strip() for line in text.splitlines()) chunks (phrase.strip() for line in lines for phrase in line.split( )) content .join(chunk for chunk in chunks if chunk) # 截取前5000字符作为示例 return content[:5000] ... if len(content) 5000 else content except Exception as e: return f提取内容时出错: {str(e)} # 导出工具实例 def get_tools(): 返回Agent可用的工具列表 search_tool SearchTool() extract_tool ExtractTool() # 你也可以使用LangChain内置工具如Tool.from_function(...) return [search_tool, extract_tool]关键点解释每个工具都继承自BaseTool必须定义name、description和args_schema。description至关重要LLM依靠它来决定何时调用该工具。args_schema使用Pydantic模型定义这能帮助LLM生成格式正确的参数。_run方法是工具的实际执行逻辑。示例中进行了简化生产环境需要完善的错误处理、日志和可能的异步调用。3.3 构建具备工具调用能力的Agent现在我们将LLM、工具和Prompt组合成一个真正的Agent。LangChain提供了多种Agent类型我们使用最通用的create_react_agent它基于ReActReasoning Acting范式能让模型“思考”一步再“行动”一步。更新 core/agent.py# core/agent.py from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate from config.settings import get_llm from core.tools import get_tools def build_agent_executor(): 构建并返回一个配置好的Agent执行器 llm get_llm() tools get_tools() # ReAct Agent的提示词模板 # 这个模板指导LLM如何思考、使用工具和格式化输出 prompt PromptTemplate.from_template( 你是一个专业的技术文档助手。你的任务是回答用户关于技术框架、库或工具的问题。 如果你不知道答案或者需要最新的信息请使用你拥有的工具来搜索和提取信息。 在给出最终答案前请确保信息准确、完整。 请严格按照以下格式回应 思考首先你需要分析问题决定是否需要使用工具以及使用哪个工具。 行动需要使用的工具名称必须是以下之一[{tool_names}] 行动输入工具的输入参数必须是一个合法的JSON字符串 观察工具返回的结果 ... (这个“思考/行动/观察”循环可以重复多次) 最终答案当你拥有足够信息时用清晰、结构化的方式给出最终答案。 开始 问题{input} 历史对话记录可能为空{agent_scratchpad} ) # 创建ReAct Agent agent create_react_agent(llmllm, toolstools, promptprompt) # 创建执行器它负责运行Agent循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志便于调试 handle_parsing_errorsTrue, # 处理LLM输出解析错误 max_iterations5, # 限制最大迭代次数防止死循环 early_stopping_methodgenerate, # 当LLM直接生成最终答案时停止 ) return agent_executor def run_agent_query(question: str): 运行Agent处理一个问题 executor build_agent_executor() try: result executor.invoke({input: question}) return result[output] except Exception as e: return fAgent执行过程中出现错误: {str(e)} if __name__ __main__: # 测试一个简单问题 question Spring Boot如何配置多数据源请给我步骤总结。 answer run_agent_query(question) print(\n *50) print(f问题: {question}) print(f回答: {answer})运行这个脚本你会看到类似以下的详细输出verboseTrue时 进入新的Agent执行链... 思考用户想了解Spring Boot配置多数据源的步骤。这是一个具体的技术问题我的知识可能不是最新的最好使用工具搜索最新的教程或官方文档。 行动web_search 行动输入{query: Spring Boot 多数据源 配置 步骤} 观察[{title: Spring Boot官方文档 - 数据访问, link: ..., snippet: ...}, {...}] 思考我得到了一些搜索结果但内容不够详细。我需要点开最相关的链接提取具体内容。 行动extract_web_content 行动输入{url: https://www.baeldung.com/spring-boot-multiple-datasources} 观察...网页正文内容... 思考我已经从一篇详细的教程中提取了配置多数据源的步骤。现在我可以总结这些信息了。 最终答案在Spring Boot中配置多数据源主要涉及以下步骤1. 在pom.xml中添加必要的数据库驱动依赖... 2. 在application.properties或.yml中为每个数据源定义独立的配置项... 3. 创建多个DataSource的配置类使用Configuration和Bean注解... 4. 使用Primary注解指定主数据源... 5. 在各自的Repository或Service中通过Qualifier注入对应的DataSource...这个输出展示了Agent完整的“思考-行动-观察”链条。verbose日志是调试Agent行为最重要的工具。3.4 为Agent添加记忆能力目前的Agent是“无状态”的每次对话都是独立的。为了让它能记住历史我们需要集成记忆模块。这里使用简单的对话缓冲区ConversationBufferMemory和向量存储长期记忆。core/memory.py# core/memory.py from langchain.memory import ConversationBufferMemory, VectorStoreRetrieverMemory from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from config.settings import settings import hashlib def create_memory_system(): 创建一个混合记忆系统 - buffer_memory: 短期记忆存储最近的对话轮次。 - vector_memory: 长期记忆将历史QA对存入向量数据库支持语义检索。 # 1. 短期记忆对话缓冲区 buffer_memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue # 返回Message对象列表而非字符串 ) # 2. 长期记忆向量存储 - 使用ChromaDB # 注意生产环境应持久化存储路径这里使用内存模式示例 embeddings OpenAIEmbeddings( modeltext-embedding-3-small, api_keysettings.openai_api_key, base_urlsettings.openai_api_base ) vectorstore Chroma( collection_nametech_doc_qa_memory, embedding_functionembeddings, persist_directory./chroma_db # 指定持久化目录 ) # 创建基于向量存储的检索器记忆 retriever vectorstore.as_retriever(search_kwargs{k: 2}) # 检索最相关的2条记忆 vector_memory VectorStoreRetrieverMemory(retrieverretriever) return buffer_memory, vector_memory, vectorstore def save_qa_to_long_memory(vectorstore, question: str, answer: str): 将一次问答保存到长期记忆向量数据库 # 为这段记忆生成一个唯一的ID例如使用问题和答案的哈希 memory_content fQ: {question}\nA: {answer} doc_id hashlib.md5(memory_content.encode()).hexdigest() # 添加到向量库 vectorstore.add_texts( texts[memory_content], metadatas[{type: qa, source: agent}], ids[doc_id] ) print(f[记忆] 已保存QA对到长期记忆ID: {doc_id[:8]}...)更新 core/agent.py 以集成记忆我们需要修改Agent的构建过程将记忆纳入提示词并在每次成功回答后保存记忆。# core/agent.py (更新版 - 集成记忆) from langchain.agents import AgentExecutor, create_react_agent from langchain_core.prompts import PromptTemplate, MessagesPlaceholder from langchain.agents.format_scratchpad import format_log_to_str from langchain.agents.output_parsers import ReActSingleInputOutputParser from config.settings import get_llm from core.tools import get_tools from core.memory import create_memory_system, save_qa_to_long_memory def build_agent_with_memory(): 构建一个具备短期和长期记忆的Agent llm get_llm() tools get_tools() buffer_memory, vector_memory, vectorstore create_memory_system() # 增强的提示词包含记忆检索指令 prompt PromptTemplate.from_template( 你是一个专业的技术文档助手拥有之前对话的记忆。 以下是可能相关的历史对话片段来自长期记忆 {long_term_memory} 最近的对话历史短期记忆 {chat_history} 请利用以上记忆更精准地回答用户问题。如果记忆中有答案请优先参考。如果没有或需要更新再使用工具。 请严格按照以下格式回应 思考分析问题结合记忆决定行动。 行动工具名 行动输入工具的输入 观察工具结果 ...可重复 最终答案结构化的最终回答。 问题{input} {agent_scratchpad} ) # 构建Agent输入需要动态注入记忆内容 def get_agent_inputs(user_input: str): 准备每次调用的输入字典 # 从长期记忆中检索相关片段 relevant_memories vector_memory.load_memory_variables( {prompt: user_input} ).get(history, ) # 从短期记忆中获取最近对话 chat_history_dict buffer_memory.load_memory_variables({}) chat_history chat_history_dict.get(chat_history, []) # 将Message列表转换为字符串 chat_history_str \n.join([f{msg.type}: {msg.content} for msg in chat_history]) return { input: user_input, long_term_memory: relevant_memories, chat_history: chat_history_str, agent_scratchpad: , # 由执行器填充 } # 由于记忆的集成我们需要自定义更复杂的执行流程。 # 这里为简化我们使用一个包装函数来模拟带记忆的Agent。 # 在实际复杂应用中可能需要使用LangChain的AgentExecutor.from_agent_and_tools并自定义中间步骤。 # 以下是一个简化的实现思路 agent create_react_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations5, memorybuffer_memory, # 将短期记忆挂载到执行器 ) # 返回执行器、向量存储和输入准备函数 return agent_executor, vectorstore, get_agent_inputs def run_agent_with_memory(question: str): 运行带记忆的Agent executor, vectorstore, get_inputs build_agent_with_memory() try: inputs get_inputs(question) result executor.invoke(inputs) answer result[output] # 如果成功获得答案将其保存到长期记忆 if answer and not answer.startswith(Agent执行过程中出现错误): save_qa_to_long_memory(vectorstore, question, answer) # 注意短期记忆buffer_memory已由AgentExecutor自动更新 return answer except Exception as e: return fAgent执行过程中出现错误: {str(e)} if __name__ __main__: # 测试连续对话 questions [ Spring Boot如何配置多数据源, 那我该如何在配置类里指定主数据源呢, # 这个问题应该能利用上文的记忆 Redis和MySQL作为数据源配置上有什么不同 ] for q in questions: print(\n *50) print(f用户: {q}) ans run_agent_with_memory(q) print(f助手: {ans}) print(*50)现在Agent已经具备了基础的记忆功能。当用户提出后续问题时Agent会先从向量数据库中检索相关的历史问答从而提供更连贯、更精准的对话体验。4. 运行验证、常见问题与生产考量4.1 运行完整流程与结果验证在项目根目录创建一个简单的测试脚本test_run.py# test_run.py import sys sys.path.append(.) from core.agent import run_agent_with_memory if __name__ __main__: test_questions [ Docker和虚拟机的区别是什么, 请比较一下Kubernetes和Docker Swarm。, 刚才提到的容器编排工具哪个学习曲线更平缓 # 测试记忆 ] for i, q in enumerate(test_questions, 1): print(f\n 测试 {i}: {q}) response run_agent_with_memory(q) print(f 响应: {response[:300]}...) # 打印前300字符运行python test_run.py。观察输出你应该能看到第一个问题触发搜索和总结。第二个问题可能触发新的搜索。第三个问题可能直接从记忆尤其是短期记忆中获取信息回答会提及“刚才提到的...”并且可能不会触发工具调用响应速度更快。验证要点工具调用日志中是否出现[工具调用]和思考/行动/观察的步骤记忆检索后续问题是否显示了[记忆] 已保存以及从长期记忆中检索到的内容输出质量答案是否结构化、准确、相关错误处理模拟一个无效URL看extract_web_content工具是否返回了友好的错误信息。4.2 常见问题排查表在开发过程中你几乎一定会遇到以下问题。下表列出了现象、原因和解决方案。问题现象可能原因检查与解决方式ModuleNotFoundError: No module named langchain虚拟环境未激活或依赖未安装。1. 确认已激活虚拟环境 (conda activate ai-agent或source venv/bin/activate)。2. 运行pip install -r requirements.txt。AuthenticationError或Invalid API KeyOpenAI API密钥错误、未设置或额度不足。1. 检查.env文件中的OPENAI_API_KEY是否正确。2. 在代码开头打印os.getenv(“OPENAI_API_KEY”)前几位确认已加载。3. 登录OpenAI平台检查额度。Agent陷入死循环不断调用同一个工具1. 工具description描述不清LLM无法理解。2.max_iterations设置过高。3. Prompt未明确要求生成“最终答案”。1. 优化工具描述确保清晰、无歧义。2. 将max_iterations设为3-5。3. 在Prompt中强调“当你拥有足够信息时用‘最终答案’开头给出回答”。4. 检查verbose日志看LLM的“思考”步骤是否合理。LLM生成的“行动输入”不是合法JSONLLM没有严格按照格式输出。1. 使用handle_parsing_errorsTrue让执行器尝试修复。2. 在Prompt中更严格地规定格式例如“行动输入必须是一个单行JSON字符串如{\”query\”: \”...\”}”。3. 考虑使用支持JSON模式JSON Schema的LLM如GPT-4或使用JsonOutputToolsParser等高级输出解析器。向量数据库检索不到相关内容1. 嵌入模型Embeddings不匹配。2. 保存记忆时文本处理不当如包含过多噪音。3. 检索参数k太小或相似度阈值不合适。1. 确保存和取使用相同的嵌入模型。2. 在保存记忆前对问答文本进行清洗去除多余空格、换行。3. 调整search_kwargs如{“k”: 4, “score_threshold”: 0.7}。工具调用超时或失败网络问题、第三方API限流、工具内部异常未处理。1. 在工具_run方法中添加超时和重试逻辑。2. 用try...except包裹核心代码返回明确的错误信息供LLM判断。3. 添加详细的日志记录工具调用的输入、输出和耗时。回答存在“幻觉”或过时信息1. 完全依赖LLM内部知识未正确触发工具。2. 搜索工具返回的结果质量差。3. 提取工具未能获取到正文。1. 强化Prompt强调“必须使用工具获取最新信息”。2. 优化搜索查询词或接入更可靠的搜索API。3. 改进网页正文提取算法或使用专门的提取服务。4.3 从原型到生产关键考量与最佳实践让一个在笔记本里跑通的Agent原型变成一个稳定、可靠的生产服务还需要很多工作。性能与成本优化缓存对相同的查询或工具调用结果进行缓存如使用Redis避免重复调用昂贵的LLM或外部API。流式响应对于长文本生成使用LLM的流式输出接口提升用户体验。Token管理监控和管理Prompt长度避免因上下文过长导致的高成本和慢响应。定期清理对话缓冲区。异步处理将耗时的工具调用如网络请求改为异步避免阻塞主线程。LangChain支持异步Agent。稳定性与可靠性完备的错误处理为LLM调用、工具调用、记忆存储等每一个环节设计降级方案和友好错误提示。熔断与限流为外部API调用如LLM、搜索添加熔断器和限流器防止单一服务故障拖垮整个Agent。验证与审核对于关键领域如金融、医疗引入人工审核环节或规则引擎对Agent的输出进行二次校验。版本化与回滚对Agent的Prompt、工具集、模型版本进行管理确保可以快速回滚到稳定版本。可观测性与监控结构化日志记录每一次用户交互的完整轨迹包括原始问题、LLM的思考过程、调用的工具及输入输出、最终回答、耗时、Token使用量。这不仅是排查问题的依据也是优化Prompt和工具的数据基础。关键指标监控平均响应时间、工具调用成功率、LLM调用错误率、用户满意度如有反馈机制。跟踪与调试集成像LangSmith这样的平台可以可视化地跟踪每个链和Agent的执行过程极大提升调试效率。安全与合规输入输出过滤对用户输入进行敏感词过滤和恶意指令检测对模型输出进行内容安全审核防止生成有害信息。权限控制不同的工具可能对应不同权限级别的操作如查询数据库、发送邮件。需要在Agent调用工具前进行权限校验。数据隐私确保用户对话记录、存入向量数据库的记忆等数据得到妥善加密和访问控制。考虑对敏感信息进行脱敏处理。5. 扩展方向与进阶学习完成基础Agent搭建后你可以根据业务需求向多个方向深化复杂工作流与多Agent协作对于超复杂任务可以设计多个各司其职的Agent如“研究Agent”、“写作Agent”、“审核Agent”通过一个“主管Agent”进行协调。框架如CrewAI、AutoGen专门为此设计。更强大的规划与反思集成LangGraph来构建有状态、可循环的图工作流实现更复杂的规划逻辑。为Agent添加“反思”步骤让其能评估工具结果的质量并在不理想时尝试其他方案。连接真实业务系统将工具扩展到企业内部API让Agent能够查询订单、生成报表、创建工单成为真正的“数字员工”。前端交互与部署使用Gradio、Streamlit快速构建Web界面或使用FastAPI封装成RESTful API集成到现有应用中。本地化与私有化部署出于成本、数据安全和网络考虑可以将核心LLM替换为本地部署的模型如通过Ollama部署Llama 3、Qwen向量数据库使用Chroma或Milvus本地部署打造完全内网的智能体系统。构建AI Agent是一个持续迭代的过程。从今天这个能搜索和总结文档的Agent开始不断根据反馈增加工具、优化Prompt、完善记忆和规划逻辑你就能逐步搭建出解决实际业务难题的智能助手。核心在于理解其作为“感知-规划-行动”循环系统的本质并扎实地处理好每一个环节的工程细节。