Dify Tutorial: Build an AI Application with Workflows and Document Retrieval

Dify provides a visual environment for building AI applications with workflows, model connections and document retrieval. Start with a bounded question-answering workflow rather than an autonomous agent. The useful outcome is an inspectable path from input to retrieved evidence to answer, with clear handling when evidence is missing.

Prepare an installation with understood terms

The official Dify repository links cloud and self-hosting options. Choose the deployment route deliberately: a self-hosted application can still send prompts to external model providers, while a managed application has its own hosting and data terms.

The repository identifies the Dify Open Source License as based on Apache 2.0 with additional conditions. Read those conditions before offering a hosted service, redistributing a modified product or changing branding. Do not describe the licence simply as unmodified Apache 2.0.

For a local development deployment, the checked repository documents Docker Compose. With Git, Docker and compatible Compose installed, the sequence is:

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d

This is an instructional example, not an executed installation. Select a reviewed release before production and inspect .env, credentials, persistent storage and exposed services. The application's stated minimum requirements do not include every resource needed by separately hosted local models.

Keep a record of the selected release and relevant documentation. Read migration notes before upgrading an existing installation, and back up persistent data rather than recreating the environment to resolve an unexplained error.

Build one explicit retrieval workflow

Configure your chosen model provider and confirm a simple prompt succeeds. Identify the generator and embedding model separately. Store credentials through the supported secret or provider configuration, never in text that will be included in prompts or exported publicly.

Create a knowledge collection from a few non-sensitive documents. Use known answers and preserve document titles and versions. Inspect extracted text and chunk boundaries, particularly for tables and scanned pages.

In a workflow application, define an input field for the user's question. Connect the documented retrieval component to the knowledge collection, then pass its returned passages and the question to a generation step. Finish by exposing the answer and source references through the supported output mechanism.

Exact node names and variable selectors can change, so match them to the chosen release's interface. The configuration decision is stable: evidence should flow explicitly from retrieval into generation, rather than relying on an unstated assumption that uploaded files are always visible to the model.

Use a prompt that requests an answer from supplied evidence and an acknowledgement when evidence is insufficient. This is a behavioural instruction, not a security boundary or a guarantee. Keep retrieved content distinguishable from application instructions.

Inspect the result before making it a service

Test directly answerable, multi-document and unanswerable questions. Save expected evidence for each. In the workflow trace, check whether retrieval found the right passage before judging the final response.

If a citation is returned, open it and verify the claim against the passage. A reference to a relevant document can still support the wrong interpretation. Include a deliberately outdated document to test version handling and conflict resolution.

Review what happens on provider failure, empty retrieval and long inputs. A good workflow should return a useful bounded error or a request for clarification, not silently invent an answer. Put limits on input size and model output to control resource use.

Check user and document permissions before sharing. Access filtering must happen before restricted text reaches generation. Also inspect logs, tracing and backups because they may retain prompts or uploaded content outside the immediate conversation.

For external actions, such as creating a ticket, add a separate validation and approval step appropriate to the consequence. Do not let a quoted document instruct the application to reveal credentials or send information elsewhere.

Your next step is a small unpublished pilot with a repeatable evaluation set. Expand workflows only after you can explain each variable, credential, evidence source and failure path. A visual editor reduces some coding work but does not replace application design or editorial judgement.

Quick questions, clear answers

Is every Dify application an agent?

No. A deterministic workflow can run retrieval and generation in a fixed sequence without letting the model choose arbitrary actions. Begin there when the process is known. Add agentic decisions only when variable task paths justify the extra evaluation and permission controls.

Does uploading documents keep them local?

That depends on deployment and configured providers. Extraction, embeddings, generation and observability can have separate endpoints. Trace the entire path with non-sensitive samples and review storage and retention. Self-hosting the interface alone does not establish an offline or confidential workflow.

Can I skip evaluating a visual workflow?

No. Visual connections can still use wrong variables, stale evidence or overly broad credentials. Test known answers and failures, then inspect traces. The interface makes the pipeline visible, but correctness depends on how its components are configured and how outputs are checked.

About this guide

Aniket Thakur prepared this guide from secondary research checked on 22 October 2026. No first-hand software testing or performance benchmarking was conducted. Examples are instructional and require validation in your environment.