Backend Copilot

A set of Dify plugins that lets an Agent query your backend business data in natural language: paste one API catalog YAML — no code needed.

Works with BladeX, RuoYi, custom Spring Boot, or any REST backend. Read-only guardrails by default — write APIs require double opt-in.

Chinese docs: README.zh-CN.md

Source repository: https://github.com/zhou0928/backend-copilot

Connection requirements

The plugin runs inside the Dify plugin container and makes outbound HTTP requests to the backend you register in the catalog ().
To reach a service on the host machine from a self-hosted Docker deployment, use (works on Docker and OrbStack). inside the container refers to the container itself.
Required credentials are set on the plugin authorization page: backend base URL, the catalog YAML, and auth material (username/password for OAuth2 password grant, or a fixed token, or an API key). No other external services are contacted.

Plugin composition

Package	Type	Description
(v0.0.3)	Tools	Universal REST connector: invoker + API catalog + 4 auth types + OpenAPI import
(v0.2.0)	Agent Strategy	Universal backend agent strategy: plan → execute → replan pipeline, reusing the tools above

Both ship as files, installable offline into self-hosted Dify (≥ 1.9.0).

Key features

Declarative API catalog: one YAML file describing all your backend APIs (path/params/auth/pagination); the Agent picks and calls them automatically
Four auth types: / (incl. OAuth2 password grant with auto login & token refresh) / / ; supports BladeX Basic header + Tenant-Id + captcha pre-fetch + SM2 encryption
Read-only guardrails: APIs are read-only by default; a write API requires both in the catalog and in credentials
Context protection: list results auto-truncated at (default 50) with total count, so the LLM context never blows up
Business envelope detection: responses that return HTTP 200 but fail business-wise are recognized as errors
OpenAPI one-click import: generate a catalog automatically from Swagger JSON/YAML
Strategy pipeline built in: plan (parallel steps supported) → execute → auto replan on failure (default cap 3), with an execution time budget (default 600s)

Quick start

1. Install plugins

Dify → Plugins → Install → Local file, install both:

Or via GitHub: install from , pick the release.

2. Write an API catalog

Start from , or pick a ready-made example. Full annotated example:

Field reference:

Field	Required	Description
	✅	Backend address; use for host services from the Dify container
	✅	/ / /
		OAuth2 login endpoint; when set, tokens are fetched and refreshed automatically
		JSON path to the token in the login response, e.g.
		List truncation limit (default 50)
		Headers attached to every request (e.g. tenant id)
		Business envelope validation
	✅	API identifier used by the Agent
	✅	Describe the purpose clearly — the Agent matches user questions against it
		Param name → type/required/description
		Pagination parameter mapping
		JSON path to extract data from the response
		Write flag; absent means read-only

3. Configure tool credentials

Dify → Plugins → Backend Copilot → Authorize:

Field	Description
Backend Base URL	Same as in the catalog
API Catalog (YAML)	Paste the full catalog YAML from the previous step
Username / Password / Token / API Key	Replaces etc. placeholders in the catalog
Allow write	Default ; only when enabled can APIs marked run

4. Use the Agent strategy

In a workflow (Chatflow / Agent node) choose the Backend Copilot strategy:

Parameter	Default	Description
Model	required	An LLM that supports tool-call
Query	required	User question, e.g. "How many open tickets this week?"
API catalog (YAML)	required	Same catalog content as in the tool credentials
Backend tools	required	Attach the tool from this plugin
Read-only mode	on	On: write APIs are always blocked; off: they may run only when the user explicitly asks
Instruction		Extra requirements such as answer style or constraints
Max plan steps	20	Maximum steps in one plan
Max replans	3	Maximum automatic replans on failure
Execution budget (seconds)	600	Timeout circuit breaker

Then just ask questions in natural language.

Example catalogs

Example	Backend	Predefined APIs
	BladeX (real oneLineCar APIs)	Ticket search/detail/comments, workflow todo/sent/stats (6 read-only)
	RuoYi	User list/detail, dept tree, roles, login logs, server monitor
	JSONPlaceholder (public demo, no auth)	Post list/detail

FAQ

Q: The plugin container can't reach my backend?
Plugins run inside a container where is the container itself. Use to reach host services (works on Docker/OrbStack).

Q: Install fails with ?
The field in must match the publisher ID.

Q: The Agent never calls any API?
Check each API's — the Agent relies entirely on it to match user questions. Also verify the catalog YAML matches the one in credentials.

Q: Write APIs are blocked?
Three checks: ① the API is marked in the catalog; ② credential form "Allow write" is ; ③ the strategy's "Read-only mode" is off (or the user explicitly asked for a write).

Q: HTTP 200 but the Agent reports an error?
That's the business envelope failure being correctly detected. Verify / match your backend's convention.

Q: Login-for-token fails?
Gateways like BladeX require specific headers on the login request (Basic, Tenant-Id) — check . Params like / belong in (sent as URL query, not body).

Local development

Note: does not exclude , which busts the 50MB limit — use the bundled .

License

See LICENSE in the repository; privacy statement in PRIVACY.md.