BailingHub Tool Plugin for Dify

Use a Dify Agent or Workflow to submit business actions through a self-hosted BailingHub control plane.

The plugin intentionally exposes only three control-plane tools:

• submit_governed_job: submit an action to an administrator-configured route;
• get_job: read the current state and terminal result of a job;
• wait_for_job: poll a job for a bounded period without waiting indefinitely.

It does not import governed business APIs into Dify and does not give Dify admin, executor, or business-system credentials.

Dify Agent or Workflow
  -> BailingHub Dify Plugin
     -> POST /run
     -> GET /jobs/{job_id}
        -> BailingHub control plane
           -> governed executor
              -> business system

Simplified Chinese

Source and Support

• Source: github.com/bailinghub/bailinghub-dify-plugin
• Bug reports and support: GitHub Issues
• Security reports: use this repository's private Security Advisory channel as described in SECURITY.md.

Project Boundary

This repository is an independent integration adapter. It is not:

• part of the ACC normative specification;
• embedded in the BailingHub server distribution;
• versioned or released together with ACC or BailingHub;
• an official Dify partnership or certification.

The dependency is one-way: this plugin consumes BailingHub's public Client API. See Project Boundaries and Compatibility.

Requirements

• Dify with Tool Plugin support;
• a reachable self-hosted BailingHub instance;
• a dedicated BailingHub Client Token restricted to the routes Dify needs;
• HTTPS between Dify and BailingHub, except for loopback development.

Configure

1. In BailingHub, create a dedicated client for this Dify application.
2. Allow only the required routes and set an appropriate rate limit.
3. Install this plugin in Dify.
4. Configure:
   • BailingHub Base URL: the BailingHub HTTPS origin;
   • Dedicated Client Token: the raw client token, without a Bearer prefix.

Never use an admin token, executor token, tool-provider secret, or business-system credential as the Client Token.

Workflow Pattern

1. Generate a deterministic request_id in the workflow, for example dify:<conversation-id>:<workflow-run-id>:<step-id>.
2. Call submit_governed_job with an administrator-provided route.
3. Save the returned job_id.
4. Call wait_for_job for a short bounded wait, or call get_job from a later step.
5. Treat done as success. Treat error and rejected as terminal failures.

queued, running, and dispatched are non-terminal. If a bounded wait times out, query the same job_id later. Do not submit a replacement action. When retrying the same business request, reuse the same request_id without changing its meaning or arguments.

Security Model

• Route choice is constrained again by the BailingHub client allowlist.
• project and profile are not plugin inputs and cannot be overridden by a model.
• Responses are limited to 1 MiB and filtered to job state and result fields.
• Arbitrary upstream response bodies are not exposed as errors.
• Non-loopback HTTP base URLs are rejected.
• Final business authorization remains in the business system.

The plugin is an adapter to governance enforcement; it is not the final authorization boundary and does not make model output trustworthy.

The plugin sends requests only to the BailingHub base URL configured by the Dify administrator. See PRIVACY.md for the complete data-flow disclosure.

Development

Python 3.12 and uv are recommended.

uv sync --dev
uv run ruff check .
uv run pytest
uv run python scripts/check_project.py

Package with a pinned Dify Plugin CLI as described in Releasing.

Related Documentation

• BailingHub Dify integration recipe
• BailingHub HTTP contract
• Dify Tool Plugin guide

License

Apache License 2.0. See LICENSE.