langgenius/dify-plugin-sdks

Dify Plugin SDK

The Python SDK for building Dify plugins: tools, model providers, agent strategies, HTTP extensions, datasources, and triggers.

Plugin development guide · Schema reference · Releases

Getting Started

Python 3.12 or later is required. Install the SDK in your plugin's Python environment:

python -m pip install dify-plugin

The package name is dify-plugin; Python imports use dify_plugin. For a new plugin, use the Dify Plugin CLI to generate the project, then follow the guide to configure, run, and package it.

Development

Install uv and just. You can install just with uv tool install rust-just. Run these commands from this repository:

just dev       # Sync dependencies and install Git hooks
just fmt       # Format code
just lint      # Format code and apply lint fixes
just check     # Check the lockfile, formatting, and linting
just test      # Run SDK tests
just build     # Build source and wheel distributions
just docs      # Generate schema documentation

CI tests Python 3.12 and 3.13. See CONTRIBUTING.md for setup details, integration test requirements, and contribution guidelines.

Production Plugin Examples

See langgenius/dify-official-plugins for production plugin implementations published and used by Dify.

OpenAI-Compatible Embeddings

Starting in SDK 0.11.0 (unreleased), OAICompatEmbeddingModel validates each response batch before sending the next request. Each input must have one nonempty vector of finite numbers, with consistent dimensions across all batches. Responses with index fields must cover every input in that batch exactly once using integer indices starting at zero; the SDK restores input order. Responses without indices retain response order. Malformed responses, including mixed index metadata, numeric strings, and booleans, raise an SDK invocation error. This applies to plugins using the shared implementation, including GiteeAI and SiliconFlow.

LLM Polling Support

Since SDK 0.9.0, model plugins can declare the polling feature and implement _start_polling() and _check_polling() to handle long-running provider jobs through separate requests. Both methods return LLMPollingResult with one of three states:

• running: return plugin_state for the next check.
• succeeded: return the final LLM result.
• failed: return a terminal error.

OpenAI-Compatible Streaming

In SDK 0.11.0 (unreleased), OAICompatLargeLanguageModel preserves SSE data alongside comments and unknown fields. Responses marked text/event-stream ignore events without data; invalid JSON in data fields still raises an invocation error. The parser handles LF, CRLF, and CR line endings within events, including with custom delimiters. A single leading UTF-8 BOM is ignored for both default and custom delimiters. Raw JSON objects, single-prefix multiline JSON, and final payloads without a blank-line terminator remain supported. Explicit response charsets are respected; responses without a charset default to UTF-8.

Version Management

SDK versions use MAJOR.MINOR.PATCH:

• Major: incompatible API or architectural changes.
• Minor: new features.
• Patch: bug fixes.

Before SDK 1.0, minor releases may include breaking changes. Review the release notes before upgrading.

For SDK Users

Constrain your SDK dependency to the minor version you have tested while allowing patch updates. For example, dify-plugin~=0.10.2 allows patches in the 0.10 series. Review and test a new minor release before updating the constraint.

HTTP Error Responses in SDK 0.11.0 (unreleased)

SDK-generated Serverless and Endpoint failures return HTTP 500 with the body Internal Server Error. The original exception and traceback are logged on the plugin server. Endpoint route failures return HTTP 404 with Not Found; exceptions from plugin construction or invocation, including ValueError, return HTTP 500. Explicit HTTP responses returned by a plugin retain their status, headers, and body. Update clients that parse exception text or treat a plugin's ValueError as a 404.

Protecting errors raised during Endpoint streaming also requires the daemon HTTP error fix on every daemon node. With that fix, a stream that fails after headers are sent is interrupted, so clients must handle response-body read errors. Upgrade the daemon first, then rebuild and deploy plugins with the updated SDK.

Agent Token Estimates

In SDK 0.11.0 (unreleased), agent token estimates include text blocks as well as string content and treat special-token spellings such as <|endoftext|> as ordinary text. Message metadata and non-text payloads are excluded. Counting previously ignored text can reduce the output budget in strategies that call recalc_llm_max_tokens, including Function Calling and ReAct. The GPT-2 estimate remains approximate: budget adjustment retains a minimum of 16 output tokens and lets the provider decide whether the prompt fits.

Manifest Version Reference

The SDK dependency version and your plugin's top-level version in manifest.yaml are separate from these compatibility fields:

• meta.version: the manifest schema version, used by Dify to determine supported plugin capabilities.
• meta.minimum_dify_version: the earliest Dify version your plugin supports.

Set meta.minimum_dify_version for the features your plugin uses and test against that version. Feature availability depends on the SDK, Dify, and the plugin daemon. See the manifest schema for field definitions.

Meta.Version Reference

Meta.MinimumDifyVersion Reference

Minimum versions apply to the listed features.

Literal Stop Sequences

Starting in SDK 0.11.0 (unreleased), LargeLanguageModel.enforce_stop_tokens stops at the earliest literal sequence, including punctuation and backslashes. An empty stop list or no matching sequence returns the full input. Callers that used regex patterns must supply literal stop strings: for example, replace r"\." with "." to stop at a period. An empty string inside the stop list still matches at the start of the input.

License

Apache License 2.0.