1. 项目概述从零构建一个AI Agent工作坊最近在GitHub上看到一个挺有意思的项目叫ashishpatel26/AIAgentWorkshop。乍一看标题你可能觉得这又是一个关于AI Agent的普通教程或者代码集合。但当我深入进去发现它其实是一个精心设计的“工作坊”Workshop旨在引导开发者特别是那些对AI Agent感兴趣但不知从何下手的开发者通过一系列结构化的任务亲手搭建一个功能完整的AI Agent系统。这不仅仅是扔给你一堆代码而是像一位经验丰富的导师带你一步步走过从环境配置、工具集成、智能体设计到最终部署的完整闭环。这个工作坊的核心价值在于“动手实践”。它假设你具备基础的Python编程知识和对大语言模型LLM的初步了解但不需要你是AI专家。通过完成它预设的几个“关卡”或“任务”你将能构建一个能够理解用户意图、调用外部工具比如搜索网络、查询数据库、执行代码并给出结构化响应的智能体。这背后涉及的核心技术栈正是当前AI应用开发的热点LangChain或类似的Agent框架、OpenAI API或其他LLM服务、以及各种工具链的集成。对于想切入AI Agent赛道的开发者、产品经理甚至是技术爱好者来说这样一个工作坊无疑是一条高效的“上手路径”。2. 工作坊核心架构与设计哲学2.1 为什么是“工作坊”而非“代码库”很多开源项目只是提供了最终的实现代码你可能需要花费大量时间去理解项目结构、配置依赖、并猜测作者的意图。AIAgentWorkshop的不同之处在于它采用了“引导式学习”的设计。项目结构通常会被清晰地划分为多个阶段或模块例如Stage 0: 环境准备与基础概念指导你设置Python虚拟环境安装核心依赖如langchain,openai并理解Agent、Tool、Chain等基本概念。Stage 1: 你的第一个简单Agent可能是一个仅能进行简单对话或者只能调用单一工具如计算器的Agent。目的是让你熟悉框架的基础API。Stage 2: 集成多个工具引入更多工具如网络搜索通过SerpAPI或DuckDuckGo、维基百科查询、甚至是执行Python代码PythonREPLTool。这时你需要学习如何让Agent学会在多个工具中做选择。Stage 3: 记忆与状态管理让Agent拥有对话记忆能够参考之前的对话历史实现多轮交互。Stage 4: 高级功能与优化可能涉及自定义工具的开发、Agent的规划Planning能力、或是与外部系统如数据库、API的深度集成。Stage 5: 部署与测试如何将这个Agent包装成API例如使用FastAPI并进行简单的测试。每个阶段都会包含明确的任务描述、相关的代码片段可能是需要你补充完整的、以及预期的输出。这种“任务驱动”的模式能极大地提升学习效率和成就感。2.2 核心组件拆解Agent, Tools, Memory要理解这个工作坊必须吃透AI Agent系统的三个核心支柱Agent智能体这是系统的大脑。它本身并不“知道”所有答案它的核心能力是“决策”和“规划”。给定一个用户问题如“北京今天的天气怎么样然后告诉我穿什么衣服合适”Agent的工作流程是理解利用LLM解析用户意图。规划决定需要哪些步骤先查天气再根据天气推荐穿搭。执行调用相应的Tools来获取信息调用天气查询Tool再调用一个穿衣建议Tool或直接由LLM推理。反思根据Tool返回的结果判断是否已回答问题或是否需要进一步行动。 工作坊可能会引导你使用LangChain提供的不同Agent类型如ZeroShotAgent零样本依赖LLM对工具描述的充分理解、ConversationalAgent带记忆的对话式等。Tools工具这是Agent的手和脚。Tool本质上是一个函数它有一个清晰的名称、描述和输入输出规范。Agent通过阅读Tool的描述来决定在什么情况下使用它。工作坊会教你如何使用预置工具如SerpAPI用于搜索WikipediaQueryRun用于查维基百科。封装自定义工具这是关键技能。例如你可以将一个查询公司内部数据库的API封装成一个Tool这样Agent就能回答关于公司数据的问题。封装时给Tool一个准确、清晰的描述至关重要这直接决定了Agent能否正确调用它。Memory记忆为了让对话连贯Agent需要记住之前说过什么。工作坊会介绍短期记忆如ConversationBufferMemory简单存储对话历史和更高级的记忆形式如ConversationSummaryMemory对长历史进行摘要存储以节省Token。注意选择哪个LLM作为Agent的“大脑”是第一个关键决策。工作坊很可能默认使用OpenAI的GPT模型因为其API稳定、功能强大。但你完全可以根据工作坊的指导替换为其他兼容OpenAI API格式的模型如本地部署的Ollama运行Llama 3等开源模型或云服务如Anthropic Claude、Google Gemini的API。这步替换通常是修改初始化LLM对象的一行代码工作坊应该会提示你这一点。3. 环境搭建与初步实践3.1 依赖管理与环境隔离第一步永远是创建一个干净的Python环境。这是避免未来依赖冲突的最佳实践。# 创建并激活一个虚拟环境以venv为例 python -m venv aiagent_env source aiagent_env/bin/activate # Linux/macOS # aiagent_env\Scripts\activate # Windows # 安装核心依赖 pip install langchain langchain-openai # 根据工作坊需要可能还需要安装以下包 pip install langchain-community # 社区贡献的Tools和组件 pip install openai # 如果使用OpenAI API pip install google-search-results # 如果使用SerpAPI进行搜索实操心得强烈建议使用requirements.txt或pyproject.toml来管理依赖。工作坊的根目录下通常会有这样一个文件。你可以直接运行pip install -r requirements.txt来一次性安装所有依赖。如果项目没有提供在你安装完所有包后可以通过pip freeze requirements.txt命令生成你自己的依赖列表方便在其他机器上复现环境。3.2 获取并配置API密钥AI Agent的运行依赖于外部服务主要是LLM API和某些Tools的API如搜索。OpenAI API Key前往OpenAI平台注册并获取API密钥。SerpAPI Key可选如果你需要让Agent进行网络搜索SerpAPI是一个不错的选择。去其官网注册获取密钥。其他Keys根据工作坊引入的工具可能还需要其他密钥。安全地管理这些密钥至关重要。绝对不要将它们硬编码在代码中并上传到GitHub。# 错误示范硬编码密钥 openai_api_key sk-...123 # 正确做法使用环境变量 import os from langchain_openai import ChatOpenAI os.environ[OPENAI_API_KEY] 你的密钥 # 临时测试或从.env文件加载 # 更佳实践是使用python-dotenv从.env文件加载 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0)最佳实践在项目根目录创建一个.env文件内容如下OPENAI_API_KEYsk-your-actual-key-here SERPAPI_API_KEYyour-serpapi-key-here然后在你的Python代码开头使用python-dotenv加载from dotenv import load_dotenv load_dotenv() # 这会从当前目录的.env文件加载所有环境变量 # 现在可以直接通过 os.environ[“OPENAI_API_KEY”] 访问3.3 第一个可运行的AgentHello, Agent!让我们跟随工作坊的指引构建一个最简单的Agent。这个Agent可能只拥有一个工具——计算器。from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 用于拉取预设的Prompt import math # 1. 定义一个简单的计算器工具 def calculator(input_str: str) - str: 一个简单的计算器可以处理基本的数学表达式。输入应为一个字符串如 2 3 * 4。 try: # 警告使用eval有安全风险仅用于演示。生产环境应用更安全的解析器。 result eval(input_str) return str(result) except Exception as e: return f计算错误: {e} calc_tool Tool( nameCalculator, funccalculator, description用于计算数学表达式。输入应该是一个可以求值的字符串例如 2 3 * 4。 ) # 2. 准备工具列表和LLM tools [calc_tool] llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 3. 使用LangChain Hub上的一个标准ReAct Prompt prompt hub.pull(hwchase17/react-chat) # 4. 创建Agent agent create_react_agent(llm, tools, prompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行 response agent_executor.invoke({input: 如果我有15个苹果吃掉3个又买了是原来剩余数量2倍的苹果我现在总共有多少个苹果}) print(response[output])当你运行这段代码并将verbose设为True时你会在控制台看到Agent的“思考过程” 进入新的AgentExecutor链... 思考用户的问题需要几步计算。首先15个苹果吃掉3个剩余12个。然后“是原来剩余数量2倍的苹果”意味着要买12 * 2 24个。最后总共有12 24 36个。 我需要使用计算器来验证我的心算。 行动使用Calculator工具。 行动输入15 - 3 观察12 思考现在计算要买的数量12 * 2。 行动使用Calculator工具。 行动输入12 * 2 观察24 思考现在计算总数12 24。 行动使用Calculator工具。 行动输入12 24 观察36 思考我现在知道最终答案了。 最终答案你现在总共有36个苹果。 链结束。这个简单的例子展示了Agent的ReAct推理行动范式它先思考Thought然后决定行动Action并调用工具获得观察Observation后再进行下一步思考直到得出最终答案。4. 构建功能完备的Multi-Tool Agent4.1 集成搜索与信息查询工具一个只会算数的Agent用处有限。接下来工作坊会引导你为Agent装上“眼睛”和“耳朵”让它能获取实时或知识库信息。集成DuckDuckGo搜索免费from langchain_community.tools import DuckDuckGoSearchRun search_tool DuckDuckGoSearchRun() search_tool.name Web_Search search_tool.description 在互联网上搜索最新信息。当问题涉及新闻、实时事件或未知实体时使用此工具。集成维基百科工具from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper api_wrapper WikipediaAPIWrapper(top_k_results2, doc_content_chars_max500) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) wiki_tool.description 查询维基百科上的结构化知识。适用于历史事件、科学概念、人物传记等事实性查询。现在你的工具列表变成了[calc_tool, search_tool, wiki_tool]。当你问Agent“特斯拉CEO马斯克最近有什么新闻”时它会优先选择Web_Search工具。当你问“爱因斯坦的相对论主要讲了什么”它可能会选择Wikipedia工具。4.2 设计高效的Agent PromptPrompt是指导Agent行为的“宪法”。工作坊可能会让你修改或自定义Prompt。一个典型的ReAct Prompt模板包含系统指令定义Agent的角色和能力。工具描述这是自动填充的LangChain会把所有Tools的名称和描述格式化后放入Prompt。思考格式严格规定Agent输出的格式例如必须包含Thought:Action:Action Input:Observation:Final Answer:等关键词以便框架能正确解析。自定义Prompt示例from langchain.prompts import PromptTemplate custom_prompt PromptTemplate.from_template( 你是一个乐于助人且能力强大的AI助手。你可以使用以下工具 {tools} 请严格按照以下格式回应 Thought: 你需要思考当前情况 Action: 需要使用的工具名称必须是[{tool_names}]中的一个 Action Input: 工具的输入 Observation: 工具返回的结果 ... (这个循环可以重复多次) 当你确信已经得到最终答案时必须使用以下格式 Thought: 我现在知道最终答案了 Final Answer: [你的最终答案] 开始 之前的对话历史 {chat_history} 人类的新问题{input} {agent_scratchpad} # agent_scratchpad 是框架自动填充的中间步骤记录 )通过调整Prompt中的指令你可以改变Agent的“性格”如更简洁或更详细、约束其行为如“不要编造信息”或优化其推理流程。4.3 为Agent赋予记忆能力没有记忆的Agent每次对话都是独立的。添加记忆非常简单from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 在创建AgentExecutor时传入memory参数 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue )现在你可以进行多轮对话了# 第一轮 resp1 agent_executor.invoke({input: 我叫小明。}) print(resp1[output]) # 可能回复“你好小明” # 第二轮Agent会记得你的名字 resp2 agent_executor.invoke({input: 我刚才说我叫什么}) print(resp2[output]) # 应该能正确回答“你刚才说你叫小明。”ConversationBufferMemory会将所有对话历史都存入Prompt这可能导致Token消耗快速增长。对于长对话工作坊可能会引入ConversationSummaryMemory它定期用LLM总结历史对话只保留摘要从而节省Token。5. 高级主题自定义工具与复杂工作流5.1 开发你自己的专属工具这是将Agent与你的个人或业务场景结合的关键。假设你想让Agent能查询你本地的待办事项从一个CSV文件或SQLite数据库。from langchain.tools import BaseTool from pydantic import BaseModel, Field import sqlite3 from typing import Type # 定义工具的输入Schema class TodoQueryInput(BaseModel): query_type: str Field(description查询类型可选all查看所有pending查看未完成completed查看已完成) class TodoQueryTool(BaseTool): name Todo_Query description 查询我的个人待办事项列表。 args_schema: Type[BaseModel] TodoQueryInput def _run(self, query_type: str) - str: 执行查询的逻辑 conn sqlite3.connect(my_todos.db) cursor conn.cursor() if query_type all: cursor.execute(SELECT id, task, status FROM todos) elif query_type pending: cursor.execute(SELECT id, task FROM todos WHERE status pending) elif query_type completed: cursor.execute(SELECT id, task FROM todos WHERE status completed) else: return 无效的查询类型请使用 all, pending, 或 completed。 results cursor.fetchall() conn.close() if not results: return f没有找到{query_type}的待办事项。 return \n.join([f{row[0]}. {row[1]} ({row[2] if len(row)2 else N/A}) for row in results]) async def _arun(self, query_type: str) - str: 异步版本如果需要 raise NotImplementedError(此工具不支持异步) # 将这个自定义工具加入到工具列表中 todo_tool TodoQueryTool() tools.append(todo_tool)现在你的Agent就能理解“帮我看看还有什么事情没做”这样的指令并调用Todo_Query工具返回结果。关键点在于description字段要写得清晰准确因为Agent完全依赖这个描述来判断何时使用该工具。5.2 实现多Agent协作与规划对于复杂问题单个Agent可能力不从心。工作坊的高级阶段可能会引入“多Agent系统”或“规划Planning”的概念。例如你可以设计一个“规划Agent”和一个“执行Agent”。规划Agent接收复杂任务如“为我策划一个周末旅行”将其分解为子任务1. 确定目的地2. 查询天气3. 查找景点4. 规划行程。执行Agent拥有各种工具负责执行规划Agent产生的每一个子任务并将结果汇总。这可以通过LangChain的PlanAndExecute执行器或更底层的LLMChain组合来实现。这标志着你的AI应用从“自动执行命令”向“自动解决问题”迈进了一大步。5.3 错误处理与稳定性提升在实际运行中Agent可能会出错比如解析错误Agent的输出格式不符合ReAct要求框架无法解析。工具错误调用的工具抛出异常如网络超时、API限额用完。无限循环Agent陷入“思考-行动-观察”的死循环。在创建AgentExecutor时有几个关键参数用于提升稳定性agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue, # 自动尝试修复解析错误 max_iterations10, # 防止无限循环限制最大迭代次数 early_stopping_methodgenerate, # 达到最大迭代次数时让LLM直接生成最终答案 return_intermediate_stepsTrue, # 返回中间步骤便于调试 )调试技巧当Agent行为异常时将verbose设为True是首要的调试手段。观察它的思考链看它是在哪一步做出了错误决策。很多时候问题出在Tool的描述不够清晰或者Prompt的指令有歧义上。6. 部署与效能优化实战6.1 将Agent封装为API服务一个本地运行的脚本无法被其他应用调用。工作坊的最后阶段通常会引导你将Agent部署为一个Web API。使用FastAPI是一个轻量且高效的选择。# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from your_agent_module import agent_executor # 导入你之前构建好的Agent执行器 app FastAPI(titleAI Agent API) class QueryRequest(BaseModel): message: str session_id: str None # 用于区分不同对话会话 class QueryResponse(BaseModel): response: str session_id: str app.post(/chat, response_modelQueryResponse) async def chat_with_agent(request: QueryRequest): try: # 这里需要根据session_id来管理不同的memory实例简化起见我们假设一个全局memory result agent_executor.invoke({input: request.message}) return QueryResponse(responseresult[output], session_idrequest.session_id or default) except Exception as e: raise HTTPException(status_code500, detailfAgent执行失败: {str(e)}) if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)运行python app.py你的Agent就拥有了一个HTTP端点。你可以用curl、Postman或任何前端应用来调用它curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 你好今天天气怎么样, session_id: user_123}6.2 性能优化与成本控制随着使用量增加你需要关注性能和成本。缓存对于相同或相似的查询没必要每次都调用LLM和工具。可以使用LangChain的缓存功能。from langchain.cache import InMemoryCache from langchain.globals import set_llm_cache set_llm_cache(InMemoryCache()) # 内存缓存简单演示。生产环境可用RedisCache。选择更经济的模型对于不需要极强推理的简单任务可以使用更小、更快的模型如gpt-3.5-turbo而非gpt-4。工作坊的代码通常将模型类型设为可配置参数。限制Token和迭代次数如前所述设置max_tokens和max_iterations可以防止单次请求消耗过多资源或陷入循环。异步处理如果Tools涉及网络请求如搜索、调用外部API使用异步版本可以大幅提升吞吐量。LangChain支持异步的Agents和Tools。6.3 扩展方向与未来探索完成这个工作坊你只是拿到了AI Agent世界的入场券。接下来可以考虑RAG检索增强生成集成让Agent能够访问你私有的文档库公司文档、个人笔记构建知识库问答系统。与自动化平台结合将Agent作为大脑通过Zapier、n8n或LangChain的Toolkits连接成千上万的SaaS工具如Slack、Notion、Google Sheets实现真正的自动化工作流。可视化与监控为Agent系统构建仪表盘监控其工具调用频率、响应时间、成本消耗和错误率。评估与测试建立一套测试用例定期评估Agent回答的准确性和可靠性实现持续改进。这个AIAgentWorkshop项目最大的价值在于它提供了一条从理论到实践的清晰路径。它没有试图展示一个完美无缺、功能繁复的终极产品而是通过拆解任务让你亲手将一个个零件组装起来并在过程中深刻理解每个组件的作用和它们之间的协作关系。这种“学中做做中学”的方式远比单纯阅读文档或复制代码更能构建起扎实的认知。当你跟着它走完全程你收获的不仅仅是一个能运行的Agent程序更是一套可以自由组合、扩展用以解决实际问题的思维框架和工具箱。