Monstrum Agent

前置知识： 阅读本文前建议先了解 核心概念 中 Bot vs Agent vs LLM 的区别。

Monstrum Agent 让你在本地环境运行一个轻量程序，通过 WebSocket 安全连接到 Monstrum 平台，将本地工具（MCP 服务器、自定义函数、Shell 命令等）桥接到平台。平台上的 Bot 可以像使用其他 Resource 一样调用这些工具——所有调用都经过完整的权限校验和审计。

---

概述

Agent 是什么

Agent 是 Monstrum 平台中的独立实体。它不是 Resource，也不是 Bot——它是连接你的本地环境与平台的桥梁。

核心特点：

• 本地运行：Agent 在你的机器上运行（笔记本、开发服务器、内网机器等），不占用平台资源
• WebSocket 连接：Agent 主动连接平台，无需暴露本地端口或配置防火墙
• 自动注册工具：Agent 连接后，自动将本地工具注册到平台，对应的 Resource 自动出现在资源列表中
• 权限不降级：通过 Agent 执行的工具调用，与云端执行遵循完全相同的权限模型（Pre-LLM 过滤 + Post-LLM 校验）
• 审计可追溯：每次通过 Agent 执行的工具调用都记录在审计日志中，标记执行位置为 agent:{name}

工作原理

你的本地环境                              Monstrum 平台
┌─────────────────────┐                ┌──────────────────────┐
│  monstrum-agent     │   WebSocket    │                      │
│  ┌───────────────┐  │ ◄────────────► │  Agent 连接管理器     │
│  │ MCP 服务器    │  │                │       │              │
│  │ @tool 函数    │  │                │  ┌────▼─────┐        │
│  │ Shell 命令    │  │                │  │ Resource │        │
│  │ .mst 插件     │  │                │  │ (自动创建) │        │
│  └───────────────┘  │                │  └────┬─────┘        │
│                     │                │       │              │
└─────────────────────┘                │  ┌────▼─────┐        │
                                       │  │   Bot    │        │
                                       │  │ (绑定使用) │        │
                                       │  └──────────┘        │
                                       └──────────────────────┘

当 Bot 调用 Agent 工具时，完整流程：

1. Bot 对话中触发工具调用
2. 平台完成 Pre-LLM 可见性过滤和 Post-LLM 参数校验
3. 平台通过 WebSocket 将工具调用请求发送到你本地的 Agent
4. Agent 在本地环境执行工具
5. 执行结果通过 WebSocket 返回平台
6. 平台将结果交给 Bot，记录审计日志

与直接创建 Resource 的区别

	手动创建 Resource	Agent 自动创建
创建方式	在页面手动配置	Agent 连接后自动创建
凭据管理	手动添加凭据	不需要——Agent 本身就在可信环境中
工具执行	平台云端执行	Agent 在本地执行
适用场景	公网可达的服务	本地/内网工具、开发环境
Resource 来源标记	user	agent:{name}

---

安装 monstrum-agent

方式一：一键安装（推荐）

平台提供一键安装脚本，创建 Agent 后会显示完整的安装命令。脚本会自动完成：

• 检测 Python 环境（需要 Python 3.9+）
• 从 GitHub Release 下载并安装 monstrum-sdk 包
• 在 ~/.monstrum/agent.yaml 写入 Agent 配置（平台地址 + Agent Key）
• 设置 PATH（如需要）
• 自动启动 Agent

安装命令的格式：

curl -fsSL https://{platform_url}/api/public/agent/install.sh | sh -s -- "{agent_key}" --url "{platform_url}"

你不需要手动拼接这个命令——创建 Agent 后页面会自动生成。

脚本支持以下选项：

选项	说明
--url <platform_url>	指定平台地址（脚本会自动填入）
--name <agent_name>	设置本地显示名称（可选）
--version <version>	安装指定版本（默认最新版）
--no-start	仅安装不启动

方式二：手动安装

pip install monstrum-sdk

安装完成后，monstrum-agent 命令即可用。运行 monstrum-agent --version 验证安装。

---

创建 Agent

操作步骤

1. 在左侧导航栏点击 Agent，进入 Agent 管理页面
2. 点击页面右上角的 新建 Agent 按钮
3. 在弹出的对话框中填写 Agent 名称
   • 名称在工作区内唯一
   • 建议使用能标识环境的名称，如 my-laptop、dev-server、office-workstation
4. 点击确定

Agent Key

