1. 项目概述从零到一的AI Agent初体验最近几年AI Agent这个概念火得不行感觉身边搞技术的朋友都在聊。但说实话很多刚入门的朋友一听到“Agent”就觉得特别高大上联想到电影里那种无所不能的智能体感觉门槛很高不知道从何下手。其实AI Agent的核心思想并不复杂简单来说就是一个能感知环境、自主决策并执行任务来达成目标的程序。今天我就想用一个最直接、最有趣的方式带大家用20行左右的Python代码亲手造出你的第一个AI Agent。这个项目不追求大而全而是聚焦于“跑通”这个最核心的体验让你在几分钟内亲眼看到一段代码如何“活”起来去完成一个你设定的任务。我们将要构建的这个微型Agent它的核心能力是你告诉它一个目标比如“查一下北京今天的天气”它能够自己分析这个目标决定需要调用什么工具比如一个天气查询函数然后执行调用最后把结果整理好返回给你。整个过程完全自动化。你可能会想这不就是一个简单的函数调用吗区别在于“自主决策”。我们的Agent会根据你的指令动态判断该做什么而不是执行预设的死板流程。这背后依赖的是大语言模型的理解和规划能力。通过这个项目你不仅能学会如何用代码将大模型“封装”成一个能干活儿的智能体更能透彻理解AI Agent运作的基本骨架规划、工具调用、执行。这比你读十篇概念文章都要来得实在。这个项目非常适合以下几类朋友对AI和Python有好奇心但不知如何开始的初学者想快速理解AI Agent核心原理的开发者或者就是单纯想体验一下“创造智能”乐趣的任何人。你只需要有最基础的Python知识知道怎么定义函数、会用print就行和一个能访问大模型API的密钥比如OpenAI的GPT系列或者国内的一些大模型平台。我们不用任何复杂的框架就从最原始的requests库开始一步步搭建。我保证跟着做下来你获得的成就感会远超你的预期。下面我们就从最核心的设计思路开始拆解。2. 核心设计思路理解AI Agent的“大脑”与“手脚”在动手写代码之前我们必须先把这个微型Agent的“大脑”和“手脚”是怎么协调工作的想明白。这决定了我们代码的结构和逻辑。一个最简单的AI Agent通常包含三个核心模块大脑LLM、工具集Tools和执行引擎Orchestrator。2.1 大脑大语言模型的核心作用在这个项目中我们选用大语言模型作为Agent的“大脑”。它的核心职责是理解和规划。具体来说当你给Agent一个指令比如“帮我写一首关于春天的诗并估算一下这首诗大概有多少个字”这个指令会首先被送到LLM。LLM的任务不是直接执行而是进行思考分解理解意图用户想要一首诗并且想知道诗的字数。任务规划要完成这个目标我需要按顺序做两件事a. 生成一首诗。b. 计算这首诗的字数。工具匹配要生成诗我可以调用“写诗工具”要计算字数我可以调用“字数统计工具”。生成结构化指令LLM最终会输出一个机器可读的决策例如[{action: write_poem, input: {theme: 春天}}, {action: count_words, input: {text: [上一步的结果]}}]。这个过程中LLM本身并不具备写诗或计算字数的能力它只是一个卓越的“规划师”和“调度员”。我们通过精心设计的提示词来引导它进行这种结构化思考。注意提示词的设计是Agent性能的关键。你需要明确告诉LLM可用的工具列表、输出的格式要求。一个模糊的提示词会导致LLM输出不可预测的自然语言让程序无法解析。2.2 手脚工具函数的定义与封装“手脚”就是Agent能使用的具体工具在代码里体现为一个Python函数。每个工具都应该有清晰的功能定义、输入和输出。例如get_weather(city: str) - str输入城市名返回天气字符串。calculate(expression: str) - float输入数学表达式字符串返回计算结果。write_poem(theme: str) - str输入主题返回一首诗。这些工具函数是你预先写好的、确定性的代码块。它们代表了Agent能执行的原子操作。Agent的强大之处在于LLM可以灵活地组合调用这些工具来解决复杂问题。在项目初期建议从2-3个简单、可靠的工具开始比如一个计算器和一个文本处理工具这能帮你快速验证整个流程是否跑通。2.3 执行引擎串联思考与行动的循环这是将大脑和手脚粘合起来的“神经系统”也是我们代码的主要部分。它的工作流程是一个经典循环接收用户输入获取初始任务。调用大脑LLM进行规划将用户任务和当前可用工具列表传给LLM请求它给出下一步的行动计划调用哪个工具传入什么参数。解析LLM的响应从LLM返回的文本中解析出action工具名和input工具参数。这里要求LLM必须返回固定的格式如JSON便于程序处理。查找并执行工具根据解析出的action在注册的工具字典中找到对应的函数并用input作为参数执行它。收集结果并判断将工具执行的结果收集起来。然后引擎需要判断任务是否完成。判断逻辑可以很简单如果LLM在规划时表示“这是最后一步”或返回了最终答案则结束否则将当前所有信息用户初始问题已执行步骤的结果再次喂给LLM让它规划下一步进入下一个循环。这个“规划 - 执行 - 再规划”的循环是AI Agent能够处理多步骤任务的核心。我们的20行代码主要就是实现这个循环逻辑。理解了这一点再看代码就会觉得清晰无比。3. 环境准备与核心工具选型工欲善其事必先利其器。为了让我们的第一个AI Agent顺利跑起来需要准备一个最精简但足够用的开发环境。我们的原则是依赖最少流程最清晰。3.1 Python环境与必要库安装首先你需要一个Python环境。我推荐使用Python 3.8或以上版本稳定性兼容性都比较好。如果你还没有安装可以去Python官网下载安装包记得安装时勾选“Add Python to PATH”。安装完成后打开命令行Windows上是CMD或PowerShellMac/Linux上是Terminal输入python --version检查是否安装成功。接下来我们只需要安装两个核心库openai这是用于调用OpenAI GPT系列模型API的官方库。当然你也可以使用其他兼容OpenAI API格式的国内大模型平台它们的调用方式通常类似。requests一个非常流行的HTTP库用于发送网络请求。虽然openai库底层也会用到但为了教学透明度和灵活性我们在示例中可能会直接使用requests来演示最原始的API调用让你看清背后发生了什么。安装命令非常简单在命令行中执行pip install openai requests如果下载速度慢可以考虑使用国内的镜像源例如清华源pip install openai requests -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 大模型API密钥申请与配置Agent的“大脑”需要一个大模型。这里我们以OpenAI的GPT-3.5-turbo为例因为它性价比高响应速度快非常适合实验。你需要做以下几步访问OpenAI平台网站注册账号并登录。进入API Keys页面点击“Create new secret key”创建一个新的密钥。这个密钥一旦生成只会显示一次请务必立即复制并妥善保存到本地它就像你的密码一样重要。在你的代码中需要设置这个密钥。绝对不要将密钥直接硬编码在代码文件里尤其是如果你打算分享代码或上传到GitHub。最佳实践是使用环境变量。在命令行中临时设置环境变量重启终端会失效# 在Windows上 set OPENAI_API_KEY你的sk-xxx密钥 # 在Mac/Linux上 export OPENAI_API_KEY你的sk-xxx密钥更一劳永逸的方法是在用户目录下创建一个.env文件注意文件名以点开头里面写入OPENAI_API_KEY你的sk-xxx密钥然后在Python中使用python-dotenv库来加载。但为了我们第一个项目的极致简洁我们先在代码开头简单设置后续你一定要改为环境变量的方式。3.3 代码编辑器选择VSCode与简单配置写Python代码一个好用的编辑器能事半功倍。我强烈推荐Visual Studio Code它免费、轻量、插件生态丰富。安装好VSCode后建议安装以下几个扩展Python微软官方出品提供语法高亮、智能提示、调试等功能。Code Runner可以一键运行当前Python文件非常方便。安装完成后用VSCode打开你准备存放项目代码的文件夹新建一个文件例如first_agent.py我们的所有代码都将写在这个文件里。至此环境准备工作就全部完成了。4. 分步实现20行代码构建核心Agent现在让我们进入最激动人心的环节——动手编码。我会将代码分成几个逻辑块并逐行解释其作用。最终组合起来就是一个能工作的微型AI Agent。4.1 第一步导入库与设置API密钥import requests import json # 注意此处仅为演示实际项目中请使用环境变量 API_KEY 你的-OpenAI-API-KEY API_URL https://api.openai.com/v1/chat/completionsrequests用来发送HTTP请求调用API。json用来处理API请求和响应的JSON数据。API_KEY和API_URL定义了连接OpenAI服务所需的信息。请务必将你的-OpenAI-API-KEY替换成你实际申请的密钥。重要安全提醒再次强调切勿将真实的API密钥提交到任何公开的版本控制系统如GitHub。一旦泄露他人可能会滥用导致你的账户产生巨额费用。正式项目务必使用环境变量或密钥管理服务。4.2 第二步定义Agent的“工具集”我们先定义两个简单的工具让Agent有“事”可做。def calculator(expression: str) - str: 计算一个数学表达式的结果。 try: # 使用eval有安全风险仅用于演示。生产环境应用更安全的方法如ast.literal_eval。 result eval(expression) return f计算结果{expression} {result} except Exception as e: return f计算错误无法处理表达式 {expression}。错误{e} def get_word_count(text: str) - str: 统计给定文本的字数这里简单按空格分割单词。 words text.split() count len(words) return f文本的字数单词数是{count}calculator函数接收一个字符串格式的数学表达式如2 3 * 4使用eval计算并返回结果。请注意eval函数会执行任何传入的Python表达式存在严重安全风险此处仅用于最简单演示。在实际应用中应使用ast.literal_eval或专门的数学表达式解析库。get_word_count函数接收一段文本按空格分割成单词并统计数量返回结果。每个工具函数都有清晰的文档字符串这很重要因为后续我们会把这些描述传给LLM帮助它理解每个工具的用途。我们将这些工具放在一个字典里方便根据名称查找TOOLS { calculator: calculator, get_word_count: get_word_count } TOOL_DESCRIPTIONS [ {name: calculator, description: 计算一个数学表达式例如2 3 * 4。}, {name: get_word_count, description: 统计一段文本中的字数单词数。} ]TOOLS字典是工具名到函数对象的映射。TOOL_DESCRIPTIONS列表则用于构造提示词告诉LLM现在有哪些工具可用。4.3 第三步构建与LLM通信的核心函数这个函数负责将我们的请求发送给GPT并获取它的回复。def ask_llm(messages): 发送请求到OpenAI API并返回回复。 headers { Content-Type: application/json, Authorization: fBearer {API_KEY} } data { model: gpt-3.5-turbo, messages: messages, temperature: 0.1, # 温度设低让输出更确定、更结构化 max_tokens: 500 } response requests.post(API_URL, headersheaders, datajson.dumps(data)) response_data response.json() # 简单错误处理 if response.status_code ! 200: print(fAPI请求错误{response_data}) return None return response_data[choices][0][message][content].strip()headers设置了请求头其中Authorization字段携带了我们的API密钥。data定义了请求体。我们使用gpt-3.5-turbo模型messages是对话历史列表。temperature设置为较低的0.1是为了让模型输出更稳定、更倾向于遵循我们要求的格式。max_tokens限制回复的最大长度。发送POST请求后解析返回的JSON提取出模型生成的文本内容。包含了一个最基本的HTTP状态码检查。4.4 第四步实现Agent的“规划-执行”循环引擎这是最核心的部分实现了前面提到的循环逻辑。def run_agent(user_query, max_steps5): 运行Agent的主循环。 # 初始化对话历史和最终结果 conversation_history [ {role: system, content: f你是一个有帮助的AI助手可以调用工具。你可以使用的工具有{TOOL_DESCRIPTIONS}。请用JSON格式回答例如{{\action\: \工具名\, \input\: \工具参数\}}。如果任务完成直接给出最终答案。}, {role: user, content: user_query} ] final_result None for step in range(max_steps): print(f\n 步骤 {step 1} ) # 1. 规划询问LLM下一步该做什么 llm_response ask_llm(conversation_history) if llm_response is None: break print(fLLM思考{llm_response}) # 尝试解析LLM的响应是否为JSON格式的工具调用 try: action_data json.loads(llm_response) action_name action_data.get(action) action_input action_data.get(input) except json.JSONDecodeError: # 如果解析失败说明LLM可能直接给出了最终答案 final_result llm_response print(fLLM直接给出了答案{final_result}) break # 2. 执行调用对应的工具 if action_name in TOOLS: tool_func TOOLS[action_name] print(f执行工具{action_name} 参数{action_input}) tool_result tool_func(action_input) print(f工具结果{tool_result}) # 将工具执行结果添加到历史中供LLM下一步参考 conversation_history.append({role: assistant, content: llm_response}) conversation_history.append({role: user, content: f工具 {action_name} 返回的结果是{tool_result}。请根据此结果继续。}) else: print(f错误未知的工具名 {action_name}) break # 简单判断如果LLM的回复看起来像最终陈述则结束 if 最终答案 in llm_response or step max_steps - 1: final_result tool_result if tool_result in locals() else llm_response break return final_result让我们拆解这个循环初始化我们构造一个初始的conversation_history。system消息至关重要它设定了Agent的角色并明确告知可用的工具列表以及必须使用指定的JSON格式进行回复。这是引导LLM进行结构化输出的关键。循环开始我们限制最多执行max_steps步防止陷入死循环。规划阶段将当前的对话历史conversation_history发送给ask_llm函数获取LLM的决策。解析决策尝试将LLM的回复解析为JSON。如果成功说明LLM决定调用工具如果失败抛出JSONDecodeError我们假设LLM直接给出了最终答案跳出循环。执行阶段根据解析出的action_name从TOOLS字典中找到对应的函数并执行传入action_input参数。更新历史将LLM的决策llm_response和工具执行的结果tool_result以对话的形式追加到conversation_history中。这模拟了Agent与环境的交互并将新的观察工具结果反馈给“大脑”供其进行下一步规划。这是实现多轮交互的核心。终止判断这里实现了一个非常简单的终止条件如果LLM的回复中包含“最终答案”字样或者达到了最大步数则结束循环。更健壮的实现应该让LLM在JSON中显式声明finished: true。4.5 第五步运行你的第一个Agent最后我们写一个主函数来启动这个Agent并测试它。if __name__ __main__: # 测试一个简单的任务 query 请先计算 15 25 * 2 等于多少然后告诉我Hello World, this is my AI agent!这句话有多少个单词。 print(f用户问题{query}) result run_agent(query) print(f\n 最终结果 \n{result})将以上所有代码块按顺序组合到first_agent.py文件中确保替换了API_KEY然后在终端运行python first_agent.py你应该会看到类似以下的输出清晰地展示了Agent的思考、决策和执行过程用户问题请先计算 15 25 * 2 等于多少然后告诉我Hello World, this is my AI agent!这句话有多少个单词。 步骤 1 LLM思考{action: calculator, input: 15 25 * 2} 执行工具calculator 参数15 25 * 2 工具结果计算结果15 25 * 2 65.0 步骤 2 LLM思考{action: get_word_count, input: Hello World, this is my AI agent!} 执行工具get_word_count 参数Hello World, this is my AI agent! 工具结果文本的字数单词数是7 步骤 3 LLM思考根据工具执行结果计算结果是65.0单词数是7。所以最终答案是计算表达式“15 25 * 2”得到65.0文本“Hello World, this is my AI agent!”的单词数是7。 最终结果 计算表达式“15 25 * 2”得到65.0文本“Hello World, this is my AI agent!”的单词数是7。恭喜你已经成功创建了一个能够理解多步骤任务、自主规划并调用工具执行的AI Agent虽然它只有20多行核心逻辑但已经完整包含了智能体的核心范式。5. 深入解析代码背后的关键技术与优化点项目跑通了但你可能对其中一些细节和潜在问题还有疑问。这部分我们来深入探讨一下并看看如何让这个微型Agent变得更强大、更健壮。5.1 提示词工程如何与LLM有效沟通我们Agent的“智商”很大程度上取决于system提示词。上面例子中的提示词已经能工作但可以优化得更鲁棒system_prompt f 你是一个AI助手可以通过调用工具来解决问题。 你拥有以下工具 {json.dumps(TOOL_DESCRIPTIONS, indent2, ensure_asciiFalse)} 请严格按以下规则响应 1. 如果需要调用工具你必须输出一个**且仅一个**合法的JSON对象格式如{{action: tool_name, input: arguments_for_tool}}。 2. 如果用户问题已解决或无需调用工具请直接给出清晰、完整的最终答案。 3. 请逐步思考。你可以基于之前工具的结果进行下一步操作。 结构化工具描述使用JSON格式清晰列出工具帮助LLM理解。明确的格式指令强调“必须输出一个且仅一个合法的JSON对象”这能极大减少LLM输出格式错误的情况。清晰的终止条件告诉LLM什么情况下应该直接给出最终答案。鼓励链式思考“逐步思考”和“基于之前工具的结果”这些指令能引导LLM更好地处理多步骤任务。你可以像调试普通代码一样调试提示词。如果LLM不按格式输出就调整提示词让它更明确。这是开发AI应用的核心技能之一。5.2 错误处理与循环终止策略我们之前的循环终止策略非常简陋。一个生产级的Agent需要更健壮的处理机制LLM响应格式错误除了JSONDecodeErrorLLM可能会返回包含JSON但格式不对或者返回多个JSON对象。我们需要更强大的解析和重试机制。例如可以尝试用正则表达式从回复中提取第一个JSON对象如果多次尝试失败则向LLM发送错误信息并要求它重试。工具执行失败工具函数本身可能抛出异常比如calculator遇到了无法计算的表达式。应该在tool_func(action_input)调用处添加try...except将错误信息捕获并格式化为自然语言然后添加到对话历史中让LLM知道上一步失败了需要调整策略。智能终止判断不应该依赖关键词如“最终答案”。更好的方式是让LLM在JSON响应中显式包含一个状态字段例如{action: final_answer, input: 这里是答案...}或者{action: tool_name, input: ..., finished: false}。然后在引擎中检查这个字段来决定是否终止循环。防止无限循环设置max_steps是必要的但还可以更智能。例如记录历史中重复的工具调用如果检测到可能陷入了循环比如连续三次调用同一个工具且参数相同则主动终止并报错。5.3 扩展你的Agent添加更多工具Agent的魅力在于其可扩展性。添加新工具非常简单定义新的工具函数。将其添加到TOOLS字典和TOOL_DESCRIPTIONS列表中。更新system_prompt如果提示词是动态生成的。例如我们添加一个查询当前时间的工具from datetime import datetime def get_current_time(query: str) - str: 返回当前的日期和时间。忽略输入参数。 now datetime.now() return f当前时间是{now.strftime(%Y-%m-%d %H:%M:%S)} # 更新工具集 TOOLS[get_current_time] get_current_time TOOL_DESCRIPTIONS.append({name: get_current_time, description: 获取当前的日期和时间。输入参数可以忽略或为任意值。})现在你的Agent就能回答“现在几点了”这样的问题了。你可以依此添加网络搜索、数据库查询、发送邮件等任何你能用Python实现的功能。5.4 从脚本到框架了解更成熟的Agent开发库我们这个20行的Agent是一个伟大的起点但它毕竟是一个教学演示。对于严肃的项目你会需要更强大的功能比如记忆管理、并行工具调用、复杂任务分解等。这时使用成熟的Agent框架是更明智的选择。它们提供了更健壮的基础设施和更高级的抽象。了解它们有助于你理解工业级Agent是如何构建的LangChain / LangGraph这是目前最流行的AI应用开发框架之一。它提供了Agent、Tool、Memory等高级组件能轻松构建复杂的链和智能体。我们的“规划-执行”循环在LangChain中对应AgentExecutor。AutoGen由微软开发专注于创建能相互对话、协作的多智能体系统。如果你设想的场景涉及多个不同角色的AI协同工作AutoGen是很好的选择。CrewAI一个较新的框架强调基于“角色”Crew的协作。它让定义具有特定角色、目标和背景的智能体变得非常直观适合模拟工作流。当你掌握了我们手搓Agent的核心原理后再去学习这些框架你会清楚地知道它们底层在帮你做什么学习起来事半功倍。6. 常见问题与实战调试技巧在实际操作中你几乎一定会遇到一些问题。这里我总结了一些最常见的坑和解决方法希望能帮你快速排雷。6.1 API调用失败与网络问题错误requests.exceptions.ConnectionError或超时原因网络连接不稳定或者API服务地址无法访问对于国内用户直接访问OpenAI可能存在困难。解决检查网络连接。如果你在国内可能需要配置网络环境或使用支持OpenAI API的国内代理服务注意此处仅指技术上的网络代理需确保其合法合规使用。更常见的做法是使用国内大模型平台提供的兼容OpenAI API格式的服务只需将代码中的API_URL和API_KEY替换为相应平台的信息即可。在requests.post中增加timeout参数例如timeout30避免程序长时间挂起。错误401 Authentication Error原因API密钥错误、过期或格式不对。解决仔细检查API_KEY字符串是否正确是否包含了多余的空格或换行符。确保密钥有效。错误429 Rate Limit Exceeded原因请求频率超过OpenAI账户的速率限制。解决免费账户的限额较低。可以尝试降低请求频率或者在代码中增加延迟如time.sleep(1)。对于生产应用需要考虑使用付费账户并实施更完善的限流和重试机制。6.2 LLM不按指定格式输出JSON这是开发Agent时最常见也最头疼的问题之一。现象LLM回复的是自然语言如“我将调用计算器工具...”导致json.loads()失败。解决强化提示词在system提示词中非常强硬、明确地规定格式。使用“你必须”、“严格遵循”、“输出一个且仅一个JSON对象”等词语。给出非常清晰的正例和反例。使用函数调用推荐OpenAI API本身支持function calling功能。你可以在请求中定义tools参数旧版叫functions模型会以特定的结构化格式返回它希望调用的函数及参数。这比让模型自己输出JSON字符串要稳定可靠得多。这是我们这个微型Agent可以进化的最重要方向。使用函数调用后解析响应的逻辑会发生变化但整体架构不变。后处理与重试如果LLM还是输出了非标准JSON可以尝试用正则表达式如r\{.*\}去匹配可能存在的JSON部分或者将错误信息连同“请重试并确保输出JSON格式”的请求再次发送给LLM。6.3 工具执行中的安全与异常eval()的安全风险我们的calculator工具使用了eval这是极其危险的。如果LLM被诱导生成__import__(os).system(rm -rf /)这样的表达式并执行后果不堪设想。解决永远不要在生产环境使用eval处理用户或LLM生成的输入。替代方案包括使用ast.literal_eval只能评估字面量表达式或使用安全的第三方库如numexpr、simpleeval或者自己编写一个简单的表达式解析器。工具参数类型错误LLM可能会为工具生成错误类型的参数。例如get_word_count期望一个字符串但LLM可能传了一个数字。解决在工具函数内部进行严格的参数类型检查和验证。如果参数无效返回清晰的错误信息而不是抛出异常导致整个Agent崩溃。这个错误信息会被反馈给LLM让它有机会自我纠正。6.4 性能与成本考量Token消耗每次调用LLM都需要消耗Token计费单位。我们的循环模式意味着一个多步骤任务会进行多次API调用成本是累加的。优化在system提示词中鼓励LLM“一次性规划所有步骤”但这对于复杂任务可能不现实。使用更便宜的模型进行简单的规划或工具选择用更强的模型进行最终合成。缓存频繁使用的工具结果。响应速度每次API调用都有网络延迟多步骤任务会显得较慢。优化对于可以并行执行且不相互依赖的工具调用可以考虑使用异步编程asyncio来并发执行显著减少总耗时。6.5 调试技巧打印与日志开发Agent时详细的日志是你的最佳伙伴。我们代码中的print语句已经提供了一个基本的调试视图。你可以将其升级结构化日志使用Python的logging模块可以按级别DEBUG, INFO, WARNING输出日志并记录到文件。记录完整对话历史将每一轮的conversation_history和llm_response都保存下来可以存为JSON文件。当Agent行为异常时回放这些历史能帮你精准定位是提示词问题、工具问题还是逻辑问题。可视化工具对于复杂Agent可以考虑使用LangSmith等平台它能可视化跟踪Agent的每一步决策、工具调用和Token消耗是强大的调试和监控工具。通过这个从零搭建的微型AI Agent项目我希望你不仅获得了一段可以运行的代码更重要的是理解了智能体背后“思考-行动-观察”的核心循环。这个简单的范式是构建一切复杂AI应用系统的基石。当你下次再听到“AI Agent”时你脑海中浮现的不再是一个模糊的概念而是一个清晰的、由ask_llm、TOOLS字典和run_agent循环构成的鲜活图景。这就是动手实践带来的最扎实的认知。