从零实现AI Agent：任务规划、工具调用与Manus架构拆解-平芜编程栈

先恭喜 Manus 团队。从年初爆火到经历各种波折，现在宣布恢复独立运营，对关注 AI Agent 方向的同学来说，确实是一个值得留意的信号。很多读者在后台留言问：Manus 到底是什么技术？为什么一个 Agent 产品能引起这么大关注？“AI Agent”和普通聊天机器人又有什么区别？

这篇文章不打算写成新闻稿，而是从技术角度出发。我们先聊清楚 Manus 这类通用型 AI Agent 的技术定位，再深入拆解它的核心架构：任务规划、工具调用、记忆管理和执行验证。最后，结合一套极简的 Python 代码，带大家从零实现一个具备“规划 — 调用 — 执行 — 反馈”闭环的轻量级 Agent。无论你是想入门 AI Agent 开发，还是想理解行业事件背后的技术逻辑，这篇都能帮上忙。

1. Manus 是什么？为什么“独立运营”值得技术人关注

1.1 一句话理解 Manus

Manus 是一个通用型 AI Agent 产品。和 ChatGPT、文心一言这类“你问我答”的对话式 AI 不同，Manus 的定位是直接帮你完成一项完整任务。

比如你给它一个需求：

“帮我分析某城市近一年的房价走势，整理成一份带图表的 PDF 报告。”

传统聊天机器人的做法是：给你一段文字分析，最多配几个表格。而 Manus 这类 Agent 的做法是：自动规划步骤 → 调用浏览器搜索数据 → 编写 Python 代码做统计分析 → 生成图表 → 输出一份完整报告文件。

从用户视角来看，Manus 像是一个“数字员工”，而不是一个“聊天窗口”。

1.2 为什么“独立运营”是一个里程碑

在 AI 行业，一个 Agent 项目从孵化状态走向独立运营，说明它已经跨过了几个关键阶段：

从技术验证走向产品化：不只是演示“能跑通”，而是有稳定服务用户的能力。
从单一模型走向工程化：Agent 依赖的不只是大模型，还涉及任务调度、工具链、沙箱环境、异步任务队列等系统工程。
从实验室走向商业化：独立运营意味着有独立的技术路线、数据策略和商业模式。

对开发者的启发是：AI Agent 已经从“概念阶段”进入“工程落地阶段”。如果你还在观望，现在是一个不错的学习切入点。

1.3 本文的技术定位

本文不分析 Manus 的商业策略，而是聚焦技术层面：

AI Agent 与传统 AI 助手的区别
Agent 的核心技术架构
实现一个轻量级 Agent 的完整代码
工程落地时的常见问题与最佳实践

2. AI Agent 的核心概念与架构演进

2.1 从“对话”到“任务执行”

传统 AI 助手的交互模式是：

用户输入 → 模型生成回答 → 结束

AI Agent 的交互模式是：

用户输入目标 → Agent 拆解任务 → 选择工具 → 执行操作 → 获取结果 → 调整计划 → 输出最终成果

差异的核心在于Agent 具备“行动能力”。它不只是理解语言，还能调用外部工具改变现实状态，比如查数据库、发请求、写文件、执行代码。

2.2 Agent 的五层基础能力模型

从技术实现角度看，一个完整的 Agent 通常包含以下五个核心模块：

模块	作用	类比
用户意图识别	理解用户真正想要的结果	项目经理
任务规划（Planning）	把大目标拆成步骤	拆解任务清单
工具调用（Tool Use）	调用 API、代码、搜索、数据库	执行者
记忆管理（Memory）	保存历史信息和中间状态	工作笔记
结果验证（Validation）	判断执行结果是否满足要求	质量验收

这五个模块共同构成了 Agent 的“感知—决策—执行”闭环。

2.3 Manus 类的通用 Agent 技术特征

结合 Manus 这类产品的公开演示和技术趋势，通用型 Agent 通常具备以下特征：

