最简智能体Pi Agent核心架构拆解：从最小Agent闭环到工程实践

Agent框架层出不穷的这几年，有一个现象很值得注意：真正让开发者卡住的，往往不是模型能力不够强，也不是工具数量不够多，而是框架本身越来越像一个黑盒。你照着文档把代码跑起来了，但一旦出现问题，你根本不知道它在哪一步做了什么决策，也不知道该从哪里下手排查。最近频繁出现在技术社区热搜里的 Pi Agent，之所以能在众多智能体工具里被反复讨论，并不是因为它的功能列表比别人长，而是因为“最简”这个定位，恰好戳中了大家已经厌倦重框架、黑盒框架的节点。

本文不会把 Pi Agent 的安装文档再复述一遍，而是想借这个选题，把智能体背后真正绕不开的核心架构拆开讲清楚。文章会做三件事：第一，分析“最简智能体”这个说法背后的架构设计逻辑；第二，给出一个不依赖任何重框架、只用少量代码就能跑通的最小 Agent 核心循环示例；第三，把新手接入时最常踩的坑和工程化建议整理出来。读完你会得到一张判断地图，知道什么样的复杂是必要的，什么样的复杂其实可以砍掉。

如果你正在学习 Agent 开发，或者刚接触 Pi Agent、想理解它和 Dify、Coze、Hermes 这类智能体平台的差异，这篇文章会比较适合你。它不是一份官方文档的搬运，而是一份架构视角的导读和实践参考。

1. 这篇文章真正要解决的问题

先说一个我观察到的现象。在很多 Agent 相关社群里，新手的提问往往不是“Agent 能做什么”，而是“我该从哪里开始”。框架文档动辄几十页，概念图一张比一张复杂，有 Orchestrator、Planner、Memory、Tool Use、Multi-Agent 协作……看起来很高大上，但真正上手时，很多人卡在了同一个地方：不知道一个最小的 Agent 应该长什么样。

你可以把这个问题理解成学做饭。给你一本几百页的米其林菜谱，你反而不知道今晚该吃什么；但如果先学会一道番茄炒蛋，你至少有了一个可以下厨的起点。Agent 开发也是同样的道理，很多框架把“什么都能做”写在了简介里，却没有告诉你“一个能跑起来的 Agent 核心循环”只需要哪几个组件。

Pi Agent 之所以值得专门聊，是因为它的定位和很多框架相反。它的关键词是“最简”，也就是说它在架构上刻意做减法，只保留让 Agent 能够完成一次任务闭环的必要组件。这里的“必要”不是随便拍脑袋定出来的，而是来自工程层面的取舍：Agent 的本质是一个循环，不是一堆模块的堆叠。

理解了这一点，你再去看任何智能体框架，都会轻松很多。无论是 Dify 这种图形化平台，还是 Coze 这种在线搭建工具，它们的底层逻辑都离不开“模型调用、工具调用、结果反馈、再决策”这个循环。差别只在于，谁把循环封装得更深，谁把循环暴露得更清晰。

这篇文章要解决的问题，就是帮你把循环看清楚。当你看懂了一个最小 Agent 的运转方式，再去评估 Pi Agent、Hermes、Opencode、Codex 这些工具各自的侧重点，就不会再被宣传话术带偏。

2. 核心设计思想：“最简”不是功能少，而是闭环短

很多人第一次听说“最简智能体”时，会下意识把它理解成“功能残缺的智能体”。这是一个很大的误解。Pi Agent 所代表的“最简”，并不是砍掉功能，而是压缩从输入到输出的决策链路，让每一个环节都足够透明。

我们对比一下两种设计思路：

传统的智能体框架，往往会把规划、执行、记忆、工具管理拆成独立模块，再通过消息队列或事件总线把这些模块串起来。架构图确实漂亮，但代价是引入大量间接层。一个请求进来，先经过规划器，再进入任务队列，然后由执行器调用工具，结果再回传给记忆模块，最后重新生成下一轮计划。只要中间有一个环节状态同步出问题，整个链路就会变得很难排查。

Pi Agent 这类“最简”设计的思路，是把重心放回到LLM 自身的推理能力上。它不预设复杂的任务编排，而是通过一个明确的循环，让模型在每一步都自己决定下一个动作。这其实有点像经典 ReAct 模式的工程化改良，也就是在“思考 - 行动 - 观察”之间建立一个封闭循环。

一个最简 Agent 的核心闭环，只需要三样东西：

