Dify

Dependencies

No additional dependencies are required beyond the Python package. The Dify resource uses httpx for async API calls. For credential setup, see the Dify Setup guide.

Configuration

import os

from mirage import MountMode, Workspace
from mirage.resource.dify import DifyConfig, DifyResource

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
)
resource = DifyResource(config=config)
ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)

Config Reference

Field	Required	Default	Description
`api_key`	Yes		Dify Knowledge API key
`base_url`	Yes		Dify API base URL
`dataset_id`	Yes		Dify Knowledge dataset
`slug_metadata_name`	No	`slug`	Dify document metadata name used as the virtual path slug

DifyConfig normalizes base_url by removing a trailing slash and trims slug_metadata_name.

Environment Example

# .env.development
DIFY_API_KEY=dataset-...
DIFY_BASE_URL=https://api.dify.ai/v1
DIFY_DATASET_ID=...
DIFY_SLUG_METADATA_NAME=slug

Metadata Setup

For stable filesystem paths and scoped search, add a Dify document metadata field named by slug_metadata_name. The default field name is slug.

name: slug
value: guides/quickstart.md

If your Dify metadata field is named path instead, configure:

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name="path",
)

Mirage maps that document to:

/knowledge/guides/quickstart.md

If a document does not have the configured slug metadata field, Mirage uses the document name as the path. To make scoped search work for those name-based documents, enable Dify’s Built-in Fields in the dataset metadata settings so document_name can be used as a metadata filter. See Dify Setup for the full metadata checklist.

Getting Started

Agents

Resources

Runtimes

Dependencies

Configuration

Config Reference

Environment Example

Metadata Setup

​Dependencies

​Configuration

​Config Reference

​Environment Example

​Metadata Setup

Dependencies

Configuration

Config Reference

Environment Example

Metadata Setup