Skip to content
AIPDocs
AIP 1.055 pagesConnector
Release status
DocumentationAIP 1.0ConnectorConnectors

Dify Connector

The Dify connector maps configured Dify applications to native AIP capabilities. It supports workflow, completion, chat, advanced chat, agent chat, and agent API families without placing Dify DTOs in the AIP semantic core.

Capability Mapping

Each configured app becomes cap:dify:{app_id}. Calls accept:

  • inputs for Dify application variables;
  • query or prompt for completion and chat families;
  • a stable user value;
  • conversation_id, files, and auto_generate_name where the Dify API family supports them.

Workflow applications call /v1/workflows/run, completion applications call /v1/completion-messages, and chat families call /v1/chat-messages.

The capability contract advertises synchronous, asynchronous, streaming, and cancellation support. Workflows and agent modes require AIP approval because they may invoke downstream tools or produce customer-visible work. Automatic retry, transactions, reconciliation, and rollback are not advertised.

Streaming and Cancellation

Streaming invocation parses bounded Dify SSE frames, emits ordered native StreamChunk records, retains the remote task id, and requires an explicit terminal event. An upstream close without a terminal event is a failure.

Cancellation uses the app-family stop endpoint after the remote task id is known. DifyTaskStore preserves the AIP action-to-task mapping. The in-memory store is for tests; FileDifyTaskStore provides atomic single-host persistence. Clustered deployments need an atomic shared implementation.

Human-input events map to native requires_human results. They do not bypass AIP approval authority.

Deployment Boundary

aip-connector-dify is an embeddable connector crate. The stock aipd 1.0 binary does not expose Dify app registration options. A deployment host must:

  1. load app descriptors and API keys from deployment-owned configuration;
  2. construct DifyConnector with at least one unique app id;
  3. provide durable task correlation appropriate to its topology;
  4. register the generated capabilities and frozen handlers with the gateway;
  5. bind authenticated AIP tenants and policy before invocation.

Supported app mode strings are workflow, completion, chat, agent-chat, advanced-chat, and agent. Unknown modes fail during connector construction.

Data and Identity

The current contract marks Dify payloads as confidential, PII-bearing, and redaction-required. The connector uses one configured app API key and does not implement frozen connector credential-handle routing. A multi-tenant deployment must therefore isolate connector instances or add a deployment-owned credential provider instead of accepting API keys in action input.

When user is omitted, the current mapper sends the fallback value aip. Production hosts should supply a stable, non-secret, tenant-scoped external user mapping so unrelated users do not share Dify conversation identity.

Qualification Boundary

Deterministic tests cover app validation, request mapping, bounded SSE parsing, stream chunks, cancellation correlation, human-input mapping, and file-store restart behavior. A complete retained isolated-live campaign against a pinned Dify deployment is absent.

Before production promotion, prove all configured app modes, provider errors, cancellation races, stream disconnects, restart recovery, tenant isolation, redaction, and downstream side effects against the exact artifact.

See Conformance and Qualification, Implementation Status, and Pinned Upstream Baselines.