扩展 Dify 内置工具集，打造自己独有的 AI Agent 工作站

Dify 提供了很多的内置工具，让我们在创建 Agent 的时候可以做更多的事情。看着琳琅满目的工具，我们是不是也想接入自己独特的工具呢？

今天演示下如何构建自己的工具并添加到 Dify 内置工具集里面。

运行 Dify

如何运行 Dify（源码和容器运行）我这里就不赘述了，大家可以参考前面这两篇文章：

• Dify + FastAPI 创建自定义工具
• Dify+谷歌翻译使用中文提示词实现本地文生图

扩展工具

厂商（供应商）和工具

首先我们了解下 Dify 内置工具的两个概念：厂商 和 工具。

你要扩展工具的话，首先要注册一个厂商，一个厂商下面可以有多个工具，在你选择工具的时候，工具会按照厂商分组。

扩展方式

扩展 Dify 工具和厂商分了两部分：

• 使用 yaml 文件描述其参数的功能
• 使用 python 文件编写厂商注册函数和工具实现

不如定义了两个工具，最终的目录结构大概是这样：

├── _assets
│   └── icon.svg
├── shuyi.py
├── shuyi.yaml
└── tools
    ├── shuyi_excel.py
    ├── shuyi_excel.yaml
    ├── shuyi_test.py
    └── shuyi_test.yaml

定义厂商

厂商定义 yaml

这个 yaml 将包含工具供应商的信息，包括供应商名称、图标、作者等详细信息，以帮助前端灵活展示。

在 core/tools/provider/builtin 目录下创建一个文件夹，比如 shuyi，然后软件 shuyi.yaml。

在文件里面增加关于工具的描述、以及展示的图标。

identity:
  author: Shuyi
  name: shuyi
  label:
    en_US: Shuyi
    zh_Hans: 数翼
    pt_BR: Shuyi
  description:
    en_US: Shuyi tools
    zh_Hans: 数翼自定义工具集
    pt_BR: Shuyi tools
  icon: icon.svg
  tags:
    - search
    - productivity

授权定义

如果工具需要授权，那么我们还需要定义授权参数。

授权一般都是填写这个工具的密钥（API Key），比如谷歌搜索、DALL-E 绘画，通过授权可以完成工具的安全调用。

如果配置了授权在工具详情就会出现一个授权按钮：

点击可以看到授权参数的填写：

我们自定义工具增加两个授权参数：

• 服务器地址：我们自己部署服务的地址
• API Key：用于验证调用的合法性

定义授权参数 shuyi_api_key 和 shuyi_api_url，表单类型分别是secret-input和text-input。Yaml 增加如下内容：

credentials_for_provider:
  shuyi_api_key:
    type: secret-input
    required: true
    default: "123456"
    label:
      en_US: Shuyi API key
      zh_Hans: Shuyi API key
      pt_BR: Shuyi API key
    placeholder:
      en_US: Please input your Shuyi API key
      zh_Hans: 请输入你的 Shuyi API key
      pt_BR: Please input your Shuyi API key
    help:
      en_US: Get your Shuyi API key from Shuyi
      zh_Hans: 从 Shuyi 获取您的 Shuyi API key
      pt_BR: Get your Shuyi API key from Shuyi
    url: https://blog.tupu.work/

  shuyi_api_url:
    type: text-input
    required: true
    default: http://localhost:8000
    label:
      en_US: Shuyi API url
      zh_Hans: Shuyi API 地址
      pt_BR: Shuyi API url
    placeholder:
      en_US: Please input your Shuyi API url
      zh_Hans: 请输入你的 Shuyi API 服务地址
      pt_BR: Please input your Shuyi API url
    help:
      en_US: Get your Shuyi API url from Shuyi
      zh_Hans: 从 Shuyi 获取您的 Shuyi API url
      pt_BR: Get your Shuyi API url from Shuyi
    url: https://blog.tupu.work/

这时候我们就可以看到工具的授权参数了：

点击可以看到授权表单：

是否必须授权和调用外部服务

自定义工具当然不是必须需要授权或者调用服务的。

你可以把所有逻辑都在你的工具代码里面实现，这样比较简单，但是也有一些弊端：

• 工具代码过于复杂，耦合性过高，也不利于测试
• 插件依赖等问题可能和 Dify 冲突，升级安装也不好保证
• 在 Dify 中计算不方便分布式扩容

如果我们的工具功能比较简单，可以不用认证这些的，就比如 JSON 相关的工具：

如果要实现的工具功能复杂，还是建议单独写一个服务，让 Dify 来调用。

工具实现

工具实现也是分为定义文件 Yaml 和功能实现类两部分。

我们再 shuyi/tools 目录下创建 shuyi_test.yaml 文件如下，内容主要就是工具描述、以及参数两部分。

identity:
  name: shuyi_test
  author: Shuyi
  label:
    en_US: ShuyiTest
    zh_Hans: 数翼工具测试
    pt_BR: ShuyiTest
description:
  human:
    en_US: A tool for testing Dify message type and input parameters.Input should be a search query.
    zh_Hans: 用于测试Dify消息类型和输入参数的工具。
    pt_BR: A tool for testing Dify message type and input parameters.Input should be a search query.
  llm: A tool for testing Dify message type and input parameters.Input should be a search query.
parameters:
  - name: query
    type: string
    required: true
    label:
      en_US: Query string
      zh_Hans: 查询语句
      pt_BR: Query string
    human_description:
      en_US: used for searching
      zh_Hans: 用于搜索内容
      pt_BR: used for searching
    llm_description: key words for searching
    form: llm

