工具

Sage 的工具系统为 Agent 提供了强大的能力扩展，支持内置工具和通过 MCP（Model Context Protocol）协议接入的外部工具。

访问工具管理

点击左侧导航栏的「个人中心」，在展开的菜单中选择「工具」，即可进入工具管理页面。

工具来源

Sage 支持多种工具来源，通过顶部的「来源分组」可以切换查看不同来源的工具：

1. 基础工具

Sage 内置的核心工具集，包含系统级功能和常用操作：

工具名称	功能说明	参数数量
sys_spawn_agent	创建新的子 Agent	4
sys_delegate_task	将任务委派给子 Agent	2
sys_finish_task	向父 Agent 报告最终结果	2
execute_shell_command	在指定目录执行 Shell 命令	6
execute_python_code	在临时文件中运行 Python 代码	5
execute_javascript_code	在临时文件中运行 JavaScript 代码	5
extract_text_from_non_text	读取 PDF、DOCX 等非文本文件	4
file_read	读取文本文件和配置文件	5
file_write	智能文件写入工具	4

2. MCP 工具集

通过 MCP 协议接入的外部工具服务，以工具集（Tool Set）的形式组织：

• diary：内置 MCP 工具集，包含 4 个工具
• IM Service：内置 MCP 工具集，包含 1 个工具
• task_scheduler：内置 MCP 工具集，包含 6 个工具

每个 MCP 工具集显示：

• 工具集名称
• 工具数量
• 来源标识（内置 MCP）

MCP 工具集详情

点击任意 MCP 工具集卡片，可以查看该工具集包含的所有工具详情。

工具集操作

在工具集详情页面，您可以进行以下操作：

• 刷新：当 MCP Server 配置发生变更后，点击刷新按钮重新加载工具列表
• 删除：移除该 MCP 工具集及其所有工具

工具详情展示

每个工具显示以下信息：

• 工具图标：标识工具类型
• 工具名称：工具的调用标识
• 功能描述：工具的用途说明
• 所属工具集：工具的来源
• 参数数量：工具所需的输入参数个数

添加 MCP 服务器

Sage 支持通过 MCP 协议接入外部工具服务，扩展 Agent 的能力边界。

配置步骤

1. 点击「添加 MCP 服务器」按钮
2. 填写服务器基本信息
3. 选择通信协议并配置连接参数
4. 保存配置

基本信息

配置项	说明
服务器名称	为 MCP 服务器命名，便于识别
描述	服务器的功能说明（可选）

协议配置

Sage 支持三种 MCP 通信协议：

1. stdio（标准输入输出）

适用于本地运行的 MCP 服务器，通过进程间通信交互。

适用场景：

• 本地脚本或程序
• 命令行工具
• 本地开发测试

配置参数：

• 命令路径
• 工作目录
• 环境变量

2. SSE（Server-Sent Events）

基于 HTTP 的服务器推送协议，适用于远程 MCP 服务。

适用场景：

• 远程 API 服务
• 云托管的 MCP 服务器
• 需要实时推送的场景

配置参数：

• 服务器 URL
• 认证信息（如需要）

3. Streamable HTTP

基于 HTTP 流的通信协议，支持双向通信。

适用场景：

• 需要双向通信的远程服务
• 大数据量传输场景
• 复杂交互需求的 MCP 服务

配置参数：

• 服务器 URL
• 连接超时设置
• 认证信息（如需要）

协议对比

协议	通信方式	适用场景	延迟	复杂度
stdio	本地进程	本地工具	低	简单
SSE	HTTP 单向推送	远程服务	中	中等
Streamable HTTP	HTTP 双向流	复杂远程服务	中	较高

刷新 MCP 工具

当您修改了 MCP Server 的配置（如添加新工具、更新工具定义）时，需要手动刷新才能生效：

1. 进入对应 MCP 工具集的详情页面
2. 点击「刷新」按钮
3. Sage 会重新连接 MCP Server 并获取最新的工具列表

工具使用

配置好的工具可以在创建 Agent 时进行授权，Agent 会根据任务需求自动选择合适的工具执行。

工具授权

在 Agent 配置页面的「工具授权」步骤中：

1. 选择需要授权的工具集或单个工具
2. 设置工具的使用范围
3. 配置工具调用权限

工具调用流程

1. Agent 分析用户请求，判断是否需要使用工具
2. 选择合适的工具并准备参数
3. 执行工具调用
4. 获取执行结果并继续处理
5. 向用户返回最终结果

内置 MCP 工具集介绍

diary 工具集

提供日记管理相关功能，包含 4 个工具：

• 创建日记条目
• 查询日记内容
• 更新日记信息
• 删除日记条目

IM Service 工具集

提供即时通讯相关功能，包含 1 个工具：

• 发送消息到指定频道

task_scheduler 工具集

提供任务调度相关功能，包含 6 个工具：

工具名称	功能说明	参数
list_tasks	列出所有任务（包括一次性任务和循环任务）	4
add_task	向调度器添加新任务	6
delete_task	从调度器删除任务	1
complete_task	手动标记任务为已完成	1
enable_task	启用或禁用循环任务	2
get_task_details	获取指定任务的详细信息	1

最佳实践

1. 选择合适的协议

• 本地工具使用 stdio，简单高效
• 远程服务优先考虑 SSE，稳定可靠
• 需要双向通信时选择 Streamable HTTP

2. 及时刷新工具列表

• 修改 MCP Server 配置后及时刷新
• 定期检查工具集状态
• 删除不再使用的 MCP 服务器

3. 合理授权工具

• 根据 Agent 的职责范围授权工具
• 避免过度授权导致安全风险
• 定期审查 Agent 的工具使用情况

4. 监控工具执行

• 关注工具执行的成功率和耗时
• 及时处理工具调用失败的情况
• 优化频繁使用的工具配置

故障排查

MCP 服务器连接失败

1. 检查服务器地址和端口是否正确
2. 确认网络连接正常
3. 验证认证信息是否有效
4. 查看 MCP Server 日志

工具刷新失败

1. 确认 MCP Server 正在运行
2. 检查网络连接状态
3. 尝试重新添加 MCP 服务器
4. 查看浏览器控制台错误信息

工具调用异常

1. 检查工具参数是否正确
2. 确认 Agent 有权限使用该工具
3. 查看工具执行日志
4. 验证 MCP Server 状态