mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
148 lines
5.5 KiB
Plaintext
148 lines
5.5 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.
|
|
*/}
|
|
|
|
<CardGroup cols="2">
|
|
<Card
|
|
title="Edit this page"
|
|
icon="pen-to-square"
|
|
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/plugin_dev_en/0411-tool.en.mdx"
|
|
>
|
|
Help improve our documentation by contributing directly
|
|
</Card>
|
|
<Card
|
|
title="Report an issue"
|
|
icon="github"
|
|
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20tool&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fplugin_dev_en%2F0411-tool.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
|
|
>
|
|
Found an error or have suggestions? Let us know
|
|
</Card>
|
|
</CardGroup>
|