Feat/assistant app (#2086)

Co-authored-by: chenhe <guchenhe@gmail.com>
Co-authored-by: Pascal M <11357019+perzeuss@users.noreply.github.com>

api/core/tools/docs/en_US/advanced_scale_out.md

@@ -0,0 +1,266 @@
+# Advanced Tool Integration
+
+Before starting with this advanced guide, please make sure you have a basic understanding of the tool integration process in Dify. Check out [Quick Integration](./tool_scale_out.md) for a quick runthrough.
+
+## Tool Interface
+
+We have defined a series of helper methods in the `Tool` class to help developers quickly build more complex tools.
+
+### Message Return
+
+Dify supports various message types such as `text`, `link`, `image`, and `file BLOB`. You can return different types of messages to the LLM and users through the following interfaces.
+
+Please note, some parameters in the following interfaces will be introduced in later sections.
+
+#### Image URL
+You only need to pass the URL of the image, and Dify will automatically download the image and return it to the user.
+
+```python
+    def create_image_message(self, image: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create an image message
+
+            :param image: the url of the image
+            :return: the image message
+        """
+```
+
+#### Link
+If you need to return a link, you can use the following interface.
+
+```python
+    def create_link_message(self, link: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a link message
+
+            :param link: the url of the link
+            :return: the link message
+        """
+```
+
+#### Text
+If you need to return a text message, you can use the following interface.
+
+```python
+    def create_text_message(self, text: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a text message
+
+            :param text: the text of the message
+            :return: the text message
+        """
+```
+
+#### File BLOB
+If you need to return the raw data of a file, such as images, audio, video, PPT, Word, Excel, etc., you can use the following interface.
+
+- `blob` The raw data of the file, of bytes type
+- `meta` The metadata of the file, if you know the type of the file, it is best to pass a `mime_type`, otherwise Dify will use `octet/stream` as the default type
+
+```python
+    def create_blob_message(self, blob: bytes, meta: dict = None, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a blob message
+
+            :param blob: the blob
+            :return: the blob message
+        """
+```
+
+### Shortcut Tools
+
+In large model applications, we have two common needs:
+- First, summarize a long text in advance, and then pass the summary content to the LLM to prevent the original text from being too long for the LLM to handle
+- The content obtained by the tool is a link, and the web page information needs to be crawled before it can be returned to the LLM
+
+To help developers quickly implement these two needs, we provide the following two shortcut tools.
+
+#### Text Summary Tool
+
+This tool takes in an user_id and the text to be summarized, and returns the summarized text. Dify will use the default model of the current workspace to summarize the long text.
+
+```python
+    def summary(self, user_id: str, content: str) -> str:
+        """
+            summary the content
+
+            :param user_id: the user id
+            :param content: the content
+            :return: the summary
+        """
+```
+
+#### Web Page Crawling Tool
+
+This tool takes in web page link to be crawled and a user_agent (which can be empty), and returns a string containing the information of the web page. The `user_agent` is an optional parameter that can be used to identify the tool. If not passed, Dify will use the default `user_agent`.
+
+```python
+    def get_url(self, url: str, user_agent: str = None) -> str:
+        """
+            get url
+        """ the crawled result
+```
+
+### Variable Pool
+
+We have introduced a variable pool in `Tool` to store variables, files, etc. generated during the tool's operation. These variables can be used by other tools during the tool's operation.
+
+Next, we will use `DallE3` and `Vectorizer.AI` as examples to introduce how to use the variable pool.
+
+- `DallE3` is an image generation tool that can generate images based on text. Here, we will let `DallE3` generate a logo for a coffee shop
+- `Vectorizer.AI` is a vector image conversion tool that can convert images into vector images, so that the images can be infinitely enlarged without distortion. Here, we will convert the PNG icon generated by `DallE3` into a vector image, so that it can be truly used by designers.
+
+#### DallE3
+First, we use DallE3. After creating the image, we save the image to the variable pool. The code is as follows:
+
+```python
+from typing import Any, Dict, List, Union
+from core.tools.entities.tool_entities import ToolInvokeMessage
+from core.tools.tool.builtin_tool import BuiltinTool
+
+from base64 import b64decode
+
+from openai import OpenAI
+
+class DallE3Tool(BuiltinTool):
+    def _invoke(self, 
+                user_id: str, 
+               tool_paramters: Dict[str, Any], 
+        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        client = OpenAI(
+            api_key=self.runtime.credentials['openai_api_key'],
+        )
+
+        # prompt
+        prompt = tool_paramters.get('prompt', '')
+        if not prompt:
+            return self.create_text_message('Please input prompt')
+
+        # call openapi dalle3
+        response = client.images.generate(
+            prompt=prompt, model='dall-e-3',
+            size='1024x1024', n=1, style='vivid', quality='standard',
+            response_format='b64_json'
+        )
+
+        result = []
+        for image in response.data:
+            # Save all images to the variable pool through the save_as parameter. The variable name is self.VARIABLE_KEY.IMAGE.value. If new images are generated later, they will overwrite the previous images.
+            result.append(self.create_blob_message(blob=b64decode(image.b64_json), 
+                                                   meta={ 'mime_type': 'image/png' },
+                                                    save_as=self.VARIABLE_KEY.IMAGE.value))
+
+        return result
+```
+
+Note that we used `self.VARIABLE_KEY.IMAGE.value` as the variable name of the image. In order for developers' tools to cooperate with each other, we defined this `KEY`. You can use it freely, or you can choose not to use this `KEY`. Passing a custom KEY is also acceptable.
+
+#### Vectorizer.AI
+Next, we use Vectorizer.AI to convert the PNG icon generated by DallE3 into a vector image. Let's go through the functions we defined here. The code is as follows:
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from typing import Any, Dict, List, Union
+from httpx import post
+from base64 import b64decode
+
+class VectorizerTool(BuiltinTool):
+    def _invoke(self, user_id: str, tool_paramters: Dict[str, Any]) \
+        -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+        Tool invocation, the image variable name needs to be passed in from here, so that we can get the image from the variable pool
+        """
+        
+    
+    def get_runtime_parameters(self) -> List[ToolParamter]:
+        """
+        Override the tool parameter list, we can dynamically generate the parameter list based on the actual situation in the current variable pool, so that the LLM can generate the form based on the parameter list
+        """
+        
+    
+    def is_tool_avaliable(self) -> bool:
+        """
+        Whether the current tool is available, if there is no image in the current variable pool, then we don't need to display this tool, just return False here
+        """     
+```
+
+Next, let's implement these three functions
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from typing import Any, Dict, List, Union
+from httpx import post
+from base64 import b64decode
+
+class VectorizerTool(BuiltinTool):
+    def _invoke(self, user_id: str, tool_paramters: Dict[str, Any]) \
+        -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        api_key_name = self.runtime.credentials.get('api_key_name', None)
+        api_key_value = self.runtime.credentials.get('api_key_value', None)
+
+        if not api_key_name or not api_key_value:
+            raise ToolProviderCredentialValidationError('Please input api key name and value')
+
+        # Get image_id, the definition of image_id can be found in get_runtime_parameters
+        image_id = tool_paramters.get('image_id', '')
+        if not image_id:
+            return self.create_text_message('Please input image id')
+
+        # Get the image generated by DallE from the variable pool
+        image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)
+        if not image_binary:
+            return self.create_text_message('Image not found, please request user to generate image firstly.')
+
+        # Generate vector image
+        response = post(
+            'https://vectorizer.ai/api/v1/vectorize',
+            files={ 'image': image_binary },
+            data={ 'mode': 'test' },
+            auth=(api_key_name, api_key_value), 
+            timeout=30
+        )
+
+        if response.status_code != 200:
+            raise Exception(response.text)
+        
+        return [
+            self.create_text_message('the vectorized svg is saved as an image.'),
+            self.create_blob_message(blob=response.content,
+                                    meta={'mime_type': 'image/svg+xml'})
+        ]
+    
+    def get_runtime_parameters(self) -> List[ToolParamter]:
+        """
+        override the runtime parameters
+        """
+        # Here, we override the tool parameter list, define the image_id, and set its option list to all images in the current variable pool. The configuration here is consistent with the configuration in yaml.
+        return [
+            ToolParamter.get_simple_instance(
+                name='image_id',
+                llm_description=f'the image id that you want to vectorize, \
+                    and the image id should be specified in \
+                        {[i.name for i in self.list_default_image_variables()]}',
+                type=ToolParamter.ToolParameterType.SELECT,
+                required=True,
+                options=[i.name for i in self.list_default_image_variables()]
+            )
+        ]
+    
+    def is_tool_avaliable(self) -> bool:
+        # Only when there are images in the variable pool, the LLM needs to use this tool
+        return len(self.list_default_image_variables()) > 0
+```
+
+It's worth noting that we didn't actually use `image_id` here. We assumed that there must be an image in the default variable pool when calling this tool, so we directly used `image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)` to get the image. In cases where the model's capabilities are weak, we recommend developers to do the same, which can effectively improve fault tolerance and avoid the model passing incorrect parameters.

api/core/tools/docs/en_US/tool_scale_out.md

@@ -0,0 +1,212 @@
+# Quick Tool Integration
+
+Here, we will use GoogleSearch as an example to demonstrate how to quickly integrate a tool.
+
+## 1. Prepare the Tool Provider yaml
+
+### Introduction
+This yaml declares a new tool provider, and includes information like the provider's name, icon, author, and other details that are fetched by the frontend for display.
+
+### Example
+
+We need to create a `google` module (folder) under `core/tools/provider/builtin`, and create `google.yaml`. The name must be consistent with the module name.
+
+Subsequently, all operations related to this tool will be carried out under this module.
+
+```yaml
+identity: # Basic information of the tool provider
+  author: Dify # Author
+  name: google # Name, unique, no duplication with 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 # Icon, needs to be placed in the _assets folder of the current module
+
+```
+ - The `identity` field is mandatory, it contains the basic information of the tool provider, including author, name, label, description, icon, etc.
+    - The icon needs to be placed in the `_assets` folder of the current module, you can refer to [here](../../provider/builtin/google/_assets/icon.svg).
+
+## 2. Prepare Provider Credentials
+
+Google, as a third-party tool, uses the API provided by SerpApi, which requires an API Key to use. This means that this tool needs a credential to use. For tools like `wikipedia`, there is no need to fill in the credential field, you can refer to [here](../../provider/builtin/wikipedia/wikipedia.yaml).
+
+After configuring the credential field, the effect is as follows:
+```yaml
+identity:
+  author: Dify
+  name: google
+  label:
+    en_US: Google
+    zh_Hans: Google
+  description:
+    en_US: Google
+    zh_Hans: Google
+  icon: icon.svg
+credentails_for_provider: # Credential field
+  serpapi_api_key: # Credential field name
+    type: secret-input # Credential field type
+    required: true # Required or not
+    label: # Credential field label
+      en_US: SerpApi API key # English label
+      zh_Hans: SerpApi API key # Chinese label
+    placeholder: # Credential field placeholder
+      en_US: Please input your SerpApi API key # English placeholder
+      zh_Hans: 请输入你的 SerpApi API key # Chinese placeholder
+    help: # Credential field help text
+      en_US: Get your SerpApi API key from SerpApi # English help text
+      zh_Hans: 从 SerpApi 获取您的 SerpApi API key # Chinese help text
+    url: https://serpapi.com/manage-api-key # Credential field help link
+
+```
+
+- `type`: Credential field type, currently can be either `secret-input`, `text-input`, or `select` , corresponding to password input box, text input box, and drop-down box, respectively. If set to `secret-input`, it will mask the input content on the frontend, and the backend will encrypt the input content.
+
+## 3. Prepare Tool yaml
+A provider can have multiple tools, each tool needs a yaml file to describe, this file contains the basic information, parameters, output, etc. of the tool.
+
+Still taking GoogleSearch as an example, we need to create a `tools` module under the `google` module, and create `tools/google_search.yaml`, the content is as follows.
+
+```yaml
+identity: # Basic information of the tool
+  name: google_search # Tool name, unique, no duplication with other tools
+  author: Dify # Author
+  label: # Label for frontend display
+    en_US: GoogleSearch # English label
+    zh_Hans: 谷歌搜索 # Chinese label
+description: # Description for frontend display
+  human: # Introduction for frontend display, supports multiple languages
+    en_US: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query.
+    zh_Hans: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
+  llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query. # Introduction passed to LLM, in order to make LLM better understand this tool, we suggest to write as detailed information about this tool as possible here, so that LLM can understand and use this tool
+parameters: # Parameter list
+  - name: query # Parameter name
+    type: string # Parameter type
+    required: true # Required or not
+    label: # Parameter label
+      en_US: Query string # English label
+      zh_Hans: 查询语句 # Chinese label
+    human_description: # Introduction for frontend display, supports multiple languages
+      en_US: used for searching
+      zh_Hans: 用于搜索网页内容
+    llm_description: key words for searching # Introduction passed to LLM, similarly, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter
+    form: llm # Form type, llm means this parameter needs to be inferred by Agent, the frontend will not display this parameter
+  - name: result_type
+    type: select # Parameter type
+    required: true
+    options: # Drop-down box options
+      - value: text
+        label:
+          en_US: text
+          zh_Hans: 文本
+      - value: link
+        label:
+          en_US: link
+          zh_Hans: 链接
+    default: link
+    label:
+      en_US: Result type
+      zh_Hans: 结果类型
+    human_description:
+      en_US: used for selecting the result type, text or link
+      zh_Hans: 用于选择结果类型，使用文本还是链接进行展示
+    form: form # Form type, form means this parameter needs to be filled in by the user on the frontend before the conversation starts
+
+```
+
+- The `identity` field is mandatory, it contains the basic information of the tool, including name, author, label, description, etc.
+- `parameters` Parameter list
+    - `name` Parameter name, unique, no duplication with other parameters
+    - `type` Parameter type, currently supports `string`, `number`, `boolean`, `select` four types, corresponding to string, number, boolean, drop-down box
+    - `required` Required or not
+        - In `llm` mode, if the parameter is required, the Agent is required to infer this parameter
+        - In `form` mode, if the parameter is required, the user is required to fill in this parameter on the frontend before the conversation starts
+    - `options` Parameter options
+        - In `llm` mode, Dify will pass all options to LLM, LLM can infer based on these options
+        - In `form` mode, when `type` is `select`, the frontend will display these options
+    - `default` Default value
+    - `label` Parameter label, for frontend display
+    - `human_description` Introduction for frontend display, supports multiple languages
+    - `llm_description` Introduction passed to LLM, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter
+    - `form` Form type, currently supports `llm`, `form` two types, corresponding to Agent self-inference and frontend filling
+
+## 4. Add Tool Logic
+After completing the tool configuration, we can start writing the tool code that defines how it is invoked.
+
+Create `google_search.py` under the `google/tools` module, the content is as follows.
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage
+
+from typing import Any, Dict, List, Union
+
+class GoogleSearchTool(BuiltinTool):
+    def _invoke(self, 
+                user_id: str,
+               tool_paramters: Dict[str, Any], 
+        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        query = tool_paramters['query']
+        result_type = tool_paramters['result_type']
+        api_key = self.runtime.credentials['serpapi_api_key']
+        # TODO: search with serpapi
+        result = SerpAPI(api_key).run(query, result_type=result_type)
+
+        if result_type == 'text':
+            return self.create_text_message(text=result)
+        return self.create_link_message(link=result)
+```
+
+### Parameters
+The overall logic of the tool is in the `_invoke` method, this method accepts two parameters: `user_id` and `tool_paramters`, which represent the user ID and tool parameters respectively
+
+### Return Data
+When the tool returns, you can choose to return one message or multiple messages, here we return one message, using `create_text_message` and `create_link_message` can create a text message or a link message.
+
+## 5. Add Provider Code
+Finally, we need to create a provider class under the provider module to implement the provider's credential verification logic. If the credential verification fails, it will throw a `ToolProviderCredentialValidationError` exception.
+
+Create `google.py` under the `google` module, the content is as follows.
+
+```python
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
+from core.tools.tool.tool import Tool
+from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool
+
+from typing import Any, Dict
+
+class GoogleProvider(BuiltinToolProviderController):
+    def _validate_credentials(self, credentials: Dict[str, Any]) -> None:
+        try:
+            # 1. Here you need to instantiate a GoogleSearchTool with GoogleSearchTool(), it will automatically load the yaml configuration of GoogleSearchTool, but at this time it does not have credential information inside
+            # 2. Then you need to use the fork_tool_runtime method to pass the current credential information to GoogleSearchTool
+            # 3. Finally, invoke it, the parameters need to be passed according to the parameter rules configured in the yaml of GoogleSearchTool
+            GoogleSearchTool().fork_tool_runtime(
+                meta={
+                    "credentials": credentials,
+                }
+            ).invoke(
+                user_id='',
+                tool_paramters={
+                    "query": "test",
+                    "result_type": "link"
+                },
+            )
+        except Exception as e:
+            raise ToolProviderCredentialValidationError(str(e))
+```
+
+## Completion
+After the above steps are completed, we can see this tool on the frontend, and it can be used in the Agent.
+
+Of course, because google_search needs a credential, before using it, you also need to input your credentials on the frontend.
+
+![Alt text](../zh_Hans/images/index/image-2.png)

api/core/tools/docs/zh_Hans/advanced_scale_out.md

@@ -0,0 +1,266 @@
+# 高级接入Tool
+
+在开始高级接入之前，请确保你已经阅读过[快速接入](./tool_scale_out.md)，并对Dify的工具接入流程有了基本的了解。
+
+## 工具接口
+
+我们在`Tool`类中定义了一系列快捷方法，用于帮助开发者快速构较为复杂的工具
+
+### 消息返回
+
+Dify支持`文本` `链接` `图片` `文件BLOB` 等多种消息类型，你可以通过以下几个接口返回不同类型的消息给LLM和用户。
+
+注意，在下面的接口中的部分参数将在后面的章节中介绍。
+
+#### 图片URL
+只需要传递图片的URL即可，Dify会自动下载图片并返回给用户。
+
+```python
+    def create_image_message(self, image: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create an image message
+
+            :param image: the url of the image
+            :return: the image message
+        """
+```
+
+#### 链接
+如果你需要返回一个链接，可以使用以下接口。
+
+```python
+    def create_link_message(self, link: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a link message
+
+            :param link: the url of the link
+            :return: the link message
+        """
+```
+
+#### 文本
+如果你需要返回一个文本消息，可以使用以下接口。
+
+```python
+    def create_text_message(self, text: str, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a text message
+
+            :param text: the text of the message
+            :return: the text message
+        """
+```
+
+#### 文件BLOB
+如果你需要返回文件的原始数据，如图片、音频、视频、PPT、Word、Excel等，可以使用以下接口。
+
+- `blob` 文件的原始数据，bytes类型
+- `meta` 文件的元数据，如果你知道该文件的类型，最好传递一个`mime_type`，否则Dify将使用`octet/stream`作为默认类型
+
+```python
+    def create_blob_message(self, blob: bytes, meta: dict = None, save_as: str = '') -> ToolInvokeMessage:
+        """
+            create a blob message
+
+            :param blob: the blob
+            :return: the blob message
+        """
+```
+
+### 快捷工具
+
+在大模型应用中，我们有两种常见的需求：
+- 先将很长的文本进行提前总结，然后再将总结内容传递给LLM，以防止原文本过长导致LLM无法处理
+- 工具获取到的内容是一个链接，需要爬取网页信息后再返回给LLM
+
+为了帮助开发者快速实现这两种需求，我们提供了以下两个快捷工具。
+
+#### 文本总结工具
+
+该工具需要传入user_id和需要进行总结的文本，返回一个总结后的文本，Dify会使用当前工作空间的默认模型对长文本进行总结。
+
+```python
+    def summary(self, user_id: str, content: str) -> str:
+        """
+            summary the content
+
+            :param user_id: the user id
+            :param content: the content
+            :return: the summary
+        """
+```
+
+#### 网页爬取工具
+
+该工具需要传入需要爬取的网页链接和一个user_agent（可为空），返回一个包含该网页信息的字符串，其中`user_agent`是可选参数，可以用来识别工具，如果不传递，Dify将使用默认的`user_agent`。
+
+```python
+    def get_url(self, url: str, user_agent: str = None) -> str:
+        """
+            get url
+        """ the crawled result
+```
+
+### 变量池
+
+我们在`Tool`中引入了一个变量池，用于存储工具运行过程中产生的变量、文件等，这些变量可以在工具运行过程中被其他工具使用。
+
+下面，我们以`DallE3`和`Vectorizer.AI`为例，介绍如何使用变量池。
+
+- `DallE3`是一个图片生成工具，它可以根据文本生成图片，在这里，我们将让`DallE3`生成一个咖啡厅的Logo
+- `Vectorizer.AI`是一个矢量图转换工具，它可以将图片转换为矢量图，使得图片可以无限放大而不失真，在这里，我们将`DallE3`生成的PNG图标转换为矢量图，从而可以真正被设计师使用。
+
+#### DallE3
+首先我们使用DallE3，在创建完图片以后，我们将图片保存到变量池中，代码如下
+
+```python
+from typing import Any, Dict, List, Union
+from core.tools.entities.tool_entities import ToolInvokeMessage
+from core.tools.tool.builtin_tool import BuiltinTool
+
+from base64 import b64decode
+
+from openai import OpenAI
+
+class DallE3Tool(BuiltinTool):
+    def _invoke(self, 
+                user_id: str, 
+               tool_paramters: Dict[str, Any], 
+        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        client = OpenAI(
+            api_key=self.runtime.credentials['openai_api_key'],
+        )
+
+        # prompt
+        prompt = tool_paramters.get('prompt', '')
+        if not prompt:
+            return self.create_text_message('Please input prompt')
+
+        # call openapi dalle3
+        response = client.images.generate(
+            prompt=prompt, model='dall-e-3',
+            size='1024x1024', n=1, style='vivid', quality='standard',
+            response_format='b64_json'
+        )
+
+        result = []
+        for image in response.data:
+            # 将所有图片通过save_as参数保存到变量池中，变量名为self.VARIABLE_KEY.IMAGE.value，如果如果后续有新的图片生成，那么将会覆盖之前的图片
+            result.append(self.create_blob_message(blob=b64decode(image.b64_json), 
+                                                   meta={ 'mime_type': 'image/png' },
+                                                    save_as=self.VARIABLE_KEY.IMAGE.value))
+
+        return result
+```
+
+我们可以注意到这里我们使用了`self.VARIABLE_KEY.IMAGE.value`作为图片的变量名，为了便于开发者们的工具能够互相配合，我们定义了这个`KEY`，大家可以自由使用，也可以不使用这个`KEY`，传递一个自定义的KEY也是可以的。
+
+#### Vectorizer.AI
+接下来我们使用Vectorizer.AI，将DallE3生成的PNG图标转换为矢量图，我们先来过一遍我们在这里定义的函数，代码如下
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from typing import Any, Dict, List, Union
+from httpx import post
+from base64 import b64decode
+
+class VectorizerTool(BuiltinTool):
+    def _invoke(self, user_id: str, tool_paramters: Dict[str, Any]) \
+        -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+        工具调用，图片变量名需要从这里传递进来，从而我们就可以从变量池中获取到图片
+        """
+        
+    
+    def get_runtime_parameters(self) -> List[ToolParamter]:
+        """
+        重写工具参数列表，我们可以根据当前变量池里的实际情况来动态生成参数列表，从而LLM可以根据参数列表来生成表单
+        """
+        
+    
+    def is_tool_avaliable(self) -> bool:
+        """
+        当前工具是否可用，如果当前变量池中没有图片，那么我们就不需要展示这个工具，这里返回False即可
+        """     
+```
+
+接下来我们来实现这三个函数
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolParamter
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from typing import Any, Dict, List, Union
+from httpx import post
+from base64 import b64decode
+
+class VectorizerTool(BuiltinTool):
+    def _invoke(self, user_id: str, tool_paramters: Dict[str, Any]) \
+        -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        api_key_name = self.runtime.credentials.get('api_key_name', None)
+        api_key_value = self.runtime.credentials.get('api_key_value', None)
+
+        if not api_key_name or not api_key_value:
+            raise ToolProviderCredentialValidationError('Please input api key name and value')
+
+        # 获取image_id，image_id的定义可以在get_runtime_parameters中找到
+        image_id = tool_paramters.get('image_id', '')
+        if not image_id:
+            return self.create_text_message('Please input image id')
+
+        # 从变量池中获取到之前DallE生成的图片
+        image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)
+        if not image_binary:
+            return self.create_text_message('Image not found, please request user to generate image firstly.')
+
+        # 生成矢量图
+        response = post(
+            'https://vectorizer.ai/api/v1/vectorize',
+            files={ 'image': image_binary },
+            data={ 'mode': 'test' },
+            auth=(api_key_name, api_key_value), 
+            timeout=30
+        )
+
+        if response.status_code != 200:
+            raise Exception(response.text)
+        
+        return [
+            self.create_text_message('the vectorized svg is saved as an image.'),
+            self.create_blob_message(blob=response.content,
+                                    meta={'mime_type': 'image/svg+xml'})
+        ]
+    
+    def get_runtime_parameters(self) -> List[ToolParamter]:
+        """
+        override the runtime parameters
+        """
+        # 这里，我们重写了工具参数列表，定义了image_id，并设置了它的选项列表为当前变量池中的所有图片，这里的配置与yaml中的配置是一致的
+        return [
+            ToolParamter.get_simple_instance(
+                name='image_id',
+                llm_description=f'the image id that you want to vectorize, \
+                    and the image id should be specified in \
+                        {[i.name for i in self.list_default_image_variables()]}',
+                type=ToolParamter.ToolParameterType.SELECT,
+                required=True,
+                options=[i.name for i in self.list_default_image_variables()]
+            )
+        ]
+    
+    def is_tool_avaliable(self) -> bool:
+        # 只有当变量池中有图片时，LLM才需要使用这个工具
+        return len(self.list_default_image_variables()) > 0
+```
+
+可以注意到的是，我们这里其实并没有使用到`image_id`，我们已经假设了调用这个工具的时候一定有一张图片在默认的变量池中，所以直接使用了`image_binary = self.get_variable_file(self.VARIABLE_KEY.IMAGE)`来获取图片，在模型能力较弱的情况下，我们建议开发者们也这样做，可以有效提升容错率，避免模型传递错误的参数。

api/core/tools/docs/zh_Hans/tool_scale_out.md

@@ -0,0 +1,212 @@
+# 快速接入Tool
+
+这里我们以GoogleSearch为例，介绍如何快速接入一个工具。
+
+## 1. 准备工具供应商yaml
+
+### 介绍
+这个yaml将包含工具供应商的信息，包括供应商名称、图标、作者等详细信息，以帮助前端灵活展示。
+
+### 示例
+
+我们需要在 `core/tools/provider/builtin`下创建一个`google`模块（文件夹），并创建`google.yaml`，名称必须与模块名称一致。
+
+后续，我们关于这个工具的所有操作都将在这个模块下进行。
+
+```yaml
+identity: # 工具供应商的基本信息
+  author: Dify # 作者
+  name: google # 名称，唯一，不允许和其他供应商重名
+  label: # 标签，用于前端展示
+    en_US: Google # 英文标签
+    zh_Hans: Google # 中文标签
+  description: # 描述，用于前端展示
+    en_US: Google # 英文描述
+    zh_Hans: Google # 中文描述
+  icon: icon.svg # 图标，需要放置在当前模块的_assets文件夹下
+
+```
+ - `identity` 字段是必须的，它包含了工具供应商的基本信息，包括作者、名称、标签、描述、图标等
+    - 图标需要放置在当前模块的`_assets`文件夹下，可以参考[这里](../../provider/builtin/google/_assets/icon.svg)。
+
+## 2. 准备供应商凭据
+
+Google作为一个第三方工具，使用了SerpApi提供的API，而SerpApi需要一个API Key才能使用，那么就意味着这个工具需要一个凭据才可以使用，而像`wikipedia`这样的工具，就不需要填写凭据字段，可以参考[这里](../../provider/builtin/wikipedia/wikipedia.yaml)。
+
+配置好凭据字段后效果如下：
+```yaml
+identity:
+  author: Dify
+  name: google
+  label:
+    en_US: Google
+    zh_Hans: Google
+  description:
+    en_US: Google
+    zh_Hans: Google
+  icon: icon.svg
+credentails_for_provider: # 凭据字段
+  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: 请输入你的 SerpApi API key # 中文占位符
+    help: # 凭据字段帮助文本
+      en_US: Get your SerpApi API key from SerpApi # 英文帮助文本
+      zh_Hans: 从 SerpApi 获取您的 SerpApi API key # 中文帮助文本
+    url: https://serpapi.com/manage-api-key # 凭据字段帮助链接
+
+```
+
+- `type`：凭据字段类型，目前支持`secret-input`、`text-input`、`select` 三种类型，分别对应密码输入框、文本输入框、下拉框，如果为`secret-input`，则会在前端隐藏输入内容，并且后端会对输入内容进行加密。
+
+## 3. 准备工具yaml
+一个供应商底下可以有多个工具，每个工具都需要一个yaml文件来描述，这个文件包含了工具的基本信息、参数、输出等。
+
+仍然以GoogleSearch为例，我们需要在`google`模块下创建一个`tools`模块，并创建`tools/google_search.yaml`，内容如下。
+
+```yaml
+identity: # 工具的基本信息
+  name: google_search # 工具名称，唯一，不允许和其他工具重名
+  author: Dify # 作者
+  label: # 标签，用于前端展示
+    en_US: GoogleSearch # 英文标签
+    zh_Hans: 谷歌搜索 # 中文标签
+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: 一个用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询。
+  llm: A tool for performing a Google SERP search and extracting snippets and webpages.Input should be a search query. # 传递给LLM的介绍，为了使得LLM更好理解这个工具，我们建议在这里写上关于这个工具尽可能详细的信息，让LLM能够理解并使用这个工具
+parameters: # 参数列表
+  - name: query # 参数名称
+    type: string # 参数类型
+    required: true # 是否必填
+    label: # 参数标签
+      en_US: Query string # 英文标签
+      zh_Hans: 查询语句 # 中文标签
+    human_description: # 用于前端展示的介绍，支持多语言
+      en_US: used for searching
+      zh_Hans: 用于搜索网页内容
+    llm_description: key words for searching # 传递给LLM的介绍，同上，为了使得LLM更好理解这个参数，我们建议在这里写上关于这个参数尽可能详细的信息，让LLM能够理解这个参数
+    form: llm # 表单类型，llm表示这个参数需要由Agent自行推理出来，前端将不会展示这个参数
+  - name: result_type
+    type: select # 参数类型
+    required: true
+    options: # 下拉框选项
+      - value: text
+        label:
+          en_US: text
+          zh_Hans: 文本
+      - value: link
+        label:
+          en_US: link
+          zh_Hans: 链接
+    default: link
+    label:
+      en_US: Result type
+      zh_Hans: 结果类型
+    human_description:
+      en_US: used for selecting the result type, text or link
+      zh_Hans: 用于选择结果类型，使用文本还是链接进行展示
+    form: form # 表单类型，form表示这个参数需要由用户在对话开始前在前端填写
+
+```
+
+- `identity` 字段是必须的，它包含了工具的基本信息，包括名称、作者、标签、描述等
+- `parameters` 参数列表
+    - `name` 参数名称，唯一，不允许和其他参数重名
+    - `type` 参数类型，目前支持`string`、`number`、`boolean`、`select` 四种类型，分别对应字符串、数字、布尔值、下拉框
+    - `required` 是否必填
+        - 在`llm`模式下，如果参数为必填，则会要求Agent必须要推理出这个参数
+        - 在`form`模式下，如果参数为必填，则会要求用户在对话开始前在前端填写这个参数
+    - `options` 参数选项
+        - 在`llm`模式下，Dify会将所有选项传递给LLM，LLM可以根据这些选项进行推理
+        - 在`form`模式下，`type`为`select`时，前端会展示这些选项
+    - `default` 默认值
+    - `label` 参数标签，用于前端展示
+    - `human_description` 用于前端展示的介绍，支持多语言
+    - `llm_description` 传递给LLM的介绍，为了使得LLM更好理解这个参数，我们建议在这里写上关于这个参数尽可能详细的信息，让LLM能够理解这个参数
+    - `form` 表单类型，目前支持`llm`、`form`两种类型，分别对应Agent自行推理和前端填写
+
+## 4. 准备工具代码
+当完成工具的配置以后，我们就可以开始编写工具代码了，主要用于实现工具的逻辑。
+
+在`google/tools`模块下创建`google_search.py`，内容如下。
+
+```python
+from core.tools.tool.builtin_tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeMessage
+
+from typing import Any, Dict, List, Union
+
+class GoogleSearchTool(BuiltinTool):
+    def _invoke(self, 
+                user_id: str,
+               tool_paramters: Dict[str, Any], 
+        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
+        """
+            invoke tools
+        """
+        query = tool_paramters['query']
+        result_type = tool_paramters['result_type']
+        api_key = self.runtime.credentials['serpapi_api_key']
+        # TODO: search with serpapi
+        result = SerpAPI(api_key).run(query, result_type=result_type)
+
+        if result_type == 'text':
+            return self.create_text_message(text=result)
+        return self.create_link_message(link=result)
+```
+
+### 参数
+工具的整体逻辑都在`_invoke`方法中，这个方法接收两个参数：`user_id`和`tool_paramters`，分别表示用户ID和工具参数
+
+### 返回数据
+在工具返回时，你可以选择返回一个消息或者多个消息，这里我们返回一个消息，使用`create_text_message`和`create_link_message`可以创建一个文本消息或者一个链接消息。
+
+## 5. 准备供应商代码
+最后，我们需要在供应商模块下创建一个供应商类，用于实现供应商的凭据验证逻辑，如果凭据验证失败，将会抛出`ToolProviderCredentialValidationError`异常。
+
+在`google`模块下创建`google.py`，内容如下。
+
+```python
+from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
+from core.tools.tool.tool import Tool
+from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
+from core.tools.errors import ToolProviderCredentialValidationError
+
+from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool
+
+from typing import Any, Dict
+
+class GoogleProvider(BuiltinToolProviderController):
+    def _validate_credentials(self, credentials: Dict[str, Any]) -> None:
+        try:
+            # 1. 此处需要使用GoogleSearchTool()实例化一个GoogleSearchTool，它会自动加载GoogleSearchTool的yaml配置，但是此时它内部没有凭据信息
+            # 2. 随后需要使用fork_tool_runtime方法，将当前的凭据信息传递给GoogleSearchTool
+            # 3. 最后invoke即可，参数需要根据GoogleSearchTool的yaml中配置的参数规则进行传递
+            GoogleSearchTool().fork_tool_runtime(
+                meta={
+                    "credentials": credentials,
+                }
+            ).invoke(
+                user_id='',
+                tool_paramters={
+                    "query": "test",
+                    "result_type": "link"
+                },
+            )
+        except Exception as e:
+            raise ToolProviderCredentialValidationError(str(e))
+```
+
+## 完成
+当上述步骤完成以后，我们就可以在前端看到这个工具了，并且可以在Agent中使用这个工具。
+
+当然，因为google_search需要一个凭据，在使用之前，还需要在前端配置它的凭据。
+
+![Alt text](images/index/image-2.png)