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.

Overview

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

Message Types

Return different types of messages such as text, links, images, and JSON

Variables

Create and manipulate variables for workflow integration

Output Schema

Define custom output variables for workflow references

Data Structure

Message Return

Dify supports various message types such as text, links, images, file BLOBs, and JSON. These messages can be returned through specialized interfaces.

By default, a tool’s output in a workflow includes three fixed variables: files, text, and json. The methods below help you populate these variables with appropriate content.

While you can use methods like create_image_message to return an image, tools also support custom output variables, making it more convenient to reference specific data in a workflow.

Message Types

Image URL

def create_image_message(self, image: str) -> ToolInvokeMessage:
    """
    Return an image URL message
    
    Dify will automatically download the image from the provided URL
    and display it to the user.
    
    Args:
        image: URL to an image file
        
    Returns:
        ToolInvokeMessage: Message object for the tool response
    """
    pass

Parameters

image · string · required

URL to an image that will be downloaded and displayed

link · string · required

URL to be displayed as a clickable link

text · string · required

Text content to be displayed

blob · bytes · required

Raw file data in bytes format

meta · dict

File metadata including:

• mime_type: The MIME type of the file (e.g., “image/png”)
• Other metadata relevant to the file

json · dict · required

Python dictionary to be serialized as JSON

When working with file blobs, always specify the mime_type in the meta dictionary to ensure proper handling of the file. For example: {"mime_type": "image/png"}.

Variables

Standard Variable

from typing import Any

def create_variable_message(self, variable_name: str, variable_value: Any) -> ToolInvokeMessage:
    """
    Create a named variable for workflow integration
    
    For non-streaming output variables. If multiple instances with the 
    same name are created, the latest one overrides previous values.
    
    Args:
        variable_name: Name of the variable to create
        variable_value: Value of the variable (any Python data type)
        
    Returns:
        ToolInvokeMessage: Message object for the tool response
    """
    pass

Parameters

variable_name · string · required

Name of the variable to be created or updated

variable_value · Any/string · required

Value to assign to the variable:

• For standard variables: Any Python data type
• For streaming variables: String data only

The streaming variable method (create_stream_variable_message) currently only supports string data. Complex data types cannot be streamed with the typewriter effect.

Custom Output Variables

To reference a tool’s output variables in a workflow application, you need to define which variables might be output. This is done using the JSON Schema format in your tool’s manifest.

Defining Output Schema

Tool Manifest with Output Schema

identity:
  author: example_author
  name: example_tool
  label:
    en_US: Example Tool
    zh_Hans: 示例工具
    ja_JP: ツール例
    pt_BR: Ferramenta de exemplo
description:
  human:
    en_US: A simple tool that returns a name
    zh_Hans: 返回名称的简单工具
    ja_JP: 名前を返す簡単なツール
    pt_BR: Uma ferramenta simples que retorna um nome
  llm: A simple tool that returns a name variable
output_schema:
  type: object
  properties:
    name:
      type: string
      description: "The name returned by the tool"
    age:
      type: integer
      description: "The age returned by the tool"
    profile:
      type: object
      properties:
        interests:
          type: array
          items:
            type: string
        location:
          type: string

Schema Structure

output_schema · object · required

The root object defining your tool’s output schema

type · string · required

Must be “object” for tool output schemas

properties · object · required

Dictionary of all possible output variables

properties.[variable_name] · object

Definition for each output variable, including its type and description

Even with an output schema defined, you still need to actually return a variable using create_variable_message() in your implementation code. Otherwise, the workflow will receive None for that variable.

Example Implementation

Basic Variable Example

def run(self, inputs):
    # Process inputs and generate a name
    generated_name = "Alice"
    
    # Return the name as a variable that matches the output_schema
    return self.create_variable_message("name", generated_name)

For complex workflows, you can define multiple output variables and return them all. This gives workflow designers more flexibility when using your tool.

Examples

Complete Tool Implementation

Weather Forecast Tool

import requests
from typing import Any

class WeatherForecastTool:
    def run(self, inputs: dict) -> Any:
        # Get location from inputs
        location = inputs.get("location", "London")
        
        try:
            # Call weather API (example only)
            weather_data = self._get_weather_data(location)
            
            # Create variables for workflow use
            self.create_variable_message("temperature", weather_data["temperature"])
            self.create_variable_message("conditions", weather_data["conditions"])
            self.create_variable_message("forecast", weather_data["forecast"])
            
            # Create a JSON message for data transmission
            self.create_json_message(weather_data)
            
            # Create an image message for the weather map
            self.create_image_message(weather_data["map_url"])
            
            # Return a formatted text response
            return self.create_text_message(
                f"Weather in {location}: {weather_data['temperature']}°C, {weather_data['conditions']}. "
                f"Forecast: {weather_data['forecast']}"
            )
            
        except Exception as e:
            # Handle errors gracefully
            return self.create_text_message(f"Error retrieving weather data: {str(e)}")
    
    def _get_weather_data(self, location: str) -> dict:
        # Mock implementation - in a real tool, this would call a weather API
        return {
            "location": location,
            "temperature": 22,
            "conditions": "Partly Cloudy",
            "forecast": "Sunny with occasional showers tomorrow",
            "map_url": "https://example.com/weather-map.png"
        }

When designing tools, consider both the direct output (what the user sees) and the variable output (what other workflow nodes can use). This separation provides flexibility in how your tool is used.

---

Edit this page | Report an issue