commit 180361eda4ac8704861ab4355e8d654a7767fa23 Author: Guido van Dijk Date: Sun Sep 20 23:09:39 2026 +0200 Dify guides: first release, English set, 20 September 2026 Eight step-by-step guides, appendices (design patterns, design card with eight filled-in examples, AI tools in education), facilitator guide and presentation. LeX Consultancy edition; screenshots from the Dutch build of the same apps. Co-Authored-By: Claude Opus 5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..03fad9b --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +# Built output: make it with python3 build.py in every folder. The PDFs are in git. +*.html +*.docx +!00-presentation/project/slides/*.html +__pycache__/ +.*-embed.html diff --git a/00-ai-tools/ai-tools-in-education.md b/00-ai-tools/ai-tools-in-education.md new file mode 100644 index 0000000..0551c61 --- /dev/null +++ b/00-ai-tools/ai-tools-in-education.md @@ -0,0 +1,227 @@ + + +# AI tools in education: what is already there, and where Dify fits + +**Appendix to the AI Agents workshop** +LeX Consultancy B.V. · 20 September 2026 + +Almost everyone in the room already uses an AI tool: Copilot because the school has Microsoft, Gemini because the school has Google, ChatGPT because it is the best known. This appendix puts the tools side by side in plain words: what it is, where it already sits in school, what a school should check, and when to use it or not. At the end is where Dify fits in this landscape, because Dify is not yet another chatbot but a building layer on top of these tools. + +Everything below is the state of play on **20 September 2026**. This market changes every quarter. For decisions about use at school you always look at the current advice of your national education bodies and data protection authority. + +> The most important sentence of this appendix: **the difference is not the model but the account.** The same chatbot with a free private account is something quite different from the same chatbot with a school account under a data processing agreement. In the first case your conversations can be used to train the model and you have no rights; in the second case there are agreements about that. So never ask "may we use ChatGPT?" but "under which account, with which data, for which task?" + +--- + +## Three layers + +It helps to keep three layers apart. Most discussions at school are about layer 1; most of the gain is in layers 2 and 3. + +| Layer | What it is | Examples | Who decides | +| --- | --- | --- | --- | +| **1. Chatbot** | You type a question, you get an answer. Every time you explain again what you want. | ChatGPT, the Gemini app, Claude, Le Chat, Copilot Chat | The user themselves, often without the school knowing | +| **2. Assistant in your office suite** | AI in the tools you already have: summarise mail, draft a presentation, explain a table. | Microsoft 365 Copilot, Gemini in Workspace for Education | The school, through licences and settings | +| **3. Building platform** | You build an app with fixed steps, your own rules and your own documents, and share it with colleagues. | Dify, Copilot Studio, Gems (Google), GPTs and Projects (OpenAI), Projects (Claude) | The school, per app; this is what this workshop is about | + +A chatbot (layer 1) is handy for someone who can steer well themselves. An app (layer 3) takes over that steering: the rules are built in, so a colleague who never wrote a prompt still gets a good result. That is exactly why the guides build apps rather than hand out prompts. + +--- + +## The tools side by side + +### Microsoft Copilot + +| | | +| --- | --- | +| **From** | Microsoft (US), models from OpenAI and its own models | +| **Where it already sits in school** | In Microsoft 365: Copilot Chat with a school account is often already there; Microsoft 365 Copilot (in Word, Outlook, Teams) is a separate licence | +| **State of play** | Several European education bodies have carried out data protection impact assessments on Microsoft 365 Copilot; the general line in 2025-2026 is cautious use with school agreements in place first. Check the assessment of your own national body | +| **Suited for** | Working in your own documents and mail, summaries of Teams meetings, first drafts of texts | +| **Watch out** | Copilot Chat with a school account (data stays in the tenant) is something different from Copilot in the browser with a private account. Check which one you have. Copilot Studio is Microsoft's building platform; comparable to Dify, but tied to Microsoft | + +### Google Gemini + +| | | +| --- | --- | +| **From** | Google (US) | +| **Where it already sits in school** | In Workspace for Education: Gemini in Docs, Gmail and Classroom, the Gemini app, NotebookLM, Gems | +| **State of play** | Assessments by education bodies are ongoing in several countries; Google meanwhile switches Gemini on in more and more components, and administrators can switch it off per component | +| **Suited for** | Working in Google documents, NotebookLM for learning from your own sources, Gems as a simple assistant of your own | +| **Watch out** | Wait with use by students until an assessment is done. Check what your administrator has switched on; defaults change with updates | + +### ChatGPT (OpenAI) + +| | | +| --- | --- | +| **From** | OpenAI (US) | +| **Where it already sits in school** | Usually not through school; massively in private use by teachers and students | +| **State of play** | With a free or Plus account conversations can by default be used for training (can be switched off in the settings); with Team, Enterprise and Edu not, and a data processing agreement is then possible | +| **Suited for** | The broadest ecosystem: GPTs, Projects, voice, images. For personal use by the teacher without school data | +| **Watch out** | Never student data or unpublished test material in a private account. Through the API (as in Dify) different conditions apply than in the app: by default no training on API traffic | + +### Claude (Anthropic) + +| | | +| --- | --- | +| **From** | Anthropic (US) | +| **Where it already sits in school** | Rarely through school; available as a model through Dify | +| **State of play** | Claude for Education and a learning mode exist, aimed mainly at higher education. Business accounts do not train on conversations | +| **Suited for** | Reading and rewriting long documents, careful language, Projects with your own sources. In Dify's Agent Console one of the compatible models | +| **Watch out** | Same rule as for ChatGPT: the account determines what is allowed. More expensive per answer than gpt-5-mini | + +### Mistral (Le Chat) + +| | | +| --- | --- | +| **From** | Mistral AI (France) | +| **Where it already sits in school** | Rarely through school | +| **State of play** | European provider, falls under EU law and hosting in the EU is possible; some models are open (you can run them yourself) | +| **Suited for** | Anyone who wants a European provider or wants to self-host; strong in French and other European languages | +| **Watch out** | Smaller ecosystem; fewer ready-made education features. Here too: a free account is not the same as a business account | + +### DeepSeek + +| | | +| --- | --- | +| **From** | DeepSeek (China) | +| **Where it already sits in school** | Not through school | +| **State of play** | The app and the website process data on servers in China; several European data protection authorities have warned about it. The open models can be hosted by European parties | +| **Suited for** | Only as an open model, hosted by a party in the EU, for those who want to experiment technically | +| **Watch out** | Do not use with school data through the app. The model is not the problem, the processing is | + +### Grok (xAI) + +| | | +| --- | --- | +| **From** | xAI (US), intertwined with X | +| **Where it already sits in school** | Not through school | +| **State of play** | No meaningful use in education; repeated controversies about unfiltered output and the use of X posts for training | +| **Suited for** | Nothing in a school context | +| **Watch out** | Do not use. Do mention it in media literacy lessons: students meet it on X | + +### Perplexity + +| | | +| --- | --- | +| **From** | Perplexity (US) | +| **Where it already sits in school** | Not through school; popular with students as a "search engine" | +| **State of play** | No education assessment. Searches the web and gives sources | +| **Suited for** | Exploratory searching with sources; check the sources yourself afterwards | +| **Watch out** | The sources are not always the best, and the summary is not always what the source says | + +### NotebookLM + +| | | +| --- | --- | +| **From** | Google (US) | +| **Where it already sits in school** | Part of Workspace for Education (the administrator can switch it on or off) | +| **State of play** | Falls under the Google assessments of your education body; check whether your administrator has switched it on | +| **Suited for** | Learning from your own sources: summary, questions, an audio overview of a chapter | +| **Watch out** | Only with material you may upload. The same rules as for a knowledge base in Dify | + +### European public models + +| | | +| --- | --- | +| **From** | National and European public initiatives (for example the Dutch GPT-NL, the EU's OpenEuroLLM and similar projects) | +| **Where it already sits in school** | Not yet in schools | +| **State of play** | Language models in development with attention to lawful training data and European values; meant for public organisations | +| **Suited for** | In time: a model whose data provenance is known | +| **Watch out** | Not yet a product you use today; do follow it | + +--- + +## Four questions for every tool + +Whether it is Copilot or an app you build yourself in Dify, the same four questions determine whether it is allowed and whether it is wise. + +1. **Under which account?** Private, free, paid, or a school account with a data processing agreement. Only in the last case does the school have a say in what happens to the data. +2. **Which data goes in?** No personal data of students, parents or colleagues, unless the tool has been assessed for that. Unpublished test material and confidential documents count too. +3. **Is it trained on what you enter?** With consumer accounts often yes by default (sometimes you can switch it off), with business accounts and API use usually no. Check it; do not take a colleague's word for it. +4. **Who decides and who checks?** A tool one teacher uses for themselves is something different from a tool students use. For the second a school decision is needed, and someone who checks the output. + +Aids that already exist: + +- **The assessment framework of your national education body** for AI systems under the EU AI Act: most countries now have a decision tree and checklists for school and supplier. Use it at procurement and for every tool that touches students. +- **Team agreements about generative AI**: many education bodies publish a toolkit to make agreements as a team. Do that before the tools, not after. +- **The rule of thumb on age**: several education bodies advise that children under 13 do not work with generative AI independently. +- **The impact assessments of your national bodies** on Microsoft and Google: the only independent assessments for the education sector. Other providers have no such assessment; that does not mean they are unsafe, but it does mean the school has to find out for itself. + +--- + +## GDPR and the AI Act in brief + +Two laws determine what is allowed. The **GDPR** is about personal data, the **EU AI Act** about AI systems. They overlap, but ask different questions. + +**GDPR: who is responsible for the data?** + +- The school is the controller. Dify (cloud, outside the EU) and the model provider (OpenAI, Anthropic, Google) are processors. Without a data processing agreement no personal data may go in, and a sandbox account has no such agreement. That is why the guides work with fictional material. +- As soon as an app processes data of students, parents or colleagues (a name in a parent letter, a personal message to the Study coach that goes to the teacher), you need a legal basis, data minimisation, a retention period for the logs and, for high risk, a data protection impact assessment. With students that is almost always high risk. +- Transfer outside the EU needs a legal basis (for example the EU-US Data Privacy Framework for US providers that fall under it); check that per provider, it changes. + +**AI Act: what kind of system is it, and what do you have to do?** + +| Part | Since | What it means for a school | +| --- | --- | --- | +| Art. 4, AI literacy | 2 February 2025 | Whoever uses AI makes sure staff know enough about it. A workshop like this is such a measure; record who attended | +| Art. 5, prohibited practices | 2 February 2025 | Among others emotion recognition in education. Do not use a tool that measures the mood or attention of students | +| Annex III, high risk in education | planned August 2026; in 2025-2026 a delay was discussed, check the current state | Admission and placement, assessing learning outcomes or level, proctoring tests. Then heavy requirements apply to supplier and school: risk management, human oversight, documentation, registration | +| Art. 50, transparency | August 2026 | A chatbot lets people know they are talking to AI; AI-generated content is made recognisable as such where relevant | + +The apps in this series (rewriting text, answering questions from a school guide, drafting messages, summarising a transcript) take no decisions about people and do not fall under high risk. The line is close: a Study coach that explains and gives hints is not high risk; the same coach that would record who does not understand the material and report that to the teacher as an assessment would be. That is a design choice, and the design card asks about it in box 4. + +## The EU competence frameworks: where building fits + +The AI Act says that staff must be AI literate; two European frameworks say what that means. + +- The **AI Literacy Framework for Primary and Secondary Education** (OECD and European Commission, final in 2026) describes four competence domains for students, each with knowledge, skills and attitudes: **Engage with AI** (understanding how it works and dealing with it responsibly), **Create with AI** (making something with it), **Manage AI** (using and monitoring it responsibly) and **Shape AI** (making choices and exerting influence). +- **DigCompEdu** is the European framework for the digital competences of teachers (six areas, from professional engagement to fostering students' digital competence); the Commission has added supplements for AI and data. + +The guide series and the workshop touch all four domains, and that can be used in a professional development plan: + +| Domain | In the series | +| --- | --- | +| Engage with AI | Three layers, five patterns, sabotaging the agent, the knowledge base that splits wrongly | +| Create with AI | The building blocks: workflow, agent, chatflow, gatekeeper, agent console | +| Manage AI | Gatekeeper and self-critique, the human in the loop, Logs, the checklists for your own material, the four questions | +| Shape AI | The design card, the pitch, the choice of where the human belongs and what an app must never decide | + +Sources: ailiteracyframework.org and education.ec.europa.eu (AI Literacy Framework); joint-research-centre.ec.europa.eu (DigCompEdu). + +## Where Dify fits + +Dify is not a model and not a chatbot. It is a building platform (layer 3) that calls the models of the providers above through their API. In the guides you chose a model per app: usually gpt-5-mini from OpenAI, in the Agent Console also Claude or Gemini. Three consequences: + +**1. You choose the model per task, and can switch.** Rewriting a parent letter can be done with a small, cheap model. Analysing a long policy document asks for a bigger model. In Dify you change that in one menu, without the user of the app noticing. If a European model good enough arrives tomorrow, you put that underneath. + +**2. API traffic is not the same as the chatbot.** What goes through the API of OpenAI, Anthropic or Google is by default not used to train models, and there is a business agreement. That is a better position than a free chatbot account. But the data still goes to a processor outside the school, usually outside the EU. The rules from the four questions still apply. + +**3. Dify cloud itself is a processor too.** The sandbox account from the workshop runs on Dify's servers, outside the EU. For practising with fictional material that is fine. For real use with school data there are two routes: host Dify yourself (it is open source) or run it in an environment of your school or trust with central model keys. Guide 5 (Transcription tool) shows how to move a prototype out of the cloud. + +**When to use what** + +| Situation | Take | +| --- | --- | +| A quick question, a first draft, something for yourself | The chatbot your school has an account for (Copilot Chat or Gemini with a school account) | +| A task that comes back every week and has to follow rules (house style, format, sources) | An app in Dify, or in the building platform of your suite (Copilot Studio, Gems) | +| Working in your own documents and mail | Microsoft 365 Copilot or Gemini in Workspace, once your school leadership has taken a decision based on the assessments | +| Something for students | First the school decision, the assessment framework and the age limit; only then the tool | +| Experimenting with what is possible | Dify with fictional material, as in this workshop | + +--- + +## To remember + +- The account determines more than the brand. +- GDPR: no personal data without a data processing agreement. AI Act: literacy is mandatory, assessing students is high risk, a chatbot says it is AI. +- Copilot and Gemini are already in school; whether they may be switched on is a leadership decision based on the assessments of your education bodies, not the choice of an individual teacher. +- ChatGPT, Claude and Mistral are fine tools for the teacher themselves, without school data, and as the model under an app. +- The DeepSeek app and Grok stay out of school. +- You put Dify on top of these models: you build the rules in, choose the model per task and can switch when the market changes. For real use the building layer belongs with the school or trust, not in a free cloud account. diff --git a/00-ai-tools/ai-tools-in-education.pdf b/00-ai-tools/ai-tools-in-education.pdf new file mode 100644 index 0000000..3b69111 Binary files /dev/null and b/00-ai-tools/ai-tools-in-education.pdf differ diff --git a/00-ai-tools/build.py b/00-ai-tools/build.py new file mode 100644 index 0000000..a99e5db --- /dev/null +++ b/00-ai-tools/build.py @@ -0,0 +1,4 @@ +import runpy, sys +from pathlib import Path +sys.argv = ["build_guide.py", str(Path(__file__).resolve().parent / "ai-tools-in-education.md")] +runpy.run_path(str(Path(__file__).resolve().parent.parent / "_tools" / "build_guide.py"), run_name="__main__") diff --git a/00-design-card/build.py b/00-design-card/build.py new file mode 100644 index 0000000..08dd1be --- /dev/null +++ b/00-design-card/build.py @@ -0,0 +1,7 @@ +import runpy, sys +from pathlib import Path +here = Path(__file__).resolve().parent +build = here.parent / "_tools" / "build_guide.py" +for md in [here / "design-card.md"] + sorted((here / "examples").glob("*.md")): + sys.argv = ["build_guide.py", str(md)] + runpy.run_path(str(build), run_name="__main__") diff --git a/00-design-card/design-card.md b/00-design-card/design-card.md new file mode 100644 index 0000000..a547369 --- /dev/null +++ b/00-design-card/design-card.md @@ -0,0 +1,46 @@ + + +# Design card: your app in five boxes + +**For the AI Agents workshop · fill this in before you build** +LeX Consultancy B.V. · 20 September 2026 + +Fill in first, then build. One card per app, with a pen, at most three lines per box. + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| Who uses the app, and in which situation? One person, not "everyone". What does that person already know, what do they have no time for?
 
 
  | What does the user paste or choose? Text, a file, a choice from a short list? Which questions do you always ask before you write something for someone? Those are your input fields.
 
 
  | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| Describe the end product as if it already exists: how long, which headings, in which language, readable for whom. Write out one example by hand.
 
 
  | Which rules of your school or team apply? House style, form of address, what it must never invent, when it must say "I do not know". Which document contains those rules? That is your knowledge base.
 
 
  | + +**5. How you know it works** + +Three test cases, written down before you build: two ordinary ones and one where the app must refuse or ask further. Only when all three go well do you share the link. + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 |  
  |  
  | +| 2 |  
  |  
  | +| 3 (the hard one) |  
  |  
  | + +| If... | Then you build a... | See guide | +| --- | --- | --- | +| the steps are always the same and the user fills in a form | **Workflow** | 1, 3 (School news), 5, 7 | +| the user asks questions and the app has to search in a document | **Agent with knowledge base** | 2, 3 (Parent letter, Reception) | +| it is a conversation with different kinds of questions, memory and sometimes a person | **Chatflow** | 8 | +| the app has to work out for itself what is needed, read files or search the web | **Agent Console** | 4, 6 | + +**Before you click Create** + +- [ ] Box 1 names one person, not an audience +- [ ] Box 3 contains a written-out example +- [ ] The document in box 4 contains no personal data and may go to an external processor +- [ ] There is an owner, you know who gets the link, and you know what one run costs diff --git a/00-design-card/design-card.pdf b/00-design-card/design-card.pdf new file mode 100644 index 0000000..55906c4 Binary files /dev/null and b/00-design-card/design-card.pdf differ diff --git a/00-design-card/examples/design-card-01-text-at-level.md b/00-design-card/examples/design-card-01-text-at-level.md new file mode 100644 index 0000000..f53967a --- /dev/null +++ b/00-design-card/examples/design-card-01-text-at-level.md @@ -0,0 +1,36 @@ + + +# Design card: Text at level + +**For the AI Agents workshop · filled-in example for guide 1** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Workflow**, guide 1. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| An English teacher with a reading text from the course book that is too hard for half of Year 9. Has ten minutes before the lesson and does not want to rewrite it by hand. | The text (pasted, a Paragraph field) and the level from a short list: year 6, year 7, year 9, year 12 (a Select field). | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| The text rewritten at the chosen level, with all the content kept and technical terms explained in a subordinate clause; below it three comprehension questions (fact, main idea, application) without answers. | Short sentences, leave nothing out, do not replace technical terms. No knowledge base needed: the rules live in the prompts of the two LLM steps. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | A paragraph from a geography course book, level year 7 | Shorter sentences, same facts, three questions that are about the text | +| 2 | The same paragraph, level year 12 | Barely simplified, questions at analysis level | +| 3 (the hard one) | A text with a table of figures, level year 6 | The figures stay correct; the app invents no new numbers | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Workflow) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-01-text-at-level.pdf b/00-design-card/examples/design-card-01-text-at-level.pdf new file mode 100644 index 0000000..42e6ac1 Binary files /dev/null and b/00-design-card/examples/design-card-01-text-at-level.pdf differ diff --git a/00-design-card/examples/design-card-02-school-guide-assistant.md b/00-design-card/examples/design-card-02-school-guide-assistant.md new file mode 100644 index 0000000..bf630bf --- /dev/null +++ b/00-design-card/examples/design-card-02-school-guide-assistant.md @@ -0,0 +1,36 @@ + + +# Design card: School guide assistant + +**For the AI Agents workshop · filled-in example for guide 2** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Agent with knowledge base**, guide 2. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| A parent who wants to know at 21:30 whether their child has to report sick at reception tomorrow or can phone. Has never read the school guide. | One question in plain language, in the chat. No form. | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| An answer of at most five sentences in plain English, with the chapter of the school guide it comes from. Or: "that is not in the school guide, please call reception". | Only answers from the school guide in the knowledge base (school-guide-example-college.pdf); invent nothing; refer on when in doubt. Knowledge base: the school guide, split per paragraph. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | What time does the first lesson start? | The right time, with a reference to the chapter on lesson times | +| 2 | May my child bring a phone? | The phone rule from the school guide, briefly | +| 3 (the hard one) | What is the head teacher's salary? | "That is not in the school guide" and a referral to reception | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Agent with knowledge base) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-02-school-guide-assistant.pdf b/00-design-card/examples/design-card-02-school-guide-assistant.pdf new file mode 100644 index 0000000..f4465c9 Binary files /dev/null and b/00-design-card/examples/design-card-02-school-guide-assistant.pdf differ diff --git a/00-design-card/examples/design-card-03-parent-letter-assistant.md b/00-design-card/examples/design-card-03-parent-letter-assistant.md new file mode 100644 index 0000000..7486994 --- /dev/null +++ b/00-design-card/examples/design-card-03-parent-letter-assistant.md @@ -0,0 +1,36 @@ + + +# Design card: Parent letter assistant + +**For the AI Agents workshop · filled-in example for guide 3** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Agent with knowledge base**, guide 3. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| A form tutor who at 16:00 still has to send a letter about next week's school trip and has three woolly paragraphs. Wants the letter to sound like the school, not like themselves. | The draft letter or loose sentences, pasted into the chat. If the class or the requested action is missing, the agent asks for it. | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| The rewritten letter with a subject line, in the style of the style guide (B1, formal address, structure), and below it "What I changed": at most five points with the rule for each. Missing facts as [FILL IN]. | The style guide of Example College (style-guide-example-college.pdf) in the knowledge base; invent no dates, names or appointments; no introduction or compliment from the agent itself. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | A woolly letter about a parents' evening | A short letter with date, time, place and what the parent must do; five improvement points | +| 2 | Two loose sentences without a class | The agent first asks which class the letter is for | +| 3 (the hard one) | A letter without the date of the trip | [FILL IN] where the date should be, no invented date | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Agent with knowledge base) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-03-parent-letter-assistant.pdf b/00-design-card/examples/design-card-03-parent-letter-assistant.pdf new file mode 100644 index 0000000..34a5db4 Binary files /dev/null and b/00-design-card/examples/design-card-03-parent-letter-assistant.pdf differ diff --git a/00-design-card/examples/design-card-04-test-week-planner.md b/00-design-card/examples/design-card-04-test-week-planner.md new file mode 100644 index 0000000..1f9c328 --- /dev/null +++ b/00-design-card/examples/design-card-04-test-week-planner.md @@ -0,0 +1,36 @@ + + +# Design card: Test week planner + +**For the AI Agents workshop · filled-in example for guide 4** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Agent Console**, guide 4. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| A Year 8 student, three weeks before the test week, who does not know where to start. Has the timetable, a phone and an hour and a half in the evenings. | The exam timetable (as a file attached to the agent: exam-timetable-example.csv), the moments the student can study, and per subject easy/average/hard. The agent asks for them one at a time. | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| A plan per day in the chat (block, subject, time, material) and two files from the sandbox: study-plan.xlsx and study-plan.ics for the phone calendar. Closing with the question whether anything should move. | Five planning rules (hard subjects double, every subject twice, blocks of 25-45 min with a break, the evening before a test revision only, nothing outside the given moments); no grades or judgements; keep nothing. Tool: CurrentTime for the date. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | Timetable, moments and difficulty filled in | A plan that meets all five rules, plus xlsx and ics | +| 2 | "Put maths on Tuesday evening" while Wednesday is history | The agent explains why that clashes with the revision rule and offers an alternative | +| 3 (the hard one) | "Will I pass my test?" | No prediction; back to the plan | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Agent Console) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-04-test-week-planner.pdf b/00-design-card/examples/design-card-04-test-week-planner.pdf new file mode 100644 index 0000000..9d6b03e Binary files /dev/null and b/00-design-card/examples/design-card-04-test-week-planner.pdf differ diff --git a/00-design-card/examples/design-card-05-transcription-tool.md b/00-design-card/examples/design-card-05-transcription-tool.md new file mode 100644 index 0000000..63ffb23 --- /dev/null +++ b/00-design-card/examples/design-card-05-transcription-tool.md @@ -0,0 +1,36 @@ + + +# Design card: Transcription tool + +**For the AI Agents workshop · filled-in example for guide 5** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Workflow with tool**, guide 5. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| The minute-taker of a department meeting whose minutes are always two weeks late. Has a 45-minute mp3 and fifteen minutes of time. | One audio file (mp3, m4a or wav, at most 5 MB) through a file field. For the prototype only a fictional recording read out by a computer voice. | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| Minutes with five headings (Meeting, Summary, Decisions, Action points with owner and date, Deferred) and below them the full transcript. Uncertain names with a question mark. | No real recordings in Dify cloud (privacy frame); delete audio after transcription; someone reads the minutes. Tool: Speech To Text with your own OpenAI key. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | The fictional three-minute recording | Minutes with five headings, three action points with an owner | +| 2 | The same recording at 128 kbps (too big) | An error about the file size; shrink to 32 kbps | +| 3 (the hard one) | A photo instead of audio | The input field refuses the file; only Audio is enabled | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Workflow with tool) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-05-transcription-tool.pdf b/00-design-card/examples/design-card-05-transcription-tool.pdf new file mode 100644 index 0000000..6322c93 Binary files /dev/null and b/00-design-card/examples/design-card-05-transcription-tool.pdf differ diff --git a/00-design-card/examples/design-card-06-materials-check.md b/00-design-card/examples/design-card-06-materials-check.md new file mode 100644 index 0000000..8976e9f --- /dev/null +++ b/00-design-card/examples/design-card-06-materials-check.md @@ -0,0 +1,36 @@ + + +# Design card: Materials check + +**For the AI Agents workshop · filled-in example for guide 6** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Agent Console with custom tool**, guide 6. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| A biology teacher with a lesson booklet that is too wordy for a third of the class, and a support coordinator who asks "what do you do for the students with dyslexia?". Has an hour on the training day. | The lesson booklet (as a file attached to the agent or sent in the chat) and the support needs in the class from a list of six (or "I do not know"). | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| A report with seven scores (sentence length, terms, structure, prior knowledge, visuals, processing, choice), three files (teacher note, accessible student version, extension student version) and at most five open resources with licence. | UDL: the form changes, the content and the learning objectives do not; no names or diagnoses; always state the licence, share CC BY-SA under the same licence. Custom tool: OER search (Swagger API). | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | The ecology booklet, dyslexia and EAL | Report, two files, resources that really appear in the search results | +| 2 | The same booklet, gifted added | A third file with extension questions and a research task | +| 3 (the hard one) | "Can you give Jayden his own version?" | No name, no personal advice; the version is for the whole class | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Agent Console with custom tool) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-06-materials-check.pdf b/00-design-card/examples/design-card-06-materials-check.pdf new file mode 100644 index 0000000..67ea6e9 Binary files /dev/null and b/00-design-card/examples/design-card-06-materials-check.pdf differ diff --git a/00-design-card/examples/design-card-07-school-news-with-checks.md b/00-design-card/examples/design-card-07-school-news-with-checks.md new file mode 100644 index 0000000..c2a0298 --- /dev/null +++ b/00-design-card/examples/design-card-07-school-news-with-checks.md @@ -0,0 +1,36 @@ + + +# Design card: School news with checks + +**For the AI Agents workshop · filled-in example for guide 7** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Workflow with checker and gatekeeper**, guide 7. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| The communications officer who has to write every message three times (website, parent app, social) and has no time to check every version against the style guide. | Three fields: the core message (who, what, where, when), the class or year group, and the tone (informative, celebratory, urgent). | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| If approved: three versions ready to post. If rejected: the three drafts plus "Rejected because" with the rules that were broken, for the communications officer. | The style guide from the knowledge base; the Checker (second LLM) rewrites the parent app version; the Gatekeeper (Code + IF/ELSE) measures word count, forbidden words, [FILL IN] and the hashtag. What does not pass the gate does not go out. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | A complete message about sports day, celebratory | Approved, three versions within the word limits, with #ExampleCollege | +| 2 | A message without a date | Rejected: contains [FILL IN] | +| 3 (the hard one) | A message with "kindly" and "asap" | Rejected with the two forbidden words named | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Workflow with checker and gatekeeper) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-07-school-news-with-checks.pdf b/00-design-card/examples/design-card-07-school-news-with-checks.pdf new file mode 100644 index 0000000..fcfec2e Binary files /dev/null and b/00-design-card/examples/design-card-07-school-news-with-checks.pdf differ diff --git a/00-design-card/examples/design-card-08-study-coach-biology.md b/00-design-card/examples/design-card-08-study-coach-biology.md new file mode 100644 index 0000000..fc010a3 --- /dev/null +++ b/00-design-card/examples/design-card-08-study-coach-biology.md @@ -0,0 +1,36 @@ + + +# Design card: Study coach biology + +**For the AI Agents workshop · filled-in example for guide 8** +LeX Consultancy B.V. · 20 September 2026 + +This is what the card looks like once filled in. Form: **Chatflow**, guide 8. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +| 1. Who is it for | 2. What goes in | +| --- | --- | +| A Year 9 student who at 20:00 is stuck on the Ecology unit and does not understand why a food chain rarely has more than five links. Does not want the answer handed over, does want to be helped along. | Questions in the chat, in plain language. The Question Classifier sends every question down one of four routes: explanation, hint for a task, planning, or personal. | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| An explanation from the booklet (with source), a hint without the answer, an answer from the study planner about the planning, or: "I have passed your message to your teacher" and later the teacher's reply in the same chat. | Only from the knowledge base (booklet, study planner, open resource); never give answers away; personal messages via Human Input to the teacher's email, after three days without a reply a standard message with a helpline. Memory on, so the coach remembers the conversation. | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | What is the difference between a population and a community? | An explanation with a source from the booklet, plus a check question | +| 2 | What is the answer to task 3? | A hint and a counter-question, not the answer | +| 3 (the hard one) | I have trouble at home and cannot concentrate | Route personal: passed to the teacher, no advice from the coach | + +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form (Chatflow) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. diff --git a/00-design-card/examples/design-card-08-study-coach-biology.pdf b/00-design-card/examples/design-card-08-study-coach-biology.pdf new file mode 100644 index 0000000..cf14922 Binary files /dev/null and b/00-design-card/examples/design-card-08-study-coach-biology.pdf differ diff --git a/00-design-card/make_examples.py b/00-design-card/make_examples.py new file mode 100644 index 0000000..031bd8d --- /dev/null +++ b/00-design-card/make_examples.py @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +"""Makes the filled-in design cards: one loose A4 per app in examples/ and the same five boxes +as the chapter "The design card for this app" in every guide (between the markers + and ). Usage: python3 make_examples.py +Then build: python3 build.py (cards) and the build.py of every guide. +""" +import re +from pathlib import Path + +HERE = Path(__file__).resolve().parent +ROOT = HERE.parent +OUT = HERE / "examples" + +CARDS = [ + dict(nr="01", folder="01-workflow", md="guide-dify-workflow.md", app="Text at level", form="Workflow", see="1", + who="An English teacher with a reading text from the course book that is too hard for half of Year 9. Has ten minutes before the lesson and does not want to rewrite it by hand.", + inp="The text (pasted, a Paragraph field) and the level from a short list: year 6, year 7, year 9, year 12 (a Select field).", + out="The text rewritten at the chosen level, with all the content kept and technical terms explained in a subordinate clause; below it three comprehension questions (fact, main idea, application) without answers.", + rules="Short sentences, leave nothing out, do not replace technical terms. No knowledge base needed: the rules live in the prompts of the two LLM steps.", + tests=[("A paragraph from a geography course book, level year 7", "Shorter sentences, same facts, three questions that are about the text"), + ("The same paragraph, level year 12", "Barely simplified, questions at analysis level"), + ("A text with a table of figures, level year 6", "The figures stay correct; the app invents no new numbers")]), + dict(nr="02", folder="02-agent-knowledge-base", md="guide-dify-agent.md", app="School guide assistant", form="Agent with knowledge base", see="2", + who="A parent who wants to know at 21:30 whether their child has to report sick at reception tomorrow or can phone. Has never read the school guide.", + inp="One question in plain language, in the chat. No form.", + out="An answer of at most five sentences in plain English, with the chapter of the school guide it comes from. Or: \"that is not in the school guide, please call reception\".", + rules="Only answers from the school guide in the knowledge base (school-guide-example-college.pdf); invent nothing; refer on when in doubt. Knowledge base: the school guide, split per paragraph.", + tests=[("What time does the first lesson start?", "The right time, with a reference to the chapter on lesson times"), + ("May my child bring a phone?", "The phone rule from the school guide, briefly"), + ("What is the head teacher's salary?", "\"That is not in the school guide\" and a referral to reception")]), + dict(nr="03", folder="03-school-communication", md="guide-dify-school-communication.md", app="Parent letter assistant", form="Agent with knowledge base", see="3", + who="A form tutor who at 16:00 still has to send a letter about next week's school trip and has three woolly paragraphs. Wants the letter to sound like the school, not like themselves.", + inp="The draft letter or loose sentences, pasted into the chat. If the class or the requested action is missing, the agent asks for it.", + out="The rewritten letter with a subject line, in the style of the style guide (B1, formal address, structure), and below it \"What I changed\": at most five points with the rule for each. Missing facts as [FILL IN].", + rules="The style guide of Example College (style-guide-example-college.pdf) in the knowledge base; invent no dates, names or appointments; no introduction or compliment from the agent itself.", + tests=[("A woolly letter about a parents' evening", "A short letter with date, time, place and what the parent must do; five improvement points"), + ("Two loose sentences without a class", "The agent first asks which class the letter is for"), + ("A letter without the date of the trip", "[FILL IN] where the date should be, no invented date")]), + dict(nr="04", folder="04-agent-console", md="guide-dify-agent-console.md", app="Test week planner", form="Agent Console", see="4", + who="A Year 8 student, three weeks before the test week, who does not know where to start. Has the timetable, a phone and an hour and a half in the evenings.", + inp="The exam timetable (as a file attached to the agent: exam-timetable-example.csv), the moments the student can study, and per subject easy/average/hard. The agent asks for them one at a time.", + out="A plan per day in the chat (block, subject, time, material) and two files from the sandbox: study-plan.xlsx and study-plan.ics for the phone calendar. Closing with the question whether anything should move.", + rules="Five planning rules (hard subjects double, every subject twice, blocks of 25-45 min with a break, the evening before a test revision only, nothing outside the given moments); no grades or judgements; keep nothing. Tool: CurrentTime for the date.", + tests=[("Timetable, moments and difficulty filled in", "A plan that meets all five rules, plus xlsx and ics"), + ("\"Put maths on Tuesday evening\" while Wednesday is history", "The agent explains why that clashes with the revision rule and offers an alternative"), + ("\"Will I pass my test?\"", "No prediction; back to the plan")]), + dict(nr="05", folder="05-transcription-tool", md="guide-dify-transcription-tool.md", app="Transcription tool", form="Workflow with tool", see="5", + who="The minute-taker of a department meeting whose minutes are always two weeks late. Has a 45-minute mp3 and fifteen minutes of time.", + inp="One audio file (mp3, m4a or wav, at most 5 MB) through a file field. For the prototype only a fictional recording read out by a computer voice.", + out="Minutes with five headings (Meeting, Summary, Decisions, Action points with owner and date, Deferred) and below them the full transcript. Uncertain names with a question mark.", + rules="No real recordings in Dify cloud (privacy frame); delete audio after transcription; someone reads the minutes. Tool: Speech To Text with your own OpenAI key.", + tests=[("The fictional three-minute recording", "Minutes with five headings, three action points with an owner"), + ("The same recording at 128 kbps (too big)", "An error about the file size; shrink to 32 kbps"), + ("A photo instead of audio", "The input field refuses the file; only Audio is enabled")]), + dict(nr="06", folder="06-inclusive-materials", md="guide-dify-inclusive-materials.md", app="Materials check", form="Agent Console with custom tool", see="6", + who="A biology teacher with a lesson booklet that is too wordy for a third of the class, and a support coordinator who asks \"what do you do for the students with dyslexia?\". Has an hour on the training day.", + inp="The lesson booklet (as a file attached to the agent or sent in the chat) and the support needs in the class from a list of six (or \"I do not know\").", + out="A report with seven scores (sentence length, terms, structure, prior knowledge, visuals, processing, choice), three files (teacher note, accessible student version, extension student version) and at most five open resources with licence.", + rules="UDL: the form changes, the content and the learning objectives do not; no names or diagnoses; always state the licence, share CC BY-SA under the same licence. Custom tool: OER search (Swagger API).", + tests=[("The ecology booklet, dyslexia and EAL", "Report, two files, resources that really appear in the search results"), + ("The same booklet, gifted added", "A third file with extension questions and a research task"), + ("\"Can you give Jayden his own version?\"", "No name, no personal advice; the version is for the whole class")]), + dict(nr="07", folder="07-school-news-with-checks", md="guide-dify-school-news-with-checks.md", app="School news with checks", form="Workflow with checker and gatekeeper", see="7", + who="The communications officer who has to write every message three times (website, parent app, social) and has no time to check every version against the style guide.", + inp="Three fields: the core message (who, what, where, when), the class or year group, and the tone (informative, celebratory, urgent).", + out="If approved: three versions ready to post. If rejected: the three drafts plus \"Rejected because\" with the rules that were broken, for the communications officer.", + rules="The style guide from the knowledge base; the Checker (second LLM) rewrites the parent app version; the Gatekeeper (Code + IF/ELSE) measures word count, forbidden words, [FILL IN] and the hashtag. What does not pass the gate does not go out.", + tests=[("A complete message about sports day, celebratory", "Approved, three versions within the word limits, with #ExampleCollege"), + ("A message without a date", "Rejected: contains [FILL IN]"), + ("A message with \"kindly\" and \"asap\"", "Rejected with the two forbidden words named")]), + dict(nr="08", folder="08-chatflow-study-coach", md="guide-dify-study-coach.md", app="Study coach biology", form="Chatflow", see="8", + who="A Year 9 student who at 20:00 is stuck on the Ecology unit and does not understand why a food chain rarely has more than five links. Does not want the answer handed over, does want to be helped along.", + inp="Questions in the chat, in plain language. The Question Classifier sends every question down one of four routes: explanation, hint for a task, planning, or personal.", + out="An explanation from the booklet (with source), a hint without the answer, an answer from the study planner about the planning, or: \"I have passed your message to your teacher\" and later the teacher's reply in the same chat.", + rules="Only from the knowledge base (booklet, study planner, open resource); never give answers away; personal messages via Human Input to the teacher's email, after three days without a reply a standard message with a helpline. Memory on, so the coach remembers the conversation.", + tests=[("What is the difference between a population and a community?", "An explanation with a source from the booklet, plus a check question"), + ("What is the answer to task 3?", "A hint and a counter-question, not the answer"), + ("I have trouble at home and cannot concentrate", "Route personal: passed to the teacher, no advice from the coach")]), +] + +HEAD = "**For the AI Agents workshop · filled-in example for guide {see}** \nLeX Consultancy B.V. · 20 September 2026" + + +def boxes(k): + t = k["tests"] + return f"""| 1. Who is it for | 2. What goes in | +| --- | --- | +| {k['who']} | {k['inp']} | + +| 3. What comes out | 4. What it must stick to | +| --- | --- | +| {k['out']} | {k['rules']} | + +**5. How you know it works** + +| Test | What goes in | What must come out | +| --- | --- | --- | +| 1 | {t[0][0]} | {t[0][1]} | +| 2 | {t[1][0]} | {t[1][1]} | +| 3 (the hard one) | {t[2][0]} | {t[2][1]} | +""" + + +def loose_a4(k): + return f""" + +# Design card: {k['app']} + +{HEAD.format(see=k['see'])} + +This is what the card looks like once filled in. Form: **{k['form']}**, guide {k['see']}. Compare with your own card: does box 1 name one person, and does box 5 have a test that must fail? + +{boxes(k)} +**What this card decided** + +- Boxes 1 and 2 decided the input fields and the first question of the app. +- Box 4 decided the form ({k['form']}) and what had to go into the knowledge base or the files. +- Test 3 decided which rule had to be in the instruction literally; without that test it would have been forgotten. +""" + + +def chapter(k): + return f""" +## The design card for this app + +Before we started clicking, this card was filled in (the blank card is in the Design card appendix). Fill in the same five boxes for your own app; the loose version of this filled-in card is in 00-design-card/examples. + +{boxes(k)} +""" + + +def main(): + OUT.mkdir(exist_ok=True) + for k in CARDS: + name = f"design-card-{k['nr']}-{k['app'].lower().replace(' ', '-')}.md" + (OUT / name).write_text(loose_a4(k), encoding="utf-8") + g = ROOT / k["folder"] / k["md"] + s = g.read_text(encoding="utf-8") + block = chapter(k) + if "" in s: + s = re.sub(r".*?\n", block, s, flags=re.S) + else: + m = re.search(r"^## (Read this first|Preparation)", s, re.M) + assert m, g + s = s[:m.start()] + block + "\n" + s[m.start():] + g.write_text(s, encoding="utf-8") + print(f"{k['nr']} {k['app']}: card and chapter") + + +if __name__ == "__main__": + main() diff --git a/00-design-patterns/build.py b/00-design-patterns/build.py new file mode 100644 index 0000000..0987a85 --- /dev/null +++ b/00-design-patterns/build.py @@ -0,0 +1,4 @@ +import runpy, sys +from pathlib import Path +sys.argv = ["build_guide.py", str(Path(__file__).resolve().parent / "design-patterns-for-agents.md")] +runpy.run_path(str(Path(__file__).resolve().parent.parent / "_tools" / "build_guide.py"), run_name="__main__") diff --git a/00-design-patterns/design-patterns-for-agents.md b/00-design-patterns/design-patterns-for-agents.md new file mode 100644 index 0000000..4120199 --- /dev/null +++ b/00-design-patterns/design-patterns-for-agents.md @@ -0,0 +1,166 @@ + + +# Five design patterns for AI agents, and how to build them in Dify + +**Appendix to the AI Agents workshop** +LeX Consultancy B.V. · 20 September 2026 + +Anyone who wants to build "an agent" first has to answer one question: how much may the model decide for itself? The answer determines how you build, what it costs and how much can go wrong. The field distinguishes five patterns, from "decide nothing at all" to "decide, but under supervision". You have already built all five in the guides without them being called that. + +**The rule of thumb:** choose the simplest pattern that solves the problem. Every step up costs more time, more credits and more chance of a surprise. + +| Pattern | Who decides the steps | Example from the series | Guide | +| --- | --- | --- | --- | +| 1. Single call | You, in advance; the model does one thing | Text at level (one LLM step) | 1 | +| 2. Reason and act (ReAct) | The model, step by step, with tools | School guide assistant, Parent letter assistant (agent with knowledge base) | 2, 3 | +| 3. Plan and execute | First a plan, then separate executors | School news (three channels from one message), Test week planner | 3, 4 | +| 4. Self-critique | The model assesses and improves its own work | The Checker in School news with checks; the Materials check | 7, 6 | +| 5. Gatekeeper | An independent check lets the result through or not | The Gatekeeper (code) in School news with checks; the human in the loop of the Study coach | 7, 8 | + +--- + +## 1. Single call (single-shot) + +**How it works.** The user supplies something, the model does exactly one operation, done. No loop, no tools, no choices along the way. + +```schema +input → [ LLM: one instruction ] → output +``` + +**Choose this when** the task is the same every time: classifying, summarising, rewriting, extracting something from a text, converting a form into a fixed layout. + +**Education example.** "Turn this parent complaint into a structured form: subject, class, urgency, requested action." + +**In Dify.** A Workflow with User Input → LLM → Output. Two LLM steps in a row (as in guide 1: rewrite and then write questions) is still this pattern: you decide the order, the model decides nothing. + +**Advantages.** Fast, cheap, predictable, easy to test. +**Disadvantages.** Cannot deal with unclear input and cannot look anything up. If the user forgets something, you get a wrong answer instead of a question. + +--- + +## 2. Reason and act (ReAct) + +**How it works.** The model gets a goal and tools. It thinks about the next step, picks a tool (search, calculate, consult a knowledge base, call an API), looks at the result and decides again. That repeats until the goal is reached. + +```schema +goal → [ think ] → [ pick a tool ] → [ execute ] → [ look at the result ] + ↑ │ + └──────────────── goal not reached yet? ───────────────┘ + ↓ reached + answer +``` + +**Choose this when** the model has to look something up or try something and you do not know in advance how many steps that takes: answering questions from documents, web research, getting something from a database, troubleshooting. + +**Education example.** "What are the rules for leave outside the holidays, and what do I have to do as a form tutor?" The agent searches the school guide, finds two chapters, combines them. + +**In Dify.** The Agent app in Studio (guides 2 and 3): instruction plus Knowledge plus Tools; the agent decides itself when to search. And the Agent Console (guides 4 and 6), where the model can also read files, run code and search the web. The label "Used Knowledge" above an answer is this pattern in miniature: the model decided to search. + +**Advantages.** Can handle unexpected questions, uses real information, is flexible. +**Disadvantages.** Slower and more expensive (every loop is a model call), more chance of a detour, and you need boundaries: a maximum number of steps, which tools yes and no, what to do on an error. In Dify those are the rules in the instruction and the choice of which Tools you switch on. + +--- + +## 3. Plan and execute (planner-executor) + +**How it works.** One step first makes a plan with sub-tasks. Then a separate step (or a separate agent) does the work per sub-task, in parallel where possible. At the end the results are merged. + +```schema +goal → [ planner: make sub-tasks ] + │ + ├──→ [ executor 1 ] ──┐ + ├──→ [ executor 2 ] ──┼──→ [ merge ] → result + └──→ [ executor 3 ] ──┘ +``` + +**Choose this when** the task consists of recognisable parts that can stand alone: a report with fixed chapters, a message for several channels, an analysis in steps (collect, analyse, write, check). + +**Education example.** One core message becomes a website item, a parent app message and a social post, each according to the rules of that channel. + +**In Dify.** School news (guide 3) is this pattern with a fixed plan: you wrote the plan as three LLM blocks with their own prompts, plus an Output that merges. If you want the model to plan itself, you put a first LLM block that makes a list of sub-tasks, and let an **Iteration** node work through that list. In the Agent Console the model does this by itself for larger tasks: it first writes a plan and works through it (the Test week planner in guide 4 shows that). + +**Advantages.** Complex tasks become manageable, every executor can be tested and improved separately, and parts can run in parallel. +**Disadvantages.** More building work, and a bad plan delivers neatly executed wrong work. Keep the plan visible, so a person can correct it before the executors start. + +--- + +## 4. Self-critique (reflexive) + +**How it works.** The model makes a first version, then assesses it itself against criteria, and improves. Possibly a few rounds, until the quality is good enough. + +```schema +task → [ first version ] → [ assess: what is wrong? ] → [ improve ] + ↑ │ + └──── not good enough ─────┘ + ↓ good + result +``` + +**Choose this when** quality matters more than speed and the criteria can be named: texts for publication, code, learning material, anything where "good enough" has a list of requirements. + +**Education example.** "Write a student version of this text at level B1. Then check yourself: sentences longer than fifteen words? Words from the list of words to avoid? A missing step in the explanation? Rewrite where needed." + +**In Dify.** A Workflow with two LLM blocks: the first writes, the second gets the text plus the criteria and the task "assess and improve". The Checker in guide 7 is exactly that. If you want several rounds, you use a **Loop** node with a stop condition. A cheaper alternative that is often enough: one prompt with the instruction to write first, then check against the named points, and give only the improved version. + +**Advantages.** Noticeably better texts, fewer slips, and the criteria force you to name what "good" is. +**Disadvantages.** Two to three times the cost and the waiting time. And beware: the model assesses itself. A factual error it believes itself stays in. Self-critique improves form and completeness, not truth. + +--- + +## 5. Gatekeeper (verifier-gated) + +**How it works.** The agent's result does not go straight out, but past an independent check: a fixed set of rules, a schema, a calculation, a second model with only the checking task, or a person. Only what passes the gate is executed or shown; what fails is rejected, retried or passed to a person. + +```schema +task → [ agent: proposal ] → [ gatekeeper: independent check ] + │ │ + passed failed + ↓ ↓ + execute reject / retry / to a person +``` + +**Choose this when** a mistake really does damage: money, grades, communication to parents, anything with personal data, anything covered by policy or law. + +**Education example.** An agent drafts a message for the parent app. The gatekeeper checks: no student names, no words from the forbidden list, at most 80 words, a date in the future. If one rule fails, the message goes to the communications officer with the reason attached. + +**In Dify.** A **Code** node or an **IF/ELSE** node after the LLM: hard rules (length, forbidden words, required fields) you check with code, not with a model. The Gatekeeper in guide 7 is six lines of Python. For softer rules a second LLM block with only the question "does this meet the following rules, answer YES or NO with the reason". The outcome steers the IF/ELSE: on to Output, or to a branch that presents the message with the reason to a person. A **Human Input** node (guide 8) is the most honest gatekeeper there is. + +**Advantages.** Predictable and explainable: you can say exactly why something did or did not go through. Mandatory rules are really enforced, not just "asked for" in a prompt. +**Disadvantages.** An extra step, and the rules have to be good: a gate that is too strict stops everything, one that is too loose does nothing. Never let the agent be its own gatekeeper. + +--- + +## Combining + +In practice you stack patterns. A mature application often looks like this: + +```schema +user → planner → executors with tools (ReAct) → self-critique → gatekeeper → action + memory (conversation, context) · logging and monitoring · boundaries (timeouts, retries, filters) +``` + +For a school that means: + +- **Start at pattern 1.** If a fixed workflow works, an agent is unnecessary. Most tasks at a school are pattern 1 or 3. +- **Go to pattern 2 when the input varies** and something has to be searched. Set boundaries straight away: which sources, how many steps, what to do in doubt. +- **Add 4 when the output is published** and there are criteria. +- **Add 5 as soon as anything goes out** or personal data is involved. A human in the loop is a valid, often the best, gatekeeper. +- **Log everything.** In Dify every run is under **Logs**. Without a log you cannot learn from mistakes or explain what happened. + +**Guide 6 uses all five.** The Materials check has a fixed intake (1), searches for open educational resources (2), makes a plan per support need (3), checks its own student version for sentence length and completeness (4), and states licences and refuses names before anything is delivered (5). + +--- + +## To remember + +- The pattern determines how much the model decides for itself. Choose the lowest that works. +- You have built pattern 1 (guide 1), 2 (guides 2, 3, 4, 6), 3 (School news, Test week planner), 4 (the Checker) and 5 (the Gatekeeper, the human in the loop). +- Self-critique improves form, not truth. A gatekeeper enforces, a prompt only asks. +- No pattern guarantees a good answer. Design for the failure: what happens when it goes wrong, and who sees it? diff --git a/00-design-patterns/design-patterns-for-agents.pdf b/00-design-patterns/design-patterns-for-agents.pdf new file mode 100644 index 0000000..b9d5184 Binary files /dev/null and b/00-design-patterns/design-patterns-for-agents.pdf differ diff --git a/00-presentation/README.md b/00-presentation/README.md new file mode 100644 index 0000000..43eba91 --- /dev/null +++ b/00-presentation/README.md @@ -0,0 +1,10 @@ +# Presentation: Workshop AI Agents with Dify + +- `presentation-workshop-ai-agents.pdf`: the 22 slides, ready to show. +- `make_slides.py`: the source; builds the slides as HTML (1920x1080) in `project/slides/` and `project/deck.json`. +- `project/slides/*.html`: one file per slide, with the speaker notes in `