tool替换relay

[bouillipx]

tool 模块 AgentScope 依赖分析

版本: v1.0
生成日期: 2026-03-10
分析范围: src/relay/domain/tool/

---

概述

tool 模块是 RelayAgent 与 AgentScope 框架集成的核心层，通过标准化的工具响应机制和扩展能力实现与 Agent 系统的无缝对接。

依赖统计：

• 总文件数：17 个
• 总导入点：41 处
• 核心依赖：ToolResponse + TextBlock（覆盖率 94%）
• 扩展依赖：ImageBlock、Msg、Toolkit、AgentBase（覆盖率 6%）

---

一、核心依赖：工具响应标准化

依赖说明

类/函数	模块路径	用途
ToolResponse	agentscope.tool	所有工具函数的统一返回类型，包含内容块和元数据
TextBlock	agentscope.message	文本内容块，用于构建工具响应的内容部分

使用文件清单

文件路径	导入位置	主要功能	响应内容类型
base_tool.py	行 616-617	工具基类动态包装器	工具执行结果
service/authorization_service.py	行 1376-1377, 1449-1450, 1514-1515, 1658-1659	授权审批服务	审批状态、风险等级、规则信息
service/browser_service.py	行 32-33	浏览器操作服务	截图路径、页面信息、操作状态
service/browser_vision.py	行 10-11, 163	浏览器视觉分析	视觉分析状态、截图路径
service/code_service.py	行 26-27	代码执行服务	执行结果、输出、错误堆栈
service/command_service.py	行 16-17	Shell 命令执行	标准输出、错误输出、返回码
service/datetime_service.py	行 13-14	日期时间查询	时间戳、时区信息
service/filesystem_service.py	行 25-26	文件系统操作	文件内容、目录列表、文件元数据
service/scheduler_service.py	行 14-15	定时任务调度	任务ID、调度状态、下次执行时间
service/sleep_service.py	行 13-14	异步等待	等待时长、完成状态
service/user_interaction_service.py	行 16-17	用户交互	用户选择、问卷答案
service/web_fetch_service.py	行 166-167	网页内容获取	网页内容、格式类型
service/web_search_service.py	行 374-375	网页搜索	搜索结果列表、标题、URL、摘要
specialized_tools/write_tool.py	行 13-14	文件写入工具	写入路径、字节数、确认信息
_codeact/interface/controllers.py	行 10	CodeAct 控制器	类型注解（无实际使用）
_codeact/interface/presenters.py	行 10-11	CodeAct 输出格式化	JSON 格式的执行结果
_lsp/adapter/agent_tools.py	行 14-15	LSP 工具适配器	补全项、定义位置、悬停信息

响应结构说明

工具响应采用统一的两层结构：

第一层：ToolResponse 对象

• content：内容块列表（支持多个 TextBlock/ImageBlock）
• metadata：元数据字典（操作状态、附加信息）

第二层：TextBlock 对象

• type：内容类型（固定为 "text"）
• text：实际文本内容（通常为 JSON 字符串）

元数据字段规范

不同服务返回的 metadata 字段：

服务类型	核心字段	说明
授权服务	approved, risk_level, rule_name	审批决策和风险信息
浏览器服务	success, operation, has_image	操作状态和图像标识
代码服务	status, error, file_path	执行状态和文件信息
命令服务	exit_code, duration	命令退出码和执行时长
文件服务	operation, bytes_written	操作类型和写入字节数

导入模式说明

延迟导入模式：大部分服务文件采用函数内导入，而非文件顶部导入。

原因：

1. 避免循环依赖问题
2. 减少模块加载时的依赖检查
3. 仅在实际需要时才加载 AgentScope 模块

导入位置：通常在函数 docstring 之后、实际逻辑之前

---

二、扩展依赖：视觉分析能力

依赖说明

类/函数	模块路径	用途
ImageBlock	agentscope.message	图像内容块，支持 base64 编码的图像数据
Msg	agentscope.message	消息对象，用于 agent memory 传递

使用文件清单

