mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
136 lines
4.6 KiB
Plaintext
136 lines
4.6 KiB
Plaintext
---
|
|
dimensions:
|
|
type:
|
|
primary: reference
|
|
detail: core
|
|
level: beginner
|
|
standard_title: Tool
|
|
language: en
|
|
title: Tool Return
|
|
description: 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.
|
|
|
|
```python
|
|
def create_image_message(self, image: str) -> ToolInvokeMessage:
|
|
pass
|
|
```
|
|
|
|
#### **Link**
|
|
|
|
If you need to return a link, use the following interface.
|
|
|
|
```python
|
|
def create_link_message(self, link: str) -> ToolInvokeMessage:
|
|
pass
|
|
```
|
|
|
|
#### **Text**
|
|
|
|
If you need to return a text message, use the following interface.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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`](https://json-schema.org/) format. Here's a simple example:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
{/*
|
|
Contributing Section
|
|
DO NOT edit this section!
|
|
It will be automatically generated by the script.
|
|
*/}
|
|
|
|
---
|
|
|
|
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/plugin-dev-en/0411-tool.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
|
|
|