{
  "schemaVersion": "1.0",
  "title": "Run Dify chat and workflows",
  "description": "Follow this guide to invoke one configured Dify app through its discovery-derived alias. The procedure applies to chat, completion, workflow, advanced-chat, agent-chat, and agent modes.",
  "canonical": "https://getaip.org/docs/connectors/dify/guides/run-chat-and-workflows",
  "route": "/docs/connectors/dify/guides/run-chat-and-workflows",
  "source": "docs/connectors/dify/guides/run-chat-and-workflows.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/guides/run-chat-and-workflows.md",
    "txt": "/docs/download/connectors/dify/guides/run-chat-and-workflows.txt",
    "json": "/docs/download/connectors/dify/guides/run-chat-and-workflows.json",
    "pdf": "/docs/download/connectors/dify/guides/run-chat-and-workflows.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Run Dify chat and workflows\ndescription: >-\n  Invoke one discovered Dify app safely and settle blocking, streaming,\n  human-input, cancellation, and uncertain outcomes\nkind: guide\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Run Dify chat and workflows\n\nFollow this guide to invoke one configured Dify app through its discovery-derived\nalias. The procedure applies to chat, completion, workflow, advanced-chat,\nagent-chat, and agent modes.\n\nThe task is complete only after AIP records a terminal result or a documented\nhuman-input state. A provider request acknowledgement, task ID, or accepted\ncancel command is not equivalent to completed work.\n\n## Before you begin\n\nObtain these values from the authorized tenant context:\n\n- one discovered `cap:dify:<app_id>` alias;\n- its configured mode and admitted connector release;\n- one stable Dify `user` mapping for the end user;\n- the exact app input contract and any approved files;\n- a unique Action ID and non-blank idempotency key;\n- approval evidence when connector or deployment policy requires it.\n\nDo not construct the capability from a provider URL. Discovery binds the app\nID to a specific credential without exposing its Bearer value.\n\n## 1. Select the app mode\n\nThe alias maps the configured mode to one provider route:\n\n| Configured mode | Provider route | Required invocation input | Connector approval |\n|---|---|---|---|\n| `workflow` | `POST /v1/workflows/run` | `user`, `inputs` | Required |\n| `completion` | `POST /v1/completion-messages` | `user`, `query` or `prompt` | Not required by alias contract |\n| `chat` | `POST /v1/chat-messages` | `user`, `query` or `prompt` | Not required by alias contract |\n| `advanced-chat` | `POST /v1/chat-messages` | `user`, `query` or `prompt` | Required |\n| `agent-chat` | `POST /v1/chat-messages` | `user`, `query` or `prompt` | Required |\n| `agent` | `POST /v1/chat-messages` | `user`, `query` or `prompt` | Required |\n\nDeployment policy can require approval for plain chat or completion even when\nthe alias contract does not. Never infer authorization from the mode alone.\n\nAll aliases are medium-risk, require an idempotency key, publish no safe retry,\nand declare rollback unsupported.\n\n## 2. Bind app and end-user identity\n\nUse one stable, non-secret `user` value for every related invocation, history\nread, stop, event resume, and form submission. It contains 1 to 256 bytes\nwithout control characters.\n\nDo not reuse a shared placeholder across customers. Dify uses this value to\nisolate conversations, messages, files, and task control within the selected\napp.\n\nRecord the tenant, capability, app ID, mode, user mapping, Action ID, and input\ndigest before dispatch. The Action cannot select a different provider origin\nor credential.\n\n## 3. Freeze approval and idempotency\n\nCreate one immutable Action input and one tenant-scoped idempotency key. AIP\nretains the key reservation for 24 hours and revalidates the input hash on\ncollision.\n\nFor approval-required modes, evidence includes the reason, input snapshot, and\npolicy decision. The connector approval window is 900,000 milliseconds.\n\nThe AIP reservation prevents conflicting reuse inside its scope. It does not\nprove that Dify deduplicates a repeated model, workflow, tool, or agent effect.\n\n## 4. Build a chat or completion input\n\nUse `query` or `prompt` for the user message. The connector trims the selected\nvalue and rejects an empty message.\n\n```json\n{\n  \"query\": \"Summarize the approved refund policy.\",\n  \"inputs\": {\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\",\n  \"files\": [],\n  \"auto_generate_name\": false\n}\n```\n\nChat-like modes can also send `conversation_id`, `files`, and\n`auto_generate_name`. Completion accepts files but does not send conversation\nor automatic-name fields.\n\n`query` and `prompt` each allow at most 1 MiB. `files` allows at most 100\nobjects. The complete encoded provider JSON cannot exceed 8 MiB.\n\nUse only file references or remote sources already authorized for the same app\nand end user. Uploading bytes and invoking the app are separate effects.\n\n## 5. Build a workflow input\n\nWorkflow invocation sends `inputs`, connector-selected `response_mode`, and the\nstable `user`. It does not require a query.\n\n```json\n{\n  \"inputs\": {\n    \"topic\": \"quarterly forecast\",\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\"\n}\n```\n\nValidate every input name and value against the published workflow contract.\nThe alias invokes the app's current published workflow; it does not select a\nspecific workflow version ID.\n\nUse the dedicated run-by-ID capability only when policy and discovery require\na pinned published version.\n\n## 6. Choose blocking or streaming execution\n\nThe alias contract supports synchronous, asynchronous, streaming, and\ncancellation surfaces. The connector, not Action input, controls Dify\n`response_mode`.\n\n| AIP execution path | Provider mode | Observable result |\n|---|---|---|\n| Blocking invocation | `blocking` | One completed or `requires_human` result |\n| Typed streaming execution | `streaming` | Bounded AIP chunks plus one terminal result |\n| Durable asynchronous caller flow | Runtime-managed | Poll the original Action; do not create a replay |\n\nCaller-supplied `response_mode` is not part of the alias input schema. Do not\nadd it to the Action or assume it overrides the execution path.\n\nStreaming limits each SSE frame to 1 MiB, parsed events to 10,000, and total\nbytes to the configured response limit. The default total limit is 8 MiB.\n\n## 7. Interpret streaming and terminal state\n\nThe connector maps provider events to AIP stream chunks:\n\n| Provider event | AIP meaning |\n|---|---|\n| `workflow_started`, `node_started` | Progress |\n| `tool_call` | Tool activity |\n| `agent_thought` | Agent reasoning metadata |\n| `message` | Data |\n| `human_input_required`, `workflow_paused` | Pending approval or input |\n| `error` | Failed result |\n| `message_end`, `workflow_finished` | Terminal result |\n\nThe connector assembles text from answer-bearing events. A terminal output can\ncontain `answer` plus `final_event`, or only the final event data.\n\nAn upstream close without a terminal event is an error. A non-succeeded\nworkflow finish is failed even when the HTTP stream began successfully.\n\n## 8. Continue chat or answer human input\n\nFor a later chat turn, use the provider `conversation_id` returned by the first\nturn and preserve the same user:\n\n```json\n{\n  \"query\": \"Apply that policy to order 1042.\",\n  \"inputs\": {\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\",\n  \"conversation_id\": \"0190c42f-2d5a-7000-8000-000000000901\"\n}\n```\n\nDo not attach a conversation from another app or user. Confirm continuity\nthrough a conversation read when identity or outcome is uncertain.\n\nA `human_input_required` or `workflow_paused` event produces an AIP\n`requires_human` result. Preserve the form token and read the form through its\ndedicated capability.\n\nSubmit one approved form response through a new Action. Forms are one-shot, so\nnever replay the original app invocation to answer a pause.\n\n## 9. Cancel with evidence\n\nDuring streaming, the connector records a remote task only after Dify emits a\ntask ID. Cancellation after that point uses the mode-specific stop route and\nthe same app and user.\n\nCancellation before a task ID arrives can close the local request but cannot\nconfirm a remote stop. Record `remote_stop_confirmed: false` and inspect the\nprovider's authoritative run or conversation state.\n\nA stop response means the provider accepted task control. Retain terminal\nevent, workflow-run, or conversation evidence before reporting the business\noperation as stopped.\n\n## 10. Settle uncertain outcomes\n\n| Observation | Decision |\n|---|---|\n| Input is rejected before dispatch | Correct the same reviewed intent without claiming a provider effect |\n| Action remains pending approval | Decide the immutable Action; do not submit a replacement |\n| Blocking response is lost | Read authoritative conversation or workflow state before another invocation |\n| Stream closes before terminal evidence | Treat completion as unknown and inspect the provider run |\n| Human-input state is returned | Preserve the form token and submit one separately approved response |\n| Cancellation lacks a task ID | Record unconfirmed remote stop and inspect provider state |\n| Terminal provider event reports failure | Keep the failed Action and repair the cause before a new intent |\n| Result crosses an app or user boundary | Stop traffic and treat the event as an isolation incident |\n\nNever automatically retry an alias invocation. A new Action is appropriate\nonly after authoritative evidence shows that a new intent is required.\n\n## Completion checklist\n\n- The capability came from authenticated tenant discovery.\n- App mode, user mapping, input, approval, and idempotency key were frozen.\n- Files and remote sources belonged to the same authorized task.\n- Blocking or streaming behavior matched the selected AIP execution path.\n- A terminal, failed, or `requires_human` state was retained.\n- Cancellation and replay claims match available provider evidence.\n- Sensitive inputs, outputs, events, and errors were redacted from general logs.\n\n## Related documentation\n\n- [Dify capability index](../capabilities/README.md)\n- [Dify app metadata and files](../capabilities/app-metadata-and-files.md)\n- [Dify chat messages, conversations, and feedback](../capabilities/chat-messages-conversations-and-feedback.md)\n- [Dify workflows, streaming, and human input](../capabilities/workflows-streaming-and-human-input.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Run Dify chat and workflows\n\nFollow this guide to invoke one configured Dify app through its discovery-derived\nalias. The procedure applies to chat, completion, workflow, advanced-chat,\nagent-chat, and agent modes.\n\nThe task is complete only after AIP records a terminal result or a documented\nhuman-input state. A provider request acknowledgement, task ID, or accepted\ncancel command is not equivalent to completed work.\n\nBefore you begin\n\nObtain these values from the authorized tenant context:\n• one discovered cap:dify: alias;\n• its configured mode and admitted connector release;\n• one stable Dify user mapping for the end user;\n• the exact app input contract and any approved files;\n• a unique Action ID and non-blank idempotency key;\n• approval evidence when connector or deployment policy requires it.\n\nDo not construct the capability from a provider URL. Discovery binds the app\nID to a specific credential without exposing its Bearer value.\n1. Select the app mode\n\nThe alias maps the configured mode to one provider route:\n\n| Configured mode | Provider route | Required invocation input | Connector approval |\n\n| workflow | POST /v1/workflows/run | user, inputs | Required |\n| completion | POST /v1/completion-messages | user, query or prompt | Not required by alias contract |\n| chat | POST /v1/chat-messages | user, query or prompt | Not required by alias contract |\n| advanced-chat | POST /v1/chat-messages | user, query or prompt | Required |\n| agent-chat | POST /v1/chat-messages | user, query or prompt | Required |\n| agent | POST /v1/chat-messages | user, query or prompt | Required |\n\nDeployment policy can require approval for plain chat or completion even when\nthe alias contract does not. Never infer authorization from the mode alone.\n\nAll aliases are medium-risk, require an idempotency key, publish no safe retry,\nand declare rollback unsupported.\n2. Bind app and end-user identity\n\nUse one stable, non-secret user value for every related invocation, history\nread, stop, event resume, and form submission. It contains 1 to 256 bytes\nwithout control characters.\n\nDo not reuse a shared placeholder across customers. Dify uses this value to\nisolate conversations, messages, files, and task control within the selected\napp.\n\nRecord the tenant, capability, app ID, mode, user mapping, Action ID, and input\ndigest before dispatch. The Action cannot select a different provider origin\nor credential.\n3. Freeze approval and idempotency\n\nCreate one immutable Action input and one tenant-scoped idempotency key. AIP\nretains the key reservation for 24 hours and revalidates the input hash on\ncollision.\n\nFor approval-required modes, evidence includes the reason, input snapshot, and\npolicy decision. The connector approval window is 900,000 milliseconds.\n\nThe AIP reservation prevents conflicting reuse inside its scope. It does not\nprove that Dify deduplicates a repeated model, workflow, tool, or agent effect.\n4. Build a chat or completion input\n\nUse query or prompt for the user message. The connector trims the selected\nvalue and rejects an empty message.\n\n{\n  \"query\": \"Summarize the approved refund policy.\",\n  \"inputs\": {\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\",\n  \"files\": [],\n  \"autogeneratename\": false\n}\n\nChat-like modes can also send conversationid, files, and\nautogeneratename. Completion accepts files but does not send conversation\nor automatic-name fields.\n\nquery and prompt each allow at most 1 MiB. files allows at most 100\nobjects. The complete encoded provider JSON cannot exceed 8 MiB.\n\nUse only file references or remote sources already authorized for the same app\nand end user. Uploading bytes and invoking the app are separate effects.\n5. Build a workflow input\n\nWorkflow invocation sends inputs, connector-selected responsemode, and the\nstable user. It does not require a query.\n\n{\n  \"inputs\": {\n    \"topic\": \"quarterly forecast\",\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\"\n}\n\nValidate every input name and value against the published workflow contract.\nThe alias invokes the app's current published workflow; it does not select a\nspecific workflow version ID.\n\nUse the dedicated run-by-ID capability only when policy and discovery require\na pinned published version.\n6. Choose blocking or streaming execution\n\nThe alias contract supports synchronous, asynchronous, streaming, and\ncancellation surfaces. The connector, not Action input, controls Dify\nresponsemode.\n\n| AIP execution path | Provider mode | Observable result |\n\n| Blocking invocation | blocking | One completed or requireshuman result |\n| Typed streaming execution | streaming | Bounded AIP chunks plus one terminal result |\n| Durable asynchronous caller flow | Runtime-managed | Poll the original Action; do not create a replay |\n\nCaller-supplied responsemode is not part of the alias input schema. Do not\nadd it to the Action or assume it overrides the execution path.\n\nStreaming limits each SSE frame to 1 MiB, parsed events to 10,000, and total\nbytes to the configured response limit. The default total limit is 8 MiB.\n7. Interpret streaming and terminal state\n\nThe connector maps provider events to AIP stream chunks:\n\n| Provider event | AIP meaning |\n\n| workflowstarted, nodestarted | Progress |\n| toolcall | Tool activity |\n| agentthought | Agent reasoning metadata |\n| message | Data |\n| humaninputrequired, workflowpaused | Pending approval or input |\n| error | Failed result |\n| messageend, workflowfinished | Terminal result |\n\nThe connector assembles text from answer-bearing events. A terminal output can\ncontain answer plus finalevent, or only the final event data.\n\nAn upstream close without a terminal event is an error. A non-succeeded\nworkflow finish is failed even when the HTTP stream began successfully.\n8. Continue chat or answer human input\n\nFor a later chat turn, use the provider conversationid returned by the first\nturn and preserve the same user:\n\n{\n  \"query\": \"Apply that policy to order 1042.\",\n  \"inputs\": {\n    \"region\": \"emea\"\n  },\n  \"user\": \"tenant-user-0190\",\n  \"conversationid\": \"0190c42f-2d5a-7000-8000-000000000901\"\n}\n\nDo not attach a conversation from another app or user. Confirm continuity\nthrough a conversation read when identity or outcome is uncertain.\n\nA humaninputrequired or workflowpaused event produces an AIP\nrequireshuman result. Preserve the form token and read the form through its\ndedicated capability.\n\nSubmit one approved form response through a new Action. Forms are one-shot, so\nnever replay the original app invocation to answer a pause.\n9. Cancel with evidence\n\nDuring streaming, the connector records a remote task only after Dify emits a\ntask ID. Cancellation after that point uses the mode-specific stop route and\nthe same app and user.\n\nCancellation before a task ID arrives can close the local request but cannot\nconfirm a remote stop. Record remotestopconfirmed: false and inspect the\nprovider's authoritative run or conversation state.\n\nA stop response means the provider accepted task control. Retain terminal\nevent, workflow-run, or conversation evidence before reporting the business\noperation as stopped.\n10. Settle uncertain outcomes\n\n| Observation | Decision |\n\n| Input is rejected before dispatch | Correct the same reviewed intent without claiming a provider effect |\n| Action remains pending approval | Decide the immutable Action; do not submit a replacement |\n| Blocking response is lost | Read authoritative conversation or workflow state before another invocation |\n| Stream closes before terminal evidence | Treat completion as unknown and inspect the provider run |\n| Human-input state is returned | Preserve the form token and submit one separately approved response |\n| Cancellation lacks a task ID | Record unconfirmed remote stop and inspect provider state |\n| Terminal provider event reports failure | Keep the failed Action and repair the cause before a new intent |\n| Result crosses an app or user boundary | Stop traffic and treat the event as an isolation incident |\n\nNever automatically retry an alias invocation. A new Action is appropriate\nonly after authoritative evidence shows that a new intent is required.\n\nCompletion checklist\n• The capability came from authenticated tenant discovery.\n• App mode, user mapping, input, approval, and idempotency key were frozen.\n• Files and remote sources belonged to the same authorized task.\n• Blocking or streaming behavior matched the selected AIP execution path.\n• A terminal, failed, or requireshuman state was retained.\n• Cancellation and replay claims match available provider evidence.\n• Sensitive inputs, outputs, events, and errors were redacted from general logs.\n\nRelated documentation\n• Dify capability index (../capabilities/README.md)\n• Dify app metadata and files (../capabilities/app-metadata-and-files.md)\n• Dify chat messages, conversations, and feedback (../capabilities/chat-messages-conversations-and-feedback.md)\n• Dify workflows, streaming, and human input (../capabilities/workflows-streaming-and-human-input.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "f4368e50c830c014fa86b303264039a40775625af74257759ee839f8198f6345"
  }
}