{
  "schemaVersion": "1.0",
  "title": "Dify modes and capability projection",
  "description": "This reference defines how startup descriptors become Dify capabilities in tenant discovery. Use it to predict a manifest, diagnose a missing suffix, or detect a mode that exposes an unintended provider route.",
  "canonical": "https://getaip.org/docs/connectors/dify/reference/modes-and-capability-projection",
  "route": "/docs/connectors/dify/reference/modes-and-capability-projection",
  "source": "docs/connectors/dify/reference/modes-and-capability-projection.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/reference/modes-and-capability-projection.md",
    "txt": "/docs/download/connectors/dify/reference/modes-and-capability-projection.txt",
    "json": "/docs/download/connectors/dify/reference/modes-and-capability-projection.json",
    "pdf": "/docs/download/connectors/dify/reference/modes-and-capability-projection.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify modes and capability projection\ndescription: >-\n  Predict the exact app and Knowledge capabilities published from frozen Dify\n  connector descriptors\nkind: reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify modes and capability projection\n\nThis reference defines how startup descriptors become Dify capabilities in\ntenant discovery. Use it to predict a manifest, diagnose a missing suffix, or\ndetect a mode that exposes an unintended provider route.\n\nProjection is static. The connector reads each configured mode at startup and\napplies compiled rules; it does not ask Dify to infer the app mode during\ndiscovery.\n\n## Projection identity\n\nThe frozen catalogue contains 33 app operations and 46 Knowledge operations.\nEach configured app publishes one invocation alias plus a mode-dependent subset\nof the app catalogue.\n\n```text\ncap:dify:<app_id>\ncap:dify:<app_id>:<app_operation>\ncap:dify:knowledge:<credential_id>:<knowledge_operation>\n```\n\nApp IDs and Knowledge credential IDs must be unique within their descriptor\ndomain. The app ID `knowledge` is reserved because it would collide with the\nKnowledge routing prefix.\n\n## Map mode to the app alias\n\nThe connector accepts six exact mode strings:\n\n| Mode | Alias provider route | Alias kind | Connector approval |\n|---|---|---|---|\n| `workflow` | `POST /v1/workflows/run` | Workflow | Required |\n| `completion` | `POST /v1/completion-messages` | Agent | Not required |\n| `chat` | `POST /v1/chat-messages` | Agent | Not required |\n| `advanced-chat` | `POST /v1/chat-messages` | Agent | Required |\n| `agent-chat` | `POST /v1/chat-messages` | Agent | Required |\n| `agent` | `POST /v1/chat-messages` | Agent | Required |\n\nEvery alias is medium-risk and requires a tenant-scoped idempotency key. All\npublish sync, async, streaming, and cancellation support, no safe retry, and\nrollback unsupported.\n\nThe absence of connector-required approval for plain completion and chat does\nnot override tenant policy.\n\n## Apply the five operation projection sets\n\nEvery app operation belongs to one of five sets.\n\n### All six modes\n\nThese 18 operations project for every configured app:\n\n| Family | Operation suffixes |\n|---|---|\n| App metadata and files | `parameters.get`, `meta.get`, `info.get`, `site.get`, `file.upload`, `file.preview`, `end_user.get` |\n| Application feedback | `feedback.list` |\n| Audio | `audio.transcribe`, `audio.synthesize` |\n| Human input | `human_input_form.get`, `human_input_form.submit` |\n| Annotations | `annotation_reply.toggle`, `annotation_reply.status`, `annotation.list`, `annotation.create`, `annotation.update`, `annotation.delete` |\n\nProjection does not remove route-specific preconditions. A human-input token,\naudio feature, annotation setting, file identity, or end user must still\nsatisfy its provider contract.\n\n### Completion only\n\n`completion.stop` projects only for `completion`.\n\nThe operation uses the completion-message task route. The connector never\nconverts a completion task ID into a chat or workflow stop.\n\n### Four chat-like modes\n\nThese nine operations project for `chat`, `advanced-chat`, `agent-chat`, and\n`agent`:\n\n- `chat.stop`\n- `message.list`\n- `message.feedback.create`\n- `message.suggested.get`\n- `conversation.list`\n- `conversation.delete`\n- `conversation.rename`\n- `conversation.variable.list`\n- `conversation.variable.update`\n\nThe connector treats all four as the chat provider family. Route-specific user\nidentity and UUID rules still apply.\n\n### Workflow and advanced-chat\n\n`workflow.run.get` and `workflow.log.list` project for `workflow` and\n`advanced-chat`.\n\nThese reads are app-scoped and can expose records from multiple end users.\nTheir availability does not make the advanced-chat alias a Workflow kind.\n\n### Workflow only\n\nThese three operations project only for `workflow`:\n\n- `workflow.run_by_id`\n- `workflow.stop`\n- `workflow.event.stream`\n\nRun-by-ID and event stream use the connector's bounded SSE implementation.\nWorkflow stop remains a separate approved mutation.\n\n## Calculate per-app capability counts\n\nThe app-operation count comes directly from the five sets. Add one for the\napp invocation alias.\n\n| Mode | App operations | Alias | Published capabilities |\n|---|---:|---:|---:|\n| `workflow` | 23 | 1 | 24 |\n| `completion` | 19 | 1 | 20 |\n| `chat` | 27 | 1 | 28 |\n| `advanced-chat` | 29 | 1 | 30 |\n| `agent-chat` | 27 | 1 | 28 |\n| `agent` | 27 | 1 | 28 |\n\nChanging an app name or description does not alter the count. Changing its ID\nchanges every capability identity. Changing its mode changes the alias binding,\napproval rule, and projected operation set.\n\n## Add independent Knowledge capabilities\n\nKnowledge descriptors have no app mode. Every configured Knowledge credential\npublishes all 46 Knowledge operations with this prefix:\n\n```text\ncap:dify:knowledge:<credential_id>:<operation>\n```\n\nAn app credential never contributes Knowledge capabilities. A Knowledge\ncredential never contributes an app alias or app operations.\n\nFor a host with configured apps and Knowledge credentials, the expected total\nis:\n\n```text\nsum(per-app published count) + 46 × knowledge credential count\n```\n\nOne `chat` app and one Knowledge credential therefore publish 74 capabilities.\nThis is fixture arithmetic, not a universal Dify manifest size.\n\nParser limits allow many descriptors, but global manifest admission can impose\na lower practical maximum. Split instances before weakening admission limits.\n\n## Interpret operation kind and policy\n\nSix app operations have Workflow kind:\n\n- `workflow.run_by_id`\n- `workflow.run.get`\n- `workflow.stop`\n- `workflow.event.stream`\n- `human_input_form.get`\n- `human_input_form.submit`\n\nThe other 27 app operations have Tool kind. Mode projection does not change an\noperation's provider method, kind, risk, approval, retry, response type, or\ncompensation contract.\n\nEvery GET remains a low-risk retryable read. Every other catalogue method is a\nmutation requiring approval and a key, with no safe retry. DELETE, workflow\nrun-by-ID, annotation-reply toggle, and annotation delete follow their compiled\nhigh-risk rules.\n\n## Separate projection from runtime evidence\n\n| Evidence | What it proves | What it does not prove |\n|---|---|---|\n| Parsed descriptor | Valid local ID and one supported mode | Provider app really uses that mode |\n| Generated manifest | Compiled capability projection | Tenant authorization for every caller |\n| Registry admission | Accepted identity and artifact boundary | Provider route compatibility |\n| App health probe | App key can read `/v1/parameters` | Invocation or every projected operation |\n| Knowledge health probe | Knowledge key can list one dataset page | Any mutation, indexing, or pipeline run |\n| Successful operation | One route worked for one input | Entire mode or catalogue qualification |\n\nDiscovery can therefore be internally correct while a provider rejects a route.\nTreat configuration, discovery, admission, readiness, and qualification as\nseparate gates.\n\n## Account for pinned projection mismatches\n\nTwo reviewed mismatches require explicit caller handling:\n\n| Connector projection | Pinned provider boundary | Decision |\n|---|---|---|\n| Conversation-variable operations include `agent` | Provider accepts chat, advanced-chat, and agent-chat | Do not invoke those two suffixes for `agent` |\n| `workflow.event.stream` is workflow-only | Provider route also accepts advanced-chat | Do not construct the missing advanced-chat capability |\n\nThe first mismatch is an exposed capability that the provider rejects. The\nsecond is a provider route intentionally absent from connector discovery.\n\nDo not patch Action IDs, bypass discovery, or call the provider route directly\nto compensate for either difference.\n\n## Change a projected surface safely\n\nApp and Knowledge descriptor files, modes, IDs, and key maps are startup-owned.\nEditing a file does not change a running manifest.\n\nUse a replacement replica and new configuration or admission revision. Compare\nthe expected count and exact capability set before routing traffic.\n\nAn app ID or mode change can invalidate stored caller assumptions, policy\nrules, task mappings, dashboards, and documentation links. Treat it as a\nversioned integration change.\n\n## Diagnose projection differences\n\n| Observation | First decision |\n|---|---|\n| Alias is absent | Verify descriptor parsing, unique ID, key source, and admission |\n| Alias route is unexpected | Compare the exact startup mode with the six-mode table |\n| App operation is absent | Find its projection set; do not derive the suffix manually |\n| Knowledge operations are absent | Verify a separate Knowledge descriptor and key file |\n| Count is one below expected | Check whether the app alias was omitted from the calculation |\n| Count differs by 46 | Check the Knowledge credential count |\n| Projected route is rejected | Compare the pinned provider mode boundary and known mismatches |\n| Configuration changed without discovery change | Replace the startup-owned host replica |\n| Admission rejects a large manifest | Reduce or split descriptors; parser ceilings are not admission guarantees |\n\n## Related documentation\n\n- [Dify connector overview](../README.md)\n- [Dify connector configuration](configuration.md)\n- [Dify capability index](../capabilities/README.md)\n- [Dify authentication and credential scopes](../getting-started/authentication-and-credential-scopes.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify modes and capability projection\n\nThis reference defines how startup descriptors become Dify capabilities in\ntenant discovery. Use it to predict a manifest, diagnose a missing suffix, or\ndetect a mode that exposes an unintended provider route.\n\nProjection is static. The connector reads each configured mode at startup and\napplies compiled rules; it does not ask Dify to infer the app mode during\ndiscovery.\n\nProjection identity\n\nThe frozen catalogue contains 33 app operations and 46 Knowledge operations.\nEach configured app publishes one invocation alias plus a mode-dependent subset\nof the app catalogue.\n\ncap:dify:\ncap:dify::\ncap:dify:knowledge::\n\nApp IDs and Knowledge credential IDs must be unique within their descriptor\ndomain. The app ID knowledge is reserved because it would collide with the\nKnowledge routing prefix.\n\nMap mode to the app alias\n\nThe connector accepts six exact mode strings:\n\n| Mode | Alias provider route | Alias kind | Connector approval |\n\n| workflow | POST /v1/workflows/run | Workflow | Required |\n| completion | POST /v1/completion-messages | Agent | Not required |\n| chat | POST /v1/chat-messages | Agent | Not required |\n| advanced-chat | POST /v1/chat-messages | Agent | Required |\n| agent-chat | POST /v1/chat-messages | Agent | Required |\n| agent | POST /v1/chat-messages | Agent | Required |\n\nEvery alias is medium-risk and requires a tenant-scoped idempotency key. All\npublish sync, async, streaming, and cancellation support, no safe retry, and\nrollback unsupported.\n\nThe absence of connector-required approval for plain completion and chat does\nnot override tenant policy.\n\nApply the five operation projection sets\n\nEvery app operation belongs to one of five sets.\n\nAll six modes\n\nThese 18 operations project for every configured app:\n\n| Family | Operation suffixes |\n\n| App metadata and files | parameters.get, meta.get, info.get, site.get, file.upload, file.preview, enduser.get |\n| Application feedback | feedback.list |\n| Audio | audio.transcribe, audio.synthesize |\n| Human input | humaninputform.get, humaninputform.submit |\n| Annotations | annotationreply.toggle, annotationreply.status, annotation.list, annotation.create, annotation.update, annotation.delete |\n\nProjection does not remove route-specific preconditions. A human-input token,\naudio feature, annotation setting, file identity, or end user must still\nsatisfy its provider contract.\n\nCompletion only\n\ncompletion.stop projects only for completion.\n\nThe operation uses the completion-message task route. The connector never\nconverts a completion task ID into a chat or workflow stop.\n\nFour chat-like modes\n\nThese nine operations project for chat, advanced-chat, agent-chat, and\nagent:\n• chat.stop\n• message.list\n• message.feedback.create\n• message.suggested.get\n• conversation.list\n• conversation.delete\n• conversation.rename\n• conversation.variable.list\n• conversation.variable.update\n\nThe connector treats all four as the chat provider family. Route-specific user\nidentity and UUID rules still apply.\n\nWorkflow and advanced-chat\n\nworkflow.run.get and workflow.log.list project for workflow and\nadvanced-chat.\n\nThese reads are app-scoped and can expose records from multiple end users.\nTheir availability does not make the advanced-chat alias a Workflow kind.\n\nWorkflow only\n\nThese three operations project only for workflow:\n• workflow.runbyid\n• workflow.stop\n• workflow.event.stream\n\nRun-by-ID and event stream use the connector's bounded SSE implementation.\nWorkflow stop remains a separate approved mutation.\n\nCalculate per-app capability counts\n\nThe app-operation count comes directly from the five sets. Add one for the\napp invocation alias.\n\n| Mode | App operations | Alias | Published capabilities |\n\n| workflow | 23 | 1 | 24 |\n| completion | 19 | 1 | 20 |\n| chat | 27 | 1 | 28 |\n| advanced-chat | 29 | 1 | 30 |\n| agent-chat | 27 | 1 | 28 |\n| agent | 27 | 1 | 28 |\n\nChanging an app name or description does not alter the count. Changing its ID\nchanges every capability identity. Changing its mode changes the alias binding,\napproval rule, and projected operation set.\n\nAdd independent Knowledge capabilities\n\nKnowledge descriptors have no app mode. Every configured Knowledge credential\npublishes all 46 Knowledge operations with this prefix:\n\ncap:dify:knowledge::\n\nAn app credential never contributes Knowledge capabilities. A Knowledge\ncredential never contributes an app alias or app operations.\n\nFor a host with configured apps and Knowledge credentials, the expected total\nis:\n\nsum(per-app published count) + 46 × knowledge credential count\n\nOne chat app and one Knowledge credential therefore publish 74 capabilities.\nThis is fixture arithmetic, not a universal Dify manifest size.\n\nParser limits allow many descriptors, but global manifest admission can impose\na lower practical maximum. Split instances before weakening admission limits.\n\nInterpret operation kind and policy\n\nSix app operations have Workflow kind:\n• workflow.runbyid\n• workflow.run.get\n• workflow.stop\n• workflow.event.stream\n• humaninputform.get\n• humaninputform.submit\n\nThe other 27 app operations have Tool kind. Mode projection does not change an\noperation's provider method, kind, risk, approval, retry, response type, or\ncompensation contract.\n\nEvery GET remains a low-risk retryable read. Every other catalogue method is a\nmutation requiring approval and a key, with no safe retry. DELETE, workflow\nrun-by-ID, annotation-reply toggle, and annotation delete follow their compiled\nhigh-risk rules.\n\nSeparate projection from runtime evidence\n\n| Evidence | What it proves | What it does not prove |\n\n| Parsed descriptor | Valid local ID and one supported mode | Provider app really uses that mode |\n| Generated manifest | Compiled capability projection | Tenant authorization for every caller |\n| Registry admission | Accepted identity and artifact boundary | Provider route compatibility |\n| App health probe | App key can read /v1/parameters | Invocation or every projected operation |\n| Knowledge health probe | Knowledge key can list one dataset page | Any mutation, indexing, or pipeline run |\n| Successful operation | One route worked for one input | Entire mode or catalogue qualification |\n\nDiscovery can therefore be internally correct while a provider rejects a route.\nTreat configuration, discovery, admission, readiness, and qualification as\nseparate gates.\n\nAccount for pinned projection mismatches\n\nTwo reviewed mismatches require explicit caller handling:\n\n| Connector projection | Pinned provider boundary | Decision |\n\n| Conversation-variable operations include agent | Provider accepts chat, advanced-chat, and agent-chat | Do not invoke those two suffixes for agent |\n| workflow.event.stream is workflow-only | Provider route also accepts advanced-chat | Do not construct the missing advanced-chat capability |\n\nThe first mismatch is an exposed capability that the provider rejects. The\nsecond is a provider route intentionally absent from connector discovery.\n\nDo not patch Action IDs, bypass discovery, or call the provider route directly\nto compensate for either difference.\n\nChange a projected surface safely\n\nApp and Knowledge descriptor files, modes, IDs, and key maps are startup-owned.\nEditing a file does not change a running manifest.\n\nUse a replacement replica and new configuration or admission revision. Compare\nthe expected count and exact capability set before routing traffic.\n\nAn app ID or mode change can invalidate stored caller assumptions, policy\nrules, task mappings, dashboards, and documentation links. Treat it as a\nversioned integration change.\n\nDiagnose projection differences\n\n| Observation | First decision |\n\n| Alias is absent | Verify descriptor parsing, unique ID, key source, and admission |\n| Alias route is unexpected | Compare the exact startup mode with the six-mode table |\n| App operation is absent | Find its projection set; do not derive the suffix manually |\n| Knowledge operations are absent | Verify a separate Knowledge descriptor and key file |\n| Count is one below expected | Check whether the app alias was omitted from the calculation |\n| Count differs by 46 | Check the Knowledge credential count |\n| Projected route is rejected | Compare the pinned provider mode boundary and known mismatches |\n| Configuration changed without discovery change | Replace the startup-owned host replica |\n| Admission rejects a large manifest | Reduce or split descriptors; parser ceilings are not admission guarantees |\n\nRelated documentation\n• Dify connector overview (../README.md)\n• Dify connector configuration (configuration.md)\n• Dify capability index (../capabilities/README.md)\n• Dify authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "a8735fe79b2c182c1e4e356012146d8cf7ab473f85ed87f618b08827b598ac90"
  }
}