最近在尝试将大语言模型LLM应用到实际业务场景时你是否遇到过这样的困境模型本身能力很强但让它独立完成一个复杂任务比如分析一份财报并生成投资建议时结果却常常不尽人意要么是逻辑混乱要么是遗漏关键步骤要么干脆“一本正经地胡说八道”。这背后暴露了一个核心问题直接调用一个“裸”的LLM就像让一个知识渊博但缺乏项目管理经验的天才去完成一个系统工程他可能知道每一步该做什么却不知道如何规划、协调、检查和修正。而智能体运行框架Agentic Harness正是为了解决这个问题而生的“项目管理工具箱”和“自动化流水线”。本文将为你系统拆解智能体运行框架的核心概念、工作原理、主流实现以及如何从零开始搭建一个简单的智能体。无论你是想了解AI应用前沿的开发者还是正在寻找将LLM能力产品化落地的工程师这篇文章都将提供一套清晰的认知地图和实操指南。1. 从单次问答到智能体为什么需要运行框架在深入框架之前我们必须先理解“智能体Agent”究竟是什么。简单来说智能体 大语言模型LLM 思考规划能力 工具使用能力 记忆能力。传统LLM调用Chat Completion用户输入一个问题模型基于其训练数据生成一个回答。这是一个单次、静态的交互。模型没有“状态”不会记住之前的对话也不会主动去调用搜索引擎或计算器。智能体Agent用户给定一个目标例如“帮我分析一下公司Q3财报”智能体会将这个目标分解为一系列子任务获取财报PDF、提取关键数据、对比历史数据、查询行业新闻、生成分析报告。它会自主决定每一步做什么规划调用合适的工具如PDF解析器、数据库、搜索引擎来执行评估执行结果并根据需要调整计划最终达成目标。这是一个多步、动态、有状态的交互过程。那么智能体运行框架Agentic Harness就是用来构建、管理和执行这类智能体的软件基础设施。你可以把它想象成一个调度中心协调LLM、工具、记忆模块之间的工作流。一个标准化接口定义了智能体如何思考、行动、观察环境并学习。一个可复用的工具箱提供了记忆、工具调用、规划、验证等常用组件的实现。没有框架你需要从零开始处理任务分解、工具路由、状态管理、错误处理等复杂逻辑有了框架你可以像搭积木一样快速组合出功能强大的智能体应用。2. 智能体运行框架的核心组件与工作原理一个典型的智能体运行框架通常包含以下几个核心组件它们共同协作完成“感知-思考-行动”的循环ReAct模式Reason Act。2.1 核心组件拆解规划器Planner职责将用户的复杂目标分解为可执行的子任务序列或流程图。这是智能体“思考”的核心。实现方式通常由LLM驱动。框架会提供提示词Prompt模板引导LLM进行任务分解。例如使用Chain-of-Thought思维链或Tree-of-Thought思维树等技术。示例目标“写一份市场调研报告” - 规划器输出步骤[1. 确定调研关键词 2. 使用搜索引擎收集信息 3. 总结信息要点 4. 生成报告大纲 5. 撰写报告正文]。工具集Tools职责扩展智能体的能力边界使其能够与外部世界交互。LLM本身不会计算、不会搜索、不能操作数据库工具就是它的“手和脚”。常见工具网络搜索如SerpAPI、DuckDuckGo。代码执行Python REPL用于数学计算或数据处理。文件操作读写本地文件解析PDF、Word、Excel。API调用连接企业内部系统CRM、ERP或第三方服务天气、股票。数据库查询执行SQL语句获取业务数据。框架的作用统一工具的注册、描述和调用接口。LLM通过工具的描述名称、功能、参数格式来决定何时调用哪个工具。记忆系统Memory职责存储和管理智能体与用户交互的历史包括对话、工具执行结果、中间状态等。使智能体具备连续性和上下文感知能力。类型短期记忆/对话记忆保存当前会话的完整历史。长期记忆/向量记忆将历史信息转换为向量存入向量数据库如Chroma、Pinecone实现基于语义的快速检索。当遇到类似问题时智能体可以“回忆”起过去的经验。摘要记忆将冗长的对话历史压缩成摘要以节省上下文窗口。执行引擎Execution Engine职责驱动整个“规划-执行-观察”循环。它按照规划器的输出依次调用工具将工具返回的结果观察反馈给LLM由LLM决定下一步行动继续、调整或结束。关键机制循环控制决定何时停止任务完成或无法继续。错误处理当工具调用失败或LLM输出格式错误时进行重试或降级处理。状态管理维护当前任务执行的上下文状态。评估与反思Evaluation Reflection职责对智能体行动的结果进行质量检查并在必要时进行修正。这是实现更可靠、更精确智能体的高级能力。工作流程智能体生成一个初步答案后框架可以启动一个“反思”步骤让另一个LLM或同一个LLM以批判性视角检查答案的准确性、完整性和逻辑性发现潜在问题然后重新规划并执行修正。2.2 智能体工作流全景图用户输入复杂目标 | v [规划器] 分解目标为任务序列 | v 进入「思考-行动」循环 | v [思考] LLM根据当前状态和任务决定下一步行动调用工具或结束 | v [行动] 执行引擎调用指定的工具 | v [观察] 获取工具执行结果更新状态和记忆 | v ------循环直到任务完成或达到最大步数------ | v [可选反思] 对最终结果进行评估和修正 | v 输出最终结果给用户3. 主流智能体框架概览与选型目前社区和商业领域已涌现出众多优秀的智能体框架它们各有侧重。了解它们有助于你根据项目需求进行技术选型。3.1 开源框架开发者友好高度定制LangChain / LangGraph定位目前最流行的AI应用开发框架之一其Agent和LangGraph模块是构建智能体的核心。特点生态丰富集成了海量工具、LLM提供商和向量数据库。灵活度高支持自定义Agent执行逻辑、工具和记忆。LangGraph专门用于构建有状态的、多智能体协作的复杂工作流支持循环和分支是构建高级智能体的利器。适合场景研发能力较强的团队需要深度定制复杂智能体工作流。LlamaIndex定位专注于数据检索增强生成RAG的框架但其Agent模块同样强大。特点在私有数据查询、文档问答场景下工具集成度极高智能体可以轻松调用其强大的检索器作为工具。适合场景智能体的核心任务围绕查询和分析企业内部文档、知识库。AutoGen (by Microsoft)定位专注于多智能体对话协作的框架。特点可以轻松定义多个具有不同角色程序员、测试员、产品经理的智能体让它们通过对话协作解决任务。内置了代码执行、人类参与等丰富功能。适合场景需要模拟团队协作完成的任务如软件开发、复杂问题求解。3.2 低代码/平台型框架快速落地注重产品化Dify / Coze扣子定位提供可视化工作流编排的AI应用平台。特点图形化编排通过拖拽节点LLM、工具、判断、循环来构建智能体工作流无需编写大量代码。一体化集成了模型管理、知识库、发布监控、插件市场等产品化功能。降低门槛让非开发者也能参与构建复杂的AI智能体应用。适合场景快速原型验证、业务团队自主搭建AI应用、追求开发效率。3.3 其他值得关注的框架CrewAI受AutoGen启发强调角色扮演和任务导向的多智能体协作设计上更贴近商业流程。Semantic Kernel (by Microsoft)轻量级SDK方便将AI能力集成到现有应用中概念上与LangChain类似。选型建议追求极致控制和定制化选择LangChain (LangGraph)。核心是私有数据问答与分析选择LlamaIndex。构建多智能体协作系统选择AutoGen或CrewAI。追求开发速度需要产品化功能选择Dify或Coze。4. 实战使用 LangChain 搭建你的第一个智能体下面我们将使用 LangChain 和 OpenAI API一步步构建一个能够联网搜索并总结信息的智能体。4.1 环境准备操作系统Windows / macOS / Linux 均可。Python 版本建议 3.8 及以上。关键依赖langchain核心框架。langchain-openaiOpenAI 模型集成。langchain-community社区工具包含搜索引擎工具。python-dotenv管理环境变量。创建项目并安装依赖# 创建项目目录 mkdir my-first-agent cd my-first-agent # 创建虚拟环境可选但推荐 python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 安装依赖 pip install langchain langchain-openai langchain-community python-dotenv # 创建环境变量文件 touch .env4.2 配置 API 密钥在.env文件中添加你的 OpenAI API 密钥和一个搜索引擎 API 密钥这里以 Tavily 为例它专为 AI 优化你也可以使用 SerpAPI 等。# .env OPENAI_API_KEYsk-your-openai-api-key-here TAVILY_API_KEYtvly-your-tavily-api-key-here4.3 编写智能体代码创建一个名为search_agent.py的文件。# search_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain_community.tools.tavily_search import TavilySearchResults from langchain_core.prompts import PromptTemplate # 1. 加载环境变量 load_dotenv() # 2. 初始化大语言模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 使用gpt-3.5-turbo温度设为0使输出更稳定 # 3. 定义工具 # 初始化Tavily搜索工具 search_tool TavilySearchResults(max_results3) # 限制每次搜索返回3条结果 # 将工具放入列表可以在这里添加更多工具如计算器、维基百科查询等 tools [search_tool] # 4. 定义智能体的提示词模板 # ReAct框架的标准提示词模板告诉LLM如何思考、使用工具和格式化输出 prompt_template Answer the following questions as best you can. You have access to the following tools: {tools} Use the following format: Question: the input question you must answer Thought: you should always think about what to do Action: the action to take, should be one of [{tool_names}] Action Input: the input to the action Observation: the result of the action ... (this Thought/Action/Action Input/Observation can repeat N times) Thought: I now know the final answer Final Answer: the final answer to the original question Begin! Question: {input} Thought:{agent_scratchpad} prompt PromptTemplate.from_template(prompt_template) # 5. 创建智能体 agent create_react_agent(llmllm, toolstools, promptprompt) # 6. 创建智能体执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # verboseTrue 打印详细执行过程 # 7. 运行智能体 if __name__ __main__: # 示例问题一个需要最新信息的问题模型本身无法回答 question What are the main highlights of the latest Apple WWDC event? Summarize in three points. print(fQuestion: {question}\n) print(*50) try: result agent_executor.invoke({input: question}) print(\n *50) print(f\nFinal Answer: {result[output]}) except Exception as e: print(fAn error occurred: {e})4.4 运行与结果分析在终端运行脚本python search_agent.py你将看到类似以下的输出verbose模式Question: What are the main highlights of the latest Apple WWDC event? Summarize in three points. Entering new AgentExecutor chain... Thought: I need to find information about the latest Apple WWDC event highlights. I should use the search tool to get recent news. Action: tavily_search_results_json Action Input: latest Apple WWDC 2024 highlights Observation: [{title: Apple WWDC 2024: Everything Announced - MacRumors, url: https://www.macrumors.com/..., content: Apple Intelligence, iOS 18, macOS Sequoia, visionOS 2...}, ...] Thought: Based on the search results, I can see the main announcements. I need to summarize them into three key points. Action: tavily_search_results_json Action Input: Apple WWDC 2024 key announcements summary Observation: [{title: WWDC 2024: Top 5 Announcements from Apple, url: ..., content: 1. Apple Intelligence: New AI system across devices. 2. iOS 18 with customizable Home Screen. 3. macOS Sequoia with iPhone mirroring.}, ...] Thought: I now have enough information to provide a three-point summary. Final Answer: The main highlights of Apple WWDC 2024 are: 1. **Apple Intelligence**: A new personal AI system deeply integrated into iOS, iPadOS, and macOS, offering on-device and server-based models for writing, image generation, and Siri enhancement. 2. **iOS 18**: Major update featuring a highly customizable Home Screen, redesigned Control Center, and new apps like Passwords. 3. **macOS Sequoia**: Introduces iPhone mirroring to Mac, Safari updates, and new gaming features. Finished chain. Final Answer: The main highlights of Apple WWDC 2024 are: 1. **Apple Intelligence**: A new personal AI system deeply integrated into iOS, iPadOS, and macOS, offering on-device and server-based models for writing, image generation, and Siri enhancement. 2. **iOS 18**: Major update featuring a highly customizable Home Screen, redesigned Control Center, and new apps like Passwords. 3. **macOS Sequoia**: Introduces iPhone mirroring to Mac, Safari updates, and new gaming features.过程解读规划智能体LLM看到问题后意识到需要最新信息决定调用搜索工具Thought。行动它执行搜索动作Action输入查询词Action Input。观察获得搜索结果Observation。再规划LLM分析搜索结果认为需要更精确的摘要信息决定进行第二次搜索。再行动与观察执行第二次搜索并获得结果。生成答案LLM基于两次搜索的结果综合生成一个三点式摘要作为最终答案。这个简单的例子展示了智能体运行框架如何将LLM的推理能力与外部工具搜索无缝结合完成一个单靠LLM无法完成或无法保证时效性的任务。5. 进阶构建具备记忆与多工具协作的智能体上面的智能体是“无状态”的每次对话都是独立的。让我们增强它为其添加对话记忆和更多工具。5.1 创建增强版智能体创建新文件advanced_agent.py。# advanced_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain_community.tools.tavily_search import TavilySearchResults from langchain_community.utilities import WikipediaAPIWrapper from langchain_community.tools import WikipediaQueryRun from langchain_community.tools import DuckDuckGoSearchRun from langchain_core.tools import Tool from langchain.memory import ConversationBufferMemory from langchain_core.prompts import MessagesPlaceholder from langchain.agents.format_scratchpad import format_log_to_str from langchain.agents.output_parsers import ReActSingleInputOutputParser from langchain.tools.render import render_text_description from langchain_core.messages import AIMessage, HumanMessage load_dotenv() # 1. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 2. 定义更多工具 search TavilySearchResults(max_results2) wikipedia WikipediaQueryRun(api_wrapperWikipediaAPIWrapper(top_k_results2)) duckduckgo DuckDuckGoSearchRun() # 作为备用搜索 # 一个简单的字符串长度计算工具演示自定义工具 def string_length(text: str) - str: Returns the length of a given string. return fThe length of the string is {len(text)} characters. length_tool Tool( nameStringLength, funcstring_length, descriptionUseful when you need to calculate the length of a string. Input should be a string. ) tools [search, wikipedia, duckduckgo, length_tool] # 3. 创建对话记忆 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 4. 构建自定义提示词包含记忆占位符 prompt_template You are a helpful assistant with access to tools and memory of our conversation. You have access to the following tools: {tools} Use the following format: Question: the input question you must answer Thought: you should always think about what to do Action: the action to take, should be one of [{tool_names}] Action Input: the input to the action Observation: the result of the action ... (this Thought/Action/Action Input/Observation can repeat N times) Thought: I now know the final answer Final Answer: the final answer to the original question Previous conversation history: {chat_history} Begin! Question: {input} {agent_scratchpad} prompt PromptTemplate.from_template(prompt_template).partial( toolsrender_text_description(tools), tool_names, .join([t.name for t in tools]), ) # 5. 构建智能体链 agent ( { input: lambda x: x[input], chat_history: lambda x: x[chat_history], agent_scratchpad: lambda x: format_log_to_str(x[intermediate_steps]), } | prompt | llm | ReActSingleInputOutputParser() ) # 6. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue) # 7. 运行一个多轮对话 if __name__ __main__: queries [ What is LangChain?, How does it help in building agents?, Now, tell me the length of the string Hello, LangChain Agent!. ] for query in queries: print(f\n[User]: {query}) print(-*30) result agent_executor.invoke({input: query}) print(f\n[Agent]: {result[output]}) print(*60) # 查看记忆内容 print(\n--- Current Conversation History ---) print(memory.load_memory_variables({}))5.2 运行与观察运行python advanced_agent.py。你会看到智能体第一问“What is LangChain?”可能使用维基百科或搜索工具。第二问“How does it help...?”智能体会利用记忆中的第一轮对话历史理解“it”指代LangChain从而进行更精准的搜索或解释。第三问计算字符串长度智能体识别出这是一个计算任务选择调用我们自定义的StringLength工具而不是去搜索。这个例子展示了记忆的运用使对话具有连续性。多工具路由智能体根据问题类型概念查询、计算自动选择最合适的工具Wikipedia、Search、StringLength。自定义工具集成如何将任意Python函数封装成智能体可用的工具。6. 常见问题与排查思路在开发智能体应用时你可能会遇到以下典型问题问题现象可能原因排查与解决思路智能体陷入循环不停调用同一个工具。1. 提示词Prompt未明确停止条件。2. LLM对工具返回的结果理解有误无法做出正确决策。3. 最大迭代次数设置过高。1. 在Prompt中强化“当任务完成时应输出Final Answer”的指令。2. 检查工具返回的结果格式是否清晰、易于LLM理解。可以尝试简化工具输出。3. 在AgentExecutor中设置max_iterations如max_iterations5和early_stopping_methodgenerate。智能体无法正确选择工具工具路由失败。1. 工具描述description不清晰或不够具体。2. 多个工具功能描述相似LLM难以区分。3. LLM的上下文理解能力不足。1. 优化工具描述精确说明其用途、输入格式和输出示例。例如“Useful for getting the current weather in a given city. Input should be a string with city name, e.g., London.”2. 为功能相似的工具添加更独特的命名和描述。3. 尝试使用能力更强的LLM如GPT-4或提供少量示例few-shot在Prompt中。解析错误OutputParserException。LLM的输出格式不符合ReAct等框架要求的严格格式如缺少Thought:Action:。1. 使用handle_parsing_errorsTrue参数让执行器尝试自动修复。2. 使用OutputFixingParser包装解析器。3. 检查Prompt模板确保格式指令清晰无误。API调用超时或费用激增。1. 智能体规划步骤过多导致调用LLM和工具的API次数激增。2. 网络不稳定或工具API响应慢。1. 严格限制max_iterations。2. 为工具调用和LLM调用设置超时timeout参数。3. 考虑使用本地小模型处理简单规划或对工作流进行优化减少不必要的循环。记忆混乱或上下文过长。1. 对话历史过长超出LLM的上下文窗口。2. 记忆存储了无关或错误信息。1. 使用ConversationSummaryMemory或ConversationBufferWindowMemory只保留最近N轮对话替代ConversationBufferMemory。2. 定期清理记忆或实现基于向量的长期记忆只检索相关历史。7. 智能体开发的最佳实践与工程建议构建用于生产环境的智能体远不止让代码跑通那么简单。以下是一些关键的最佳实践提示词工程是核心清晰的角色与指令在Prompt开头明确智能体的角色、职责和约束如“你是一个数据分析助手必须基于事实回答”。结构化输出严格要求LLM按照框架能解析的格式如ReAct格式输出。提供示例在Prompt中包含1-2个完整的“问题-思考-行动-答案”示例Few-shot能极大提升智能体执行的一致性。迭代优化将Prompt视为重要代码进行版本管理和A/B测试。工具设计要可靠单一职责每个工具应只做一件事并做好。功能复杂的工具应拆解。健壮性工具函数必须有完善的错误处理try-except返回清晰的错误信息避免因工具崩溃导致整个智能体失败。安全性对工具输入进行严格的验证和清洗防止注入攻击。特别是执行代码、访问数据库或调用内部API的工具。严格控制成本与延迟设置预算上限在AgentExecutor中设置max_iterations防止无限循环消耗大量Token。缓存策略对LLM的常见查询结果或工具的计算结果进行缓存减少重复调用。异步执行对于可并行的工具调用如同时查询多个数据源使用异步模式如LangChain的ainvoke来提升性能。实施严格的评估与监控单元测试为智能体的核心组件如工具、规划逻辑编写测试。端到端评估构建一个包含各种边缘案例的测试集定期运行评估智能体的成功率、准确率和成本。链路追踪记录每一次智能体运行的完整轨迹Thought, Action, Observation这是调试和优化不可或缺的数据。可以使用LangSmith等专门平台。设计人性化的交互与兜底进度反馈对于长任务智能体应向用户反馈当前进度如“正在搜索资料...”“正在生成报告...”。确认机制对于高风险操作如发送邮件、删除数据智能体应主动向用户确认。优雅降级当智能体多次尝试仍失败时应能给出一个友好的失败提示并可能将问题转交给人工处理。智能体运行框架将大语言模型从“聊天机器人”升级为“自主任务执行者”是构建下一代AI应用的关键基础设施。从理解其核心组件规划、工具、记忆、执行开始选择一个适合的框架如LangChain进行深度开发或Dify进行快速原型遵循小步快跑、持续迭代的原则你就能逐步搭建起解决实际业务问题的智能体系统。记住一个优秀的智能体不仅是技术的堆砌更是对业务逻辑的深刻理解与可靠工程实践的结合。现在就从定义一个明确的小目标开始动手搭建你的第一个智能体吧。