1. 一个可调用的 LLM，负责理解和决策；
2. 一组工具，让 Agent 能对外部环境产生影响；
3. 一个循环控制结构，负责把模型输出解析成动作，再把动作结果反馈给模型。

少了任何一样，Agent 都无法完成一个完整的任务闭环。这就是“最小可运行集合”的概念，它和数学里的“基”很相似：不要求元素最多，只要求不可或缺。

这个设计还有一个额外的好处：可解释性。因为闭环短，你很容易在每一步打印出模型到底看到了什么、决定做什么、执行结果如何。这种透明性在调试阶段尤其宝贵，尤其是当你使用的模型在复杂任务上表现不稳定时，能看到完整的决策链，比任何日志系统都管用。

3. 核心架构拆解：控制层、工具层、记忆层

如果要把 Pi Agent 这类最简智能体的架构画成一张图，核心只有三层。我把每一层都讲清楚，并说明这层的职责边界，以及新手最容易误解的地方。

3.1 控制层：Agent 的“大脑”

控制层解决的核心问题是：下一步该做什么。

在传统程序里，控制流由开发者写死，if-else 或者状态机决定程序走向。在 Agent 里，控制流的决策权交给了大模型。每一次循环，控制层都会把当前的目标、已有信息和可用的工具列表发给模型，让模型输出下一步动作。

这块需要特别注意的是：控制层并不负责“执行”工具，它只负责“决定”调用哪个工具、传入什么参数。如果把执行也塞进控制层，你会发现代码很快变成一团乱麻。

一个典型的最简控制循环代码如下：

# agent_minimal.py # 最简 Agent 核心循环：思考 -> 行动 -> 观察 import json import os import urllib.request def call_llm(messages, tools): """ 调用兼容 OpenAI 协议的 LLM 接口。 如果使用本地模型或代理服务，请自行替换 base_url 和 api_key。 """ api_key = os.getenv("LLM_API_KEY", "EMPTY") base_url = os.getenv("LLM_BASE_URL", "http://localhost:8000/v1") model = os.getenv("LLM_MODEL", "qwen2.5:7b") url = base_url.rstrip("/") + "/chat/completions" payload = { "model": model, "messages": messages, "tools": tools, "tool_choice": "auto", } req = urllib.request.Request( url, data=json.dumps(payload).encode("utf-8"), headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"}, method="POST", ) with urllib.request.urlopen(req, timeout=60) as resp: result = json.loads(resp.read().decode("utf-8")) return result["choices"][0]["message"]

这段代码里的call_llm是整个控制层的中枢。它干的事情很简单：把当前对话消息和可用工具列表发给模型，然后让模型返回一个响应。响应里可能是纯文本回复，也可能包含工具调用请求。控制层拿到响应之后，再决定下一步是继续调用工具，还是结束循环。

3.2 工具层：Agent 的“手脚”

控制层负责决策，工具层负责执行。工具层把外部能力封装成统一接口，让模型可以通过结构化参数来调用。这里的核心设计原则是：工具签名越简单越好。

一个函数能被 Agent 正确调用，前提是它的入参和出参都是清晰的 JSON 格式。如果你把一个复杂的类方法直接暴露给 Agent，模型经常会在参数格式上出错。更推荐的做法是，用独立的函数做一层薄封装，把复杂逻辑藏在函数内部。

下面是一个最小工具层的示例，包含两个工具：一个是查询“当前时间”，一个是计算器。其中get_tools_schema返回给模型看的工具描述，run_tool是实际的执行入口。

# tool_layer.py # 工具层：定义 Agent 可调用的工具函数，以及给 LLM 看的工具描述 schema import datetime import json def get_current_time(): """返回当前系统时间，用于测试 Agent 的工具调用能力。""" return {"current_time": datetime.datetime.now().isoformat()} def calculator(expression): """ 一个简单的计算器，只支持加减乘除，不要在生产环境直接执行任意字符串表达式。 """ allowed = set("0123456789+-*/(). ") if any(c not in allowed for c in expression): raise ValueError("表达式包含非法字符") # 在受限字符集下执行，且仅用于示例 result = eval(expression, {"__builtins__": {}}, {}) return {"result": result} def get_tools_schema(): """返回工具描述，让 LLM 知道有哪些工具可用、参数长什么样。""" return [ { "type": "function", "function": { "name": "get_current_time", "description": "获取当前系统时间", "parameters": { "type": "object", "properties": {}, }, }, }, { "type": "function", "function": { "name": "calculator", "description": "计算简单数学表达式，例如 (1+2)*3", "parameters": { "type": "object", "properties": { "expression": { "type": "string", "description": "数学表达式字符串", } }, "required": ["expression"], }, }, }, ] def run_tool(name, arguments): """根据模型返回的工具名称和参数，分发到具体的执行函数。""" if name == "get_current_time": return get_current_time() if name == "calculator": args = json.loads(arguments) return calculator(args["expression"]) raise ValueError(f"未知工具: {name}")