文件路径	导入位置	主要功能	使用场景
service/browser_vision.py	行 10	浏览器截图视觉分析	将截图添加到 agent memory

工作流程说明

视觉分析的工作流程：

1. 截图捕获：调用 browser_screenshot 获取页面截图
2. 图像块构建：将 base64 编码的图像数据封装为 ImageBlock
3. 消息创建：使用 Msg 创建包含 ImageBlock 的消息对象
4. 内存注入：通过 agent memory 的异步添加方法将图像消息注入
5. LLM 分析：LLM 从 memory 中读取图像进行视觉分析

设计原因

为什么需要单独的消息注入：

AgentScope 的消息格式化器会将工具响应中的 ImageBlock 转换为字符串，导致图像数据丢失。通过单独创建消息并添加到 memory，可以确保 LLM 接收到正确格式的图像数据。

---

三、扩展依赖：工具注册管理

依赖说明

类/函数	模块路径	用途
Toolkit	agentscope.tool	工具包管理器，提供工具注册、卸载、schema 查询能力

使用文件清单

文件路径	导入位置	主要功能	使用场景
_lsp/adapter/agent_tools.py	行 15	LSP 工具组管理	批量注册和卸载 LSP 工具

核心方法说明

方法名	功能	使用场景
register_tool_function	注册单个工具函数	LSP 工具初始化时注册代码补全、定义跳转等工具
remove_tool_groups	批量卸载工具组	LSP 服务停止时清理所有 LSP 相关工具
get_json_schemas	获取所有工具的 JSON Schema	参数类型转换时查询工具参数定义

工具分组机制

LSP 工具使用分组标识（LSP_TOOL_GROUP）进行统一管理：

优势：

1. 支持批量卸载，无需逐个移除
2. 避免工具名称冲突
3. 便于工具生命周期管理

应用场景：

• LSP 服务启动时注册整个工具组
• LSP 服务停止时一次性清理所有 LSP 工具
• 从多个 agent 实例中统一卸载 LSP 工具

---

四、扩展依赖：参数类型转换

依赖说明

类/函数	模块路径	用途
AgentBase	agentscope.agent	Agent 基类，提供访问 toolkit 的能力

使用文件清单

文件路径	导入位置	主要功能	使用场景
service/tool_parse_service.py	行 25	参数类型转换服务	修复 LLM 错误识别的参数类型

问题背景

LLM 在生成工具调用时，可能将参数错误识别为字符串类型：

正确类型	LLM 错误识别	示例
boolean	string	True → "true"
integer	string	123 → "123"
number	string	3.14 → "3.14"

解决方案

参数类型转换服务的工作流程：

1. 获取工具 Schema：通过 AgentBase.toolkit.get_json_schemas() 获取所有工具的参数定义
2. 匹配当前工具：根据工具名称查找对应的参数 Schema
3. 类型转换：根据 Schema 中定义的参数类型，将字符串值转换回正确类型
4. 返回修正参数：返回类型正确的参数字典

类型转换规则

Schema 类型	字符串值	转换结果
boolean	"true", "false"	True, False
integer	"123", "-456"	123, -456
number	"3.14", "-2.5"	3.14, -2.5
string	任意字符串	保持不变
array	JSON 字符串	解析为列表
object	JSON 字符串	解析为字典

---

五、依赖关系图

tool 模块对 AgentScope 的依赖
│
├── 核心层（必需，94% 覆盖率）
│   ├── ToolResponse
│   │   └── 统一的工具响应格式
│   │       ├── content: List[TextBlock | ImageBlock]
│   │       └── metadata: Dict[str, Any]
│   │
│   └── TextBlock
│       └── 文本内容块
│           ├── type: "text"
│           └── text: str (通常为 JSON)
│
├── 扩展层（可选，6% 覆盖率）
│   ├── ImageBlock
│   │   └── 图像内容块（浏览器视觉分析）
│   │
│   ├── Msg
│   │   └── 消息对象（agent memory 传递）
│   │
│   ├── Toolkit
│   │   └── 工具包管理（LSP 工具生命周期）
│   │
│   └── AgentBase
│       └── Agent 基类（schema 访问）
│
└── 使用模式
    ├── 延迟导入：函数内导入，避免循环依赖
    ├── 统一响应：所有工具返回 ToolResponse
    └── 元数据规范：标准化的 metadata 字段

