无影 Agent 开发套件 AgentBay：MCP工具汇总

工具能力

工具名称

工具描述

参数示例

创建沙箱环境

create_sandbox

创建一个新的AgentBay沙箱并返回其ID。

{
  "type": "object",
  "properties": {},
  "required": []
}

获取沙箱访问URL

get_sandbox_url

获取无影MCP运行时URL的命令，供用户访问该运行时使用。每次获取的URL仅单次有效，使用后立即失效。

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

全屏截图并分享

system_screenshot

捕获当前屏幕的全屏截图，并返回一个可共享的URL。截图会自动被处理并安全存储。出于安全考虑，生成的URL将在64分钟后过期。

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

释放沙箱资源

kill_sandbox

任务完成后释放资源。

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

执行Shell命令

shell

执行 shell 命令并返回输出或错误。

{
  "inputSchema": {
    "properties": {
      "command": {
        "description": "客户端输入的命令",
        "type": "string"
      },
      "timeout_ms": {
        "default": 1000,
        "description": "命令执行超时时间（单位：毫秒）。如果未指定，默认值（例如 1000 毫秒）",
        "type": "integer"
      }
    },
    "required": ["command", "timeout_ms"],
    "type": "object"
  }
}

关闭浏览器页面

browser_close

关闭浏览器页面

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

调整浏览器窗口

browser_resize

调整浏览器窗口大小

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "width": {
        "type": "number",
        "description": "浏览器窗口的宽度"
      },
      "height": {
        "type": "number",
        "description": "浏览器窗口的高度"
      }
    },
    "required": ["width", "height"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

获取控制台消息

browser_console_messages

返回所有控制台消息

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

处理弹出对话框

browser_handle_dialog

处理对话框

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "accept": {
        "type": "boolean",
        "description": "是否接受对话框。"
      },
      "promptText": {
        "type": "string",
        "description": "在提示对话框中的提示文本。"
      }
    },
    "required": ["accept"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器上传文件

browser_file_upload

上传一个或多个文件

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "paths": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "要上传的文件的绝对路径。可以是单个文件或多个文件。"
      }
    },
    "required": ["paths"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

安装浏览器

browser_install

安装配置中指定的浏览器。如果收到浏览器未安装的错误，请调用此工具。

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器按键操作

browser_press_key

在键盘上按下按键

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "要按下的按键名称或生成的字符，例如 `ArrowLeft` 或 `a`"
      }
    },
    "required": ["key"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器导航URL

browser_navigate

导航到 URL

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "要导航到的 URL"
      }
    },
    "required": ["url"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器返回上一页

browser_navigate_back

返回到上一页

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器前进下一页

browser_navigate_forward

前进到下一页

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

获取网络请求

browser_network_requests

返回自加载页面以来的所有网络请求

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

页面截图

browser_take_screenshot

截取当前页面的屏幕截图。不能基于截图执行操作，需使用 browser_snapshot 进行操作。

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "raw": {
        "type": "boolean",
        "description": "是否以 PNG 格式返回无压缩数据。默认值为 false，返回 JPEG 图像。"
      },
      "filename": {
        "type": "string",
        "description": "保存截图的文件名。如果未指定，默认为 `page-{timestamp}.{png|jpeg}`。"
      },
      "element": {
        "type": "string",
        "description": "用于获取截图元素权限的人类可读元素描述。如果未提供，将截取视口。如果提供 element，必须同时提供 ref。"
      },
      "ref": {
        "type": "string",
        "description": "页面快照中的目标元素引用。如果未提供，将截取视口。如果提供 ref，必须同时提供 element。"
      }
    },
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

捕获页面快照

browser_snapshot

捕获当前页面的可访问性快照。