工具层写起来不难，真正难的是调参和边界控制。模型并不总是能猜对你的参数类型，所以工具函数内部一定要做校验，不要把未经检查的输入直接丢给底层系统。上面示例里的calculator就做了一个字符白名单校验，这是工具层最基本的自我防护。

3.3 记忆层：Agent 的“上下文”

记忆层在最小 Agent 里往往是最容易被忽视，却又最容易决定成败的部分。它的职责是维护对话历史，让模型知道“我们已经聊过什么、做过什么”。

在最简架构里，你不需要引入向量数据库，也不需要复杂的知识库管理。只需要一个 list，把用户输入、模型思考、工具执行结果按顺序追加进去。每一轮循环都把完整的 messages 列表发给模型，模型就能基于最新状态做下一步决策。

# memory_layer.py # 记忆层简化版：用一个 list 维护对话上下文 def init_messages(system_prompt): return [{"role": "system", "content": system_prompt}] def add_user_message(messages, content): messages.append({"role": "user", "content": content}) return messages def add_assistant_message(messages, content): messages.append({"role": "assistant", "content": content}) return messages def add_tool_result(messages, tool_call_id, content): messages.append({"role": "tool", "tool_call_id": tool_call_id, "content": content}) return messages def trim_messages(messages, max_len=20): """ 简单粗暴的上下文截断策略：只保留系统提示和最近 max_len 条消息。 生产环境建议用 token 数做精确控制。 """ if len(messages) <= max_len: return messages return [messages[0]] + messages[-max_len + 1:]

这里的trim_messages其实已经引出了一个工程问题：上下文长度总会耗尽。不同的模型上下文长度不一样，如果你的任务是长流程任务，一旦超过模型的 context window，最远端的信息就会被截断，导致 Agent“失忆”。面向生产环境时，记忆层的设计会复杂很多，比如用向量库存历史、用摘要压缩早期对话。但在理解核心架构阶段，先用 list 跑通最重要。

3.4 三层如何协作

三层写完之后，协作方式就是一个 while 循环。控制层决定调用工具时，把工具名和参数传给工具层；工具层执行完，把结果通过工具消息追加进记忆层；控制层再带着新的记忆去问模型。如此往复，直到模型不再请求调用工具，直接输出最终答案。

这个协作模型是理解所有 Agent 框架的钥匙。你去看 Dify 的工作流编排、Coze 的 Bot 搭建，本质上都是在用图形化方式控制这个循环，只不过把每一层都封装成了可视化的节点。

4. 最小可运行示例：用标准库实现 Agent 核心循环

理解了三个层级之后，接下来我们把它们组装成一个真正能跑的 Agent。为了照顾到不同读者的环境，我尽量少引入第三方依赖，直接用 Python 标准库urllib调用兼容 OpenAI 协议的接口。这样你无论使用云端的模型服务，还是本地部署的模型，都能按同样的方式对接。

4.1 环境准备

建议环境如下，版本以你本地实际项目为准：

• Python 3.9 及以上
• 一个可用的 LLM API，兼容 OpenAI 的/v1/chat/completions接口即可
• 环境变量LLM_BASE_URL、LLM_API_KEY、LLM_MODEL

如果你使用的是本地模型服务，比如 Ollama 或 vLLM 启动的 OpenAI 兼容服务，通常会得到类似http://localhost:8000/v1的地址。如果你用的是云端服务，请把对应的 Base URL 和 API Key 填入环境变量。权限和密钥请妥善管理，不要在代码里硬编码。

export LLM_BASE_URL="http://localhost:8000/v1" export LLM_API_KEY="EMPTY" export LLM_MODEL="qwen2.5:7b"

4.2 组装 Agent 主循环

下面是一个不依赖第三方库的最小 Agent 实现文件。我把它命名为minimal_agent.py，代码中包含了完整的循环控制逻辑。

