Tool Return

This document provides a detailed introduction to the data structure and usage of Tools in Dify plugins. It covers how to return different types of messages (image URLs, links, text, files, JSON), how to create variable and streaming variable messages, and how to define tool output variable schemas for reference in workflows.

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.