AI Agent也就是 AI 智能体是目前人工智能应用开发中的热门方向。普通聊天程序只能回答问题而 Agent 更强调“执行任务”。例如查看当前时间列出文件夹中的文件统计不同类型文件的数量根据用户要求选择合适的工具获取工具执行结果并返回答案很多 Agent 教程一开始就使用 LangChain、LangGraph 等框架初学者容易被大量概念和依赖劝退。本文先不调用大模型也不使用第三方框架只用 Python 标准库手写一个最小 Agent 雏形理解智能体最基本的运行流程。一、Agent 的基本工作流程一个简单的 Agent 可以拆成以下几个部分接收用户任务 ↓ 判断用户想做什么 ↓ 选择合适的工具 ↓ 执行工具 ↓ 读取执行结果 ↓ 把结果返回给用户例如用户输入帮我统计文件类型Agent 判断这是一个文件统计任务于是选择count_file_types工具执行完成后Agent 再把统计结果返回给用户。本文实现三个工具查看当前时间。查看工作目录中的文件。统计不同类型文件的数量。二、完整代码新建一个 Python 文件mini_agent.py复制下面的完整代码一个只使用 Python 标准库实现的最小 Agent 雏形。 import argparse from collections import Counter from datetime import datetime from pathlib import Path class MiniAgent: 根据用户输入选择并执行本地工具。 def __init__(self, workspace): self.workspace workspace.resolve() if not self.workspace.is_dir(): raise ValueError(工作目录不存在或者不是文件夹。) self.tools { current_time: self.current_time, list_files: self.list_files, count_file_types: self.count_file_types, } def current_time(self): 返回当前本地时间。 return datetime.now().strftime( 当前时间%Y-%m-%d %H:%M:%S ) def list_files(self): 列出工作目录第一层的文件。 files sorted( [ item.name for item in self.workspace.iterdir() if item.is_file() ], keystr.lower, ) if not files: return 当前目录中没有文件。 # 防止目录中文件过多只显示前20个 visible_files files[:20] result [当前目录中的文件] for number, file_name in enumerate( visible_files, start1, ): result.append( str(number) . file_name ) if len(files) 20: result.append( 还有 str(len(files) - 20) 个文件没有显示。 ) return \n.join(result) def count_file_types(self): 统计工作目录第一层中不同类型文件的数量。 counter Counter() for item in self.workspace.iterdir(): if not item.is_file(): continue file_type item.suffix.lower() if not file_type: file_type 无扩展名 counter[file_type] 1 if not counter: return 当前目录中没有可以统计的文件。 sorted_results sorted( counter.items(), keylambda item: (-item[1], item[0]), ) result [文件类型统计结果] for file_type, count in sorted_results: result.append( file_type str(count) 个 ) return \n.join(result) def decide(self, user_input): 根据关键词选择工具。 text user_input.strip().lower() if any( keyword in text for keyword in [时间, 几点, 日期] ): return current_time if ( 统计 in text and any( keyword in text for keyword in [文件, 类型, 扩展名] ) ): return count_file_types if any( keyword in text for keyword in [查看文件, 列出文件, 有哪些文件] ): return list_files return None def run(self, user_input): 完成一次任务判断和工具调用。 tool_name self.decide(user_input) if tool_name is None: return ( 暂时无法识别这个任务。\n 你可以尝试输入\n 1. 现在几点\n 2. 查看文件\n 3. 统计文件类型 ) tool self.tools[tool_name] try: tool_result tool() except OSError as error: return 工具执行失败 str(error) return ( 执行工具 tool_name \n tool_result ) def main(): parser argparse.ArgumentParser( description运行一个最小 Python Agent ) parser.add_argument( workspace, nargs?, default., help允许 Agent 读取的工作目录, ) args parser.parse_args() try: agent MiniAgent( Path(args.workspace) ) except ValueError as error: print(启动失败 str(error)) return 1 print(最小 Python Agent 已启动。) print(工作目录 str(agent.workspace)) print(输入 exit 可以退出程序。) while True: user_input input(\n请输入任务).strip() if user_input.lower() in { exit, quit, 退出, }: print(Agent 已退出。) break if not user_input: print(请输入具体任务。) continue print(agent.run(user_input)) return 0 if __name__ __main__: raise SystemExit(main())三、运行 Agent在mini_agent.py所在目录打开 PowerShell执行python mini_agent.py程序启动后会显示最小 Python Agent 已启动。 工作目录当前目录的完整路径 输入 exit 可以退出程序。输入现在几点Agent 会选择时间工具执行工具current_time 当前时间2026-09-16 10:30:00实际时间以电脑运行时显示的结果为准。四、让 Agent 查看文件输入查看文件Agent 会执行list_files运行结果类似执行工具list_files 当前目录中的文件 1. mini_agent.py 2. 工作计划.docx 3. 产品资料.pdf 4. 数据.csv为了避免一次输出太多内容程序最多显示前20个文件。五、让 Agent 统计文件类型输入帮我统计文件类型运行结果类似执行工具count_file_types 文件类型统计结果 .pdf3 个 .txt2 个 .csv1 个 .docx1 个 无扩展名1 个程序会把大写和小写扩展名合并。例如图片.PNG 截图.png都会被统计为.png六、指定需要处理的文件夹默认情况下Agent 读取程序当前所在的文件夹。如果想处理其他目录可以在启动时填写文件夹路径python mini_agent.py D:\工作资料路径中包含空格时需要使用英文双引号。例如python mini_agent.py D:\2026 年项目资料Agent 只读取指定目录第一层的文件不会修改、移动或者删除文件。处理重要资料前建议先使用测试文件夹运行。七、为什么它可以算作 Agent 雏形这个程序已经包含了 Agent 的几个基础组成部分。1. 接收任务user_input input(请输入任务)用户可以使用自然语言描述自己的需求。2. 任务判断tool_name self.decide(user_input)decide()根据用户输入判断需要使用哪个工具。3. 工具注册self.tools { current_time: self.current_time, list_files: self.list_files, count_file_types: self.count_file_types, }工具名称和实际的 Python 函数保存在字典中。后续增加新工具时只需要编写对应函数再把它注册到字典中。4. 工具调用tool self.tools[tool_name] tool_result tool()Agent 根据任务判断结果调用对应工具。5. 返回执行结果return ( 执行工具 tool_name \n tool_result )工具完成任务后Agent 将结果整理并返回给用户。八、它和真正的大模型 Agent 有什么区别本文程序使用关键词判断任务if 时间 in text: return current_time优点是代码简单不需要联网不需要申请 API Key不会产生模型调用费用运行结果容易理解和检查缺点也很明显只能理解提前设置好的关键词无法处理复杂表达不会自动拆分多步骤任务不具备上下文记忆不会根据结果继续规划真正的大模型 Agent 通常会让模型负责理解任务和选择工具。例如用户输入先看看这个文件夹有哪些文件 再统计一下哪种文件最多。大模型可能将任务拆成两步第一步调用 list_files 第二步调用 count_file_types这也是本文程序后续可以继续升级的方向。九、如何增加一个新工具例如我们想增加“统计文件总数”工具。首先编写函数def count_all_files(self): count sum( 1 for item in self.workspace.iterdir() if item.is_file() ) return 文件总数 str(count)然后注册工具self.tools { current_time: self.current_time, list_files: self.list_files, count_file_types: self.count_file_types, count_all_files: self.count_all_files, }最后在decide()中增加判断if 文件总数 in text: return count_all_files这样 Agent 就获得了一项新的能力。十、常见问题输入任务后提示无法识别当前版本依靠关键词判断任务。可以尝试输入现在几点 查看文件 统计文件类型提示工作目录不存在检查文件夹路径是否正确python mini_agent.py D:\工作资料不要把具体文件当成工作目录。文件统计数量不正确本文只统计指定文件夹第一层的文件不统计子文件夹中的内容。另外脚本文件mini_agent.py本身也位于工作目录时它会被统计为一个.py文件。中文路径能不能使用可以。建议使用完整路径并添加英文双引号python mini_agent.py D:\中文资料目录十一、总结本文没有直接使用复杂框架而是通过 Python 标准库实现了一个最小 Agent 雏形。它具备以下能力接收用户任务判断任务类型选择工具执行工具返回执行结果限制文件访问范围这个版本还没有接入真正的大模型但已经展示了 Agent 最核心的结构。理解这套流程后下一步可以把关键词判断替换为大模型再加入多轮对话自动任务拆分记忆功能大模型 API本地 Ollama 模型多工具连续调用相比一开始就使用复杂框架先手写一个最小版本更容易理解 Agent 到底是怎样工作的。本文代码由 AI 辅助编写。运行时请先使用测试文件夹不要直接处理重要资料。