# minimal_agent.py # 最简 Agent 核心循环：思考 -> 行动 -> 观察 import json import os import urllib.request # ---------- 控制层 ---------- def call_llm(messages, tools): api_key = os.getenv("LLM_API_KEY", "EMPTY") base_url = os.getenv("LLM_BASE_URL", "http://localhost:8000/v1") model = os.getenv("LLM_MODEL", "qwen2.5:7b") url = base_url.rstrip("/") + "/chat/completions" payload = { "model": model, "messages": messages, "tools": tools, "tool_choice": "auto", } req = urllib.request.Request( url, data=json.dumps(payload).encode("utf-8"), headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"}, method="POST", ) with urllib.request.urlopen(req, timeout=60) as resp: result = json.loads(resp.read().decode("utf-8")) return result["choices"][0]["message"] # ---------- 工具层 ---------- def get_current_time(): import datetime return {"current_time": datetime.datetime.now().isoformat()} def calculator(expression): allowed = set("0123456789+-*/(). ") if any(c not in allowed for c in expression): raise ValueError("表达式包含非法字符") result = eval(expression, {"__builtins__": {}}, {}) return {"result": result} def get_tools_schema(): return [ { "type": "function", "function": { "name": "get_current_time", "description": "获取当前系统时间", "parameters": {"type": "object", "properties": {}}, }, }, { "type": "function", "function": { "name": "calculator", "description": "计算简单数学表达式，例如 (1+2)*3", "parameters": { "type": "object", "properties": { "expression": {"type": "string", "description": "数学表达式字符串"} }, "required": ["expression"], }, }, }, ] def run_tool(name, arguments): if name == "get_current_time": return get_current_time() if name == "calculator": args = json.loads(arguments) return calculator(args["expression"]) raise ValueError(f"未知工具: {name}") # ---------- 记忆层 ---------- def init_messages(system_prompt): return [{"role": "system", "content": system_prompt}] def trim_messages(messages, max_len=10): if len(messages) <= max_len: return messages return [messages[0]] + messages[-max_len + 1:] # ---------- Agent 主循环 ---------- def agent_run(user_query, max_steps=5): system_prompt = "你是一个最简智能体。在合适的场景下，请优先使用工具来回答用户问题。" messages = init_messages(system_prompt) messages.append({"role": "user", "content": user_query}) tools = get_tools_schema() for step in range(max_steps): print(f"\n===== Step {step + 1} =====") response = call_llm(messages, tools) if response.get("tool_calls"): for tool_call in response["tool_calls"]: fn_name = tool_call["function"]["name"] fn_args = tool_call["function"]["arguments"] print(f"[Action] 调用工具: {fn_name}, 参数: {fn_args}") # 将模型请求追加到上下文 messages.append({ "role": "assistant", "content": response.get("content") or "", "tool_calls": response["tool_calls"], }) # 执行工具 observation = run_tool(fn_name, fn_args) print(f"[Observation] 执行结果: {observation}") messages.append({ "role": "tool", "tool_call_id": tool_call["id"], "content": json.dumps(observation, ensure_ascii=False), }) messages = trim_messages(messages) continue # 没有 tool_calls，说明模型已经生成最终答案 final_answer = response.get("content") or "" print(f"[Final Answer] {final_answer}") return final_answer return "达到最大步数，Agent 循环结束。" if __name__ == "__main__": query = input("请输入你的问题: ") agent_run(query)

4.3 代码的关键点解释

这段代码虽然不到 120 行，但已经完整包含了一个 Agent 的核心机制。几个关键点值得单独解释：

第一，call_llm里设置了tool_choice: "auto"。这意味着模型可以自行决定这次该回复普通文本，还是应该调用工具。如果你希望模型每次都必须调用工具，可以改成"required"，但日常场景下auto更灵活。

第二，循环跳出条件只有一个：模型返回的响应里没有tool_calls字段。换句话说，Agent 的结束条件不是由代码写死的，而是由模型自主决定的。如果模型觉得不需要工具就能回答，它会直接输出文字；如果模型觉得需要多次调用工具，它会在一次循环后继续发起下一次调用。

第三，trim_messages在每个步骤之后被调用，目的是控制上下文长度。这里的max_len写的是 10，你可以根据模型上下文窗口大小进行调整。要注意的是，截断策略不能粗暴地把所有消息都砍掉，至少需要保留系统提示和当前正在处理的那一轮工具调用记录。

5. 运行结果与效果验证

完成代码后，在终端执行下面的命令：

python minimal_agent.py

程序会提示你输入问题。我们分别测试两个场景。

5.1 测试场景一：纯文本回答

输入：

什么是智能体？

