Integration Guide
Dify
Connect Dify to OSuite and get your first governed action into /decisions in under 20 minutes.
Instance URL detected: https://docs.osuite.ai
Governance context
Runtime class
Low-Code / Workflow Builder
A visual or builder-style platform where governance depth depends on exposed control points.
Recommended surfaces
Evidence Import Surface
Import actions, traces, and logs when the external runtime cannot be governed directly.
Control Plane
Run policy, approvals, replay, and evidence management as the operator system of record.
Typical governance range
Evidence Import -> Advisory Governance -> Approval-Orchestrated Governance
Self-host and future SaaS are deployment model choices for the OSuite control plane. They do not determine governance level by themselves.
Confirm your Dify app can run
Start in Dify. Make sure the app token is valid and the app has a working model provider behind it.
If Dify returns a provider initialization error, the OSuite bridge can still record the failed run, but the Dify answer itself will not complete until that provider credential is configured.
Set bridge environment variables
Keep Dify auth and OSuite auth separate. The bridge only needs both API endpoints and tokens.
.env
OSUITE_BASE_URL=https://docs.osuite.ai OSUITE_API_KEY=<your-workspace-api-key> DIFY_BASE_URL=https://api.dify.ai/v1 DIFY_APP_API_KEY=<your-dify-app-api-key> OSUITE_AGENT_ID=dify-investment-copilot DIFY_QUERY=Analyze Tesla in three bullets
Wrap the Dify call in OSuite governance
Use a small bridge process to report the Dify runtime connection, run guard, create the action, call Dify, then write the outcome back.
dify-bridge.mjs
import { OSuite } from 'osuite';
const osuite = new OSuite({
baseUrl: process.env.OSUITE_BASE_URL,
apiKey: process.env.OSUITE_API_KEY,
agentId: process.env.OSUITE_AGENT_ID || 'dify-bridge',
});
await osuite.reportConnections([{
provider: 'dify',
auth_type: 'api_key',
status: 'active',
metadata: {
base_url: process.env.DIFY_BASE_URL,
runtime_class: 'workflow-builder',
},
}]);
const decision = await osuite.guard({
action_type: 'dify.agent_run',
declared_goal: process.env.DIFY_QUERY,
risk_score: 42,
systems_touched: ['dify'],
});
if (decision.decision === 'block') {
throw new Error(decision.reason || 'Blocked by OSuite policy');
}
const created = await osuite.createAction({
action_type: 'dify.agent_run',
declared_goal: process.env.DIFY_QUERY,
risk_score: 42,
systems_touched: ['dify'],
});
const actionId = created.action?.action_id || created.action_id;
try {
// Agent-chat apps should be called through /chat-messages.
// Use streaming mode and collect the final answer in your bridge.
const response = await fetch(`${process.env.DIFY_BASE_URL}/chat-messages`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.DIFY_APP_API_KEY}`,
},
body: JSON.stringify({
inputs: {},
query: process.env.DIFY_QUERY,
response_mode: 'streaming',
user: 'osuite-guide',
}),
});
if (!response.ok) {
const error = await response.text();
throw new Error(error);
}
await osuite.updateOutcome(actionId, {
status: 'completed',
output_summary: 'Dify run completed and was recorded by OSuite',
});
} catch (error) {
await osuite.updateOutcome(actionId, {
status: 'failed',
error_message: error.message,
});
throw error;
}This is the right model for low-code builders: OSuite becomes the control plane and evidence system of record around the external runtime.
Run the packaged test harness
Inside this repository, you can execute the end-to-end bridge with one command.
Terminal
npm run dify:trust:test
The script records the Dify connection, creates an action in OSuite, calls the Dify app, and writes either a completed or failed outcome.
Verify action and trust state in OSuite
Open the OSuite workbench and inspect the agent, action, and replay surfaces.
Check /decisions for the run, /agents for the Dify-backed agent, and /integrations for the saved Dify connection metadata.
What success looks like
You should see a Dify-backed agent appear in /agents, a dify.agent_run action in /decisions, and the resulting success or provider error attached to the action outcome.
Navigate to /decisions in your OSuite instance. Your action should appear in the ledger within seconds of the agent run.
Governance as Code
Drop a guardrails.yml in your project root to enforce policies without code changes. OSuite evaluates these rules at the guard step before any action executes.
guardrails.yml
version: 1
project: dify-bridge
description: >
Governance policy for a Dify bridge.
Low-risk research can run automatically. High-impact actions require approval.
policies:
- id: allow_research
description: Advisory analysis runs can proceed
applies_to:
action_types:
- dify.agent_run
when:
max_risk_score: 49
rule:
allow: true
- id: gate_high_impact
description: External actions with higher risk require a human checkpoint
applies_to:
action_types:
- dify.agent_run
when:
min_risk_score: 50
rule:
require: approval