Skip to main content
⚠️ 本文档由 AI 自动翻译。如有任何不准确之处,请参考英文原版

概述

在深入了解详细的接口文档之前,请确保您对 Dify 插件的工具集成流程有基本的了解。

数据结构

消息返回

Dify 支持多种消息类型,如 textlinksimagesfile BLOBsJSON。这些消息可以通过专用接口返回。
默认情况下,工作流中工具的输出包含三个固定变量:filestextjson。以下方法可帮助您为这些变量填充适当的内容。
虽然您可以使用 create_image_message 等方法返回图片,但工具也支持自定义输出变量,这使得在工作流中引用特定数据更加方便。

消息类型

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
image
string
required
将被下载并显示的图片 URL
将显示为可点击链接的 URL
text
string
required
要显示的文本内容
blob
bytes
required
字节格式的原始文件数据
meta
dict
文件元数据,包括:
  • mime_type:文件的 MIME 类型(例如 “image/png”)
  • 与文件相关的其他元数据
json
dict
required
要序列化为 JSON 的 Python 字典
处理文件 blob 时,请始终在 meta 字典中指定 mime_type,以确保文件得到正确处理。例如:{"mime_type": "image/png"}

变量

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
variable_name
string
required
要创建或更新的变量名称
variable_value
Any/string
required
要分配给变量的值:
  • 对于标准变量:任何 Python 数据类型
  • 对于流式变量:仅支持字符串数据
流式变量方法(create_stream_variable_message)目前仅支持字符串数据。复杂数据类型无法通过打字机效果进行流式输出。

自定义输出变量

要在工作流应用中引用工具的输出变量,您需要定义可能输出的变量。这是通过在工具清单中使用 JSON 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
output_schema
object
required
定义工具输出模式的根对象
type
string
required
工具输出模式必须为 “object”
properties
object
required
所有可能输出变量的字典
properties.[variable_name]
object
每个输出变量的定义,包括其类型和描述
即使定义了输出模式,您仍需要在实现代码中使用 create_variable_message() 实际返回变量。否则,工作流将收到该变量的 None 值。

实现示例

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)
对于复杂的工作流,您可以定义多个输出变量并全部返回。这为工作流设计者使用您的工具时提供了更大的灵活性。

示例

完整的工具实现

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"
        }
设计工具时,请同时考虑直接输出(用户看到的内容)和变量输出(其他工作流节点可以使用的内容)。这种分离为工具的使用方式提供了灵活性。

Edit this page | Report an issue