创建成功后，页面会弹出安装引导对话框，显示以下信息：

• Agent Key：以 ak_ 开头的认证密钥
• 安装命令：一键安装脚本命令
• 启动命令：安装完成后的启动命令

重要提示： Agent Key 仅在创建时显示一次。请立即复制保存。如果丢失，需要重新生成 Key（旧 Key 会立即失效）。

Agent Key 使用加密安全的随机数生成（48 个十六进制字符）。每个 Agent 独立的 Key，互不影响。连接建立后 Key 仅用于初始握手，不在后续通信中传输。

---

连接 Agent

使用一键安装

如果你使用了一键安装脚本，Agent 会在安装完成后自动启动并连接到平台。

手动连接

如果你手动安装了 monstrum-sdk，需要先创建配置文件，然后启动 Agent。

配置文件 ~/.monstrum/agent.yaml：

# Monstrum Agent Configuration
platform_url: "https://your-platform-url.com"
agent_key: "ak_your_agent_key_here"

# 内置工具（默认全部启用）
builtins:
  system_info: true
  file_ops: true
  shell_exec: true
  sandbox: true
  browser: true

启动 Agent：

monstrum-agent start

也可以指定配置文件路径：

monstrum-agent start -c ./my-project/agent.yaml

连接成功后

Agent 连接成功后，你会观察到：

1. 终端输出：Agent 打印连接成功信息和注册的工具列表
2. 平台状态更新：Agent 管理页面中，该 Agent 状态变为在线（绿色圆点）
3. 自动创建 Resource：Agent 注册的工具按来源分组，每组自动创建一个 Resource
4. Resource 出现在资源列表：在资源管理页面可以看到 Agent 自动创建的 Resource

连接生命周期

Agent 与平台之间维持长连接，通过心跳机制保持活性：

• 平台每 30 秒发送一次心跳探测（ping），Agent 回复 pong
• 如果 Agent 超过 40 秒未响应，平台判定连接断开
• Agent 断开后，其注册的工具从平台移除（Resource 仍保留，状态变为”已断开”）
• Agent 重新连接后，工具自动恢复注册

---

工具注册

工具来源与分组

Agent 可以注册多种来源的工具，按来源自动分组，每组创建一个独立的 Resource：

来源	说明	Resource 类型	Resource 名称示例
@tool 装饰器函数	Python 自定义工具	Monstrum Agent	[my-laptop] agent
MCP 服务器	代理本地/内网 MCP	MCP	[my-laptop] MCP: http://localhost:8080
.mst 插件	Monstrum 插件包	对应插件类型	[my-laptop] Plugin: github

这种分组设计的好处：

• 不同来源的工具独立管理权限
• Bot 可以绑定 Agent 的部分工具组，而非全部
• MCP 服务器的工具与自定义函数分开治理

工具的动态性

Agent 注册的工具属于动态发现模式（参见 核心概念 中的工具发现模式）：

• 工具列表在 Agent 连接时动态注册，断开时自动移除
• Bot 绑定时使用工具名勾选或 glob 模式（如 list_*、run_*）控制可用工具
• 工具定义（名称、描述、参数 Schema）由 Agent 侧决定，平台不修改

工具 vs Resource 的持久性

与 MCP Resource 不同，Agent 注册的工具不持久化到数据库——它们仅存在于 Agent 连接期间。Agent 断开后，工具从平台内存中移除；重新连接后，工具重新注册。

Resource 本身（名称、绑定关系、权限配置）是持久化的，不会因 Agent 断开而丢失。

---

绑定到 Bot

Agent 注册工具后，对应的 Resource 自动出现在资源列表中。绑定过程与其他资源类型完全一致。

绑定步骤

1. 进入 Bot 详情页，切换到 资源配置 Tab
2. 点击 绑定资源
3. 在资源列表中找到 Agent 创建的 Resource（通常以 [agent_name] 开头）
4. 选择允许的工具：
   • 勾选模式：从已注册的工具中逐个勾选
   • glob 模式：使用通配符（如 read_*、*_file）匹配工具名
5. 配置权限约束（详见下方权限维度）
6. 保存绑定

注意： Agent 创建的 Resource 不需要选择凭据。工具执行由 Agent 在本地完成，不需要平台侧的凭据解密。

权限维度

Monstrum Agent 类型的 Resource 支持以下权限维度：

