Plugin Architecture#

Dify plugins are self-contained packages that extend the platform with tools, models, endpoints, agent strategies, datasources, or triggers. Each plugin ships a manifest.yaml that declares its identity, resource requirements, permissions, and pointers to provider YAML definitions. The Dify API layer validates manifests against a Pydantic model (PluginDeclaration) at install time; at runtime, the plugin daemon is the source of truth.

manifest.yaml Schema#

Every plugin root contains exactly one manifest.yaml. The canonical fields are defined by PluginDeclaration in api/core/plugin/entities/plugin.py:

Category auto-detection: The @model_validator on PluginDeclaration inspects the top-level tool, model, datasource, agent_strategy, and trigger keys and sets category accordingly; a plugin with none of these is categorized as Extension 4.

Installation sources: PluginInstallationSource supports Github, Marketplace, Package, and Remote 7.

Single-Provider-per-Plugin Convention#

Official plugins follow a strict one-provider-per-plugin layout. The plugins.tools (or plugins.models) list in manifest.yaml always contains a single entry pointing to provider/<name>.yaml:

• Slack: plugins.tools: [provider/slack.yaml] 8
• AWS Tools: plugins.tools: [provider/aws_tools.yaml] 9
• OpenAI: plugins.models: [provider/openai.yaml] 10

The provider YAML (provider/<name>.yaml) holds the provider identity, optional credentials_for_provider, and a tools list of individual tool YAML paths. The AWS provider, for example, references 22+ tool YAML files under tools/. Each tool YAML has a paired .py implementation.

Directory Layout#

A standard plugin folder looks like:

<plugin-name>/
├── manifest.yaml # Plugin declaration (root of plugin identity)
├── main.py # Entrypoint: Plugin(DifyPluginEnv()).run()
├── provider/
│ ├── <name>.yaml # Provider identity, credentials, tool refs
│ └── <name>.py # Provider Python class
├── tools/
│ ├── <tool>.yaml # Tool schema (parameters, descriptions)
│ └── <tool>.py # Tool implementation
├── _assets/ # Icons, screenshots
├── pyproject.toml # Python deps (requires dify_plugin>=0.9.0)
└── uv.lock

Permissions and Resource Requirements#

The resource block controls both memory allocation and capability permissions 11:

• resource.memory: integer bytes (AWS uses 256 MB 12, Slack/OpenAI use 1 MB 13)
• resource.permission: nested flags for tool, model (with sub-flags llm, text_embedding, rerank, tts, speech2text, moderation), node, endpoint, storage (capped 1 KB–1 GB 14)

Validation & Loading#

The API does not parse manifest.yaml directly. The plugin daemon handles YAML loading; the API receives JSON which is validated via Pydantic model_validate(). The primary entry points are:

• PluginInstaller.fetch_plugin_manifest() — fetches a validated PluginDeclaration from the daemon
• PluginService.fetch_plugin_manifest() — high-level service wrapper
• PluginDeclaration in api/core/plugin/entities/plugin.py — the authoritative Pydantic schema

Key Source References#