预期输出：模型直接返回一段解释，不调用任何工具，循环在第一轮就结束。因为模型认为回答问题不需要工具，所以在tool_calls为空的情况下直接输出最终答案。

5.2 测试场景二：工具调用

输入：

现在几点了？顺便帮我算一下 (12+8)*3 等于多少。

预期输出大致如下：

===== Step 1 ===== [Action] 调用工具: get_current_time, 参数: {} [Observation] 执行结果: {'current_time': '2026-01-01T10:00:00.123456'} [Action] 调用工具: calculator, 参数: {"expression": "(12+8)*3"} [Observation] 执行结果: {'result': 60} ===== Step 2 ===== [Final Answer] 当前时间是 2026-01-01 10:00:00，计算结果为 60。

这里需要注意的是，模型可能会在第一步只调用一个工具，把另一个工具调用放到第二步，这取决于模型自身的决策。AI 的行为不完全确定，只要最终能给出正确答案，流程就是成功的。

5.3 如何判断成功与失败

判断成功的标准有三个：

1. Agent 能够根据问题内容，自主决定是否调用工具；
2. 工具调用的参数能被run_tool正确解析并执行；
3. 工具的返回结果被成功追加到上下文，模型最终利用这个结果生成答案。

如果运行失败，第一步先看终端有没有打印异常信息。最常见的失败原因是网络连接不上模型服务，其次是 API Key 错误，再其次是模型不支持 tools 接口。关于这些问题，下一节会给出更细的排查方向。

6. 常见问题与排查思路

以下是我认为实践中最常见的问题，整理成表格方便查阅。

这里的第 6 条尤其要说一下。Agent 的工具调用并不保证永远按照预期发展，模型可能因为任务描述不清晰而反复调用同一个工具。工程上最稳妥的做法永远是设置最大迭代次数，也就是代码里的max_steps。宁可让 Agent 提前结束，也不要让它陷入无限循环。

另外，calculator中的eval仅用于教学演示。生产环境如果要做公式计算，建议使用ast模块解析表达式，或者直接使用专门的表达式求值库。

7. 从最小架构到完整工程：工程化建议

当你能跑通上面这个最小 Agent 循环以后，下一步是把它放到真实项目里。很多开发者在这里会发现，跑通 demo 很容易，上了生产却一堆问题。这里有几个工程化建议，我认为优先级是最高的。

7.1 给工具加权限边界

工具层最容易被忽略的是权限控制。当你把 Agent 接入数据库、文件系统或第三方 API 时，务必要给每个工具明确标注权限范围。建议先问自己几个问题：这个工具能被未登录用户调用吗？工具的参数是否会被外部输入控制？工具的返回结果是否包含敏感数据？

一个通用的做法是工具白名单机制。在工具层维护一个字典，只允许调用预先注册过的函数，任何动态导入或者反射调用的方式都应该被禁止。

# tool_registry.py # 工具注册表：推荐在工程化阶段使用显式注册方式 TOOL_REGISTRY = { "get_current_time": { "handler": get_current_time, "description": "获取当前系统时间", "required_roles": ["user", "admin"], "enable_audit": True, }, "calculator": { "handler": calculator, "description": "计算简单数学表达式", "required_roles": ["user"], "enable_audit": False, }, } def execute_tool(name, arguments, user_role="user"): if name not in TOOL_REGISTRY: raise ValueError(f"工具不存在或未注册: {name}") tool = TOOL_REGISTRY[name] if user_role not in tool["required_roles"]: raise PermissionError(f"当前角色无权限调用工具: {name}") if tool.get("enable_audit"): # 生产环境应写入审计日志 print(f"[AUDIT] user={user_role} tool={name} args={arguments}") return tool["handler"](**arguments)

这样的注册表结构，比直接写 if-else 分发更清晰，也为后续接入配置中心和权限系统预留了位置。

7.2 循环里加日志和追踪

最小示例里我用了print来打印关键信息。生产环境建议把这些输出统一接入日志系统，关键节点打上 trace_id，这样一次 Agent 执行的全链路都可以被追溯。日志至少要包含这几个信息：

• 模型输入的消息列表（可脱敏）；
• 模型返回的工具调用请求；
• 工具执行结果；
• 每一步消耗的 token 数和耗时；
• 最终退出原因（正常完成还是达到最大步数）。

有了这些日志，你才能回答最基本的运维问题：一次用户请求，Agent 到底做了几次工具调用，每一步花了多少钱和时间。Copy 到表格里就是：

