Help: How to make a custom tool output include valid files?

[Area-Ivy]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

When I try to use a custom tool and make it output a file, the files field in the output is always empty ("files": []). How can I make it work properly? Could you explain how I should implement my backend program and define the schema so that the file output is handled correctly?

2. Additional context or comments

No response

[dosubot[bot]]

Hi @Area-Ivy! I'm Dosu and I’m helping the dify team.

To make your custom tool output valid files in Dify, you need to handle both the backend response and the output schema correctly:

Backend Implementation:
When your tool generates a file, use Dify's ToolFileManager to save the file (from raw bytes or a URL). Then, emit a ToolInvokeMessage of type LINK (or IMAGE_LINK/BINARY_LINK for images/binary files) and include a file object in the meta field. This file object must be an instance of the File class and should include metadata like tenant_id, type, transfer_method, related_id, filename, extension, mime_type, size, and storage_key. If you omit the file object or only provide a URL, the files field will remain empty in the output. See example and test.

Output Schema:
Define your tool's output schema to include file outputs. For a single file, use type "file"; for multiple files, use "arrayFile". Example:

{
  "type": "object",
  "properties": {
    "attachments": {
      "type": "arrayFile",
      "description": "Supporting files"
    }
  }
}

This schema ensures the frontend and backend recognize and display file outputs properly reference.

Common Pitfalls:

• If your backend doesn't provide the actual file content (e.g., the blob field is missing or empty), the output will be empty even if metadata or a URL is present. Always pass the file bytes when invoking the tool reference.
• In self-hosted Docker setups, make sure your FILES_URL and INTERNAL_FILES_URL are set correctly and the API service exposes the right port, so files are accessible to plugins and tools reference.

Checklist:

1. Use ToolFileManager to save files and get a file object.
2. Emit a ToolInvokeMessage with type LINK (or IMAGE_LINK/BINARY_LINK) and include the file object in meta.
3. Define your output schema with "file" or "arrayFile" types.
4. Ensure file content is actually provided, not just metadata.
5. Check your Docker and URL configs if files are not accessible.

If you follow these steps, your custom tool's files output should be populated and work as expected.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Area-Ivy]

Thank you for your reply@dosu, but I’m not familiar with the specific usage of the functions you mentioned, such as ToolFileManager and ToolInvokeMessage. Could you please provide a simple and complete Python example to demonstrate how they should be used?

[dosubot[bot]]

Here's a minimal Python example showing how to use ToolFileManager and ToolInvokeMessage to output a file from a custom tool in Dify:

from core.tools.tool_file_manager import ToolFileManager
from core.tools.entities.tool_entities import ToolInvokeMessage

def my_custom_tool_invoke(user_id, tenant_id, conversation_id):
    # 1. Prepare your file content and metadata
    file_bytes = b"Hello, world!"  # Your file content as bytes
    mimetype = "text/plain"        # MIME type of the file
    filename = "hello.txt"         # Optional: original filename

    # 2. Save the file using ToolFileManager
    tool_file_manager = ToolFileManager()
    tool_file = tool_file_manager.create_file_by_raw(
        user_id=user_id,
        tenant_id=tenant_id,
        conversation_id=conversation_id,
        file_binary=file_bytes,
        mimetype=mimetype,
        filename=filename,
    )

    # 3. Build the file URL (Dify convention)
    extension = ".txt"  # Or use a helper to guess from mimetype
    file_url = f"/files/tools/{tool_file.id}{extension}"

    # 4. Choose the correct message type
    if "image" in mimetype:
        msg_type = ToolInvokeMessage.MessageType.IMAGE_LINK
    else:
        msg_type = ToolInvokeMessage.MessageType.BINARY_LINK

    # 5. Emit the ToolInvokeMessage with file URL and metadata
    yield ToolInvokeMessage(
        type=msg_type,
        message=ToolInvokeMessage.TextMessage(text=file_url),
        meta={
            "mime_type": mimetype,
            "filename": filename,
            # You can add more metadata if needed
        }
    )

# Example usage:
for msg in my_custom_tool_invoke("user-123", "tenant-456", "conv-789"):
    print(msg)

This pattern fits directly into your custom tool's invoke method. The key steps are: save the file with ToolFileManager, construct the file URL, select the right ToolInvokeMessage type, and yield the message with the file metadata. Dify will handle the rest and populate the files output in the UI as expected. You can adapt this for images, PDFs, etc., by changing the mimetype and msg_type accordingly.
For more details, see the relevant code and tests in the Dify repo (ToolFileManager, ToolInvokeMessage, usage example).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Area-Ivy]

Thank you, but what I actually need is an independent external service that can be imported into Dify as a custom tool via a schema. The example you provided seems to be for developing a built-in (internal) tool, rather than an external custom tool.

[dosubot[bot]]

To integrate an independent external service as a custom tool in Dify and support file outputs, your external API must do two things: (1) define the output schema to include files, and (2) return file metadata in the response in a format Dify recognizes.

