Tool Plugin¶
Note: ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。
工具是指可以被 Chatflow / Workflow / Agent 类型应用调用的第三方服务，提供完整的 API 实现能力来增强 FlexAI 应用。例如，添加在线搜索、图像生成等额外功能。
在本文中，"工具插件"指的是一个完整的项目，包含工具提供者文件、功能代码和其他结构。一个工具提供者可以包含多个工具（可以理解为单个工具内提供的额外功能），结构如下：
本文将以 Google Search 为例，演示如何快速开发一个工具插件。
前置条件¶
- FlexAI 插件脚手架工具
- Python 环境，版本 ≥ 3.12
关于如何准备插件开发脚手架工具的详细说明，请参考初始化开发工具。如果你是首次开发插件，建议先阅读 FlexAI 插件开发：Hello World 指南。
创建新项目¶
运行脚手架命令行工具来创建一个新的 FlexAI 插件项目。
如果你已将二进制文件重命名为 flexai 并复制到 /usr/local/bin 路径，可以运行以下命令来创建新的插件项目：
在后续文本中，将使用
flexai作为命令行示例。如果遇到任何问题，请将flexai命令替换为命令行工具的路径。
选择插件类型和模板¶
脚手架工具中的所有模板都提供完整的代码项目。在本示例中，选择 Tool 插件。
如果你已经熟悉插件开发且不需要依赖模板，可以参考通用规范指南来完成不同类型插件的开发。
配置插件权限¶
插件还需要从 FlexAI 平台读取的权限。为本示例插件授予以下权限：
- Tools
- Apps
- 启用持久化存储 Storage，分配默认大小存储
- 允许注册 Endpoints
在终端中使用方向键选择权限，使用"Tab"按钮授予权限。
勾选所有权限项后，按 Enter 完成插件创建。系统将自动生成插件项目代码。
开发工具插件¶
1. 创建工具提供者文件¶
工具提供者文件是一个 yaml 格式文件，可以理解为工具插件的基本配置入口，用于向工具提供必要的授权信息。
进入插件模板项目的 /provider 路径，将 yaml 文件重命名为 google.yaml。这个 yaml 文件将包含工具提供者的信息，包括提供者的名称、图标、作者等详细信息。这些信息将在安装插件时显示。
示例代码
identity: # Basic information of the tool provider
author: Your-name # Author
name: google # Name, unique, cannot have the same name as other providers
label: # Label, for frontend display
en_US: Google # English label
zh_Hans: Google # Chinese label
description: # Description, for frontend display
en_US: Google # English description
zh_Hans: Google # Chinese description
icon: icon.svg # Tool icon, needs to be placed in the _assets folder
tags: # Tags, for frontend display
- search
确保文件路径在 /tools 目录中，完整路径如下：
其中 google.yaml 需要使用其在插件项目中的绝对路径。在本示例中，它位于项目根目录。YAML 文件中的 identity 字段说明如下：identity 包含工具提供者的基本信息，包括作者、名称、标签、描述、图标等。
- 图标需要是附件资源，需要放置在项目根目录的
_assets文件夹中。 - 标签可以帮助用户通过分类快速找到插件。以下是目前支持的所有标签。
class ToolLabelEnum(Enum):
SEARCH = 'search'
IMAGE = 'image'
VIDEOS = 'videos'
WEATHER = 'weather'
FINANCE = 'finance'
DESIGN = 'design'
TRAVEL = 'travel'
SOCIAL = 'social'
NEWS = 'news'
MEDICAL = 'medical'
PRODUCTIVITY = 'productivity'
EDUCATION = 'education'
BUSINESS = 'business'
ENTERTAINMENT = 'entertainment'
UTILITIES = 'utilities'
OTHER = 'other'
2. 完善第三方服务凭据¶
为了开发方便，我们选择使用第三方服务 SerpApi 提供的 Google Search API。SerpApi 需要 API Key 才能使用，因此我们需要在 yaml 文件中添加 credentials_for_provider 字段。
完整代码如下：
identity:
author: FlexAI
name: google
label:
en_US: Google
zh_Hans: Google
pt_BR: Google
description:
en_US: Google
zh_Hans: GoogleSearch
pt_BR: Google
icon: icon.svg
tags:
- search
credentials_for_provider: #Add credentials_for_provider field
serpapi_api_key:
type: secret-input
required: true
label:
en_US: SerpApi API key
zh_Hans: SerpApi API key
placeholder:
en_US: Please input your SerpApi API key
zh_Hans: Please enter your SerpApi API key
help:
en_US: Get your SerpApi API key from SerpApi
zh_Hans: Get your SerpApi API key from SerpApi
url: https://serpapi.com/manage-api-key
tools:
- tools/google_search.yaml
extra:
python:
source: google.py
credentials_for_provider的子级结构需要满足通用规范的要求。- 你需要指定提供者包含哪些工具。本示例只包含一个
tools/google_search.yaml文件。 - 作为提供者，除了定义其基本信息外，还需要实现一些代码逻辑，因此需要指定其实现逻辑。在本示例中，我们将功能代码文件放在
google.py中，但暂时不实现它，而是先编写google_search的代码。
3. 填写工具 YAML 文件¶
一个工具插件可以有多个工具功能，每个工具功能都需要一个 yaml 文件进行描述，包括工具功能的基本信息、参数、输出等。
仍以 GoogleSearch 工具为例，在 /tools 文件夹中创建一个新的 google_search.yaml 文件。
identity:
name: google_search
author: FlexAI
label:
en_US: GoogleSearch
zh_Hans: Google Search
pt_BR: GoogleSearch
description:
human:
en_US: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
zh_Hans: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
pt_BR: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
llm: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
parameters:
- name: query
type: string
required: true
label:
en_US: Query string
zh_Hans: Query string
pt_BR: Query string
human_description:
en_US: used for searching
zh_Hans: used for searching web content
pt_BR: used for searching
llm_description: key words for searching
form: llm
extra:
python:
source: tools/google_search.py
identity包含工具的基本信息，包括名称、作者、标签、描述等。parameters参数列表name（必填）参数名称，唯一，不能与其他参数同名。type（必填）参数类型，目前支持string、number、boolean、select、secret-input五种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框。对于敏感信息，请使用secret-input类型。label（必填）参数标签，用于前端显示。form（必填）表单类型，目前支持llm、form两种类型。- 在智能体应用中，
llm表示该参数由 LLM 自行推断，form表示参数可以预先设置以使用此工具。 - 在工作流应用中，
llm和form都需要由前端填写，但llm参数将用作工具节点的输入变量。
- 在智能体应用中，
required是否必填- 在
llm模式下，如果参数是必填的，智能体将被要求推断此参数。 - 在
form模式下，如果参数是必填的，用户将被要求在对话开始前在前端填写此参数。
- 在
options参数选项- 在
llm模式下，FlexAI 会将所有选项传递给 LLM，LLM 可以根据这些选项进行推断。 - 在
form模式下，当type为select时，前端将显示这些选项。
- 在
default默认值。min最小值，当参数类型为number时可以设置。max最大值，当参数类型为number时可以设置。human_description用于前端显示的介绍，支持多语言。placeholder输入字段的提示文本，当表单类型为form且参数类型为string、number、secret-input时可以设置，支持多语言。llm_description传递给 LLM 的介绍。为了让 LLM 更好地理解此参数，请在此处写尽可能详细的关于此参数的信息，以便 LLM 能够理解该参数。
4. 准备工具代码¶
填写完工具的配置信息后，就可以开始编写工具功能的代码，实现工具的逻辑目的。在 /tools 目录中创建 google_search.py，内容如下：
from collections.abc import Generator
from typing import Any
from flexai_plugin import Tool
from flexai_plugin.entities.tool import ToolInvokeMessage
SERP_API_URL = "https://serpapi.com/search"
class GoogleSearchTool(Tool):
def _parse_response(self, response: dict) -> dict:
result = {}
if "knowledge_graph" in response:
result["title"] = response["knowledge_graph"].get("title", "")
result["description"] = response["knowledge_graph"].get("description", "")
if "organic_results" in response:
result["organic_results"] = [
{
"title": item.get("title", ""),
"link": item.get("link", ""),
"snippet": item.get("snippet", ""),
}
for item in response["organic_results"]
]
return result
def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
params = {
"api_key": self.runtime.credentials["serpapi_api_key"],
"q": tool_parameters["query"],
"engine": "google",
"google_domain": "google.com",
"gl": "us",
"hl": "en",
}
response = requests.get(url=SERP_API_URL, params=params, timeout=5)
response.raise_for_status()
valuable_res = self._parse_response(response.json())
yield self.create_json_message(valuable_res)
此示例表示请求 serpapi 并使用 self.create_json_message 返回格式化的 json 数据字符串。如果你想了解更多关于返回数据类型的信息，可以参考远程调试插件和持久化存储 KV 文档。
5. 完善工具提供者代码¶
最后，你需要为提供者创建一个实现代码来实现凭据验证逻辑。如果凭据验证失败，将抛出 ToolProviderCredentialValidationError 异常。验证成功后，google_search 工具服务将被正确请求。
在 /provider 目录中创建 google.py 文件，内容如下：
from typing import Any
from flexai_plugin import ToolProvider
from flexai_plugin.errors.tool import ToolProviderCredentialValidationError
from tools.google_search import GoogleSearchTool
class GoogleProvider(ToolProvider):
def _validate_credentials(self, credentials: dict[str, Any]) -> None:
try:
for _ in GoogleSearchTool.from_credentials(credentials).invoke(
tool_parameters={"query": "test", "result_type": "link"},
):
pass
except Exception as e:
raise ToolProviderCredentialValidationError(str(e))
调试插件¶
完成插件开发后，需要测试插件是否能正常工作。FlexAI 提供了便捷的远程调试方法，帮助你在测试环境中快速验证插件的功能。
前往"插件管理"页面获取远程服务器地址和调试 Key。
返回插件项目，复制 .env.example 文件并重命名为 .env，然后填写你获取的远程服务器地址和调试 Key 信息。
.env 文件：
INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug.flexai.com.tr:5003
REMOTE_INSTALL_KEY=********-****-****-****-************
运行 python -m main 命令启动插件。在插件页面上，你可以看到插件已安装在工作区中，团队的其他成员也可以访问该插件。
打包插件（可选）¶
确认插件可以正常运行后，你可以使用以下命令行工具打包和命名插件。运行后，你会在当前文件夹中发现一个 google.difypkg 文件，这就是最终的插件包。
恭喜，你已经完成了工具类型插件的开发、调试和打包的整个流程！
发布插件（可选）¶
如果你想将插件发布到 FlexAI Marketplace，请确保你的插件符合发布到 FlexAI Marketplace 中的规范。通过审核后，代码将被合并到主分支并自动上架到 FlexAI Marketplace。
探索更多¶
快速开始：¶
插件接口文档：¶
- 通用规范 - Manifest 结构和工具规范
- Endpoint - 详细的 Endpoint 定义
- 反向调用 - 反向调用 FlexAI 能力
- 模型 Schema - 模型
- 智能体插件 - 扩展智能体策略
下一步学习¶
- 远程调试插件 - 学习更多高级调试技巧
- 持久化存储 - 学习如何在插件中使用数据存储
- Slack Bot 插件开发示例 - 查看更复杂的插件开发案例
- 工具插件 - 探索工具插件的高级功能
{/ Contributing Section DO NOT edit this section! It will be automatically generated by the script. /}