Dify 支持的参数有四种类型：

• string
• number
• boolean
• select

这块儿我们不在赘述，需要的话可以参考官方文档^[2]。

值得注意的是 form 这个参数， form 表示表单类型，目前支持llm、form两种类型，分别对应 Agent 自行推理和前端填写。

Agent 自行推理的意思就是有 LLM 确定字段的值。

工具的实现类 shuyi_test.py 最简单的莫过于直接返回一个固定的消息。

from typing import Any, Union

from core.tools.entities.tool_entities import ToolInvokeMessage
from core.tools.tool.builtin_tool import BuiltinTool

class ShuyiTestTool(BuiltinTool):
    def _invoke(self,
                user_id: str,
                tool_parameters: dict[str, Any],
                ) -> Union[ToolInvokeMessage, list[ToolInvokeMessage]]:
        return self.create_link_message('hello')

当然现实中肯定不会这么简单，我们一般要获取插件认证的参数：

api_url = self.runtime.credentials['shuyi_api_url'],
params = {
    "api_key": self.runtime.credentials['shuyi_api_key'],
    "type": tool_parameters['type'],
    "query": tool_parameters['query'],
}

调用外部服务：

response = requests.get(url=api_url, params=params)

解析调用结果的服务返回一般逻辑比较复杂，我们可以使用一个单独的函数实现：

def _parse_response(self, response: dict) -> dict:
    result = {}
    # logics
    return result

然后返回：

response.raise_for_status()
valuable_res = self._parse_response(response.json())
return self.create_json_message(valuable_res)

我写了这样一个模板，大家可以基于这个模板来创建自己的工具：

from typing import Any, Union

import requests

from core.tools.entities.tool_entities import ToolInvokeMessage
from core.tools.tool.builtin_tool import BuiltinTool

class ShuyiTestTool(BuiltinTool):

    def _parse_response(self, response: dict) -> dict:
        result = {}
        # logics
        return result

    def _invoke(self,
                user_id: str,
                tool_parameters: dict[str, Any],
                ) -> Union[ToolInvokeMessage, list[ToolInvokeMessage]]:
        api_url = self.runtime.credentials['shuyi_api_url'],
        params = {
            "api_key": self.runtime.credentials['shuyi_api_key'],
            "type": tool_parameters['type'],
            "query": tool_parameters['query'],
        }
        response = requests.get(url=api_url, params=params)
        response.raise_for_status()
        valuable_res = self._parse_response(response.json())
        return self.create_json_message(valuable_res)

消息类型

Dify 提供了几种消息类型^[3]，在我看来都是文本（Markdown）类型的封装，下面是对应的封装方法：

• 图片：create_image_message(self, image: str, save_as: str = '')
• 链接：create_link_message(self, link: str, save_as: str = '')
• 文本：create_text_message(self, text: str, save_as: str = '')
• Blob: create_blob_message(self, blob: bytes, meta: dict = None, save_as: str = '')
• JSON: create_json_message(self, object: dict)

当然，也支持返回多个消息，用数组表示即可。

文本

文本类型其实是 Markdown 。

我们创建一个包含图片、列表、标题的 Markdown 消息：

return self.create_text_message(
                """### User message
%s
### 生成式 AI 应用创新引擎
开源的 LLM 应用开发平台，轻松构建和运营生成式 AI 原生应用。
- 生成式 AI
- 应用开发框架



#### RAG Pipeline
""" % params['query'])

效果如下：

图片消息

图片消息需要传递一个地址：

image_path = 'https://buffer.com/cdn-cgi/image/w=1000,fit=contain,q=90,f=auto/library/content/images/size/w1200/2023/10/free-images.jpg'
return self.create_image_message(image_path)

效果如下：

Blob 消息

文档上说 Blob 消息可以返回文件的原始数据，如图片、音频、视频、PPT、Word、Excel 等。

但是实际测试下来效果不太对。

with open(file_path, 'rb') as mp4:
    byte_arr = mp4.read()

return self.create_blob_message(
    blob=byte_arr,
    meta={
        # 'mime_type': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
        'mime_type': 'video/mp4',
        'file_name': 'xxx.mp4',},
    save_as=self.VARIABLE_KEY.IMAGE.value
)

效果并没有显示出文件内容，或者下载链接：

经过尝试，如果想要返回文档，发现只有使用 Markdown 来实现一个下载超链接。

[something.xlsx](https://yourhost/xxx.xlsx

链接消息

连接类型的消息只需要出入一个地址，

return self.create_link_message(link)

返回的内容就是：Link: 后面跟上你的链接：

多条消息

Dify 还支持多条消息的返回，使用数组即可：

messages = [
    self.create_text_message("""### User message ...""" % params['query']),
    self.create_json_message({'result': 'success', 'text': 'This is a message'}),
    self.create_image_message(image_path),
    self.create_link_message(link),
    ...
]

效果也是多条消息的拼接：

使用工具

当我们编写好工具类，重启服务就可以使用刚刚创建的工具类了。

添加节点的时候找到并选择自己的工具：

就可以和 Dify 提供的默认工具一样用了。

总结

相比于在 UI 上创建基于 OpenAPI 的自定义工具，通过代码来扩展供应商和工具集更使能方便我们完成工具的积累和传播，在使用上也有更大的可能性。

通过扩展工具，基于 Dify 打造自己独特的 AI 工作站，同时还可以复用自己之前的工具积累，而不仅仅是通用的 AI Agent 工作站。

{{userData.name}}已认证