1. Define the output schema (OpenAPI example):
Your tool schema should use type file (for a single file) or arrayFile (for multiple files) in the output properties. For example:

{
  "type": "object",
  "properties": {
    "attachments": {
      "type": "arrayFile",
      "description": "Supporting files"
    }
  }
}

This tells Dify to expect file outputs in the attachments field. See schema reference.

2. Format your API response:
Your external service should return file metadata objects for each file. Each file object must include at least:

• dify_model_identity: must be "dify__file"
• transfer_method: one of "TOOL_FILE", "LOCAL_FILE", "REMOTE_URL", or "DATASOURCE_FILE"
• related_id: a unique file identifier (e.g., the file's ID in your system)
• filename, extension, mime_type, and (optionally) a signed url for download

Example response for a single file:

{
  "attachments": [
    {
      "dify_model_identity": "dify__file",
      "transfer_method": "REMOTE_URL",
      "related_id": "abc123",
      "filename": "report.pdf",
      "extension": ".pdf",
      "mime_type": "application/pdf",
      "url": "https://your-service.com/files/abc123?token=secure"
    }
  ]
}

Dify will convert these objects into file outputs and populate the files field in the UI if the metadata is correct and the file is accessible. See webhook/file handling logic.

Caveats:

• The file must be accessible via the provided url (signed URLs are recommended for security).
• The transfer_method and related_id are required for Dify to process the file.
• If you return only metadata without a valid file or URL, the output will be empty.
• Make sure your service supports CORS and authentication as needed.

This approach works for any external HTTP API you want to integrate as a Dify custom tool. If you need to support multiple files, return an array of such file objects. If you want to support images, set the correct mime_type and extension.

Let me know if you need a full OpenAPI spec example or have questions about a specific use case!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Area-Ivy]

I tried the method you suggested, but I didn’t get the result I expected. Could you please help me check where the issue might be? Below are the Response and Schema I used during my test:

Response Body：

{
  "attachments": [
    {
      "dify_model_identity": "dify__file",
      "transfer_method": "REMOTE_URL",
      "related_id": "abc123",
      "filename": "report.pdf",
      "extension": ".pdf",
      "mime_type": "application/pdf",
      "url": "https://arxiv.org/pdf/2512.07796"
    }
  ]
}

Schema：

{
  "openapi": "3.1.0",
  "info": {
    "title": "Dify File Tool API",
    "version": "v1.0.0"
  },
  "servers": [
    { "url": "<my_api_serve>" }
  ],
  "paths": {
    "/generate-report": {
      "post": {
        "operationId": "GenerateReport",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FileMetadata": {
        "type": "object",
        "properties": {
          "dify_model_identity": { "type": "string", "enum": ["dify__file"] },
          "transfer_method": {
            "type": "string",
            "enum": ["TOOL_FILE", "LOCAL_FILE", "REMOTE_URL", "DATASOURCE_FILE"]
          },
          "related_id": { "type": "string" },
          "filename": { "type": "string" },
          "extension": { "type": "string" },
          "mime_type": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": [
          "dify_model_identity",
          "transfer_method",
          "related_id",
          "filename",
          "extension",
          "mime_type"
        ]
      },
      "ToolResponse": {
        "type": "object",
        "properties": {
          "attachments": {
            "type": "arrayFile",
            "items": { "$ref": "#/components/schemas/FileMetadata" }
          }
        },
        "required": ["attachments"]
      }
    }
  }
}

[smirk-dev]

I see the confusion - the previous examples were for internal tools. For an external HTTP service, here's what you actually need:

Quick Implementation Guide

1. External Service Response Format:

Your HTTP endpoint must return a JSON response with file metadata in this structure:

{
  "attachments": [
    {
      "dify_model_identity": "dify__file",
      "transfer_method": "REMOTE_URL",
      "related_id": "file_id_123",
      "filename": "output.pdf",
      "extension": ".pdf",
      "mime_type": "application/pdf",
      "url": "https://your-service.com/files/file_id_123?token=abc"
    }
  ]
}

2. Define Output Schema in Dify:

When creating your custom tool, define the output schema as:

{
  "type": "object",
  "properties": {
    "attachments": {
      "type": "arrayFile",
      "description": "Generated files"
    }
  }
}

3. Key Points for External Services:

• The dify_model_identity MUST be exactly "dify__file" (with double underscore)
• transfer_method should be "REMOTE_URL" for external files
• The url must be publicly accessible (with signed tokens if needed)
• related_id is a unique identifier for the file in your system
• Make sure your service returns the correct mime_type so Dify displays files properly

4. Testing:

• First test your external endpoint independently to ensure it returns valid JSON
• Check that the URLs in the response are accessible
• Make sure all required fields are present in the metadata

Common Issues:

• ✗ Missing dify_model_identity field → files won't display
• ✗ Invalid/inaccessible URL → files can't be downloaded
• ✗ Wrong schema type (use arrayFile not file for lists) → schema mismatch
• ✓ Follow this format and your files should appear!

This approach works for ANY external HTTP service without any Dify SDK dependencies.