trustgraph/docs/tech-specs/tool-services.zh-cn.md

工具服务：动态可插拔的代理工具

状态

已实现

概述

该规范定义了一种动态可插拔的代理工具机制，称为“工具服务”。 与现有的内置工具类型（如 KnowledgeQueryImpl、McpToolImpl 等），工具服务允许通过以下方式引入新的工具：

1. 部署一个新的基于 Pulsar 的服务
2. 添加一个配置描述符，告诉代理如何调用它

这使得无需修改核心 agent-react 框架即可实现扩展。

术语

术语	定义
内置工具	具有在 tools.py 中硬编码实现的现有工具类型
工具服务	一个基于 Pulsar 的服务，可以被其他工具调用
配置描述符	用于配置工具服务的 JSON 格式文件

实现细节

流程

1. 服务启动: 服务将自身注册到 agent，包含服务名称、队列路径等信息
2. 工具配置: 客户端通过加载配置描述符，动态注册服务
3. 调用服务: 客户端使用 ToolServiceClient 调用服务

架构

[客户端 (agent-react)] <-> [ToolServiceClient] <-> [服务 (dynamic_tool_service)] <-> [Pulsar 队列]

示例

# 客户端 (agent-react)
async def call_service(service_name, args):
  # 从配置中获取 service_配置
  service_config = get_config(service_name)
  # 创建 ToolServiceClient
  client = ToolServiceClient(service_config)
  # 调用服务
  response = await client.call(args)
  return response

示例配置描述符

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [
    {"name": "style", "required": false}
  ]
}

示例工具配置

{
  "type": "tool-service",
  "name": "tell-joke",
  "description": "Tell a joke on a given topic",
  "service": "joke-service",
  "style": "pun",
  "arguments": [
    {"name": "topic", "type": "string", "description": "The topic for the joke"}
  ]
}

示例服务实现

import asyncio
import json
from trustgraph.base import dynamic_tool_service
from trustgraph.base.tool_service_client import ToolServiceClient
from trustgraph.schema.services.tool_service import ToolServiceRequest

class Processor(dynamic_tool_service.DynamicToolService):
    async def invoke(self, user, config, arguments):
        style = config.get("style", "pun")
        topic = arguments.get("topic", "")
        joke = await self.get_joke(topic, style)  # 假设这里调用一个 joke 库
        return f"Hey {user}! Here's a {style} for you:\n\n{joke}"

    async def get_joke(self, topic, style):
        # 这是一个占位符，实际需要调用 joke 库来获取笑话
        if topic == "programming" and style == "pun":
            return "Why did the programmer quit? Because he didn't get arrays!"
        else:
            return "I don't know any jokes right now."

例子：加载配置

# 加载工具服务配置
tg-put-config-item tool-service/joke-service < joke-service.json

# 加载工具配置
tg-put-config-item tool/tell-joke < tell-joke.json

重新启动 agent-react

agent-react 必须重新启动才能拾取新的配置。

未来考虑

自主宣布的服务

未来的增强可以允许服务发布自己的描述符：

• 服务将自身注册到 agent，包含服务名称、队列路径等信息
• Agent 订阅并动态注册工具
• 这使得无需修改配置即可实现真正的可插拔性

此功能超出了初始实现范围。

参考

• 现有工具实现：trustgraph-flow/trustgraph/agent/react/tools.py
• 工具注册：trustgraph-flow/trustgraph/agent/react/service.py:105-214
• agent 方案：trustgraph-base/trustgraph/schema/services/agent.py