7.3 上下文管理不能只靠截断

上文的trim_messages是最粗暴的截断方式，生产环境很快会遇到问题。比如一个长任务，前面几步已经完成了关键信息提取，如果直接截掉，Agent 后面就失去了判断依据。

更稳妥的做法是分层记忆：

• 短期记忆：最近几轮的工具调用和模型输出，原样保留；
• 工作记忆：当前任务的中间结论，每次工具返回后做一次摘要；
• 长期记忆：跨会话的知识，存放在外部的向量数据库或普通数据库里。

一般情况下，小项目的 Agent 只需要做好短期记忆和工作记忆就够了。只有当你的 Agent 需要处理跨会话、跨用户的历史信息时，才需要引入向量数据库。不要一上来就上向量数据库，这是很多项目过度设计的典型例子。

7.4 为 Agent 增加人工确认机制

在自动化任务中，Agent 调用了破坏性工具（比如删除文件、清空数据库、发送邮件），一旦决策失误，后果会比较麻烦。生产环境建议在工具层增加人工确认回调机制。当 Agent 请求调用高风险工具时，系统先挂起执行，返回一个确认链接给用户，用户点击同意后再真正执行。

这个机制的实现并不复杂，在工具注册表里给每个工具增加need_confirm字段即可。重点是要在架构层面预留这个能力，而不是等出事之后才补丁式地加。

8. 你还需要知道的：Pi Agent 与几个常见框架的定位差异

聊完最小架构，我们再看回 Pi Agent 在整个智能体工具生态里的位置。最近围绕它的讨论，大多是“Pi Agent 和 Opencode、Codex 哪个好用”“Pi Agent 和 Hermes 怎么选”这类问题。这类问题其实没有一个放之四海而皆准的答案，但我们可以从架构定位上做一些判断。

有一个很值得留意的现象：Pi Agent 的热搜词里，除了“安装”“官网”之外，出现频率很高的还有“编码 Skill”“Agent 开发”“框架对比”。这说明它的核心受众主要是工程师，关注的是能不能用更轻的配置方式完成编码类自动化任务。它和 Dify、Coze 这类面向业务人员的可视化搭建平台定位不同，也和 Hermes、Opencode 这类同样面向开发者的 Agent 工具存在差异化。具体选型时，可以从四个方面去对比：

1. 闭环透明度：工具是否让你看清每一步决策？Pi Agent 的“最简”定位通常意味着更好的可观测性；
2. 默认能力 vs 扩展成本：框架开箱自带的功能越多，你在自定义时的自由度往往越低；
3. Skill 机制：Pi Agent 的编码 Skill 意味着可以针对特定任务类型（比如代码生成、代码审查）做定向优化；
4. 多智能体协作：如果你需要多个 Agent 分工协作，那么单 Agent 的最简设计是否仍然适用，需要仔细评估。

我的建议是，不要以“哪个工具最强”作为选型依据，而是以“哪个工具的闭环最短、最适合我的任务”为依据。工具只是把架构思想工程化了，真正决定你项目天花板的，是你对核心循环的理解深度。

9. 总结与下一步实践方向

这篇内容从架构角度拆解了最简智能体 Pi Agent 的核心思路，也给出了一个不依赖重框架的最小 Agent 实现。你现在应该能回答这几个问题了：一个 Agent 的最小可运行闭环需要哪几个组件；控制层、工具层、记忆层各自负责什么；工具调用循环里的结束条件是什么；在工程化阶段需要补上哪些能力。

下一步的实践路径，我建议按顺序做三件事：

第一，把上面的minimal_agent.py跑通，分别测试纯文本回答和工具调用两个场景。

第二，给代码增加一个新的工具函数，比如获取天气、查数据库等，重点关注模型的参数生成能力。如果模型频繁传错参数，多试几次调整工具描述里的 description，往往比改代码更有效。

第三，给自己设定一个稍微复杂一点的任务，比如“帮我读取某个目录下所有 Python 文件，统计每个文件的行数，并按行数排序输出”。这个任务要求 Agent 多次调用工具并整合结果，是检验循环控制逻辑的好练习。

把最小可运行闭环跑通之后，你再去对比 Dify 这类平台是如何封装工作流的，或者看 Pi Agent、Hermes 这类工具是如何做 Skill 编排的，都会有完全不同的理解深度。尤其是当你在项目里遇到 Agent 行为不符合预期时，基于这套闭环思维，你能更快定位是模型问题、工具问题，还是上下文管理的问题。