Tool Return

Before reading the detailed interface documentation, please make sure you have a general understanding of the tool integration process for Dify plugins.

​

Data Structure

​

Message Return

Dify supports various message types such as text, links, images, file BLOBs, and JSON. You can return different types of messages through the following interfaces.

By default, a tool’s output in a workflow includes three fixed variables: files, text, and json. You can use the methods below to return data for these three variables.

For example, you can use create_image_message to return an image, but tools also support custom output variables, making it more convenient to reference these variables in a workflow.

​

Image URL

Simply pass the image URL, and Dify will automatically download the image through the link and return it to the user.

    def create_image_message(self, image: str) -> ToolInvokeMessage:
        pass

​

Link

If you need to return a link, use the following interface.

    def create_link_message(self, link: str) -> ToolInvokeMessage:
        pass

​

Text

If you need to return a text message, use the following interface.

    def create_text_message(self, text: str) -> ToolInvokeMessage:
        pass

File

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, in bytes type.
• meta The metadata of the file. If developers need a specific file type, please specify mime_type, otherwise Dify will use octet/stream as the default type.

    def create_blob_message(self, blob: bytes, meta: dict = None) -> ToolInvokeMessage:
        pass

​

JSON

If you need to return a formatted JSON, you can use the following interface. This is typically used for data transmission between nodes in a workflow. In agent mode, most large models can also read and understand JSON.

• object A Python dictionary object that will be automatically serialized to JSON.

    def create_json_message(self, json: dict) -> ToolInvokeMessage:
        pass

​

Variable

For non-streaming output variables, you can use the following interface to return them. If you create multiple instances, the latter will override the former.

    def create_variable_message(self, variable_name: str, variable_value: Any) -> ToolInvokeMessage:
        pass

​

Streaming Variable

If you want to output text with a “typewriter” effect, you can use streaming variables to output text. If you use an answer node in a chatflow application and reference this variable, the text will be output with a “typewriter” effect. However, currently this method only supports string type data.

    def create_stream_variable_message(
        self, variable_name: str, variable_value: str
    ) -> ToolInvokeMessage:

​

Returning Custom Variables

If you want to reference a tool’s output variables in a workflow application, it’s necessary to define in advance which variables might be output. Dify plugins support output variable definitions in json_schema format. Here’s a simple example:

identity:
  author: author
  name: tool
  label:
    en_US: label
    zh_Hans: 标签
    ja_JP: レベル
    pt_BR: etiqueta
description:
  human:
    en_US: description
    zh_Hans: 描述
    ja_JP: 説明
    pt_BR: descrição
  llm: description
output_schema:
  type: object
  properties:
    name:
      type: string

The example code above defines a simple tool and specifies an output_schema for it, which includes a name field that can be referenced in a workflow. However, please note that you still need to return a variable in the tool’s implementation code to actually use it, otherwise you will get a None return result.