infiAgent 自定义工具开发教程：30分钟给你的Agent加上专属动态工具-平芜编程栈

人工智能
大模型
AI Agent
Agent 框架
多智能体
AI 技能/插件

【免费下载链接】infiAgent

Build your own Cowork, AI Scientist and other SoTA Agents just by editing config files. Support anthropic skills. An infinite-horizon agent framework designed for long-running, complex tasks.

项目地址：https://gitcode.com/gh_mirrors/inf/infiAgent

点击查看免费下载

想用 infiAgent 构建 AI 智能体，却发现内置工具无法满足你的业务需求？这篇infiAgent 自定义工具开发教程带你从零上手：只需放一个 Python 文件、写几行 YAML 声明，就能为你的 Agent 加上专属动态工具（Dynamic Tool）。无需修改框架源码，30 分钟即可完成一次完整的外挂工具扩展。

infiAgent（又名 MLA V3 / Multi-Level Agent）是一个面向无限时长运行的 AI 智能体框架，你只需编辑配置文件即可构建强大的通用或垂类智能体。它的工具系统天然支持"外挂"——通过tools_library目录自动扫描加载你的自定义 Python 工具，让模型按需调用。

📖 本教程对应的官方完整说明见：docs/SDK_GUIDE.md（第 14 章"如何外挂自己的动态工具"）

为什么需要"自定义动态工具"

infiAgent 已内置文件读写、网络搜索、文档解析等数十个工具，但当你有如下需求时，仅靠内置工具就不够了：

对接你自己的业务 API（如内部订单系统、客服工单）
调用专有硬件 / 私有服务
封装一段可复用的复杂逻辑，让模型像调用普通工具一样使用它

好消息是：infiAgent 的工具扩展完全声明式 + 文件式，不侵入框架核心。整个流程只有三件"零件"，下面逐个拆解。

一图看懂：infiAgent 自定义工具的三大件

外挂一个自定义工具，本质上是补齐三个环节：

环节	作用	所在文件
① Python 工具类	工具的真正实现	`tools_library/<工具名>/<工具名>.py`
② 工具 schema 声明	告诉模型这个工具"长什么样、怎么用"	`level_0_tools.yaml`
③ Agent 授权可见	让某个 Agent真的能调到它	`level_3_agents.yaml`

三者缺一不可：只放.py不声明，模型根本不知道它的存在；只声明不授权，Agent 也调用不到。

第一步：把 Python 工具文件放进 tools_library

动态工具的默认根目录是~/mla_v3/tools_library/。加载规则如下（来自 tool_server_lite/registry.py）：

tools_library/下每个一级子目录代表一个工具
每个工具目录顶层必须且只能有一个.py文件作为主工具文件
该.py里必须有一个公开工具类，并实现execute(...)或execute_async(...)
工具名优先取类属性name，否则回退为文件名
工具名不能与内置工具重名

推荐目录结构（以"回显文本"工具echo_text为例）：

~/mla_v3/tools_library/ └── echo_text/ └── echo_text.py

一个最小可运行的工具类，只需继承 tool_server_lite/tools/file_tools.py 中的BaseTool：

from tool_server_lite.tools.file_tools import BaseTool, get_abs_path class EchoTextTool(BaseTool): name = "echo_text" def execute(self, task_id: str, parameters: dict) -> dict: text = str(parameters.get("text") or "") output_path = str(parameters.get("output_path") or "").strip() if output_path: abs_path = get_abs_path(task_id, output_path) abs_path.parent.mkdir(parents=True, exist_ok=True) abs_path.write_text(text, encoding="utf-8") return {"status": "success", "output": text, "error": ""}

💡两个要点：

task_id就是当前 task 的 workspace 根目录，所有相对路径都应通过get_abs_path(task_id, rel)转为绝对路径
辅助代码建议放进子目录，避免顶层出现多个.py（否则加载失败）

第二步：在 level_0_tools.yaml 里声明工具 schema

光有实现还不够——只有声明了 schema，模型才知道这个工具存在。把下面片段加进你的 agent 系统配置 config/agent_library/OpenCowork/level_0_tools.yaml：

tools: echo_text: level: 0 type: tool_call_agent name: "echo_text" description: "回显文本，并可选写入当前 task 工作目录中的文件。" parameters: type: "object" properties: text: type: "string" description: "要输出的文本。" output_path: type: "string" description: "可选。相对于当前 task 工作目录的输出文件路径。" required: ["text"]

这里的name必须与.py里类的name、以及这里的工具 key三者完全一致，这是新手最常出错的点。type固定为tool_call_agent（表示由工具运行时直接执行，区别于llm_call_agent子智能体）。

第三步：让 Agent 在 level_3_agents.yaml 里"看见"它

最后一步，让具体的 Agent 能够调用该工具。打开 config/agent_library/OpenCowork/level_3_agents.yaml，你有两种授权方式：

方式 A：显式available_tools列表—— 逐个列出，把echo_text加进去：

tools: alpha_agent: level: 3 type: llm_call_agent name: "alpha_agent" available_tools: - file_read - file_write - echo_text # 👈 新增你的自定义工具 - final_output

方式 B：按 level 自动收集—— 如果你的 Agent 用的是available_tool_level，那么只要工具在level_0_tools.yaml里是level: 0，该 Agent 会自动包含所有 level 0 工具，无需逐个列举。

第四步：验证与刷新（fresh）

新增工具后的生效规则：

新启动的 task：通常直接可见，无需额外操作
已在运行中的 task：需要调用fresh()重新加载工具注册表

在 SDK 调用场景下，刷新命令形如：

agent.fresh( task_id="/path/to/my_agent_project/tasks/refactor_task", reason="installed new custom tool echo_text", )

对于使用 Docker Web UI 或 CLI 的用户，最稳妥的做法是新增工具后重新启动任务，即可让新工具立即生效。

最容易踩的 5 个坑（工具"写了却调不到"自查清单）

如果工具调用不到，按顺序排查：

✅ 工具目录顶层是否只有一个.py？多个会直接加载失败
✅ 工具类是否为公开类且实现了execute或execute_async？
✅ 工具name（类属性 / YAML key / YAMLname）三者是否一致？
✅ 目标 Agent是否真的被授权看到该工具（available_tools或 level 匹配）？
✅ 运行中的 task是否已fresh()或重启？

⚠️ 另注意：工具名不能与内置工具重名（如file_read、web_search），否则会冲突。

参考文件清单

官方 SDK 完整文档（含外挂工具章节）：docs/SDK_GUIDE.md
工具运行时注册中心（自定义工具扫描逻辑）：tool_server_lite/registry.py
工具基类BaseTool与get_abs_path定义：tool_server_lite/tools/file_tools.py
工具 schema 声明样例：config/agent_library/OpenCowork/level_0_tools.yaml
Agent 工具授权样例：config/agent_library/OpenCowork/level_3_agents.yaml
内置动态工具目录范例（每个子目录一个工具）：apps/cheapclaw/tools_library/

🎉 到这里，你已经掌握了infiAgent 自定义工具开发的完整闭环：一个 Python 类 + 一段 YAML schema + 一行授权，即可让你的 Agent 拥有别人没有的"超能力"。试着把你的第一个业务 API 封装成工具吧！

人工智能
大模型
AI Agent
Agent 框架
多智能体
AI 技能/插件

【免费下载链接】infiAgent

Build your own Cowork, AI Scientist and other SoTA Agents just by editing config files. Support anthropic skills. An infinite-horizon agent framework designed for long-running, complex tasks.

项目地址：https://gitcode.com/gh_mirrors/inf/infiAgent

点击查看免费下载