{
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器点击操作

browser_click

在网页上执行点击操作

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "用于获取与元素交互权限的人类可读元素描述"
      },
      "ref": {
        "type": "string",
        "description": "页面快照中的目标元素引用"
      }
    },
    "required": ["element", "ref"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器元素拖拽

browser_drag

在两个元素之间执行拖放操作

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "startElement": {
        "type": "string",
        "description": "用于获取与源元素交互权限的人类可读元素描述"
      },
      "startRef": {
        "type": "string",
        "description": "页面快照中的源元素引用"
      },
      "endElement": {
        "type": "string",
        "description": "用于获取与目标元素交互权限的人类可读元素描述"
      },
      "endRef": {
        "type": "string",
        "description": "页面快照中的目标元素引用"
      }
    },
    "required": ["startElement", "startRef", "endElement", "endRef"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器元素悬停

browser_hover

鼠标悬停在页面元素上

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "用于获取与元素交互权限的人类可读元素描述"
      },
      "ref": {
        "type": "string",
        "description": "页面快照中的目标元素引用"
      }
    },
    "required": ["element", "ref"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

浏览器输入文本

browser_type

在可编辑元素中输入文本

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "用于获取与元素交互权限的人类可读元素描述"
      },
      "ref": {
        "type": "string",
        "description": "页面快照中的目标元素引用"
      },
      "text": {
        "type": "string",
        "description": "要输入到元素中的文本"
      },
      "submit": {
        "type": "boolean",
        "description": "是否提交输入的文本（输入后按回车）"
      },
      "slowly": {
        "type": "boolean",
        "description": "是否逐个字符输入。这对于触发页面中的按键处理程序很有用。默认情况下整个文本一次性填充。"
      }
    },
    "required": ["element", "ref", "text"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

下拉菜单选择

browser_select_option

在下拉菜单中选择一个选项

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "element": {
        "type": "string",
        "description": "用于获取与元素交互权限的人类可读元素描述"
      },
      "ref": {
        "type": "string",
        "description": "页面快照中的目标元素引用"
      },
      "values": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "要在下拉菜单中选择的值数组。可以是单个值或多个值。"
      }
    },
    "required": ["element", "ref", "values"],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

等待页面内容

browser_wait_for

等待文本出现或消失或指定时间过去

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "time": {
        "type": "number",
        "description": "等待的时间（秒）"
      },
      "text": {
        "type": "string",
        "description": "要等待的文本"
      },
      "textGone": {
        "type": "string",
        "description": "要等待消失的文本"
      }
    },
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
}

创建目录

create_directory

创建一个新目录或确保目录存在。可以在一次操作中创建多个嵌套目录。如果目录已存在，此操作将静默成功。非常适合设置项目所需的目录结构或确保所需路径存在。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "要创建的目录路径。",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

基于行编辑文件

edit_file

对文本文件进行基于行的编辑。每次编辑会用新内容替换精确的行序列。返回 git 样式的差异以显示所做的更改。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "dryRun": {
        "default": false,
        "description": "使用 git 样式的差异格式预览更改",
        "type": "boolean"
      },
      "edits": {
        "items": {
          "properties": {
            "newText": {
              "description": "要替换的新文本",
              "type": "string"
            },
            "oldText": {
              "description": "要搜索的文本 - 必须完全匹配",
              "type": "string"
            }
          },
          "required": ["oldText", "newText"],
          "type": "object"
        },
        "type": "array"
      },
      "path": {
        "description": "要编辑的文件路径。",
        "type": "string"
      }
    },
    "required": ["path", "edits"],
    "type": "object"
  }
}

获取文件元数据

get_file_info

检索文件或目录的详细元数据。返回包括大小、创建时间、最后修改时间、权限和类型的综合信息。此工具非常适合在不读取实际内容的情况下了解文件特性。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "要检查的文件或目录路径。",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

读取文件内容

read_file