---

六、最佳实践建议

1. 工具响应规范

推荐做法：

• 所有工具函数必须返回 ToolResponse 对象
• content 使用 TextBlock 列表，即使只有一个内容块
• metadata 包含操作状态和关键信息
• 文本内容使用 JSON 格式，便于解析和扩展

避免做法：

• 直接返回字符串或字典
• 省略 metadata 字段
• 使用非标准的内容块类型

2. 导入策略

推荐做法：

• 服务层文件使用函数内延迟导入
• 基础设施层文件可使用顶部导入
• 保持导入语句的一致性

避免做法：

• 在循环或频繁调用的代码段中导入
• 混合使用顶部导入和延迟导入

3. 视觉分析集成

推荐做法：

• 使用专门的视觉分析服务（browser_vision.py）
• 将图像消息单独添加到 agent memory
• 返回简化的 ToolResponse（不含 ImageBlock）

避免做法：

• 在 ToolResponse.content 中直接返回 ImageBlock
• 期望 AgentScope formatter 保留图像数据

4. 工具生命周期管理

推荐做法：

• 使用工具分组标识进行批量管理
• 在服务停止时主动卸载工具
• 避免工具名称冲突

避免做法：

• 逐个注册和卸载工具
• 忽略工具清理导致内存泄漏

---

七、版本兼容性说明

AgentScope 版本要求

依赖项	最低版本	推荐版本	说明
agentscope.tool	-	最新	ToolResponse、Toolkit 核心功能稳定
agentscope.message	-	最新	TextBlock、ImageBlock、Msg 核心功能稳定
agentscope.agent	-	最新	AgentBase 基类稳定

接口稳定性

接口	稳定性	变更风险
ToolResponse	高	核心接口，变更可能性低
TextBlock	高	核心接口，变更可能性低
ImageBlock	中	视觉功能，可能随多模态能力演进
Msg	高	消息传递核心，变更可能性低
Toolkit	中	工具管理，可能随工具系统演进
AgentBase	中	Agent 基类，可能随框架演进

---

八、附录

A. 文件分类统计

分类	文件数	占比
基础工具	2	12%
服务层	11	65%
专用工具	1	6%
适配器	3	17%

B. 导入位置统计

导入位置类型	文件数	说明
文件顶部	6	浏览器、代码、命令、日期时间、文件系统、调度器服务
函数内部	11	授权、网页获取、网页搜索、视觉分析、基类等

C. 依赖深度分析

依赖深度	文件数	说明
单层依赖（仅 ToolResponse + TextBlock）	14	标准工具服务
双层依赖（+ Toolkit）	1	LSP 适配器
双层依赖（+ AgentBase）	1	参数转换服务
三层依赖（+ ImageBlock + Msg）	1	浏览器视觉分析

---

文档维护者: RelayAgent 开发团队
最后更新: 2026-03-10

[bouillipx]

已基于当前仓库设计和 issue214 现状分析，整理出一份正式的可落地切换指导。仓库内本地文档路径：

• docs/todos/2026-03-10_issue214_agentscope_tool_cutover_guide.md

下面同步核心结论，供后续实施直接作为 baseline。

---

AgentScope tool -> DARE tool 切换指导（保留 GLM5 + AgentScope ReactAgent）

1. 结论先行

当前最稳妥的切换目标，不是立即“完全去 AgentScope”，而是：

• 保留 AgentScope ReactAgent + GLM5 作为当前 LLM/tool-calling 外壳
• 将 业务工具实现、注册、schema、生命周期、权限治理 全部收敛到 DARE
• 在 AgentScope 与 DARE 之间增加一层 极薄 bridge，只负责：
  • 把 AgentScope 工具调用转发到 DARE
  • 把 DARE ToolResult 适配回 AgentScope ToolResponse + TextBlock
  • 保持现有工具 name/schema/metadata 兼容，降低 GLM5 行为漂移风险

