跳转到内容
Mirobody
快速开始

③ 问答

工具与 Agent 概览

agent、运行期发现的 Python 工具、Skills 与 MCP 端点是怎么拼在一起的

一次对话由四个部件共同完成，本页是它们之间的地图。

Agent

两种运行时：DeepAgent 与 BaseAgent，区别在于 tool loop 在谁那边运行。

工具

就是普通 Python 函数，服务启动时扫描目录发现。

Skills

一批按需读取的说明目录：写给 agent 看的文字，不是它调用的代码。

MCP 端点

/mcp：同一批工具，用 JSON-RPC 2.0 暴露给外部客户端。

两种 agent

Section titled “两种 agent”

Mirobody 内置两种 agent 运行时，每轮对话选其一。两者读取的是同一份工具注册表， 区别在于tool loop 在谁那边运行。

Agent一轮对话的形态
DeepAgentLangChain create_agent 加 deepagents 中间件栈，运行在 PostgreSQL 支撑的虚拟文件系统上，另带一个进程内 JavaScript REPL。循环在这边运行。
BaseAgent不用 LangChain：它把 /mcp 交给 provider，再把结果转发出去，循环在 provider 那边运行。

哪种 agent 应答、各自能用哪些 provider、prompt 怎么配，见 Agent 类型。

运行期发现机制

Section titled “运行期发现机制”

没有注册宏，也没有编译步骤。服务启动时，引擎遍历 MCP_TOOL_DIRS 里列出的每个目录，导入找到的模块，把合规的可调用对象变成 MCP 工具。

  1. 扫描 MCP_TOOL_DIRS 中的目录 子目录、非 .py 文件、以及文件名以 _ 开头的文件都会跳过
  2. 逐个导入模块 导入失败只记一条日志并跳过该模块，服务照常启动
  3. 注册顶层函数 以及类名以 Service 结尾的类的方法
  4. 由类型标注生成 JSON schema str int float bool list[...] dict[...]
  5. 由 docstring 生成描述 首段 → 工具描述；Args: 段 → 各参数的描述

完整规则：

  • 目录来自 MCP_TOOL_DIRS 配置键。发行默认值只有包内那一个 mirobody/agent/tools；把你自己的加上并列在最前面。
  • 文件必须以 .py 结尾。文件名前的下划线表示「这不是工具模块」，__init__.py 以及私有辅助文件正是这样被排除在注册表之外的。
  • 模块级函数会被注册为工具。名字以下划线开头的除外。
  • 类只在类名以 Service 结尾时才纳入考虑。这样的类里，公开方法成为工具；_ 开头的方法、继承自基类的方法、以及从别的模块导入进来的方法都会被忽略。
  • 类可以主动退出：定义一个静态方法 _enabled() -> bool，返回 False 则整个类被跳过， 它的工具一个都不存在。可选集成在没配 API key 时就是这样干净地消失的。

用户身份的注入

Section titled “用户身份的注入”

需要知道「是谁在问」的工具，声明一个 user_info 参数即可。这个参数不会出现在模型看到的 schema 里，而是在函数执行前由服务端按已认证的调用者填入：

{"success": True, "user_id": "...", "session_id": "..."}

也就是说模型既提供不了、也伪造不了身份；工具用 user_info.get("user_id") 取到它， 再把查询限定在该用户范围内。

Skills

Section titled “Skills”

Skills 是「agent 会做什么」的另一半，它不是工具。一个 skill 就是一个目录，里面放一份 SKILL.md：它的 frontmatter 说明什么时候该用它、并被注入每一次提示词，正文只在任务需要 时才被读取。内容进入上下文，而不是发起一次函数调用。见 Agent Skills。

MCP 端点

Section titled “MCP 端点”

同一份注册表以 JSON-RPC 2.0 暴露在 /mcp，因此 Claude Desktop、Cursor 以及任何自定义客户端调用到的， 和你自己的 agent 调用的是同一批工具。tools/list 无需认证，而且是按账号如实回答的： 那两个绑定用户数据的工具，只在该账号确实持有对应类型的数据时才会被列出。

Terminal window
curl -X POST http://localhost:18080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

这个端点是双向的：它对外提供工具，同时 Mirobody 也按用户维护一份外部 MCP 服务器的注册表。 Mirobody MCP Server 讲客户端接入、远程 HTTPS 访问与 OAuth。

工具可见性

Section titled “工具可见性”

每个 agent 有两个配置键用来收窄注册表，后缀取 agent 名字的大写形式，随包两个 agent 分别对应 DEEP 与 BASE：

配置键作用
ALLOWED_TOOLS_{NAME}白名单。一旦设置，就只提供这些工具。
DISALLOWED_TOOLS_{NAME}黑名单。在白名单之后生效，因此它总是说了算。

两个都留空（发行版 config.yaml 就是这样），该 agent 就能用上全部被发现的工具。

下一步

Section titled “下一步”
内置工具

开箱即有的那些，逐个参数说明

添加自定义工具

丢一个 .py 文件进去，重启

Mirobody MCP Server

接 Claude、Cursor 与远程客户端

配置

MCP_TOOL_DIRS、provider 密钥，以及其它一切