从文件系统读取文件的内容。可以指定一个可选的 'offset'（以字节为单位）来从特定位置开始读取，以及一个可选的 'length'（以字节为单位）来限制要读取的字节数。如果 'length' 被省略或为 0，文件将读取到末尾。处理各种文本编码，并在文件无法读取时提供详细的错误信息。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "length": {
        "description": "要读取的字节数。如果省略或为 0，读取到文件末尾。",
        "minimum": 0,
        "type": "integer"
      },
      "offset": {
        "default": 0,
        "description": "从这个字节偏移量开始读取。",
        "minimum": 0,
        "type": "integer"
      },
      "path": {
        "description": "要读取的文件路径。",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

批量读取文件

read_multiple_files

同时读取多个文件的内容。这比逐个读取文件更高效，当你需要分析或比较多个文件时。每个文件的内容会以其路径作为参考返回。单个文件读取失败不会停止整个操作。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "paths": {
        "description": "要读取的文件路径数组。",
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": ["paths"],
    "type": "object"
  }
}

列出目录文件

list_directory

获取指定路径中所有文件和目录的详细列表。结果通过 [FILE] 和 [DIR] 前缀清楚地区分文件和目录。此工具对于了解目录结构和查找特定文件非常实用。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "path": {
        "description": "要列出的目录路径。",
        "type": "string"
      }
    },
    "required": ["path"],
    "type": "object"
  }
}

移动或重命名文件

move_file

移动或重命名文件和目录。可以在一次操作中将文件移动到不同目录并重命名。如果目标已存在，操作将失败。可以在不同目录之间工作，并可用于在同一目录内进行简单重命名。源和目标都必须在允许的目录中。

{
  "inputSchema": {
    "properties": {
      "destination": {
        "description": "目标文件或目录路径。",
        "type": "string"
      },
      "source": {
        "description": "源文件或目录路径。",
        "type": "string"
      }
    },
    "required": ["source", "destination"],
    "type": "object"
  }
}

递归搜索文件

search_files

递归搜索匹配模式的文件和目录。从起始路径搜索所有子目录。搜索区分大小写并匹配部分名称。返回所有匹配项的完整路径。非常适合在不知道确切位置时查找文件。仅在允许的目录中搜索。

