尧图网页设计 
1. 项目概述为什么现在必须掌握 Agent 开发最近两年如果你在技术社区里没听过“Agent”这个词那可能有点落伍了。从 OpenAI 的 Codex 到各种宣称能自主完成复杂任务的 AI 助手再到招聘网站上悄然出现的“Agent 开发工程师”岗位一股新的技术浪潮已经拍到了岸边。但说实话当我第一次看到“构建 Agent 实战指南”这个标题时心里想的是这又是一个被过度炒作的概念吗还是说它真的代表了一种全新的、能解决实际问题的生产力工具经过一段时间的摸索和几个项目的实战我的结论是Agent 不是噱头而是一种将大语言模型LLM从“聊天机器人”升级为“数字员工”的关键架构思想。它解决的核心痛点是如何让一个 AI 模型不仅会回答“怎么做”还能真正动手去“做”。想象一下你不再需要一步步告诉 AI“先打开这个文件找到第三行修改某个变量然后保存”而是直接说“帮我把这个模块的性能优化一下”它就能自主分析代码、定位瓶颈、尝试多种优化方案并提交修改。这就是 Agent 试图赋予 AI 的能力——自主规划、使用工具、与环境交互并完成目标。对于开发者、产品经理甚至业务人员来说学习构建 Agent 不再是可选的前沿探索而是逐步成为一项核心技能。无论是想开发一个能自动处理客服工单的智能坐席一个能根据自然语言描述自动生成数据分析报告的数据助手还是一个能24小时监控系统并自主排障的运维机器人其底层都是 Agent 技术。因此这篇指南将完全从实战出发抛开那些晦涩的理论和空洞的展望直接带你进入构建一个可用、好用 Agent 的每一个具体环节。我们会从最基础的概念拆解开始一步步走到架构设计、工具集成、记忆与协作最后分享那些只有踩过坑才知道的调试和优化经验。2. 核心概念拆解Agent、框架与智能体生态在动手写第一行代码之前我们必须把几个关键概念掰扯清楚。市面上关于 Agent 的讨论常常混杂着不同层面的术语容易让人晕头转向。2.1 Agent 的本质超越简单提示的“大脑”首先Agent智能体到底是什么你可以把它理解为一个配备了“大脑”通常是 LLM、“记忆”和“手脚”工具的自主程序。它与传统程序或简单提示工程Prompt Engineering最根本的区别在于“循环”与“决策”。简单提示工程用户输入一个问题模型给出一个回答。交互是单次的、静态的。比如你问“Python里怎么排序列表”它回答“用sorted()函数”。任务结束。Agent用户给定一个目标比如“帮我分析一下上个月的销售数据找出销量下降最多的三个产品并写一份简短的报告”。这时Agent 的“大脑”会进行如下思考循环思考Think“要完成这个目标我需要先获取数据。我有访问数据库的工具吗哦有query_database工具。我需要先知道具体是哪个月的数据用户说的是‘上个月’我需要计算一下日期范围。”行动Act调用query_database工具传入计算好的日期参数执行 SQL 查询。观察Observe拿到数据库返回的原始数据。“数据拿到了但很杂乱。我需要一个数据分析工具来聚合和排序。”再思考“我有analyze_data_with_pandas工具。调用它来处理数据找出销量降幅 Top 3。”再行动调用数据分析工具。再观察拿到了处理结果。“现在需要生成报告。我有generate_markdown_report工具。”最终行动与输出调用报告生成工具将最终结果返回给用户。这个“思考 - 行动 - 观察 - 再思考...”的循环就是 Agent 的核心工作流业内常称为ReActReasoning Acting框架。Agent 通过这个循环将复杂的任务分解为可执行的子步骤并动态决定每一步该做什么、使用什么工具。2.2 主流 Agent 框架纵览从 LangChain 到自主框架理解了核心思想我们来看看实现它的“脚手架”—— Agent 框架。框架帮你处理了任务规划、工具调用、记忆管理等通用逻辑让你能更专注于定义具体的任务和工具。LangChain / LangGraph定位生态最繁荣的“全家桶”。它不仅仅是一个 Agent 框架更提供了从连接模型、管理提示词、构建索引到创建 Agent 的全套工具链。其AgentExecutor是早期接触 Agent 概念最直接的入口。优点社区庞大教程和示例极多集成了一大批现成的工具Tools和组件非常适合快速原型验证。缺点抽象层次高有时感觉“黑盒”在构建复杂、定制化高的 Agent 时可能会被其复杂的抽象所困扰性能开销相对较大。适用场景学习 Agent 概念、快速搭建业务原型、利用大量现成生态组件。AutoGen微软定位专注于“多智能体协作”的框架。它的核心思想是创建多个具备不同角色和能力的 Agent让它们通过对话Conversation来协同解决复杂问题。优点多 Agent 对话模式非常直观模拟了人类团队协作内置了群聊管理、对话流程控制等高级功能在需要分工协作的场景下优势明显。缺点对单 Agent 的底层控制不如一些轻量框架直接多 Agent 间的通信成本需要仔细设计。适用场景模拟评审会一个编码 Agent一个测试 Agent一个评审 Agent、复杂任务分解与分配、需要多角度决策的场景。CrewAI定位在 AutoGen 多 Agent 协作思想基础上更加强调“角色扮演”和“结构化流程”。它引入了Role角色如“研究员”、“分析师”、Task任务和Process流程如顺序执行、分层执行等概念。优点抽象非常贴合企业工作流设计清晰易于理解和组织在构建有明确分工和流程的 Agent 团队时代码非常简洁优雅。缺点相对较新生态和社区还在成长中灵活性可能不如底层框架。适用场景内容创作团队策划、写作、校对、标准化业务流程自动化如招聘筛选、客户调研分析。Semantic Kernel微软 / LlamaIndex定位更偏向于将 Agent 能力作为其整体架构的一部分。Semantic Kernel 强调“规划”与“插件”技能LlamaIndex 则擅长数据连接与检索其 Agent 能力常专注于基于知识的问答和决策。适用场景SK 适合深度集成在 .NET 生态或需要复杂规划的应用LlamaIndex Agent 适合构建基于私有知识库的专家顾问。自主开发轻量级框架定位当你对控制力、性能和简洁性有极高要求时完全可以基于 OpenAI 的 Function Calling、Anthropic 的 Tool Use 或开源模型的类似能力自己实现一个轻量级的 ReAct 循环引擎。优点完全可控无额外依赖性能最优深度定制。缺点需要自己实现记忆、工具管理、错误处理等所有基础设施开发成本高。适用场景对延迟和成本敏感的生产级应用、有独特且复杂的工作流需求。实操心得框架选型第一原则不要纠结于寻找“最好”的框架而应寻找“最适合当前阶段和场景”的框架。我强烈建议初学者从 LangChain 开始因为它能让你最快地看到 Agent 跑起来建立直观感受。当你的项目需要清晰的多人协作流程时再转向 CrewAI。当原型验证完毕需要追求极致性能和定制化时再考虑基于底层 API 自研。记住框架是工具你的业务逻辑和对于 Agent 行为的精准控制才是核心。2.3 关键组件深度解析一个完整的 Agent 系统通常由以下核心组件构成理解它们是你进行架构设计的基础LLM大语言模型Agent 的“大脑”。负责理解目标、进行推理、做出决策。选择时需权衡智商能力、速度延迟和成本。闭源模型GPT-4o、Claude 3.5 Sonnet 等能力强但 API 调用有成本和延迟。开源模型Llama 3、Qwen 2.5、DeepSeek 等可本地部署成本可控但可能需要更多提示工程来达到闭源模型的效果。使用 Ollama、LM Studio 等工具可以方便地在本地运行。工具ToolsAgent 的“手脚”。任何 Agent 可以调用的函数例如搜索网络、查询数据库、执行代码、调用第三方 API、操作文件系统等。工具的定义需要清晰的名称、描述和参数模式以便 LLM 理解何时以及如何使用它。记忆MemoryAgent 的“经验”。分为短期记忆当前会话的上下文和长期记忆跨会话存储和检索。如何高效、准确地让 Agent 记住关键信息是避免其“金鱼脑”、实现连贯交互的关键。规划器Planner复杂任务中负责将高层目标分解为一系列子任务的模块。有些框架将其内置于 LLM 的提示中有些则提供独立的规划组件。执行引擎Agent Executor驱动整个 ReAct 循环的“发动机”。它管理着思考、行动、观察的流程处理工具调用的结果决定何时继续、何时停止或何时报错。3. 从零到一构建你的第一个实用 Agent理论说再多不如动手跑通一个。我们以构建一个“技术文档问答与摘要 Agent”为例它能够根据你的问题从指定的技术文档库中查找信息并生成简洁的摘要。3.1 环境准备与框架选择我们选择LangChain作为入门框架因为它生态完善例子多。# 创建项目目录并初始化环境推荐使用 Python 3.10 mkdir tech-doc-agent cd tech-doc-agent python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装核心依赖 pip install langchain langchain-community langchain-openai # 安装用于文档加载和向量数据库的包 pip install chromadb pypdf tiktoken # 安装用于网页访问的工具如果需要 pip install langchain-experimental # 可能包含一些实验性工具这里我们选择 OpenAI 的模型作为大脑同时使用 Chroma 作为向量数据库来存储和检索文档知识。langchain-experimental里包含一些有用的工具链。3.2 构建核心工具集让 Agent 拥有“手脚”Agent 的强大与否很大程度上取决于它的工具库。我们为这个文档 Agent 打造几个核心工具。# tools.py import os from typing import Type from langchain.tools import BaseTool, Tool from pydantic import BaseModel, Field import requests from bs4 import BeautifulSoup # 工具1网络搜索工具模拟 class WebSearchInput(BaseModel): query: str Field(description用于搜索的查询关键词) class WebSearchTool(BaseTool): name web_search description 在互联网上搜索最新的技术资讯或未知的公开信息。当问题涉及最新动态或知识库中没有的信息时使用。 args_schema: Type[BaseModel] WebSearchInput def _run(self, query: str) - str: # 注意这是一个简化示例。实际应用中你应该接入Serper API、Google Search API等。 # 这里我们模拟返回一些固定结果。 print(f[工具调用] 正在搜索: {query}) # 模拟网络请求和解析 # response requests.get(fhttps://api.serper.dev/search?q{query}) # 解析 response.json()... return f关于 {query} 的模拟搜索结果1. LangChain发布了0.2版本。2. 向量数据库Chroma宣布支持新索引。3. 相关博客文章《如何优化RAG系统》。 def _arun(self, query: str): raise NotImplementedError(此工具不支持异步) # 工具2计算器 class CalculatorInput(BaseModel): expression: str Field(description需要计算的数学表达式例如 3 * (4 5)) class CalculatorTool(BaseTool): name calculator description 计算一个数学表达式的值。用于解决任何涉及数字计算的问题。 args_schema: Type[BaseModel] CalculatorInput def _run(self, expression: str) - str: print(f[工具调用] 正在计算: {expression}) try: # 警告直接使用eval有安全风险仅用于演示。生产环境应使用安全计算库如 ast.literal_eval 或 numexpr result eval(expression) return f计算结果: {expression} {result} except Exception as e: return f计算错误: {e} def _arun(self, expression: str): raise NotImplementedError(此工具不支持异步) # 工具3获取当前时间 from datetime import datetime def get_current_time(format: str %Y-%m-%d %H:%M:%S): 返回当前时间。用于回答与时间相关的问题。 now datetime.now() return now.strftime(format) # 将函数包装成LangChain Tool time_tool Tool( nameget_current_time, funcget_current_time, description获取当前的日期和时间。当用户的问题涉及‘现在’、‘今天’、‘当前时间’时使用。 ) # 工具4文档检索工具核心 # 这个工具需要与向量数据库联动我们稍后在主流程中构建。注意事项工具设计的艺术描述description是灵魂LLM 完全依靠工具的name和description来决定是否以及如何调用它。描述必须清晰、准确说明工具的用途、适用场景和输入格式。例如“计算数学表达式”就比“做计算”好得多。输入模式args_schema使用 Pydantic 模型严格定义输入参数这能帮助 LLM 生成格式正确的参数。Field中的description对每个参数也至关重要。安全与边界像CalculatorTool中使用eval是极其危险的绝对不能用于生产环境。这里仅为演示。实际工具必须进行严格的输入验证和沙箱隔离。工具粒度工具应该保持“单一职责”。一个工具只做一件事。不要创建一个“万能的文档处理工具”而应该拆分成“检索文档”、“总结文档”、“翻译文档”等多个小工具。3.3 构建知识库与检索工具我们的 Agent 需要能理解专业文档这就需要给它建立一个“长期记忆”——向量知识库。# knowledge_base.py from langchain_community.document_loaders import PyPDFLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma import os # 1. 加载文档 def load_documents(doc_path): all_docs [] if os.path.isdir(doc_path): for filename in os.listdir(doc_path): file_path os.path.join(doc_path, filename) if filename.endswith(.pdf): loader PyPDFLoader(file_path) elif filename.endswith(.txt) or filename.endswith(.md): loader TextLoader(file_path, encodingutf-8) else: continue docs loader.load() all_docs.extend(docs) else: # 假设是单个文件 if doc_path.endswith(.pdf): loader PyPDFLoader(doc_path) else: loader TextLoader(doc_path, encodingutf-8) all_docs loader.load() print(f已加载 {len(all_docs)} 个文档片段。) return all_docs # 2. 分割文本 def split_documents(docs): text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个片段的大小 chunk_overlap200, # 片段间的重叠部分保持上下文连贯 separators[\n\n, \n, 。, , , , , , ] ) split_docs text_splitter.split_documents(docs) print(f分割后得到 {len(split_docs)} 个文本块。) return split_docs # 3. 创建向量数据库 def create_vector_store(split_docs, persist_directory./chroma_db): # 初始化嵌入模型需要设置 OPENAI_API_KEY 环境变量 embeddings OpenAIEmbeddings(modeltext-embedding-3-small) # 创建并持久化向量存储 vectordb Chroma.from_documents( documentssplit_docs, embeddingembeddings, persist_directorypersist_directory ) vectordb.persist() print(f向量数据库已创建并保存至 {persist_directory}) return vectordb # 主函数初始化知识库 if __name__ __main__: # 假设你的技术文档放在 ./docs 目录下 raw_docs load_documents(./docs) split_docs split_documents(raw_docs) vector_store create_vector_store(split_docs)运行这个脚本它会将你的文档切片、转化为向量并存入本地的 Chroma 数据库。接下来我们需要创建一个检索工具让 Agent 能够查询这个知识库。# 在主程序中集成检索工具 from langchain.tools import Tool def setup_retrieval_tool(vector_store): # 定义检索函数 def retrieve_docs(query: str, k: int 4) - str: 从知识库中检索与问题最相关的文档片段。 print(f[检索工具] 正在查询: {query}) retriever vector_store.as_retriever(search_kwargs{k: k}) docs retriever.invoke(query) context \n\n---\n\n.join([doc.page_content for doc in docs]) return f根据你的问题我从知识库中找到了以下相关信息\n\n{context} # 包装成 Tool retrieval_tool Tool( namesearch_tech_docs, funcretrieve_docs, description从内部技术文档知识库中搜索相关信息。当问题涉及公司技术、产品文档、API 使用或内部流程时优先使用此工具。 ) return retrieval_tool3.4 组装 Agent 并运行现在我们把大脑LLM、工具和记忆组装起来。# main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationBufferMemory from knowledge_base import create_vector_store, load_documents, split_documents from tools import WebSearchTool, CalculatorTool, time_tool, setup_retrieval_tool # 加载环境变量在 .env 文件中设置 OPENAI_API_KEY load_dotenv() # 1. 初始化 LLM llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 使用 gpt-4o-mini 平衡性能与成本 # 2. 准备工具列表 tools [] # 添加基础工具 tools.append(WebSearchTool()) tools.append(CalculatorTool()) tools.append(time_tool) # 3. 初始化知识库和检索工具假设已经运行过 knowledge_base.py 创建了数据库 persist_dir ./chroma_db if not os.path.exists(persist_dir): print(未找到向量数据库正在创建...) raw_docs load_documents(./docs) # 你的文档路径 split_docs split_documents(raw_docs) vector_store create_vector_store(split_docs, persist_dir) else: from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vector_store Chroma(persist_directorypersist_dir, embedding_functionembeddings) print(已加载现有向量数据库。) retrieval_tool setup_retrieval_tool(vector_store) tools.append(retrieval_tool) # 添加检索工具 # 4. 创建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的技术文档助手。你的核心能力是结合内部知识库和外部工具准确、高效地回答技术问题。 请遵循以下步骤思考 1. 首先判断用户问题是否与内部技术文档如产品手册、API文档、内部wiki相关。 2. 如果相关务必优先使用 search_tech_docs 工具从知识库中查找信息。 3. 如果知识库信息不足或问题涉及最新动态、通用计算、时间等再使用其他工具。 4. 你的回答应基于工具返回的事实做到简洁、清晰、有条理。如果信息来自知识库可以注明。 请严格使用提供的工具。不要编造信息。), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), # 这是给Agent记录思考过程的地方 ]) # 5. 创建记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建 Agent 和 Executor agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 开启详细日志方便调试 handle_parsing_errorsTrue, # 优雅处理解析错误 max_iterations10, # 防止死循环 early_stopping_methodgenerate # 当Agent认为任务完成时停止 ) # 7. 运行测试 if __name__ __main__: print(技术文档问答 Agent 已启动输入 quit 退出。) while True: user_input input(\n你: ) if user_input.lower() quit: break try: response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f执行出错: {e})运行python main.py你的第一个具备文档检索、网络搜索、计算等能力的 Agent 就启动了试试问它“LangChain 的 AgentExecutor 是做什么用的” 它会先调用search_tech_docs工具去你的知识库里找答案。4. 进阶实战打造更强大的 Agent 系统一个基础的 Agent 跑起来只是第一步。要让它在真实场景中可靠工作我们需要解决一系列进阶问题。4.1 记忆系统的设计与优化基础的ConversationBufferMemory会把所有对话历史都塞进上下文这有两个问题1) 消耗大量 Token成本高、速度慢2) 无关历史会干扰模型当前决策。解决方案向量记忆与摘要记忆向量记忆将对话中的重要事实例如用户说“我叫张三”“我的项目用的是 Python 3.11”转化为向量存入一个独立的向量数据库。当需要回忆时用当前问题去检索相关的记忆片段。这实现了“长期记忆”和“精准回忆”。摘要记忆随着对话进行定期让 LLM 对之前的对话历史进行总结用一段简短的摘要替代冗长的原始记录。新的对话基于“摘要 近期对话”进行。# 示例结合摘要记忆和向量记忆概念代码 from langchain.memory import ConversationSummaryBufferMemory, VectorStoreRetrieverMemory from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma # 摘要记忆保留最近交互的原始记录但将更早的历史总结起来 summary_memory ConversationSummaryBufferMemory( llmllm, # 需要一个LLM来生成摘要 memory_keychat_history, max_token_limit1000, # 控制上下文总长度 return_messagesTrue ) # 向量记忆存储和检索关键事实 embeddings OpenAIEmbeddings() vectorstore Chroma(embedding_functionembeddings) retriever vectorstore.as_retriever() vector_memory VectorStoreRetrieverMemory(retrieverretriever) # 在提示词中可以同时引入两种记忆 prompt ChatPromptTemplate.from_messages([ (system, 你是一个助手。以下是之前对话的摘要{summary}\n\n此外以下是一些相关的事实{relevant_facts}), MessagesPlaceholder(variable_namerecent_chat_history), (human, {input}), ]) # 需要在调用时分别从 summary_memory 和 vector_memory 获取内容并格式化填入。4.2 复杂任务规划与分解对于“帮我制定一个下周的营销计划”这样的复杂任务单步思考的 ReAct 可能力不从心。我们需要引入规划器Planner。实现思路任务分解首先用一个专门的“规划 LLM”将大目标分解为清晰的、有序的子任务列表。例如[“分析目标受众” “研究竞品动态” “制定内容主题” “规划发布渠道”]。子任务执行让“执行 Agent”依次或并行处理每个子任务每个子任务都可以使用自己的工具集。结果合成所有子任务完成后由一个“合成 Agent”或主 Agent 将结果汇总成最终输出。CrewAI 在这方面提供了优雅的抽象# 使用CrewAI的示例框架 from crewai import Agent, Task, Crew, Process from langchain_openai import ChatOpenAI # 定义角色 Agent researcher Agent( role市场研究员, goal找出最新的市场趋势和竞争对手信息, backstory你是一名资深市场分析师擅长从海量信息中提炼关键洞察。, llmChatOpenAI(modelgpt-4), tools[web_search_tool] # 赋予它搜索工具 ) writer Agent( role内容策略师, goal基于研究结果制定有吸引力的内容主题和文案, backstory你是一名创意十足的内容专家知道如何打动目标客户。, llmChatOpenAI(modelgpt-4), # 可以赋予它文档写作工具 ) # 定义任务 task1 Task( description分析2024年Q3在AI编程助手领域的市场竞争格局和用户主要痛点。, agentresearcher, expected_output一份包含3-5个关键发现点的简明报告。 ) task2 Task( description基于研究员提供的报告构思一个针对初级开发者的内容营销活动包括3个核心主题和对应的宣传语。, agentwriter, context[task1], # 依赖任务1的输出 expected_output一份内容营销方案草案。 ) # 组建团队并运行 crew Crew( agents[researcher, writer], tasks[task1, task2], processProcess.sequential, # 顺序执行也可以选 hierarchical分层或 sequential顺序 verbose2 ) result crew.kickoff() print(result)4.3 工具调用的可靠性保障工具调用失败是家常便饭。API 超时、参数错误、返回结果格式异常……我们必须让 Agent 具备容错和重试能力。结构化输出与重试使用支持 JSON 模式如 GPT-4或 Function Calling 的模型能极大提高工具调用参数解析的成功率。同时在AgentExecutor中设置max_execution_time和max_iterations来防止无限循环。错误处理与降级策略在工具函数内部做好异常捕获返回结构化的错误信息例如{error: true, message: API请求超时}。在 Agent 的提示词中可以教导它“如果某个工具调用失败请尝试另一种方法或告知用户具体错误。”验证与确认对于高风险操作如删除文件、发送邮件可以实现一个“确认工具”让 Agent 在最终执行前先输出计划操作让用户确认。# 一个更健壮的工具函数示例 import requests from tenacity import retry, stop_after_attempt, wait_exponential class SafeAPITool(BaseTool): name fetch_data_from_api description 从一个指定的API端点获取数据。 args_schema: Type[BaseModel] APIToolInput retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def _call_api(self, url): response requests.get(url, timeout10) response.raise_for_status() return response.json() def _run(self, url: str) - str: try: data self._call_api(url) return fAPI调用成功返回数据{data} except requests.exceptions.Timeout: return 错误API请求超时请检查网络或稍后重试。 except requests.exceptions.HTTPError as e: return f错误API返回了HTTP错误状态码{e.response.status_code} except Exception as e: return f错误调用API时发生未知异常 - {str(e)}5. 避坑指南与性能优化在实际项目中我踩过不少坑也总结出一些让 Agent 更“聪明”、更稳定的经验。5.1 提示词工程引导 Agent 正确思考Agent 的行为几乎完全由提示词System Prompt塑造。一份好的提示词需要明确角色与边界开宗明义告诉 Agent 它“是谁”、“该做什么”、“不该做什么”。定义清晰的思考流程像我们之前示例那样给出步骤化的指导“先判断再检索后计算”。格式化输出要求要求 Agent 以特定格式如 Markdown、JSON输出便于后续处理。提供少量示例Few-Shot在提示词中加入一两个完整的思考-行动-观察的示例能显著提升 Agent 的推理质量。# 一个改进版的 System Prompt 示例 你是一个严谨的技术支持专家。你的目标是准确、高效地解决用户的技术问题。 **工作流程** 1. **理解与分类**首先精确理解用户问题。判断它属于A) 内部知识库文档问题B) 通用技术问题C) 需要计算或查询外部信息的问题。 2. **选择工具** - 如果是 A使用 search_tech_docs。 - 如果是 B 且知识库无答案使用 web_search。 - 如果是 C使用 calculator 或 get_current_time。 3. **执行与整合**调用工具仔细分析工具返回的结果。如果结果不完整或未解决问题可以继续思考并使用其他工具。 4. **生成回答**基于所有工具返回的**事实**组织答案。答案应结构清晰分点说明。如果信息来源于知识库请在末尾注明。 **重要规则** - 绝对不要编造你不知道的信息。如果工具没有返回相关信息就如实告知用户“根据现有资料未找到相关信息”。 - 一次只调用一个工具。 - 你的最终输出必须是纯文本可以使用 Markdown 格式来增强可读性。 **示例** 用户我们产品的 API 速率限制是多少 思考这是一个关于产品内部 API 的问题应优先查询内部知识库。 行动调用 search_tech_docs查询“API rate limit”。 观察工具返回了知识库中关于“API 配置”的片段其中提到“默认速率限制为每分钟1000次请求”。 回答根据产品文档该 API 的默认速率限制为 **每分钟 1000 次请求**。如需调整请联系管理员。5.2 评估与迭代如何知道你的 Agent 变好了开发 Agent 是一个持续迭代的过程。你需要一套评估方法单元测试为每个工具函数编写测试确保其功能正常。端到端测试构建一个测试集QA对涵盖常见问题、边界情况和易错点。定期运行记录准确率、工具调用成功率、平均响应时间等指标。人工评估定期进行人工审核查看 Agent 在实际对话中的表现特别是它的“思考过程”开启verboseTrue找出逻辑错误或工具误用。A/B测试如果对提示词或模型做了修改可以并行运行新旧两个版本对比它们的回答质量。5.3 成本与延迟优化Agent 的每次“思考”和工具调用都可能产生成本API调用和延迟。模型选型在原型阶段使用能力强的模型如 GPT-4在稳定期可尝试切换到更小、更快的模型如 GPT-4o-mini, Claude Haiku或本地模型通过 Ollama 运行 Llama 3并进行充分的提示词调优。上下文管理如前所述使用摘要记忆、向量记忆来减少不必要的上下文长度这是降低成本和延迟最有效的手段之一。异步与流式对于耗时较长的工具调用如网络请求使用异步执行。对于最终答案的生成如果模型支持使用流式输出Streaming可以提升用户体验。缓存对频繁出现的、结果固定的查询如“你们公司地址在哪”可以在工具层或 Agent 层添加缓存机制。构建一个成熟可用的 Agent 系统远比跑通一个 demo 复杂。它涉及到软件工程、机器学习、用户体验等多个领域的知识。但万变不离其宗核心依然是那个简单的 ReAct 循环让 AI 学会思考学会使用工具学会从错误中学习。从这个循环开始不断丰富它的工具库优化它的记忆和规划能力你就能打造出真正能解决实际问题的智能体。 AI Agent开发实战：从ReAct框架到多智能体协作的完整指南
1. 项目概述为什么现在必须掌握 Agent 开发最近两年如果你在技术社区里没听过“Agent”这个词那可能有点落伍了。从 OpenAI 的 Codex 到各种宣称能自主完成复杂任务的 AI 助手再到招聘网站上悄然出现的“Agent 开发工程师”岗位一股新的技术浪潮已经拍到了岸边。但说实话当我第一次看到“构建 Agent 实战指南”这个标题时心里想的是这又是一个被过度炒作的概念吗还是说它真的代表了一种全新的、能解决实际问题的生产力工具经过一段时间的摸索和几个项目的实战我的结论是Agent 不是噱头而是一种将大语言模型LLM从“聊天机器人”升级为“数字员工”的关键架构思想。它解决的核心痛点是如何让一个 AI 模型不仅会回答“怎么做”还能真正动手去“做”。想象一下你不再需要一步步告诉 AI“先打开这个文件找到第三行修改某个变量然后保存”而是直接说“帮我把这个模块的性能优化一下”它就能自主分析代码、定位瓶颈、尝试多种优化方案并提交修改。这就是 Agent 试图赋予 AI 的能力——自主规划、使用工具、与环境交互并完成目标。对于开发者、产品经理甚至业务人员来说学习构建 Agent 不再是可选的前沿探索而是逐步成为一项核心技能。无论是想开发一个能自动处理客服工单的智能坐席一个能根据自然语言描述自动生成数据分析报告的数据助手还是一个能24小时监控系统并自主排障的运维机器人其底层都是 Agent 技术。因此这篇指南将完全从实战出发抛开那些晦涩的理论和空洞的展望直接带你进入构建一个可用、好用 Agent 的每一个具体环节。我们会从最基础的概念拆解开始一步步走到架构设计、工具集成、记忆与协作最后分享那些只有踩过坑才知道的调试和优化经验。2. 核心概念拆解Agent、框架与智能体生态在动手写第一行代码之前我们必须把几个关键概念掰扯清楚。市面上关于 Agent 的讨论常常混杂着不同层面的术语容易让人晕头转向。2.1 Agent 的本质超越简单提示的“大脑”首先Agent智能体到底是什么你可以把它理解为一个配备了“大脑”通常是 LLM、“记忆”和“手脚”工具的自主程序。它与传统程序或简单提示工程Prompt Engineering最根本的区别在于“循环”与“决策”。简单提示工程用户输入一个问题模型给出一个回答。交互是单次的、静态的。比如你问“Python里怎么排序列表”它回答“用sorted()函数”。任务结束。Agent用户给定一个目标比如“帮我分析一下上个月的销售数据找出销量下降最多的三个产品并写一份简短的报告”。这时Agent 的“大脑”会进行如下思考循环思考Think“要完成这个目标我需要先获取数据。我有访问数据库的工具吗哦有query_database工具。我需要先知道具体是哪个月的数据用户说的是‘上个月’我需要计算一下日期范围。”行动Act调用query_database工具传入计算好的日期参数执行 SQL 查询。观察Observe拿到数据库返回的原始数据。“数据拿到了但很杂乱。我需要一个数据分析工具来聚合和排序。”再思考“我有analyze_data_with_pandas工具。调用它来处理数据找出销量降幅 Top 3。”再行动调用数据分析工具。再观察拿到了处理结果。“现在需要生成报告。我有generate_markdown_report工具。”最终行动与输出调用报告生成工具将最终结果返回给用户。这个“思考 - 行动 - 观察 - 再思考...”的循环就是 Agent 的核心工作流业内常称为ReActReasoning Acting框架。Agent 通过这个循环将复杂的任务分解为可执行的子步骤并动态决定每一步该做什么、使用什么工具。2.2 主流 Agent 框架纵览从 LangChain 到自主框架理解了核心思想我们来看看实现它的“脚手架”—— Agent 框架。框架帮你处理了任务规划、工具调用、记忆管理等通用逻辑让你能更专注于定义具体的任务和工具。LangChain / LangGraph定位生态最繁荣的“全家桶”。它不仅仅是一个 Agent 框架更提供了从连接模型、管理提示词、构建索引到创建 Agent 的全套工具链。其AgentExecutor是早期接触 Agent 概念最直接的入口。优点社区庞大教程和示例极多集成了一大批现成的工具Tools和组件非常适合快速原型验证。缺点抽象层次高有时感觉“黑盒”在构建复杂、定制化高的 Agent 时可能会被其复杂的抽象所困扰性能开销相对较大。适用场景学习 Agent 概念、快速搭建业务原型、利用大量现成生态组件。AutoGen微软定位专注于“多智能体协作”的框架。它的核心思想是创建多个具备不同角色和能力的 Agent让它们通过对话Conversation来协同解决复杂问题。优点多 Agent 对话模式非常直观模拟了人类团队协作内置了群聊管理、对话流程控制等高级功能在需要分工协作的场景下优势明显。缺点对单 Agent 的底层控制不如一些轻量框架直接多 Agent 间的通信成本需要仔细设计。适用场景模拟评审会一个编码 Agent一个测试 Agent一个评审 Agent、复杂任务分解与分配、需要多角度决策的场景。CrewAI定位在 AutoGen 多 Agent 协作思想基础上更加强调“角色扮演”和“结构化流程”。它引入了Role角色如“研究员”、“分析师”、Task任务和Process流程如顺序执行、分层执行等概念。优点抽象非常贴合企业工作流设计清晰易于理解和组织在构建有明确分工和流程的 Agent 团队时代码非常简洁优雅。缺点相对较新生态和社区还在成长中灵活性可能不如底层框架。适用场景内容创作团队策划、写作、校对、标准化业务流程自动化如招聘筛选、客户调研分析。Semantic Kernel微软 / LlamaIndex定位更偏向于将 Agent 能力作为其整体架构的一部分。Semantic Kernel 强调“规划”与“插件”技能LlamaIndex 则擅长数据连接与检索其 Agent 能力常专注于基于知识的问答和决策。适用场景SK 适合深度集成在 .NET 生态或需要复杂规划的应用LlamaIndex Agent 适合构建基于私有知识库的专家顾问。自主开发轻量级框架定位当你对控制力、性能和简洁性有极高要求时完全可以基于 OpenAI 的 Function Calling、Anthropic 的 Tool Use 或开源模型的类似能力自己实现一个轻量级的 ReAct 循环引擎。优点完全可控无额外依赖性能最优深度定制。缺点需要自己实现记忆、工具管理、错误处理等所有基础设施开发成本高。适用场景对延迟和成本敏感的生产级应用、有独特且复杂的工作流需求。实操心得框架选型第一原则不要纠结于寻找“最好”的框架而应寻找“最适合当前阶段和场景”的框架。我强烈建议初学者从 LangChain 开始因为它能让你最快地看到 Agent 跑起来建立直观感受。当你的项目需要清晰的多人协作流程时再转向 CrewAI。当原型验证完毕需要追求极致性能和定制化时再考虑基于底层 API 自研。记住框架是工具你的业务逻辑和对于 Agent 行为的精准控制才是核心。2.3 关键组件深度解析一个完整的 Agent 系统通常由以下核心组件构成理解它们是你进行架构设计的基础LLM大语言模型Agent 的“大脑”。负责理解目标、进行推理、做出决策。选择时需权衡智商能力、速度延迟和成本。闭源模型GPT-4o、Claude 3.5 Sonnet 等能力强但 API 调用有成本和延迟。开源模型Llama 3、Qwen 2.5、DeepSeek 等可本地部署成本可控但可能需要更多提示工程来达到闭源模型的效果。使用 Ollama、LM Studio 等工具可以方便地在本地运行。工具ToolsAgent 的“手脚”。任何 Agent 可以调用的函数例如搜索网络、查询数据库、执行代码、调用第三方 API、操作文件系统等。工具的定义需要清晰的名称、描述和参数模式以便 LLM 理解何时以及如何使用它。记忆MemoryAgent 的“经验”。分为短期记忆当前会话的上下文和长期记忆跨会话存储和检索。如何高效、准确地让 Agent 记住关键信息是避免其“金鱼脑”、实现连贯交互的关键。规划器Planner复杂任务中负责将高层目标分解为一系列子任务的模块。有些框架将其内置于 LLM 的提示中有些则提供独立的规划组件。执行引擎Agent Executor驱动整个 ReAct 循环的“发动机”。它管理着思考、行动、观察的流程处理工具调用的结果决定何时继续、何时停止或何时报错。3. 从零到一构建你的第一个实用 Agent理论说再多不如动手跑通一个。我们以构建一个“技术文档问答与摘要 Agent”为例它能够根据你的问题从指定的技术文档库中查找信息并生成简洁的摘要。3.1 环境准备与框架选择我们选择LangChain作为入门框架因为它生态完善例子多。# 创建项目目录并初始化环境推荐使用 Python 3.10 mkdir tech-doc-agent cd tech-doc-agent python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装核心依赖 pip install langchain langchain-community langchain-openai # 安装用于文档加载和向量数据库的包 pip install chromadb pypdf tiktoken # 安装用于网页访问的工具如果需要 pip install langchain-experimental # 可能包含一些实验性工具这里我们选择 OpenAI 的模型作为大脑同时使用 Chroma 作为向量数据库来存储和检索文档知识。langchain-experimental里包含一些有用的工具链。3.2 构建核心工具集让 Agent 拥有“手脚”Agent 的强大与否很大程度上取决于它的工具库。我们为这个文档 Agent 打造几个核心工具。# tools.py import os from typing import Type from langchain.tools import BaseTool, Tool from pydantic import BaseModel, Field import requests from bs4 import BeautifulSoup # 工具1网络搜索工具模拟 class WebSearchInput(BaseModel): query: str Field(description用于搜索的查询关键词) class WebSearchTool(BaseTool): name web_search description 在互联网上搜索最新的技术资讯或未知的公开信息。当问题涉及最新动态或知识库中没有的信息时使用。 args_schema: Type[BaseModel] WebSearchInput def _run(self, query: str) - str: # 注意这是一个简化示例。实际应用中你应该接入Serper API、Google Search API等。 # 这里我们模拟返回一些固定结果。 print(f[工具调用] 正在搜索: {query}) # 模拟网络请求和解析 # response requests.get(fhttps://api.serper.dev/search?q{query}) # 解析 response.json()... return f关于 {query} 的模拟搜索结果1. LangChain发布了0.2版本。2. 向量数据库Chroma宣布支持新索引。3. 相关博客文章《如何优化RAG系统》。 def _arun(self, query: str): raise NotImplementedError(此工具不支持异步) # 工具2计算器 class CalculatorInput(BaseModel): expression: str Field(description需要计算的数学表达式例如 3 * (4 5)) class CalculatorTool(BaseTool): name calculator description 计算一个数学表达式的值。用于解决任何涉及数字计算的问题。 args_schema: Type[BaseModel] CalculatorInput def _run(self, expression: str) - str: print(f[工具调用] 正在计算: {expression}) try: # 警告直接使用eval有安全风险仅用于演示。生产环境应使用安全计算库如 ast.literal_eval 或 numexpr result eval(expression) return f计算结果: {expression} {result} except Exception as e: return f计算错误: {e} def _arun(self, expression: str): raise NotImplementedError(此工具不支持异步) # 工具3获取当前时间 from datetime import datetime def get_current_time(format: str %Y-%m-%d %H:%M:%S): 返回当前时间。用于回答与时间相关的问题。 now datetime.now() return now.strftime(format) # 将函数包装成LangChain Tool time_tool Tool( nameget_current_time, funcget_current_time, description获取当前的日期和时间。当用户的问题涉及‘现在’、‘今天’、‘当前时间’时使用。 ) # 工具4文档检索工具核心 # 这个工具需要与向量数据库联动我们稍后在主流程中构建。注意事项工具设计的艺术描述description是灵魂LLM 完全依靠工具的name和description来决定是否以及如何调用它。描述必须清晰、准确说明工具的用途、适用场景和输入格式。例如“计算数学表达式”就比“做计算”好得多。输入模式args_schema使用 Pydantic 模型严格定义输入参数这能帮助 LLM 生成格式正确的参数。Field中的description对每个参数也至关重要。安全与边界像CalculatorTool中使用eval是极其危险的绝对不能用于生产环境。这里仅为演示。实际工具必须进行严格的输入验证和沙箱隔离。工具粒度工具应该保持“单一职责”。一个工具只做一件事。不要创建一个“万能的文档处理工具”而应该拆分成“检索文档”、“总结文档”、“翻译文档”等多个小工具。3.3 构建知识库与检索工具我们的 Agent 需要能理解专业文档这就需要给它建立一个“长期记忆”——向量知识库。# knowledge_base.py from langchain_community.document_loaders import PyPDFLoader, TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma import os # 1. 加载文档 def load_documents(doc_path): all_docs [] if os.path.isdir(doc_path): for filename in os.listdir(doc_path): file_path os.path.join(doc_path, filename) if filename.endswith(.pdf): loader PyPDFLoader(file_path) elif filename.endswith(.txt) or filename.endswith(.md): loader TextLoader(file_path, encodingutf-8) else: continue docs loader.load() all_docs.extend(docs) else: # 假设是单个文件 if doc_path.endswith(.pdf): loader PyPDFLoader(doc_path) else: loader TextLoader(doc_path, encodingutf-8) all_docs loader.load() print(f已加载 {len(all_docs)} 个文档片段。) return all_docs # 2. 分割文本 def split_documents(docs): text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个片段的大小 chunk_overlap200, # 片段间的重叠部分保持上下文连贯 separators[\n\n, \n, 。, , , , , , ] ) split_docs text_splitter.split_documents(docs) print(f分割后得到 {len(split_docs)} 个文本块。) return split_docs # 3. 创建向量数据库 def create_vector_store(split_docs, persist_directory./chroma_db): # 初始化嵌入模型需要设置 OPENAI_API_KEY 环境变量 embeddings OpenAIEmbeddings(modeltext-embedding-3-small) # 创建并持久化向量存储 vectordb Chroma.from_documents( documentssplit_docs, embeddingembeddings, persist_directorypersist_directory ) vectordb.persist() print(f向量数据库已创建并保存至 {persist_directory}) return vectordb # 主函数初始化知识库 if __name__ __main__: # 假设你的技术文档放在 ./docs 目录下 raw_docs load_documents(./docs) split_docs split_documents(raw_docs) vector_store create_vector_store(split_docs)运行这个脚本它会将你的文档切片、转化为向量并存入本地的 Chroma 数据库。接下来我们需要创建一个检索工具让 Agent 能够查询这个知识库。# 在主程序中集成检索工具 from langchain.tools import Tool def setup_retrieval_tool(vector_store): # 定义检索函数 def retrieve_docs(query: str, k: int 4) - str: 从知识库中检索与问题最相关的文档片段。 print(f[检索工具] 正在查询: {query}) retriever vector_store.as_retriever(search_kwargs{k: k}) docs retriever.invoke(query) context \n\n---\n\n.join([doc.page_content for doc in docs]) return f根据你的问题我从知识库中找到了以下相关信息\n\n{context} # 包装成 Tool retrieval_tool Tool( namesearch_tech_docs, funcretrieve_docs, description从内部技术文档知识库中搜索相关信息。当问题涉及公司技术、产品文档、API 使用或内部流程时优先使用此工具。 ) return retrieval_tool3.4 组装 Agent 并运行现在我们把大脑LLM、工具和记忆组装起来。# main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationBufferMemory from knowledge_base import create_vector_store, load_documents, split_documents from tools import WebSearchTool, CalculatorTool, time_tool, setup_retrieval_tool # 加载环境变量在 .env 文件中设置 OPENAI_API_KEY load_dotenv() # 1. 初始化 LLM llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 使用 gpt-4o-mini 平衡性能与成本 # 2. 准备工具列表 tools [] # 添加基础工具 tools.append(WebSearchTool()) tools.append(CalculatorTool()) tools.append(time_tool) # 3. 初始化知识库和检索工具假设已经运行过 knowledge_base.py 创建了数据库 persist_dir ./chroma_db if not os.path.exists(persist_dir): print(未找到向量数据库正在创建...) raw_docs load_documents(./docs) # 你的文档路径 split_docs split_documents(raw_docs) vector_store create_vector_store(split_docs, persist_dir) else: from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vector_store Chroma(persist_directorypersist_dir, embedding_functionembeddings) print(已加载现有向量数据库。) retrieval_tool setup_retrieval_tool(vector_store) tools.append(retrieval_tool) # 添加检索工具 # 4. 创建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的技术文档助手。你的核心能力是结合内部知识库和外部工具准确、高效地回答技术问题。 请遵循以下步骤思考 1. 首先判断用户问题是否与内部技术文档如产品手册、API文档、内部wiki相关。 2. 如果相关务必优先使用 search_tech_docs 工具从知识库中查找信息。 3. 如果知识库信息不足或问题涉及最新动态、通用计算、时间等再使用其他工具。 4. 你的回答应基于工具返回的事实做到简洁、清晰、有条理。如果信息来自知识库可以注明。 请严格使用提供的工具。不要编造信息。), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), # 这是给Agent记录思考过程的地方 ]) # 5. 创建记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建 Agent 和 Executor agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 开启详细日志方便调试 handle_parsing_errorsTrue, # 优雅处理解析错误 max_iterations10, # 防止死循环 early_stopping_methodgenerate # 当Agent认为任务完成时停止 ) # 7. 运行测试 if __name__ __main__: print(技术文档问答 Agent 已启动输入 quit 退出。) while True: user_input input(\n你: ) if user_input.lower() quit: break try: response agent_executor.invoke({input: user_input}) print(f\n助手: {response[output]}) except Exception as e: print(f执行出错: {e})运行python main.py你的第一个具备文档检索、网络搜索、计算等能力的 Agent 就启动了试试问它“LangChain 的 AgentExecutor 是做什么用的” 它会先调用search_tech_docs工具去你的知识库里找答案。4. 进阶实战打造更强大的 Agent 系统一个基础的 Agent 跑起来只是第一步。要让它在真实场景中可靠工作我们需要解决一系列进阶问题。4.1 记忆系统的设计与优化基础的ConversationBufferMemory会把所有对话历史都塞进上下文这有两个问题1) 消耗大量 Token成本高、速度慢2) 无关历史会干扰模型当前决策。解决方案向量记忆与摘要记忆向量记忆将对话中的重要事实例如用户说“我叫张三”“我的项目用的是 Python 3.11”转化为向量存入一个独立的向量数据库。当需要回忆时用当前问题去检索相关的记忆片段。这实现了“长期记忆”和“精准回忆”。摘要记忆随着对话进行定期让 LLM 对之前的对话历史进行总结用一段简短的摘要替代冗长的原始记录。新的对话基于“摘要 近期对话”进行。# 示例结合摘要记忆和向量记忆概念代码 from langchain.memory import ConversationSummaryBufferMemory, VectorStoreRetrieverMemory from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma # 摘要记忆保留最近交互的原始记录但将更早的历史总结起来 summary_memory ConversationSummaryBufferMemory( llmllm, # 需要一个LLM来生成摘要 memory_keychat_history, max_token_limit1000, # 控制上下文总长度 return_messagesTrue ) # 向量记忆存储和检索关键事实 embeddings OpenAIEmbeddings() vectorstore Chroma(embedding_functionembeddings) retriever vectorstore.as_retriever() vector_memory VectorStoreRetrieverMemory(retrieverretriever) # 在提示词中可以同时引入两种记忆 prompt ChatPromptTemplate.from_messages([ (system, 你是一个助手。以下是之前对话的摘要{summary}\n\n此外以下是一些相关的事实{relevant_facts}), MessagesPlaceholder(variable_namerecent_chat_history), (human, {input}), ]) # 需要在调用时分别从 summary_memory 和 vector_memory 获取内容并格式化填入。4.2 复杂任务规划与分解对于“帮我制定一个下周的营销计划”这样的复杂任务单步思考的 ReAct 可能力不从心。我们需要引入规划器Planner。实现思路任务分解首先用一个专门的“规划 LLM”将大目标分解为清晰的、有序的子任务列表。例如[“分析目标受众” “研究竞品动态” “制定内容主题” “规划发布渠道”]。子任务执行让“执行 Agent”依次或并行处理每个子任务每个子任务都可以使用自己的工具集。结果合成所有子任务完成后由一个“合成 Agent”或主 Agent 将结果汇总成最终输出。CrewAI 在这方面提供了优雅的抽象# 使用CrewAI的示例框架 from crewai import Agent, Task, Crew, Process from langchain_openai import ChatOpenAI # 定义角色 Agent researcher Agent( role市场研究员, goal找出最新的市场趋势和竞争对手信息, backstory你是一名资深市场分析师擅长从海量信息中提炼关键洞察。, llmChatOpenAI(modelgpt-4), tools[web_search_tool] # 赋予它搜索工具 ) writer Agent( role内容策略师, goal基于研究结果制定有吸引力的内容主题和文案, backstory你是一名创意十足的内容专家知道如何打动目标客户。, llmChatOpenAI(modelgpt-4), # 可以赋予它文档写作工具 ) # 定义任务 task1 Task( description分析2024年Q3在AI编程助手领域的市场竞争格局和用户主要痛点。, agentresearcher, expected_output一份包含3-5个关键发现点的简明报告。 ) task2 Task( description基于研究员提供的报告构思一个针对初级开发者的内容营销活动包括3个核心主题和对应的宣传语。, agentwriter, context[task1], # 依赖任务1的输出 expected_output一份内容营销方案草案。 ) # 组建团队并运行 crew Crew( agents[researcher, writer], tasks[task1, task2], processProcess.sequential, # 顺序执行也可以选 hierarchical分层或 sequential顺序 verbose2 ) result crew.kickoff() print(result)4.3 工具调用的可靠性保障工具调用失败是家常便饭。API 超时、参数错误、返回结果格式异常……我们必须让 Agent 具备容错和重试能力。结构化输出与重试使用支持 JSON 模式如 GPT-4或 Function Calling 的模型能极大提高工具调用参数解析的成功率。同时在AgentExecutor中设置max_execution_time和max_iterations来防止无限循环。错误处理与降级策略在工具函数内部做好异常捕获返回结构化的错误信息例如{error: true, message: API请求超时}。在 Agent 的提示词中可以教导它“如果某个工具调用失败请尝试另一种方法或告知用户具体错误。”验证与确认对于高风险操作如删除文件、发送邮件可以实现一个“确认工具”让 Agent 在最终执行前先输出计划操作让用户确认。# 一个更健壮的工具函数示例 import requests from tenacity import retry, stop_after_attempt, wait_exponential class SafeAPITool(BaseTool): name fetch_data_from_api description 从一个指定的API端点获取数据。 args_schema: Type[BaseModel] APIToolInput retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def _call_api(self, url): response requests.get(url, timeout10) response.raise_for_status() return response.json() def _run(self, url: str) - str: try: data self._call_api(url) return fAPI调用成功返回数据{data} except requests.exceptions.Timeout: return 错误API请求超时请检查网络或稍后重试。 except requests.exceptions.HTTPError as e: return f错误API返回了HTTP错误状态码{e.response.status_code} except Exception as e: return f错误调用API时发生未知异常 - {str(e)}5. 避坑指南与性能优化在实际项目中我踩过不少坑也总结出一些让 Agent 更“聪明”、更稳定的经验。5.1 提示词工程引导 Agent 正确思考Agent 的行为几乎完全由提示词System Prompt塑造。一份好的提示词需要明确角色与边界开宗明义告诉 Agent 它“是谁”、“该做什么”、“不该做什么”。定义清晰的思考流程像我们之前示例那样给出步骤化的指导“先判断再检索后计算”。格式化输出要求要求 Agent 以特定格式如 Markdown、JSON输出便于后续处理。提供少量示例Few-Shot在提示词中加入一两个完整的思考-行动-观察的示例能显著提升 Agent 的推理质量。# 一个改进版的 System Prompt 示例 你是一个严谨的技术支持专家。你的目标是准确、高效地解决用户的技术问题。 **工作流程** 1. **理解与分类**首先精确理解用户问题。判断它属于A) 内部知识库文档问题B) 通用技术问题C) 需要计算或查询外部信息的问题。 2. **选择工具** - 如果是 A使用 search_tech_docs。 - 如果是 B 且知识库无答案使用 web_search。 - 如果是 C使用 calculator 或 get_current_time。 3. **执行与整合**调用工具仔细分析工具返回的结果。如果结果不完整或未解决问题可以继续思考并使用其他工具。 4. **生成回答**基于所有工具返回的**事实**组织答案。答案应结构清晰分点说明。如果信息来源于知识库请在末尾注明。 **重要规则** - 绝对不要编造你不知道的信息。如果工具没有返回相关信息就如实告知用户“根据现有资料未找到相关信息”。 - 一次只调用一个工具。 - 你的最终输出必须是纯文本可以使用 Markdown 格式来增强可读性。 **示例** 用户我们产品的 API 速率限制是多少 思考这是一个关于产品内部 API 的问题应优先查询内部知识库。 行动调用 search_tech_docs查询“API rate limit”。 观察工具返回了知识库中关于“API 配置”的片段其中提到“默认速率限制为每分钟1000次请求”。 回答根据产品文档该 API 的默认速率限制为 **每分钟 1000 次请求**。如需调整请联系管理员。5.2 评估与迭代如何知道你的 Agent 变好了开发 Agent 是一个持续迭代的过程。你需要一套评估方法单元测试为每个工具函数编写测试确保其功能正常。端到端测试构建一个测试集QA对涵盖常见问题、边界情况和易错点。定期运行记录准确率、工具调用成功率、平均响应时间等指标。人工评估定期进行人工审核查看 Agent 在实际对话中的表现特别是它的“思考过程”开启verboseTrue找出逻辑错误或工具误用。A/B测试如果对提示词或模型做了修改可以并行运行新旧两个版本对比它们的回答质量。5.3 成本与延迟优化Agent 的每次“思考”和工具调用都可能产生成本API调用和延迟。模型选型在原型阶段使用能力强的模型如 GPT-4在稳定期可尝试切换到更小、更快的模型如 GPT-4o-mini, Claude Haiku或本地模型通过 Ollama 运行 Llama 3并进行充分的提示词调优。上下文管理如前所述使用摘要记忆、向量记忆来减少不必要的上下文长度这是降低成本和延迟最有效的手段之一。异步与流式对于耗时较长的工具调用如网络请求使用异步执行。对于最终答案的生成如果模型支持使用流式输出Streaming可以提升用户体验。缓存对频繁出现的、结果固定的查询如“你们公司地址在哪”可以在工具层或 Agent 层添加缓存机制。构建一个成熟可用的 Agent 系统远比跑通一个 demo 复杂。它涉及到软件工程、机器学习、用户体验等多个领域的知识。但万变不离其宗核心依然是那个简单的 ReAct 循环让 AI 学会思考学会使用工具学会从错误中学习。从这个循环开始不断丰富它的工具库优化它的记忆和规划能力你就能打造出真正能解决实际问题的智能体。