异步任务执行：用户提交任务后，Agent 在云端服务器逐步执行，而不是同步等待。
多工具协同：Agent 不是只依赖一个模型，而是能调用搜索、代码解释器、文件处理、浏览器等多种工具。
自主规划与反思：每一步执行后，Agent 会检查结果是否符合预期，决定是继续还是调整方案。
可视化过程：用户可以看到 Agent 当前的执行步骤，而不是只拿到最终结果。

3. Agent 的技术拆解：规划、工具、记忆、执行

3.1 任务规划（Planning）

规划是 Agent 和普通 AI 工具最关键的区别。现在常用两种方式：

方式一：ReAct 模式（推理 + 行动）

模型在每一步输出“思考 → 行动 → 观察”循环，例如：

Thought: 用户需要一份房价分析报告，我需要先获取数据。 Action: 调用搜索工具查询房价数据 Observation: 获取到某城市近12个月平均房价 Thought: 数据已获取，接下来需要做趋势分析。 Action: 调用代码执行工具编写 Python 分析脚本 ...

ReAct 的优势是灵活，适合开放式任务，缺点是可能陷入长循环。

方式二：Plan-and-Execute 模式（先规划再执行）

Agent 先一次性生成完整执行计划，再逐步执行：

Plan: 1. 获取某城市近12个月房价数据 2. 使用 pandas 进行数据清洗和趋势计算 3. 使用 matplotlib 生成趋势图 4. 将结果渲染为 PDF 报告

这种方式更可控，但应对动态变化时不够灵活。实际产品中一般会混合使用。

3.2 工具调用（Tool Use）

工具调用是 Agent“动手”的接口。核心设计是工具抽象层——将所有外部能力统一封装成结构化接口，让模型可以“看到”有哪些工具、工具需要什么参数。

例如一个工具定义：

{ "name": "web_search", "description": "搜索互联网获取实时信息", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "搜索关键词"} }, "required": ["query"] } }

模型输出一个结构化调用请求，代码层解析后真正执行搜索，把结果返回给模型。

3.3 记忆管理（Memory）

Agent 的记忆可以粗略分为三层：

短期记忆：当前任务内保留的上下文，如已经执行过的步骤、获取到的中间结果。
长期记忆：跨任务保存的用户偏好、历史任务、知识库。
工作记忆：当前环境中的文件状态、变量状态、运行环境信息。

实际实现中，短期记忆常用滑动窗口或摘要压缩，长期记忆常使用向量数据库进行语义检索。

3.4 执行验证（Validation）

Agent 执行完操作后，需要判断“做得对不对”，常用策略：

代码执行是否报错
生成的文件是否存在且非空
调用 API 是否返回预期状态码
让模型自我反思（Self-Reflection）：“根据结果，任务是否已经完成？还需要什么？”

4. 环境准备与项目结构

接下来进入实战环节。我们用 Python 从零实现一个轻量级 AI Agent，具备任务规划、工具注册、调用外部工具、结果返回的基本能力。

注意：示例里的模型调用方式使用 OpenAI 兼容接口的通用写法，你需要根据自己的模型服务商替换base_url和api_key。代码重点在 Agent 框架，不在具体模型。

4.1 环境版本

本文示例使用的环境如下：

Python 3.10+
openai Python SDK 1.x
操作系统不限（Windows / macOS / Linux 均可）
需要一个支持 function calling 的大模型 API，如 OpenAI 系列、国产大模型兼容接口等

如果你本地没有模型 API，也可以用模拟接口调试整个流程，稍后会说。

4.2 项目目录结构

simple_agent/ ├── agent.py # Agent 核心实现 ├── tools.py # 工具定义与注册 ├── config.py # 模型配置 ├── main.py # 启动入口 └── requirements.txt # 依赖文件

4.3 安装依赖

pip install openai python-dotenv

5. 完整实现：从零写一个轻量级 Agent

下面我们按模块逐个实现。

5.1 工具层：tools.py

先定义两个示例工具：get_current_time和calculate，并提供一个工具注册字典。

