Skip to main content

Overview#

A tool returns its results as messages and variables. This page covers the message interfaces, variable creation, and output schema definitions.

Data Structure#

Message Return#

Dify supports several message types—text, links, images, file blobs, and JSON—each returned through a dedicated interface.

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

Tip

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

Message Types#

Parameters
imagestringrequired#

URL to an image that will be downloaded and displayed.

textstringrequired#

Text content to display.

blobbytesrequired#

Raw file data in bytes.

metadict#

File metadata, including:

  • mime_type: The MIME type of the file, for example image/png.
  • Other metadata relevant to the file.
jsondictrequired#

Python dictionary to serialize as JSON.

Tip

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#

Parameters
variable_namestringrequired#

Name of the variable to create or update.

variable_valueAny/stringrequired#

Value to assign to the variable:

  • Standard variables: any Python data type.
  • Streaming variables: string data only.
Warning

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, declare which variables the tool might output using JSON Schema in the tool’s manifest.

Define Output Schema#

Schema Structure
output_schemaobjectrequired#

Root object defining the tool’s output schema.

typestringrequired#

Must be object for tool output schemas.

propertiesobjectrequired#

Dictionary of all possible output variables.

properties.[variable_name]object#

Definition of each output variable, including its type and description.

Warning

Defining an output schema is not enough on its own: your implementation must still return each variable with create_variable_message(). Otherwise, the workflow receives None for that variable.

Example Implementation#

Tip

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#

Tip

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.