{
  "inputSchema": {
    "properties": {
      "excludePatterns": {
        "default": [],
        "description": "要排除的模式（可选）。",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "path": {
        "description": "要开始搜索的目录路径。",
        "type": "string"
      },
      "pattern": {
        "description": "要匹配的模式。",
        "type": "string"
      }
    },
    "required": ["path", "pattern"],
    "type": "object"
  }
}

写入文件内容

write_file

创建一个新文件或写入现有文件的内容。可以选择完全覆盖文件或通过指定 mode参数追加到文件末尾。使用 overwrite 模式（默认）在写入前清除文件，或使用 append模式将内容添加到文件末尾。处理带适当编码的文本内容。仅在允许的目录中工作。

{
  "inputSchema": {
    "properties": {
      "content": {
        "description": "要写入的内容。",
        "type": "string"
      },
      "mode": {
        "default": "overwrite",
        "description": "写入模式：'overwrite' 清除文件，'append' 添加到文件末尾。",
        "enum": ["overwrite", "append"],
        "type": "string"
      },
      "path": {
        "description": "要写入的文件路径。",
        "type": "string"
      }
    },
    "required": ["path", "content"],
    "type": "object"
  }
}

同步执行页面操作

page_use_act

在当前网页上执行一个或多个操作，并阻塞直至所有操作完成。

该方法通过当前 Agent 立即执行所提供的操作，并在整个操作序列完成后返回最终结果。它能够处理单个交互，也支持一系列连续操作。

{
  "type": "object",
  "title": "page_use_actArguments",
  "required": [
    "sandbox_id",
    "action"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "variables": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object",
      "title": "Variables"
    },
    "action": {
      "type": "string",
      "title": "Action"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "type": "boolean",
      "title": "Iframe"
    },
    "timeout_ms": {
      "type": "integer",
      "title": "Timeout Ms"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

网页截图

page_use_screenshot

捕获当前网页的屏幕截图。

该工具提供灵活的截图功能，支持整页截图、指定区域裁剪以及图像质量设置。结果以数据 URL 的形式返回（如data:image/png;base64等），可直接用于前端应用中。

{
  "type": "object",
  "title": "page_use_screenshotArguments",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "full_page": {
      "default": true,
      "type": "boolean",
      "title": "Full Page"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "clip": {
      "additionalProperties": {
        "type": "number"
      },
      "type": "object",
      "title": "Clip"
    },
    "timeout": {
      "type": "integer",
      "title": "Timeout"
    },
    "quality": {
      "default": 80,
      "type": "integer",
      "title": "Quality"
    }
  },
  "required": [
    "sandbox_id"
  ]
}

关闭浏览器会话

page_use_close_session

关闭当前浏览器代理会话。

这将终止由代理管理的浏览器进程，并释放相关资源。

{
  "type": "object",
  "title": "page_use_close_sessionArguments",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    }
  },
  "required": [
    "sandbox_id"
  ]
}

查找可交互元素

page_use_observe

识别并定位可交互的用户界面元素。

该工具可帮助你发现和描述可进行交互的元素（例如按钮或输入框），以便在后续操作中使用。

当需要查找可操作元素时，使用observe工具。

若需提取结构化数据或文本内容，则应优先使用extract工具。

{
  "type": "object",
  "title": "page_use_observeArguments",
  "required": [
    "sandbox_id",
    "instruction"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "instruction": {
      "type": "string",
      "title": "Instruction"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "default": false,
      "type": "boolean",
      "title": "Iframe"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

异步执行页面操作

page_use_act_async

在当前网页上异步开始执行一个或多个操作，并返回一个用于进度轮询的 task_id。

与page_use_act不同，该方法不会阻塞直至操作完成。它会立即启动执行，返回唯一的task_id，并允许客户端通过page_use_get_act_result轮询获取中间进度和最终结果。

{
  "type": "object",
  "title": "page_use_act_asyncArguments",
  "required": [
    "sandbox_id",
    "action"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "dom_settle_timeout_ms": {
      "type": "integer",
      "title": "Dom Settle Timeout Ms"
    },
    "page_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Id"
    },
    "variables": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object",
      "title": "Variables"
    },
    "action": {
      "type": "string",
      "title": "Action"
    },
    "context_id": {
      "default": 0,
      "type": "integer",
      "title": "Context Id"
    },
    "iframe": {
      "type": "boolean",
      "title": "Iframe"
    },
    "timeout_ms": {
      "type": "integer",
      "title": "Timeout Ms"
    },
    "use_vision": {
      "default": false,
      "type": "boolean",
      "title": "Use Vision"
    }
  }
}

获取异步操作任务进度

page_use_get_act_result

获取异步操作任务的当前进度或最终结果。

该方法应配合之前调用page_use_act_async所获得的task_id使用。它将返回任务的当前状态，如果执行已完成（is_done），则包含相应的结果内容。

{
  "type": "object",
  "title": "page_use_get_act_resultArguments",
  "required": [
    "sandbox_id",
    "task_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  }
}

获取异步提取任务结果

page_use_get_extract_result

异步函数，用于获取 extract 任务的结果。

{
  "type": "object",
  "title": "page_use_get_extract_resultArguments",
  "required": [
    "sandbox_id",
    "task_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  }
}

页面导航URL

page_use_navigate

在浏览器中导航至指定的 URL。

{
  "type": "object",
  "title": "page_use_navigateArguments",
  "required": [
    "sandbox_id",
    "url"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "title": "Sandbox Id",
      "description": "The sandbox ID is the identifier for the tool execution environment. This sandbox_id comes from the create_sandbox tool."
    },
    "url": {
      "type": "string",
      "title": "Url"
    }
  }
}

执行代码

run_code

在 Linux 平台上运行指定上下文中的代码并返回输出或错误。

{
  "inputSchema": {
    "properties": {
      "code": {
        "description": "要执行的代码",
        "type": "string"
      },
      "language": {
        "description": "用于代码执行的编程语言。支持的值：'python', 'javascript'。如果未指定，默认使用 Python。",
        "type": "string"
      },
      "timeout_s": {
        "default": 300,
        "description": "命令执行超时时间（单位：秒）。如果未指定，默认值（例如 300 秒），最大 3600 秒。",
        "type": "integer"
      }
    },
    "required": ["code"],
    "type": "object"
  }
}