# 文件路径：simple_agent/tools.py import datetime import json from typing import Any, Callable def get_current_time() -> dict: """返回当前系统时间""" now = datetime.datetime.now() return { "time": now.strftime("%Y-%m-%d %H:%M:%S"), "timezone": "Asia/Shanghai" } def calculate(expression: str) -> dict: """ 计算简单的数学表达式 注意：生产环境中不要直接使用 eval，这里仅为演示 """ try: result = eval(expression, {"__builtins__": {}}, {}) return {"result": result} except Exception as e: return {"error": str(e)} # 工具定义：供模型识别的 JSON Schema TOOL_SCHEMAS = [ { "type": "function", "function": { "name": "get_current_time", "description": "获取当前系统时间", "parameters": { "type": "object", "properties": {}, "required": [] } } }, { "type": "function", "function": { "name": "calculate", "description": "计算数学表达式，如 '1 + 2 * 3'", "parameters": { "type": "object", "properties": { "expression": { "type": "string", "description": "数学表达式" } }, "required": ["expression"] } } } ] # 工具名称到函数的映射 TOOL_FUNCTIONS: dict[str, Callable[..., Any]] = { "get_current_time": get_current_time, "calculate": calculate } def call_tool(tool_name: str, arguments: dict) -> dict: """统一的工具调用入口""" if tool_name not in TOOL_FUNCTIONS: return {"error": f"未知工具: {tool_name}"} try: result = TOOL_FUNCTIONS[tool_name](**arguments) return {"success": True, "result": result} except TypeError as e: return {"success": False, "error": f"参数错误: {e}"} except Exception as e: return {"success": False, "error": str(e)}

需要说明几点：

TOOL_SCHEMAS用于让模型知道有哪些工具可以调用，这是 Function Calling 机制的基础。
call_tool是所有工具的统一入口，方便后续加日志和权限控制。
生产环境不建议直接使用eval，建议使用ast.literal_eval或专门的计算库，这里仅做示例。

5.2 配置层：config.py

# 文件路径：simple_agent/config.py import os from dotenv import load_dotenv load_dotenv() MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4o-mini") API_BASE = os.getenv("API_BASE", "") # 留空则使用 OpenAI 官方接口 API_KEY = os.getenv("API_KEY", "") MAX_STEPS = int(os.getenv("MAX_STEPS", "5"))

用环境变量管理配置，避免把密钥硬编码在代码中。

5.3 Agent 核心：agent.py

# 文件路径：simple_agent/agent.py import json from openai import OpenAI import config from tools import TOOL_SCHEMAS, TOOL_FUNCTIONS, call_tool class SimpleAgent: def __init__(self): self.client = OpenAI( api_key=config.API_KEY, base_url=config.API_BASE if config.API_BASE else None ) self.messages = [] self.model = config.MODEL_NAME self.max_steps = config.MAX_STEPS def run(self, user_query: str) -> str: """执行用户任务""" self.messages.append({"role": "user", "content": user_query}) print(f"\n[用户]: {user_query}") for step in range(1, self.max_steps + 1): print(f"\n--- 第 {step} 步 ---") response = self.client.chat.completions.create( model=self.model, messages=self.messages, tools=TOOL_SCHEMAS, tool_choice="auto", ) message = response.choices[0].message # 模型没有要求调用工具，说明任务完成 if not message.tool_calls: final_answer = message.content print(f"[Agent]: {final_answer}") return final_answer # 模型要求调用工具 self.messages.append(message) for tool_call in message.tool_calls: tool_name = tool_call.function.name tool_args = json.loads(tool_call.function.arguments) print(f"[调用工具]: {tool_name}({tool_args})") tool_result = call_tool(tool_name, tool_args) # 将工具结果加入上下文中 self.messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(tool_result, ensure_ascii=False) }) print(f"[工具返回]: {tool_result}") return "已达最大执行步数，任务可能未完成。" if __name__ == "__main__": agent = SimpleAgent() while True: query = input("\n请输入你的问题（输入 exit 退出）: ") if query.lower() == "exit": break agent.run(query)

run方法的流程：

