dify-guides/README.md

# Dify guides

Step-by-step guides, appendices and a two-hour workshop on building AI agents in Dify for
education. Made by LeX Consultancy B.V. All examples play at Example College (fictional);
screens captured on Dify cloud, 20 September 2026.

The screenshots show the English Dify interface and the English build of each app.

Licence: CC BY-SA 4.0 (documents, slides, images) and MIT (scripts), see LICENSE.md.
Owner and contact: Guido van Dijk, guido@l-e-x.nl.


## The five series side by side

The same six agents, built in four environments, so you can practise in the platform your school
already has. The Dutch series are in Dutch; this one is the English edition.

| Series | Where you build | Who can build | Pick this if |
| --- | --- | --- | --- |
| [dify-guides](https://git.lexconsultancy.nl/guido/dify-guides) | Dify, English | Anyone with an account | You work in English (this series) |
| [dify-handleidingen](https://git.lexconsultancy.nl/guido/dify-handleidingen) | Dify, Dutch | Anyone with an account | You want to see the mechanics: knowledge base, custom tools, gatekeeper, a human in the loop |
| [copilot-handleidingen](https://git.lexconsultancy.nl/guido/copilot-handleidingen) | Microsoft 365 Copilot Chat, Dutch | Any colleague with a school account | Your school runs on Microsoft 365 |
| [chatgpt-handleidingen](https://git.lexconsultancy.nl/guido/chatgpt-handleidingen) | ChatGPT, custom GPTs, Dutch | Only with a paid plan or workspace | You already have a ChatGPT workspace |
| [gemini-handleidingen](https://git.lexconsultancy.nl/guido/gemini-handleidingen) | Google Gemini, Gems, Dutch | Any colleague with a school account | Your school runs on Google Workspace for Education |

All series: CC BY-SA 4.0 for documents and images, MIT for the scripts. The Python scripts in
`_gereedschap` turn the texts into PDFs and build the slides and the explainer videos; you do not
need them to follow a guide or to build an agent.

## Contents

| Folder | Title | For whom | Size |
| --- | --- | --- | --- |
| 01-workflow | Building in Dify: from workflow to agent | Beginners | 22 pp. |
| 02-agent-knowledge-base | Building in Dify: an agent with its own knowledge base | Beginners, sequel to 01 | 22 pp. |
| 03-school-communication | Dify for school communication: parent letter, school news, reception | Communications teams | 36 pp. |
| 04-agent-console | Building in the Agent Console: the Test week planner (agent with file, tool and sandbox) | Form tutors, ICT coordinators | 27 pp. |
| 05-transcription-tool | Building in Dify: from recording to minutes | Departments, teams | 30 pp. |
| 06-inclusive-materials | Building in the Agent Console: the Materials check (UDL, custom search tool for open educational resources) | Teachers, support coordinators | 26 pp. |
| 07-school-news-with-checks | School news with checks: self-critique and gatekeeper, sequel to 03 | Communications teams | 26 pp. |
| 08-chatflow-study-coach | Study coach biology Year 9: Chatflow with four routes, memory and a teacher in the loop | Teachers | 46 pp. |
| 00-workshop | Facilitator guide for the workshop AI Agents with Dify (2 hours): programme, formats, pitfalls per block | Facilitators | 8 pp. |
| 00-presentation | Presentation for the workshop: PDF, source of the slides and speaker notes | Facilitators | 22 slides |
| 00-design-patterns | Five design patterns for AI agents and how to build them in Dify | Everyone | 5 pp. |
| 00-design-card | Design card: one A4 to design your app before you click; in examples/ the filled-in card of each of the eight apps | Everyone | 1 A4 + 8 examples |
| 00-ai-tools | AI tools in education: what is already in school, what is allowed (GDPR, AI Act), the EU competence frameworks | Everyone | 9 pp. |
| 00-self-hosting | Self-hosting Dify: the Community Edition with Docker on Windows, Mac and Linux, and what changes for a school server | IT, curious builders | 8 pp. |

Every guide has a green "Your choice" box per step (what you replace with your own material,
style or prompt) and a closing chapter "Make it yours" with adjustments, assignments and a checklist.

## What each app is for

Every guide builds one app. This is what they are meant for and when you choose which.

| App | What it does | For whom | Kind | Choose this if |
| --- | --- | --- | --- | --- |
| Text at level (01) | Rewrites a text for a chosen audience or reading level | Teachers, communications | Workflow | You want to learn what a workflow is: fixed steps, one input, one output |
| School guide assistant (02) | Answers questions from parents and students out of the school guide, with sources | Reception, form tutors, parents | Agent with knowledge base | You have a document that keeps getting the same questions |
| Parent letter assistant (03) | Writes a parent letter in the school's style, based on the style guide | Teams, heads of year | Agent with knowledge base | Letters must have one tone and one layout, written by different people |
| School news (03 and 07) | Turns one message into three versions: website, parent app and social; in 07 with a checker and a gatekeeper that rejects what breaks the rules | Communications officers | Workflow | You want to see how an app checks itself before something goes out |
| Test week planner (04) | Makes a study plan for the test week with a student and delivers Excel and a calendar file | Form tutors, students (after an impact assessment) | Agent Console | You want to see what an agent can do that a workflow cannot: decide how, and make files |
| Transcription tool (05) | Turns a recording of a meeting into minutes with decisions and action points | Departments, teams | Workflow with tool | You want a file as input and a tool (speech to text) in a workflow |
| Materials check (06) | Assesses learning material for accessibility (UDL), makes versions for teacher and student and searches for open educational resources | Teachers, support coordinators | Agent Console with custom tool | You want to make your own tool out of a website with an API |
| Study coach biology (08) | Helps a student with explanations, hints and planning on ecology; passes personal questions to the teacher | Teachers, students (after an impact assessment) | Chatflow | You want a conversation with routes, memory and a human in the loop |

The order is also a learning path: 01 and 02 in the first hour of the workshop, 03 and 07 when you want to help a team, 05 and 08 when you want to serve a subject, 04 and 06 when you want to know what the Agent Console adds.

## Example apps

The apps are live to try out:

- Text at level (01): https://udify.app/workflow/VHWboGL9462eA1KI
- School guide assistant (02, with the Reception mode from 03): https://udify.app/chat/6Y6WnP0m5Z3jSHRs
- Parent letter assistant (03): https://udify.app/chat/oB2H2mLaoKR6d4IC
- School news (03 and 07): https://udify.app/workflow/E2CHtVPKe3PLg7GF
- Test week planner (04): https://udify.app/agent/x0yjuGoRIVdZaVZe
- Transcription tool (05): https://udify.app/workflow/EPAc3PPeD3E4764l
- Materials check (06): https://udify.app/agent/BIKJSPHj1JnCRzAp
- Study coach biology (08): https://udify.app/chat/mgvtZPbDVAIp5gbh

## Installing the apps in your own Dify

Every Studio app is also in its guide's folder as a file: `<name>.dify.yml`. That is Dify's DSL
export. This is how you put it in your own workspace (online or self-hosted):

1. Download the `.dify.yml` file from the folder.
2. In Dify go to **Studio**, click **Create** and choose **Import DSL file**.
3. Drag the file into the window and click **Create**.
4. At every LLM step pick your own model (the export refers to gpt-5-mini via OpenAI) and under
   **Knowledge** attach your own knowledge base; that does not travel with the file. Create it
   first with the sample document from the same folder (guide 02, steps 1 to 5).
5. **Publish**.

The files contain no keys. An Agent Console app (04, 06) is imported the same way, but from the
**Agents** page (**Create**, **Import DSL file**). An agent export lists the uploaded file but
does not contain it: after importing, upload the CSV or PDF from the guide's folder again under
**FILES**. For 06, first create the custom tool (Integrations, Swagger API as Tool, schema from
`oer-search.openapi.json`) and add it under **TOOLS**.

| File | Guide |
| --- | --- |
| 01-workflow/text-at-level.dify.yml | 01 |
| 02-agent-knowledge-base/school-guide-assistant.dify.yml | 02 (including the Reception mode from 03) |
| 03-school-communication/parent-letter-assistant.dify.yml | 03 |
| 03-school-communication/school-news.dify.yml | 03 and 07 (version 2, with Checker and Gatekeeper) |
| 04-agent-console/test-week-planner.dify.yml | 04 (Agent Console; upload exam-timetable-example.csv again) |
| 05-transcription-tool/transcription-tool.dify.yml | 05 |
| 06-inclusive-materials/materials-check.dify.yml | 06 (Agent Console; recreate the OER search tool, upload the PDF again) |
| 08-chatflow-study-coach/study-coach-biology.dify.yml | 08 |

## Building or editing yourself

Every folder has the same structure:

    guide-*.md            source (edit this)
    screenshots/          screenshots, numbered in order
    build.py              makes .html, .pdf and .docx from the .md:  python3 build.py

`python3 _tools/build_all.py` builds everything at once; `python3 00-presentation/build.py`
builds the slides and the PDF of the presentation. `python3 _tools/make_samples.py` regenerates
the fictional sample documents. Needed: python3 with `markdown`, google-chrome and libreoffice.
The PDFs are in git next to the sources; HTML and Word you make yourself with build.py.

Formatting in the sources: numbered list = actions, table "What you type" = field values,
code block = type literally (label "Type in"), orange box = pitfall, green box = "Your choice"
(a blockquote that starts with **Your choice**). Layout and logo are in `_tools/build_guide.py`;
replace the logo with that of your own school or organisation.

The Dutch original of this series is at https://git.lexconsultancy.nl/guido/dify-handleidingen.
The same apps built in Microsoft 365 Copilot (Agent Builder, Dutch): https://git.lexconsultancy.nl/guido/copilot-handleidingen
and as Gems in Google Gemini (Dutch): https://git.lexconsultancy.nl/guido/gemini-handleidingen
The same apps built as Custom GPTs in ChatGPT (Dutch): https://git.lexconsultancy.nl/guido/chatgpt-handleidingen