维度	说明	示例
tools	允许调用的工具名	run_shell、read_file、list_*
paths	允许访问的文件路径	/home/user/project/*、/var/log/*
commands	允许执行的命令	ls *、git *、npm *
images	允许使用的容器镜像	python:3.*、node:*

使用 glob 模式匹配。未配置的维度表示不限制。

如果 Agent 同时注册了 MCP 类型的工具（代理 MCP 服务器），对应 Resource 的权限维度遵循 MCP 类型规则（tools 维度）。详见 资源与凭据 中 MCP 资源章节。

如果已创建角色模板（详见 角色与权限），可以在绑定时选择角色快速应用预设的权限配置。

---

执行流程

当 Bot 对话中调用 Agent 的工具时，完整的执行链路：

1. Pre-LLM：工具可见性过滤

Bot 开始推理之前，平台根据资源绑定过滤工具列表。只有绑定中明确允许的 Agent 工具才会出现在 LLM 的工具列表中。未授权的工具对 LLM 完全不可见。

2. LLM 推理

LLM 基于可见的工具列表和用户消息，决定是否调用工具以及调用哪个工具。

3. Post-LLM：参数级权限校验

LLM 返回工具调用后，平台校验调用参数是否在权限约束范围内（如 paths、commands 维度）。参数越界则拒绝请求。

4. Agent 路由

权限校验通过后，平台检查 Resource 关联的 Agent 是否在线：

• Agent 在线 → 通过 WebSocket 转发到 Agent
• Agent 离线 → 返回”Agent 未连接”的错误

5. 本地执行与结果返回

Agent 在本地环境执行工具，将结果通过 WebSocket 返回平台。平台将结果交给 Bot 并记录审计日志。

超时处理

工具调用有 30 秒的默认超时。如果 Agent 在超时期限内未返回结果，平台向 Bot 返回超时错误。如果工具需要更长执行时间，可以在工具实现中考虑异步模式。

---

Agent 管理

Agent 列表

在左侧导航栏点击 Agent 进入管理页面。列表中每个 Agent 显示：

列	说明
状态	在线（绿色圆点）或离线（灰色圆点）
名称	Agent 名称（创建时设定）
Agent Key	脱敏显示（前 8 位 + … + 后 4 位），可点击复制完整 Key
资源数	Agent 自动创建的 Resource 数量
最后在线	Agent 最后一次连接或心跳的时间

启用/禁用 Agent

在操作列中通过开关切换 Agent 的启用状态：

• 启用：Agent 可以连接平台
• 禁用：Agent 无法连接。如果当前已连接，下次心跳检测时会断开

重新生成 Agent Key

如果 Agent Key 泄露或出于安全策略需要轮换：

1. 在 Agent 操作列中点击重新生成图标
2. 确认操作
3. 新 Key 生成后显示在安装引导对话框中

注意： 旧 Key 立即失效。你需要更新本地 Agent 配置文件中的 agent_key 字段并重新启动 Agent。

删除 Agent

在 Agent 操作列中点击删除图标并确认。删除后：

• Agent 的 Key 失效，无法再连接
• Agent 自动创建的 Resource 状态变为”已断开”
• 已有的 Bot 绑定关系保留，但工具调用会因 Agent 离线而失败
• 审计日志中的历史记录不受影响

---

一键安装脚本详解

平台提供的一键安装脚本执行以下步骤：

1. 环境检测：检查 Python 3.9+ 是否可用
2. 下载安装包：从 GitHub Release 下载最新的 monstrum-sdk wheel 包
3. 安装依赖：通过 pip 安装 monstrum-sdk[agent]（包含 Agent 运行所需的额外依赖）
4. 写入配置：在 ~/.monstrum/agent.yaml 写入平台地址和 Agent Key
5. PATH 处理：如果 monstrum-agent 命令不在 PATH 中，提示添加方法
6. 自动启动：默认安装完成后自动启动 Agent（可通过 --no-start 跳过）

如果配置文件 ~/.monstrum/agent.yaml 已存在，脚本会备份原文件为 agent.yaml.bak，仅更新 agent_key 字段，保留其他配置不变。

再次运行安装脚本会自动升级到最新版本，也可以通过 --version 参数指定版本。

---

常见用法

桥接本地开发工具

将本地开发环境中的工具注册到平台，让 Bot 参与开发流程：

• 代码检查：注册 linter、formatter、type checker，Bot 可以直接检查代码质量
• 构建和测试：注册 npm run build、pytest 等命令，Bot 可以触发构建和运行测试
• 文件和 Git 操作：注册文件读写和 Git 命令工具，Bot 可以查看变更、创建分支

使用 commands 和 paths 权限维度限制 Bot 可以执行的命令和访问的文件路径。

接入现有 MCP 服务器

如果你在本地或内网已经运行了 MCP 服务器，但无法从公网访问，可以通过 Agent 作为代理接入：

1. Agent 在本地启动后，连接到本地/内网的 MCP 服务器
2. Agent 获取 MCP 服务器的工具列表
3. Agent 将这些工具以 MCP 类型注册到平台
4. 平台上的 Bot 通过 Agent 间接调用 MCP 服务器的工具

优势：不需要将 MCP 服务器暴露到公网，不需要在平台上配置凭据，可同时代理多个 MCP 服务器。

自定义 @tool 函数

使用 Python 装饰器定义自定义工具函数，Agent 会自动发现并注册。典型场景：

• 数据库查询：封装内部数据库查询，Bot 可以查询报表数据
• 内部 API 调用：封装公司内部 API，Bot 可以查询工单、发送通知
• 特定业务逻辑：将业务操作封装为工具，如”生成报告”、“检查库存”

多 Agent 协作

你可以在不同环境中运行多个 Agent，每个 Agent 注册不同的工具集：

• 开发环境 Agent：注册代码工具（编辑器、编译器、测试框架）
• 运维环境 Agent：注册运维工具（监控查询、日志查看、服务管理）
• 数据环境 Agent：注册数据工具（数据库查询、ETL 操作、报表生成）

不同的 Bot 绑定不同 Agent 的 Resource，实现职责分离。

---

安全考量

Agent Key 保护

• Agent Key 等同于该 Agent 的身份凭证，请妥善保管
• 不要将 Agent Key 提交到版本控制系统
• 建议将配置文件权限设置为 600（仅所有者可读写）
• 如果怀疑 Key 泄露，立即在平台上重新生成

工具权限最小化

• 为 Bot 绑定 Agent Resource 时，只勾选必要的工具
• 善用 paths 和 commands 维度限制操作范围
• 避免注册过于宽泛的 Shell 执行工具而不设任何约束

网络安全

• Agent 到平台的 WebSocket 连接使用 WSS（TLS 加密）
• Agent 仅维护出站连接，不需要开放本地端口
• 工具调用的凭据（如有）在每次调用时由平台解密传递，Agent 不缓存

审计追踪

所有通过 Agent 执行的工具调用都记录在审计日志中，标记执行位置为 agent:{agent_name}。你可以在数据中心的日志审计中按执行位置筛选查看。

---

常见问题

Agent 连接后没有工具注册

可能原因： Agent 配置中未启用任何内置工具；自定义 @tool 函数未被正确发现；MCP 服务器地址不可达。

排查方法： 检查 Agent 终端输出中是否有工具发现相关日志；检查 ~/.monstrum/agent.yaml 中 builtins 配置；确认 MCP 服务器正在运行且地址正确。

Agent 频繁断线

可能原因： 网络连接不稳定；平台地址配置错误；本地防火墙阻断 WebSocket 连接。

排查方法： 确认 agent.yaml 中 platform_url 配置正确；检查是否有代理或防火墙阻断 WebSocket 连接（WSS 使用 443 端口）。Agent 断线后会自动尝试重连。

工具调用超时

可能原因： 本地工具执行时间超过默认 30 秒超时；网络延迟过高；本地工具执行阻塞。

排查方法： 检查本地工具执行时间，考虑优化或拆分长时间操作；在 Agent 终端查看工具执行日志。

重新生成 Key 后 Agent 无法连接

复制新生成的 Agent Key，编辑本地配置文件 ~/.monstrum/agent.yaml 更新 agent_key 字段，然后重启 Agent：monstrum-agent start。

Bot 调用 Agent 工具提示”Agent 未连接”

在 Agent 管理页面查看 Agent 状态是否为在线；检查本地 Agent 进程是否正在运行；确认 Agent 的启用开关是否打开。

如何更新 Agent

再次运行安装命令即可自动升级到最新版本并保留现有配置。也可以手动更新：pip install --upgrade monstrum-sdk，更新后重启 Agent。

---

下一步

• 资源与凭据 — 了解 Resource 管理和权限配置的完整指南
• Bot 管理 — 创建 Bot 并绑定 Agent 注册的 Resource
• 角色与权限 — 使用角色模板快速配置 Agent 工具的权限