将用户问题加入消息列表。
调用模型，带上工具定义。
如果模型返回工具调用请求，则执行工具并回传结果。
如果没有工具调用，说明模型已生成最终答案，返回结果。
最多执行MAX_STEPS步，防止死循环。

5.4 启动入口：main.py

# 文件路径：simple_agent/main.py from agent import SimpleAgent def main(): agent = SimpleAgent() print("=== 简单 AI Agent 演示 ===") print("输入 exit 退出\n") while True: query = input("你: ") if query.lower() in ("exit", "quit"): break if not query.strip(): continue agent.run(query) if __name__ == "__main__": main()

5.5 运行与验证

创建.env文件：

MODEL_NAME=gpt-4o-mini API_KEY=你的API密钥 API_BASE= MAX_STEPS=5

运行：

python main.py

输入示例：

现在几点了？顺便算一下 (12 + 34) * 2 的结果。

预期流程如下：

=== 简单 AI Agent 演示 === 你: 现在几点了？顺便算一下 (12 + 34) * 2 的结果。 [用户]: 现在几点了？顺便算一下 (12 + 34) * 2 的结果。 --- 第 1 步 --- [调用工具]: get_current_time({'time': '2025-02-17 14:23:45', 'timezone': 'Asia/Shanghai'}) [工具返回]: {'success': True, 'result': {'time': '2025-02-17 14:23:45', 'timezone': 'Asia/Shanghai'}} --- 第 2 步 --- [调用工具]: calculate({'expression': '(12 + 34) * 2'}) [工具返回]: {'success': True, 'result': {'result': 92}} --- 第 3 步 --- [Agent]: 当前时间是 2025-02-17 14:23:45（Asia/Shanghai），(12 + 34) * 2 的结果是 92。

这里核心机制是：模型先识别出需要调用两个工具，按顺序调用并把结果推送给模型，模型最后综合所有工具结果生成最终回答。

5.6 没有真实 API 时怎么调试

如果你想先跑通流程，但没有模型 API，可以写一个模拟的响应模块，固定返回“调用某个工具”的结构。这样能验证工具调度和消息流转是否正确。

实际开发中，可以先 mock 模型层，再接入真实模型。

6. 从示例到工程化：Agent 落地中的关键问题

上面这个示例能跑通，但距离工程化还有较大距离。下面重点介绍企业在落地 Agent 时遇到的几类典型问题。

6.1 Function Calling 的稳定性

真实业务中，模型可能返回不存在的工具名、参数格式错误、多轮反复调用同一个工具。需要增加：

工具调用白名单校验
参数 JSON 解析异常处理
同一工具连续调用的熔断机制
超时限制

示例代码已经包含call_tool的异常处理，但在生产环境中还要增加更细粒度的错误码与重试策略。

6.2 上下文长度控制

Agent 每执行一步，消息列表都会增加一条工具结果。长任务会迅速消耗上下文窗口。

常见方案：

只保留最近 N 轮消息
对历史消息做摘要压缩
关键结果存入外部存储，需要时再检索

6.3 沙箱与安全控制

Agent 一旦具备执行代码、访问网络的能力，就需要严格的沙箱机制：

代码执行放入容器或虚拟机，禁止直接跑在宿主机
文件读写限制在指定目录
网络请求做域名白名单
涉及敏感操作（删除、支付、发送消息）必须增加人工确认环节

6.4 异步任务与状态管理

真实产品中的 Agent 任务往往耗时较长。需要把任务从同步调用改为异步队列：

任务提交后返回任务 ID
Agent 在后台逐步执行
前端轮询或 WebSocket 推送执行状态
支持任务暂停、取消、断点续跑

7. 常见问题与排查思路

问题现象	常见原因	解决思路
模型没有调用工具，直接返回文本	工具描述不够清晰，或模型版本不支持 Function Calling	检查模型是否支持工具调用，优化工具`description`
工具参数解析报错	模型返回的参数不是合法 JSON	在`json.loads`外层加 try-except，解析失败时提示模型重新生成
工具被反复调用多次	缺少终止条件	增加最大执行步数，或让模型明确输出“任务已完成”标记
调用真实 API 超时	外部接口响应慢	给工具调用设置超时时间，超时后返回明确错误信息
上下文超出模型限制	工具结果太大，或历史消息过多	使用消息裁剪、摘要压缩或向量检索
模型返回不存在的工具名称	工具清单和模型理解不一致	在调用前加白名单校验，过滤非法工具名
任务执行到一半中断	进程崩溃或外部依赖失败	引入任务状态持久化，支持断点恢复