也就是说：

1. 只要 ReactAgent 还在，严格意义上仍然存在 AgentScope 依赖
2. 但这部分依赖应被压缩到 bridge 壳层
3. tool 域业务代码不应再直接 import agentscope.tool / agentscope.message / agentscope.agent

---

2. 当前事实基线

2.1 issue214 已确认的依赖结构

issue214 里已经把范围界定得比较清楚：

• 总文件数：17
• 总导入点：41
• 核心依赖：ToolResponse + TextBlock，覆盖率约 94%
• 扩展依赖：ImageBlock、Msg、Toolkit、AgentBase，覆盖率约 6%

2.2 DARE 当前可直接承接的能力

DARE 的 tool 域已经提供本轮迁移所需的主干能力：

• ITool
• IToolProvider
• ToolManager
• ToolGateway
• ToolResult
• CapabilityDescriptor

结合仓库现状，可以直接得出两个判断：

1. tool 域业务逻辑可以先完整切到 DARE
2. AgentScope 暂时只保留在 GLM5 ReAct 外壳，不必让它继续承担业务工具体系职责

---

3. Scope Freeze

In Scope

本轮只做：

1. 将 src/relay/domain/tool/ 中的业务工具实现迁移为 DARE ITool / IToolProvider
2. 用 DARE ToolManager + ToolGateway 取代 AgentScope Toolkit 的业务注册职责
3. 建立 AgentScope -> DARE 的 tool bridge
4. 保持 GLM5 + AgentScope ReactAgent 的当前交互路径不变
5. 替换 ToolResponse/TextBlock 主链路依赖
6. 替换 Toolkit 与 AgentBase.toolkit.get_json_schemas() 的直接依赖
7. 补充 schema、参数 coercion、bridge 集成回归

Out of Scope

本轮不做：

1. 不切换 GLM5 接入方式
2. 不替换 AgentScope ReactAgent
3. 不重写 memory/session/message 全链路
4. 不把 browser_vision 的 ImageBlock/Msg 注入一起切到 DARE message 体系
5. 不引入并行 tool call 或流式 tool result 的框架级重构

Deferred

延后到下一阶段：

1. 去掉 AgentScope ReactAgent，改接 DARE ReactAgent
2. 把 browser_vision 的 ImageBlock/Msg 迁到 DARE canonical message
3. 流式工具返回（ToolResponse(stream=True)）的统一框架替代方案

---

4. 目标架构

GLM5
  -> AgentScope ReactAgent
    -> AgentScope tool registration shell
      -> AgentScope/DARE bridge
        -> DARE ToolGateway
          -> DARE ToolManager / IToolProvider / ITool
            -> Relay tool services

约束：

• ToolResponse 只能在 bridge 层出现
• TextBlock 只能在 bridge 层出现
• Toolkit 只能在 bridge 层出现
• 业务 service 不允许再直接依赖 agentscope.*
• tool schema 的 source of truth 应切到 CapabilityDescriptor.input_schema

---

5. AgentScope -> DARE 映射表

AgentScope 依赖	当前用途	DARE 对应能力	本轮处理策略
ToolResponse	所有工具统一返回类型	ToolResult	业务层改回 ToolResult；bridge 层再转 ToolResponse
TextBlock	包装文本结果	无需业务依赖	只在 bridge 层创建
Toolkit.register_tool_function()	工具注册	ToolManager.register_tool() / register_provider()	统一改到 DARE registry
Toolkit.remove_tool_groups()	工具组卸载	unregister_provider() / change_capability_status()	改为 provider 生命周期
Toolkit.get_json_schemas()	参数类型修正	CapabilityDescriptor.input_schema	建 ToolSchemaCatalog 替代
AgentBase.toolkit	获取 schema	显式注入 schema catalog	业务层不再依赖 agent 基类
ImageBlock	浏览器视觉图像输入	DARE message 附件体系可承接，但本轮不切	留在专门 bridge
Msg	memory 注入	DARE Message 可承接，但本轮不切	留在专门 bridge

