直接说结论AI Agent 本质上就是一个“循环”。模型负责想工具负责做循环负责把“想”和“做”串起来直到任务完成。很多人一听到 Agent 就联想到复杂的框架、海量的配置、漫长的推理链路但实际上一个最小可用的 Agent 核心逻辑用 100 行 Python 就能完整表达。这篇文章我打算拆掉所有神秘感带你把一个 Agent 从零写出来。代码量控制在 100 行左右不依赖任何 Agent 框架只用一个大模型接口回调和一个 Python 标准库。适合已经写过 Python、大概知道 API 怎么调的开发者阅读。我会把每个设计决定背后的“为什么”也一并说清楚这样你以后用任何现成框架都不会再被黑盒坑到。1. 内容整体设计与思路拆解1.1 Agent 不是模型而是一个系统很多人以为 Agent 是一个更聪明的模型这个误解会导致你拿着模型 API 去硬套 Agent 场景结果发现效果很差。其实 Agent 是一个系统它的组成是一个大模型负责理解和决策一组工具负责实际执行动作一条消息历史负责让模型记住上下文一个循环控制负责判断任务是否完成。这四件事合在一起才叫 Agent。单独拎出任何一个都不是 Agent。我习惯把它类比成一个“新员工带教”的过程你不是直接问他“你怎么看这个问题”而是给他一个明确任务告诉他公司有哪些资源可以用让他每次汇报都按固定格式说“我准备用什么工具、传什么参数”。模型就是那个员工工具就是公司资源消息历史就是工作日志循环控制就是带教人的催促和验收。1.2 为什么用 100 行代码来理解现成框架动辄几千行功能强大但恰恰因为功能多你很难分清哪些是 Agent 的本质哪些是附加能力。比如记忆持久化、规划器、人机交互、多代理协作这些都有价值但它们属于外围增强。本质只有一件事模型在循环里反复“决策-执行-观察”。用 100 行代码实现这个本质好处是你能一眼看穿主流程。以后再用框架遇到问题也能很快定位到底是模型没理解工具还是工具注册表结构不对还是循环终止条件有问题这些定位能力比会用某个框架值钱得多。我采用的拆解思路是四层消息层维护对话上下文工具层维护一个“工具注册表”决策层让模型输出结构化的动作指令控制层执行动作、反馈结果、判断结束。这四个层在一个 Agent 类里通过简单方法组织起来既保证代码短又能对应到真实框架的模块上。后面你去看 LangChain、MetaGPT 这类项目时会发现它们只不过是在这四个层上加了更多封装。2. 核心细节解析与实操要点2.1 消息历史模型记忆的唯一方式大模型本身没有跨轮记忆它只对你给它的上下文做反应。所以 Agent 必须自己维护一个“messages 列表”把用户请求、模型决策、工具执行结果都按顺序塞回去。在设计消息历史时有三个细节需要注意角色区分用户消息和工具结果最好用不同角色标记。即便某些 API 不支持“tool”角色你也可以用“user”角色加前缀“工具返回”来区分保证模型能看懂哪些是真实世界反馈。顺序敏感消息顺序必须严格按时间排列否则模型会混淆因果关系。工具结果必须紧跟在对应的决策消息之后。长度控制无限堆消息会撑爆上下文窗口。这个在最小实现里可以用“只保留最近 N 轮”来解决后面我会在常见问题里展开。我在项目里把消息历史直接放在 Agent 类的 self.messages 里新增对话和新增工具结果都通过 add_message 方法统一走。这样后续想改成数据库持久化或者改为向量记忆只需要动这一个方法。2.2 工具注册表给模型一份“菜单”模型本身不会直接操作你的系统它只能输出文本。你要让它调用工具就得把工具的信息告诉它让它从中选择。这就是工具注册表存在的意义。工具注册表本质是一个 dictkey 是工具名value 里包含工具的说明、参数描述、可调用的函数对象。为什么要给说明和参数描述因为模型是通过自然语言理解工具的如果工具的描述写得含糊模型很可能在关键时刻“不会用”。我在模拟项目 X 里踩过这个坑给模型的工具描述写着“计算两个数之和”但没说清参数格式结果模型输出了{num1: 1, num2: 2}还是{numbers: [1,2]}全靠猜。所以工具描述必须写清楚参数结构最好附上一个调用示例。在代码实现里我设计了 register_tool 方法。它的签名是agent.register_tool(name, description, func)内部存成字典后续构建提示词时把这些工具描述转成文本给模型。这个设计很便宜但很重要你新增一个工具不需要改 Agent 主流程只需要注册一次。2.3 动作返回协议模型与大模型的“握手”模型怎么告诉系统“我要调用工具”需要一种协议。我采用简单的 JSON 格式。模型输出一个 JSON 对象包含两个字段{action: tool_name, action_input: {key: value}}如果任务已经完成模型输出{action: finish, action_input: 最终答案文本}为什么用 JSON 而不是让模型直接输出“请帮我调用某某工具”因为 JSON 结构化程度高机器好解析也方便校验。但代价是模型偶尔会输出不合法 JSON或者多余的解释文字。所以解析时要做容错我会在代码里用一个简化版解析函数只提取第一个 JSON 块。这里还有一个容易被忽略的细节模型可能把工具参数传给一个不存在的工具或者输出了一个字符串而不是对象。因此 100 行代码里我在_parse之后做了一次动作白名单校验没注册过的工具直接返回错误信息而不是硬调。2.4 循环控制什么时候开始什么时候结束Agent 和普通对话的最大区别就是它会循环。普通对话是“用户说一句模型答一答”Agent 是“模型说要用工具系统执行把结果返回模型再继续想”。循环控制的核心是终止条件。我在最小实现里用了两个模型输出action: finish代表它认为任务已完成循环次数达到max_steps强制退出防止模型陷入无限循环或疯狂调用工具。这两个条件缺一不可。只有一个 finish 条件碰到模型胡说八道时程序会一直跑下去只有一个 max_steps 条件任务没完成就直接截断了体验很差。实际项目里还会加预算控制、时间限制、人工审批等但 100 行里这两个就够了。另外工具执行出现异常时不能把异常直接抛出来那样 Agent 流程就断了。正确的做法是捕获异常把错误信息作为“工具结果”返回给模型让它自己决定是换工具还是换个参数重试。这个思路在下面代码里也有体现。3. 实操过程与核心环节实现3.1 完整代码一个最小 Agent 框架下面这段是我整理后直接可以跑的版本行数在 110 行左右含空行和注释。依赖只有 Python 标准库大模型部分用回调函数注入方便你接任何 API。import json import re from datetime import datetime class Agent: def __init__(self, llm_func, system_prompt, max_steps5): self.llm_func llm_func # 大模型回调函数 self.system_prompt system_prompt # 系统提示词 self.max_steps max_steps # 最大循环次数 self.messages [] # 消息历史 self.tools {} # 工具注册表 def register_tool(self, name, description, func): self.tools[name] {description: description, func: func} def add_message(self, role, content): self.messages.append({role: role, content: content}) def _tool_desc(self): # 把工具注册表转成给模型看的文本描述 lines [可用工具] for name, info in self.tools.items(): lines.append(f- {name}: {info[description]}) lines.append( 调用格式{\action\: \工具名\, \action_input\: {...}}\n 任务完成时{\action\: \finish\, \action_input\: \最终答案\} ) return \n.join(lines) def _parse(self, text): # 从模型回复里提取 JSON兼容多余文字 try: match re.search(r\{.*\}, text, re.DOTALL) data json.loads(match.group(0)) action data.get(action) action_input data.get(action_input) return action, action_input except Exception: return None, text def run(self, task): # 第一步先把用户任务加入消息历史 self.add_message(user, task) for step in range(self.max_steps): # 第二步让模型基于历史工具描述做决策 user_content f请根据情况选择工具或输出 finish。第{step 1}轮。 response self.llm_func( systemself.system_prompt \n self._tool_desc(), messagesself.messages [{role: user, content: user_content}] ) action, action_input self._parse(response) # 模型不打算调用工具直接视为最终回复 if action is None: return action_input # 任务完成返回答案 if action finish: return action_input # 调用工具把结果写回消息历史 tool_info self.tools.get(action) if tool_info is None: error_msg f未找到工具: {action} self.add_message(user, f工具执行失败{error_msg}) continue try: result tool_info[func](action_input) self.add_message(user, f调用 {action} 的结果{result}) except Exception as e: self.add_message(user, f调用 {action} 出错{e}) return 达到最大执行轮数任务未完成。 # ---------- 以下为工具定义和大模型回调 ---------- def llm_func(system, messages): 模拟一个大模型响应。 实际使用时替换成你的 API 调用即可。 last_user messages[-1][content] if 当前时间 in last_user: return {action: get_time, action_input: {}} if 计算 in last_user: expr re.search(r计算\s*([\d\\-\*\/\(\)\.\s]), last_user) if expr: return json.dumps({action: calculate, action_input: {expression: expr.group(1).strip()}}) return {action: finish, action_input: 我不理解这个任务。} def get_time(args): return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def calculate(args): expression args.get(expression, ) # 只用 eval 处理数字和四则运算生产环境要换安全方案 if not re.fullmatch(r[\d\\-\*\/\(\)\.\s], expression): return 表达式不合法 try: return str(eval(expression)) except Exception as e: return f计算错误: {e} def save_note(args): content args.get(content, ) with open(note.txt, a, encodingutf-8) as f: f.write(content \n) return f已保存: {content} if __name__ __main__: agent Agent(llm_funcllm_func, system_prompt你是一个能调用工具的助手。) agent.register_tool(get_time, 获取当前时间无参数。, get_time) agent.register_tool(calculate, 计算四则运算参数格式{\expression\: \12\}, calculate) agent.register_tool(save_note, 保存一段文本到笔记文件参数格式{\content\: \文本\}, save_note) result agent.run(先告诉我当前时间然后计算 123*456 的结果。) print(result)这段代码的输出结果会是调用 get_time 的结果2025-01-05 14:32:10 调用 calculate 的结果56088 达到最大执行轮数任务未完成。注意那个模拟的llm_func只会在最后一步返回 finish所以它会一直循环到 max_steps。真正的模型不会这么死板而是会逐步给出工具调用最后给出 finish。3.2 代码里蕴含的 Agent 核心流程整个run方法就是 Agent 的引擎。我拆解一下第一轮任务进入消息历史模型看到任务结合工具描述输出决策系统解析决策找到工具并执行执行结果写回消息历史模型看到结果继续决策直到输出 finish 或达到 max_steps。这个流程可能在你的脑海里很简单但它就是所有 Agent 框架的骨架。我写代码的时候刻意让工具结果用add_message(user, ...)写回而不是用专门的 tool 角色。这样在最小实现里能省掉不少兼容性处理而且大多数模型 API 都能直接理解“用户说工具返回了 xxx”。为什么会这样设计因为模型自己并不区分“哪句话是工具返回的”它只会根据上下文里的内容来做推理。如果你的 API 支持独立 tool 角色你当然可以改不支持的时候用 user 角色加前缀也能达到效果。我在生产环境里也遇到过只能用 user 角色的情况这个技巧很实用。3.3 如何接入真实大模型接口上面代码里的llm_func是模拟的实际你只需要把函数内部替换成你自己的大模型 API 调用。以常见 OpenAI 风格接口为例你的回调长这样import openai # 仅示例实际使用对应你接的 SDK def llm_func(system, messages): client openai.Client(api_key你的key) resp client.chat.completions.create( model你的模型名, messages[{role: system, content: system}] messages, temperature0.2, ) return resp.choices[0].message.content需要注意一点messages列表里的角色需要符合你所用 API 的约束。如果某个 API 不认user之外的额外角色就会报错。最简单的兜底方案是在add_message方法里做角色映射把所有非 system 消息统一改成 user并在内容前加标记。我在模拟项目 X 里就是这么做兼容的。如果你的模型输出不稳定可以在系统提示词里加一个 few-shot 示例比如示例 用户现在几点 助手{action: get_time, action_input: {}} 工具结果2025-01-05 14:32:10 助手{action: finish, action_input: 当前时间是14点32分。}这种示例对模型理解格式的帮助很大比你在提示词里写十遍“请遵守格式”都管用。3.4 为什么 100 行就够了还需要什么有人会质疑这也能算 Agent确实它缺少记忆持久化、没有子任务规划、没有多步推理、没有并行工具调用、没有权限控制。但它已经具备 Agent 的三个核心特征用工具、看结果、再决策。这就是本质。那实际项目里还需要加什么我的建议优先级是工具调用结果的语义校验不能只看模型说“调用成功”就信异常重试机制工具报错时让模型重试但要限制重试次数截断上下文防止多轮后消息过长并发工具调用效率提升但会提高解析复杂度人工确认环节涉及敏感操作时强制人审。这些都是在 100 行骨架上逐步长肉的过程。你从零写一遍、再逐个加功能比直接读一个几千行的框架源码理解深刻得多。4. 常见问题与排查技巧实录4.1 模型总是输出不合法 JSON在最小实现里我提到用正则r\{.*\}去抓取模型回复里的 JSON 片段这是低成本的兜底。但这个正则不够健壮如果模型输出里有两个{}可能抓到错误的那一个。我在模拟项目 X 里遇到最多的情况是模型在 JSON 外面加了“好的我来调用工具”这类自然语言所以正则兜底是必须的。更可靠的方案是要求模型只输出 JSON不要有任何解释但即便这样模型偶尔也会违反所以解析失败时把错误信息返回给模型让它重新输出 JSON 格式。操作方式解析失败时把你输出的不是合法JSON请只输出JSON加入消息历史然后 continue 进入下一轮。我建议把这个逻辑加入_parse的异常分支而不是直接返回。4.2 Agent 陷入死循环疯狂调用工具这是我做 Agent 时碰到的最头疼问题。模型为了“完成”一个简单任务反复调用同一个工具结果永远不结束。原因通常是工具返回结果不明确模型没看到有效信息工具结果没有被正确写入消息历史模型误以为自己“没调用过”模型本身对任务的理解有偏差一直在原地打转。解决手段有三层第一层max_steps硬性限制保证不会无限跑第二层检查工具结果写回逻辑确保每轮调用结果模型都能看到第三层在工具结果中增加“是否成功”的标记比如“计算成功56088”让模型更容易判断状态。我实际调试的时候会打印每一轮的完整消息历史。打印之后往往一眼就能看到问题要么模型没看到结果要么结果是空白字符串。所以这个排查技巧很值得养成。4.3 工具参数类型不匹配模型输出的action_input可能是个字符串也可能是个对象甚至可能是 null。如果你的工具接口约定参数是 dict那你必须在run里做一次类型检查。我在代码里已经假设action_input能直接传给工具函数但实际会有翻车情况。建议在run里加一个保护if not isinstance(action_input, dict): action_input {value: action_input}这种兜底至少能避免程序直接崩溃让工具收到一个标准化的参数结构。更严谨的做法是给每个工具定义一个参数 schema在调用前做校验。100 行里不展开但你现在知道问题在哪了。4.4 上唤文太长了模型开始“失忆”多轮工具调用后消息列表会越来越大超出上下文窗口或者模型开始忽略早期信息。解决办法不是无限扩容而是“截断摘要”。最简单的截断策略是只保留最近的 N 条消息比如最后 6 条。但这样会丢掉早期任务目标模型可能跑偏。所以更好的是做摘要在每轮结束后把前面的关键信息压缩成一句话替换掉冗长的工具结果。示例历史摘录用户要计算商品总价已调用 calculate 得到单价当前合计 56088。这个摘要可以由大模型自己生成也可以用简单规则写。我在最小项目里为了省 token直接保留最后 4 条消息加一个“任务目标”字段效果也还行。从这里也能看出记忆管理本身就是 Agent 工程的一大半内容。4.5 工具副作用与安全性最后提一个甚至比功能更重要的点工具是有副作用的。比如save_note会写文件、send_email会发邮件、buy_item会下单。你的 Agent 一旦接上这些工具模型又失控的话后果可能很尴尬。所以我个人强烈建议在工具层做权限标记。最小实现里我给每个工具加一个“禁回调”的标记默认工具不允许被模型调用只有显式标注 allow_agent 的工具才能进工具注册表。这样即便模型“想到”要发邮件它也没有权限调用因为对应工具根本没注册进来。这是我在实际项目中反复踩坑后养成的习惯不要把所有能力都暴露给模型只暴露当前任务需要的最小工具集。宁可多注册一次也不要因为模型乱调用而出事故。4.6 排查问题时的快速定位方法这里给你一个我调试 Agent 时惯用的三件套打印self.messages看模型究竟看到了什么打印模型原始输出确认它到底回复了什么而不是只看解析后的 action手动调用工具函数确认工具本身没有 bug。很多时候 Agent 行为诡异不是模型“笨”而是你喂给它的上下文有问题。比如工具结果里包含了一大段无关日志模型就抓不住关键信息。把工具结果格式化得干净、短小、可读比调任何提示词都有效。我在代码里故意让工具结果直接返回字符串就是为了保证消息历史的可读性。5. 关键设计决策表和扩展方向在设计这个最小 Agent 时有几个容易纠结的决策点我做成一张表总结一下决策点我的选择原因什么时候该改消息角色工具结果用 user 角色加前缀最大兼容性不挑 API你用的 API 支持独立 tool 角色时工具协议JSON 对象{action, action_input}结构化、易解析需要并发调用时可以改成数组终止条件max_steps finish简单可靠生产环境要加预算、人工审批工具参数校验仅做类型兜底100 行内保持简单多工具复杂场景用 JSON Schema上下文管理无依靠 max_steps 间接控制演示最小实现真实项目务必加截断或摘要最后说一点个人经验。这个 100 行框架不是给别人做产品用的而是给你“透视” Agent 用的。当你能亲手写出这个循环再看任何 AI Agent 框架时你都会发现它们做的大部分事其实是在这个基础循环的外面增加稳定性、效率、可观测性和安全性。理解到这个层面的感觉和你只是调用一个 Agent SDK 是完全不同的。如果你想继续扩展我建议下一步把模拟的llm_func换成真实接口然后试着给 Agent 增加两个新工具一个联网搜索工具一个读写文件工具。当你发现模型能够组合这些工具解决一个多步任务时你会真正体会到 Agent 的本质力量。