8. AI Agent 工程落地的最佳实践

8.1 工具设计原则

工具是 Agent 能力的边界。设计工具时有几条原则：

一个工具只做一件事，职责单一，方便模型理解和复用。
description 写清楚，包括用途、参数含义、返回值格式、典型调用场景。模型的工具选择能力很大程度上依赖描述质量。
参数校验在函数内部做，不要假设模型会传正确参数。

8.2 规划策略选择

简单、步骤固定的任务：优先用 Plan-and-Execute，稳定可控。
开放式、需要探索的任务：用 ReAct 循环，灵活但需要限制步数。
混合策略：先让模型判断任务类型，再动态选择规划模式。

8.3 日志与可观测性

Agent 调试比传统程序更困难，因为模型输出充满不确定性。工程上建议：

记录每一步的模型原始输出
记录工具调用的完整输入输出
记录最终的判断依据
为每一步生成 trace_id，方便追踪

8.4 人与 Agent 的协作边界

不是所有步骤都适合让 Agent 自主完成。建议按风险等级划分：

风险等级	示例	策略
低风险	搜索资料、生成代码草稿、格式化文本	全自动执行
中风险	修改配置文件、写文件、发内部消息	自动执行但留审计日志
高风险	删除数据、支付操作、对外发邮件	生成建议，人工确认后执行

8.5 成本控制

Agent 的多步交互会消耗大量 Token。控制成本的几种有效方式：

设定单任务最大步数
使用小型模型处理简单步骤，大型模型处理复杂决策
对工具返回的长文本做截断或摘要
缓存高频工具的执行结果

9. 从 Manus 独立运营看 AI Agent 的未来方向

Manus 选择恢复独立运营，对行业来说具有指向意义：

第一，AI Agent 的技术栈正在成型。规划、工具调用、沙箱执行、异步任务管理已经有可复用的技术套路，不再只是论文里的炫技概念。

第二，模型能力之外，工程能力开始成为竞争壁垒。谁能把工具链做得更稳定、任务拆解更合理、执行过程更可控，谁的产品体验就更好。

第三，Agent 的应用场景将从“简单工具调用”走向“复杂工作流自动化”，比如自动生成周报并发送邮件、监控数据指标并生成预警、自动完成竞品分析并生成报告——这些场景已经具备落地条件。

对普通开发者来说，现在正是学习 Agent 开发的最佳时机。不需要等“大模型再强一点”，而是可以先把规划、工具调用、状态管理这套框架跑通，后续换更好的模型，系统能力自然升级。

10. 总结与后续学习建议

本文围绕 Manus 恢复独立运营这个行业信号，梳理了 AI Agent 的核心技术架构，并通过一个可运行的 Python 示例演示了“模型 + 工具调用”的基础 Agent 闭环。

你已经掌握的：

AI Agent 与传统 AI 助手的区别
Agent 五大核心模块：意图识别、规划、工具、记忆、验证
Function Calling 在 Agent 中的核心作用
一个完整的轻量级 Agent 代码实现
工程落地的常见问题与解决方案

下一步可以从这几个方向继续深入：

加入长期记忆：引入向量数据库，让 Agent 记住用户偏好和历史任务。
实现异步任务：把同步调用改为消息队列驱动，支持后台执行和状态推送。
构建复杂工具链：接入搜索、文件处理、数据库查询、浏览器自动化等工具。
引入结果反思机制：让 Agent 在得到结果后自动评估质量，不满意则重新执行。

每个方向都可以独立写一篇教程，本文的代码框架可以作为所有方向的起点。如果你在复现过程中遇到问题，或者实现了更有意思的 Agent 功能，欢迎在评论区交流。