---

6. GLM5 场景下的关键原则

由于当前替换环境只能使用 GLM5，因此必须优先保证“模型看到的工具面”稳定：

1. 工具 name 先保持不变
2. 工具 description 先保持语义等价，不做润色性改写
3. parameters/properties/required 先保持兼容
4. 不要同时修改系统提示词和 tool schema
5. 先维持单 tool-call 串行执行，不顺手引入并行

这是本轮最重要的风险控制点。

---

7. 推荐切片

建议拆成 3 个切片推进，而不是一次性混改：

Slice 1: tool-core-cutover

目标：把业务工具实现全部切到 DARE

交付物：

• DARE tool runtime
• ITool 化标准工具
• IToolProvider 化工具组
• ToolSchemaCatalog

Slice 2: agentscope-bridge-shim

目标：保留 AgentScope ReactAgent，把 tool 调用转接到 DARE

交付物：

• bridge adapter
• ToolResult -> ToolResponse 适配
• schema 兼容回归

Slice 3: lsp-and-vision-edge-cleanup

目标：处理非主链路边角依赖

交付物：

• LSP tool group 生命周期改造
• tool_parse_service 去 AgentBase 化
• browser_vision 留桥不留耦合

---

8. 具体实施步骤

Step 1. 冻结现网工具契约

先导出当前所有工具契约快照：

• tool name
• description
• JSON schema
• required 参数
• ToolResponse.metadata 字段
• 特殊行为（字符串 JSON 输出、参数自动修正、图像消息注入）

建议输出：

• tool_contract_snapshot.json
• tool_metadata_snapshot.json

Step 2. 建 DARE runtime 外壳

建议新增如下结构：

src/relay/domain/tool/
  runtime.py
  schema_catalog.py
  bridges/
    agentscope_tool_bridge.py
  providers/
    standard_provider.py
    lsp_provider.py
  tools/
    *.py

职责：

