1. 为什么我要自己搭一个 AgentManus 火的那阵子我身边不少做后端和算法的朋友都在讨论同一个问题它到底是不是“套壳”。讨论到最后大家基本达成一个共识——底层模型不是它自己的工具链也大多是现成的但它的工程化整合确实做得漂亮。任务调度、工具编排、上下文管理这几块拼在一起让一个通用 Agent 真的能跑起来干活这件事本身就有价值。不过对于想深入理解 Agent 的人来说光看演示视频是不够的。你需要把它拆开自己动手搭一遍才能知道 LLM 选型、Prompt 编排、工具调用这三件事在工程上到底怎么落地。OpenManus 就是在这个背景下进入视野的——MetaGPT 团队开源的一个简洁实现代码结构比 LangChain 清爽不少适合拿来学习和二次开发。这篇内容的目标很明确带你从零跑通一个可定制的 Agent以 OpenManus 为参照把 config.toml 骨架、TaoToken 统一 Key 配置、本地启动和对话验证这几个关键动作全部走一遍。你不需要有 Agent 开发经验但最好会一点 Python知道什么是 API Key能看懂 TOML 配置文件。跑完之后你会得到一个能对话、能调工具、能自己规划步骤的最小 Agent后面想加什么工具、换什么模型都在你手里。2. TaoToken 前置统一 Key 与模型接入在动手写 Agent 之前先把模型接入这件事解决掉。Agent 和普通聊天最大的区别是它会反复调用 LLM——规划一次、执行一次、反思一次一个任务下来可能十几次请求。如果你每个模型都单独配 Key、单独改 base_url调试起来会非常痛苦。我的做法是用 TaoToken 做统一入口。它兼容 OpenAI 的接口格式也就是说你原来用 openai 库写的调用代码只需要改 base_url 和 api_key 两个字段就能切过去。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点直接用 https://taotoken.net/api 就行注意这个地址后面不要加多余的路径。你需要先去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面点创建复制出来的那串 sk- 开头的字符串就是你的凭证。这个 Key 在后面的 config.toml 里会用到先放好。注意API Key 不要硬编码在代码里提交到 Git用环境变量或者单独的配置文件管理。OpenManus 的 config.toml 默认就在项目根目录记得把它加进 .gitignore。模型选型方面Agent 场景对模型的指令遵循能力和工具调用格式要求比较高。我实测下来qwen-max 系列和 claude 系列在 ReAct 循环里表现比较稳前者便宜、后者工具调用格式更规范。你可以在 TaoToken 的模型对话页面先试试哪个模型对你的任务响应更好地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。选好之后把模型名填进配置就行不用改代码。如果你打算长期跑编码类 Agent比如让它自动写代码、跑测试、修 bug那可以考虑 Coding Plan额度更划算具体在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 看。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题可以先翻这里。3. 可复制配置config.toml 骨架与工具注册OpenManus 的配置体系围绕一个 config.toml 展开里面分了几块LLM 配置、Agent 配置、工具配置。我把它简化成一个最小可跑版本你直接复制就能用。先看 LLM 部分。这里的关键是把 base_url 指向 TaoToken 的 API 端点api_key 填你刚才创建的那串model 填你想用的模型名。temperature 建议设 0.3 左右Agent 场景不需要太发散稳定执行比创意重要。# config.toml [llm] base_url https://taotoken.net/api api_key sk-你的Key model qwen-max-latest max_tokens 4096 temperature 0.3 [llm.vision] base_url https://taotoken.net/api api_key sk-你的Key model qwen-vl-max [agent] max_steps 20 max_observe 5000 [agent.react] enable_reflection true [tools] enable_python true enable_search true enable_file truemax_steps 控制 Agent 最多走多少步防止死循环。max_observe 限制每次工具返回结果截断的长度避免上下文爆炸。这两个参数在调试阶段可以调小一点跑通了再放宽。接下来是工具注册。OpenManus 的工具系统是插件式的每个工具继承 BaseTool实现 name、description、parameters 和 execute 四个部分。description 特别重要LLM 就是靠它来判断什么时候该调这个工具。我写一个最简单的计算器工具给你看结构# tools/calculator.py from pydantic import Field from app.tool.base import BaseTool class Calculator(BaseTool): name: str calculator description: str 执行基础数学运算支持加减乘除和幂运算。输入应为合法的 Python 数学表达式。 parameters: dict { type: object, properties: { expression: { type: string, description: 要计算的数学表达式例如 2 3 * 4 } }, required: [expression] } async def execute(self, expression: str) - str: try: result eval(expression, {__builtins__: {}}, {}) return f计算结果{result} except Exception as e: return f计算失败{str(e)}写完工具后在 Agent 初始化时注册进去LLM 就能在需要的时候调用它。这里有个坑eval 直接执行用户输入有安全风险生产环境一定要换成受限的表达式解析器比如 ast.literal_eval 或者专门的数学解析库。我这里只是为了演示结构。Prompt 编排是另一个核心。OpenManus 把 Prompt 分成两层system prompt 定义 Agent 的身份和能力边界next_step prompt 告诉它当前有哪些工具可用、下一步该做什么。system prompt 不要写得太泛比如“你是一个有用的助手”这种基本没用。要具体到任务域比如“你是一个数据分析 Agent擅长用 Python 处理表格数据优先使用 pandas”。SYSTEM_PROMPT 你是一个可执行任务的 AI Agent。 你可以使用以下工具calculator数学计算、python_execute执行 Python 代码、file_saver保存文件。 规则 1. 先理解用户目标再决定是否需要调用工具。 2. 每次只调用一个工具观察结果后再决定下一步。 3. 如果任务完成直接给出最终答案不要继续调用工具。 4. 如果连续两次工具调用没有进展停止并说明原因。 NEXT_STEP_PROMPT 根据当前对话和上一步的观察结果决定下一步行动。 如果需要调用工具输出工具名和参数如果任务已完成输出最终答案。这两段 Prompt 配合 ReAct 循环使用Agent 会交替进行思考和行动。实测下来把规则写清楚比堆砌形容词有效得多。4. 验证请求本地启动与对话测试配置和代码准备好之后启动流程分三步。第一步确认依赖装好OpenManus 依赖 openai、pydantic、httpx 这几个核心库用 pip 装就行pip install openai pydantic httpx toml第二步把 config.toml 放在项目根目录确保 api_key 和 base_url 填对了。可以先写个最小脚本验证 Key 能不能通# test_connection.py from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keysk-你的Key ) response client.chat.completions.create( modelqwen-max-latest, messages[{role: user, content: 回复 OK 两个字母即可}] ) print(response.choices[0].message.content)跑一下python test_connection.py如果输出 OK说明 Key 和端点都没问题。这一步能帮你排除掉大部分配置错误别跳过。第三步启动 Agent 主循环。OpenManus 的入口是 main.py核心逻辑是一个 while 循环每轮调用 LLM 判断下一步动作如果是工具调用就执行工具、把结果塞回 memory如果是最终答案就退出。简化版长这样# main.py import asyncio from app.agent.react import ReActAgent from app.llm import LLM from app.memory import Memory from tools.calculator import Calculator async def main(): llm LLM() memory Memory() agent ReActAgent( nameMyManus, llmllm, memorymemory, tools[Calculator()] ) task input(请输入任务) result await agent.run(task) print(f\n最终结果{result}) if __name__ __main__: asyncio.run(main())启动后输入一个测试任务比如“计算 (15 27) * 3 再除以 7 的结果”。正常的话你会看到 Agent 先思考、然后调用 calculator 工具、拿到结果后再给出最终答案。整个过程在终端里会打印出 Thought、Action、Observation 三个阶段的日志这就是 ReAct 循环的可视化。如果任务复杂一点比如“帮我写一个快速排序的 Python 实现并验证正确性”Agent 会先规划步骤然后依次调用 python_execute 写代码、跑测试、最后汇总。这时候你能明显感觉到 Planning 和单纯 ReAct 的区别——有计划的时候步骤更清晰没计划的时候 LLM 容易一步到位但可解释性差。5. 本篇常见错排查跑不通的情况我基本都踩过按出现频率排一下。第一种是 401 错误提示 invalid api key。先检查 config.toml 里的 api_key 有没有多余空格再确认 base_url 是不是写成了 https://taotoken.net/api/ 带了尾部斜杠。OpenAI 客户端对 base_url 的处理是直接拼接 /chat/completions尾部斜杠会导致路径变成 //chat/completions有些服务端会拒绝。正确写法就是 https://taotoken.net/api 不带斜杠。第二种是模型返回 tool_calls 为空Agent 一直在思考但不行动。这通常是 Prompt 里工具描述不够清晰或者模型本身对 function calling 支持不好。解决办法有两个换一个工具调用能力更强的模型或者在 next_step prompt 里明确要求“必须调用工具不要直接回答”。我试过把工具描述从“计算数学表达式”改成“当用户问题涉及数字运算时必须调用此工具输入为 Python 表达式字符串”调用率明显上升。第三种是上下文超限报 context length exceeded。Agent 每轮都会把 memory 里的全部消息发给 LLM步数一多就爆了。排查方法是打印每轮请求的 token 数看看是哪一步开始膨胀的。解决思路是给 memory 加截断策略比如只保留最近 N 条消息或者对工具返回结果做摘要压缩。OpenManus 的 max_observe 参数就是干这个的把它调小到 2000 试试。第四种是工具执行报错但 Agent 不停止反复重试同一个失败操作。这是 ReAct 循环缺少失败退出机制导致的。你需要在 Prompt 里加一条规则“如果同一个工具连续失败两次停止调用并报告错误”。或者在代码层面加计数器同一个工具失败超过阈值就强制终止。第五种是异步调用报 RuntimeError: no running event loop。OpenManus 的工具 execute 方法是 async 的如果你在同步代码里直接调就会报这个。确保入口用 asyncio.run() 包起来工具内部如果需要调同步库用 asyncio.to_thread() 包一层。排障的时候建议把日志级别调到 DEBUG把每次发给 LLM 的完整请求和返回都打出来。大部分问题看一遍请求体就能定位。6. 下一步从能跑到好用跑通第一个 Agent 只是起点。接下来你会遇到几个真实问题工具多了之后 LLM 选错工具怎么办、任务长了之后记忆怎么管理、多个 Agent 怎么协作。这些问题没有标准答案但有一些实践方向可以参考。工具选择方面与其让 LLM 在几十个工具里挑不如做分层路由。先用一个轻量模型判断任务类型再路由到对应的工具子集。这样既降低 LLM 的决策难度也减少 token 消耗。工具描述要写得像 API 文档说清楚什么时候用、输入输出是什么、有什么限制。记忆管理方面短期记忆靠上下文窗口长期记忆得靠外部存储。简单做法是把历史任务和结果存进向量库每次新任务先检索相似经验注入 Prompt。复杂一点可以参考 MemGPT 的分层设计把记忆分成核心记忆、工作记忆和归档记忆按需加载。多 Agent 协作是另一个方向。单个 Agent 上下文有限复杂任务拆给多个专职 Agent 各管一摊最后汇总结果。但多 Agent 会引入通信开销和一致性问题不是越多越好。建议先从两三个 Agent 的简单分工开始试比如一个规划、一个执行、一个检查。如果你想把 Agent 接到实际工作流里比如自动处理数据报表、自动写测试用例那 Coding Plan 的额度会更适合长期跑。模型对话页面可以随时对比不同模型在你任务上的表现接入文档里有完整的参数说明和示例代码。先把最小闭环跑通再逐步加工具、换模型、调 Prompt这个顺序不要反。