• runtime.py：组装 ToolManager + ToolGateway
• schema_catalog.py：schema 查询与参数 coercion
• bridges/agentscope_tool_bridge.py：最薄适配层
• providers/*.py：按分组暴露工具集合
• tools/*.py：只放业务逻辑

Step 3. 标准工具改为 DARE ITool

优先迁移：

• base_tool.py
• service/authorization_service.py
• service/browser_service.py
• service/code_service.py
• service/command_service.py
• service/datetime_service.py
• service/filesystem_service.py
• service/scheduler_service.py
• service/sleep_service.py
• service/user_interaction_service.py
• service/web_fetch_service.py
• service/web_search_service.py
• specialized_tools/write_tool.py

迁移后要求：

• 业务逻辑返回 ToolResult
• 不再直接创建 ToolResponse
• 不再直接创建 TextBlock
• 异常统一收敛为 ToolResult(success=False, error=...)

Step 4. 引入 ToolSchemaCatalog

tool_parse_service.py 当前对 AgentBase.toolkit.get_json_schemas() 的依赖，应替换为显式 schema catalog。

能力要求：

• 根据 capability id 返回 input_schema
• 根据 schema 做参数字符串纠正：
  • "true" -> True
  • "123" -> 123
  • "3.14" -> 3.14
  • JSON 字符串转 array/object
• 作为 bridge 执行前的统一参数归一化步骤

这一步对 GLM5 很关键。

Step 5. 建 AgentScope bridge

bridge 层只做三件事：

1. 根据 tool name 找到 DARE capability
2. 用 DARE ToolGateway.invoke(...) 执行
3. 将 ToolResult 转回 AgentScope ToolResponse

建议形态：

result = await runtime.gateway.invoke(...)
payload = {
    "success": result.success,
    "output": result.output,
    "error": result.error,
}
return ToolResponse(
    content=[TextBlock(type="text", text=json.dumps(payload, ensure_ascii=False, default=str))],
    metadata=legacy_metadata,
)

bridge 约束：

• 不承载业务逻辑
• 不承载 schema 定义
• 不承载权限判定
• 只做协议/数据形状转换

Step 6. 替换 Toolkit 生命周期

对于 _lsp/adapter/agent_tools.py 一类动态工具组：

• 启动时：register_provider(provider)
• 停止时：unregister_provider(provider)
• 临时禁用时：change_capability_status(capability_id, enabled=False)

不要继续依赖 AgentScope 的 group 管理接口。

Step 7. browser_vision 保桥不硬切

这是本轮最容易误伤的点，建议：

1. 工具执行本身改为 DARE ITool
2. 工具结果只返回截图路径、分析状态、摘要
3. ImageBlock/Msg 注入 AgentScope memory 的动作，先保留在专门 bridge/service 层
4. 等 message 体系切换时，再整体迁移

---

9. 给内部 GLM5 Agent 的执行约束

可直接用作内部替换 agent 的操作说明：

任务目标：
仅替换 relay 的 tool 域到 DARE，不替换当前 AgentScope ReactAgent 与 GLM5 调用链。

硬约束：
1. 不修改当前 GLM5 接入方式。
2. 不修改 AgentScope ReactAgent 主循环。
3. 只有 bridge 层允许 import agentscope.tool / agentscope.message / agentscope.agent。
4. 业务工具实现统一改为 DARE ITool / IToolProvider。
5. 工具 name / description / JSON schema / metadata key 先保持兼容。
6. browser_vision 的 ImageBlock / Msg 注入逻辑先保留在桥接层，不进入本轮改造。
7. 每迁一个工具，必须补 schema 快照测试、参数 coercion 测试、bridge 集成测试。

执行顺序：
A. 导出现网工具契约快照
B. 建 DARE ToolManager + ToolGateway + SchemaCatalog
C. 把标准工具切成 ITool
D. 接 AgentScope bridge
E. 最后处理 LSP / browser_vision / AgentBase.toolkit 残留依赖

---

10. 验收矩阵

结构验收

迁移完成后必须满足：

• service/*.py 不再直接 import agentscope.tool.ToolResponse
• service/*.py 不再直接 import agentscope.message.TextBlock
• tool_parse_service.py 不再依赖 AgentBase.toolkit
• _lsp/adapter/agent_tools.py 不再依赖 Toolkit
• 除 bridge 外，没有业务文件直接 import agentscope.*

行为验收

至少跑通以下三类回归：

1. 普通文本工具
2. 参数类型修正工具
3. 浏览器/视觉相关工具

契约验收

每个工具至少验证：

• tool name 不变
• description 语义不变
• required 字段不变
• JSON schema 不变或只做兼容增强
• metadata key 不丢失

---

11. 风险与回滚

主要风险：

1. GLM5 对工具 schema 很敏感，如果 name/required/description 同时改动，tool-call 命中率会波动
2. 若把 browser_vision 和标准 tool core 一起重构，容易把 message/memory 问题误判为 tool 问题
3. 若 bridge 中掺入业务逻辑，会形成新的双栈耦合

回滚建议：

• 每个切片保留旧 AgentScope tool 注册路径一个版本周期
• bridge 支持 feature flag 切回旧实现
• 契约快照测试失败时，优先回滚 schema 变更，再排查执行逻辑

---

12. 最终里程碑

Milestone A

• DARE tool runtime 建好
• 标准工具完成 ITool 化
• schema catalog 可用

Milestone B

• AgentScope bridge 接通
• GLM5 在现有 ReactAgent 下能稳定调用 DARE tools
• 主链路工具回归通过

Milestone C

• LSP group 生命周期切换
• tool_parse_service 去 AgentBase.toolkit
• browser_vision 留桥收口

完成 Milestone C 后，可视为：

tool 域业务上已脱离 AgentScope，仅保留 GLM5 ReAct 外壳依赖。