Agentsamenwerkingsmodel: Onderzoeksagent · Curator · Schrijfagents¶
Versie: 1.0.0 | Bijgewerkt: 15 maart 2026 | Beheer: Niels (architect)
🎯 Doel van dit document¶
Dit document legt de samenwerking, verantwoordelijkheden, workflow en mapstructuur vast voor de drie kernagents die samen de kennisproductie en rapportage naar de kerngroep verzorgen:
| Agent | Code-equivalent | Kernrol |
|---|---|---|
| Onderzoeksagent | ScoutAgent (agents/scout.py) |
Data verzamelen: kennisbank + interne surveys |
| Curator | CuratorAgent (agents/curator.py) |
Valideren, filteren en beheren van de kennisbank |
| Schrijfagent(s) | OllamaSynthesizer / MockSynthesizer |
Rapporten en adviezen schrijven voor de kerngroep |
Kernregel: Schrijfagents halen hun input uitsluitend bij de Curator op. Onderzoeksagent levert uitsluitend aan de Curator, nooit rechtstreeks aan de Schrijfagent of aan de kerngroep.
🗺️ Workflow overzicht¶
┌─────────────────────────────────────────────────────────────────┐
│ ONDERZOEKSAGENT (Scout) │
│ Bronnen: │
│ • Interne kennisbank (ChromaDB / SharePoint) │
│ • Externe datasets en kennisinstituten │
│ • Interne surveys bij medewerkers │
│ • Teamvergaderingen, MDO's, KWP-sessies │
└───────────────────────┬─────────────────────────────────────────┘
│ Gestructureerde raw output
│ (UDS V2 metadata: zone, domein,
│ ldf_level, bron_type, similarity)
▼
✅ SELECTIEPUNT 1
(Heeft de chunk geldige UDS-metadata?)
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ CURATOR │
│ Taken: │
│ • UDS-veldvalidatie (Domain_ID, Severity_Scale, │
│ Target_Audience) │
│ • Similarity-drempelcheck (≥ 0.5 standaard) │
│ • Zone-routing: GREEN / YELLOW / RED │
│ • YELLOW → menselijke review vóór vrijgave │
│ • RED → blokkering, doorverwijzing, nooit vrijgegeven │
│ • Verslaggeving van afkeuringen en waarschuwingen │
└───────────────────────┬─────────────────────────────────────────┘
│ Gevalideerde kennisbank-entries
│ (alleen GREEN vrijgegeven; YELLOW
│ na HITL-goedkeuring)
▼
✅ SELECTIEPUNT 2
(Is de chunk vrijgegeven voor rapportage?)
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SCHRIJFAGENT(S) │
│ Taken: │
│ • Ophaalt uitsluitend gevalideerde kennis bij Curator │
│ • Schrijft narratief rapport conform intake/outputschema │
│ • Voegt bronverwijzingen toe (traceerbaarheid) │
│ • Levert conceptrapport op voor kerngroep │
└───────────────────────┬─────────────────────────────────────────┘
│
▼
✅ SELECTIEPUNT 3
(Akkoord kerngroep / Aandachtsfunctionaris?)
│
▼
📤 PUBLICATIE naar kerngroep
👥 Rollen en verantwoordelijkheden¶
1. Onderzoeksagent (ScoutAgent)¶
Verantwoordelijkheid: Verzamelt en structureert nieuwe kennisbronnen.
Doet:
- Doorzoekt de interne ChromaDB-kennisbank semantisch (rag/vector_store.py)
- Scrapt externe kennisbronnen (wetenschappelijke literatuur, beleidsdocumenten)
- Voert interne surveys uit onder medewerkers (Feeder 1/2/3 conform Kennis_Oogsten_Strategie.md)
- Structureert alle output met UDS V2 metadata (zone, domein, ldf_level, bron_type)
- Stuurt alles ongevalideerd door naar de Curator — nooit rechtstreeks naar de Schrijfagent
Doet niet: - Content beoordelen of filteren - Resultaten rechtstreeks aan de kerngroep presenteren - Iets committen naar de kennisbank zonder Curator-goedkeuring
Output-formaat (UDS V2):
chunk_id: "scout-<uuid>"
content: "Tekst van het gevonden fragment"
metadata:
Domain_ID: "Autisme" # verplicht
Severity_Scale: "Medium" # verplicht
Target_Audience: "AF" # verplicht
safety_zone: "green" # green | yellow | red
ldf_level: 2 # 1-5
bron_type: "intern" # intern | extern | survey
similarity_score: 0.87
bron_url: "sharepoint://..."
datum: "2026-03-15"
2. Curator (CuratorAgent)¶
Verantwoordelijkheid: Poortwachter en beheerder van de kennisbank.
Doet:
- Valideert elke chunk op verplichte UDS V2 velden (Domain_ID, Severity_Scale, Target_Audience)
- Past similarity-drempelcheck toe (standaard ≥ 0.5, configureerbaar in config.py)
- Routeert naar de juiste SafetyZone (GREEN / YELLOW / RED)
- YELLOW-chunks: voegt waarschuwing toe en wacht op menselijke goedkeuring (HITL)
- RED-chunks: blokkeert altijd, registreert reden, nooit vrijgegeven
- Documenteert alle goedkeuringen, afkeuringen en waarschuwingen
- Beheert de gevalideerde kennisbank die beschikbaar is voor Schrijfagents
- Informeert de Aandachtsfunctionaris (AF) over chunks die menselijke review vereisen
Doet niet: - Schrijven van rapporten of narratieve content - Rechtstreeks communiceren met de kerngroep - Chunks goedkeuren die de UDS-validatie niet doorstaan
Output: CurationResult met:
- approved_count — aantal goedgekeurde chunks
- rejected_count + afkeuringsredenen
- warnings — YELLOW-zone waarschuwingen voor HITL-review
- chunks — de goedgekeurde, vrijgegeven kennisfragmenten
3. Schrijfagent(s) (Synthesizer)¶
Verantwoordelijkheid: Rapporteren aan de kerngroep op basis van uitsluitend gevalideerde kennis.
Doet: - Haalt input uitsluitend op via de Curator (nooit rechtstreeks uit ruwe data of van de Onderzoeksagent) - Schrijft rapporten, adviezen en samenvattingen conform het intake/outputschema (zie §6) - Voegt altijd traceerbare bronverwijzingen toe (chunk-id's, domeinen, datums) - Benoemt expliciet welke safety-zone de gebruikte kennis heeft - Levert het concept aan voor kerngroep-review voordat het definitief wordt
Doet niet: - Kennis ophalen uit niet-gevalideerde bronnen - Redactionele beslissingen nemen over welke kennis geldig is (dat is de Curator) - Rapporten publiceren zonder selectiepunt 3 te passeren
🔄 Validatieflow per chunk¶
ONDERZOEKSAGENT levert chunk aan
↓
┌────────────────────────────────┐
│ CHECK 1: UDS-velden aanwezig? │
│ (Domain_ID + Severity_Scale + │
│ Target_Audience) │
└────────────────────────────────┘
│ NEE → AFKEURING (log + reden)
│ JA ↓
┌────────────────────────────────┐
│ CHECK 2: Similarity ≥ 0.5? │
│ (0.4–0.5: grensgebied → YELLOW │
│ voor HITL-beoordeling) │
└────────────────────────────────┘
│ < 0.4 → AFKEURING
│ 0.4–0.5 → YELLOW (grensgebied, HITL)
│ ≥ 0.5 ↓
┌────────────────────────────────┐
│ CHECK 3: Safety zone bepalen │
│ GREEN → direct vrijgegeven │
│ YELLOW → HITL review vereist │
│ RED → geblokkeerd altijd │
└────────────────────────────────┘
│ GREEN vrijgegeven
│ YELLOW: naar AF-dashboard → na goedkeuring vrijgegeven
↓
Beschikbaar voor Schrijfagent
✅ Checkpoints en afstemmingsmomenten¶
Checkpoint 1 — Onderzoeksagent → Curator (Inlevermoment)¶
Wanneer: Na iedere onderzoekscyclus (survey, kennisbank-sweep, externe harvest)
Wie: Onderzoeksagent levert aan; Curator ontvangt
Wat: Alle ruwe chunks met UDS V2 metadata, nog ongevalideerd
Waar: data/chromadb_yellow/ (staging zone) of via POST /sharepoint/ingest (beschikbaar vanaf Sprint B, ✅ gereed per 15 mrt 2026)
Formaat: UDS V2 YAML/JSON (zie §1)
Commit-verantwoordelijkheid: Onderzoeksagent/automatisch via ingest-pipeline; geen handmatige commit in docs/
Checkpoint 2 — Curator HITL-review (YELLOW zone)¶
Wanneer: Na elke curation-cyclus waarbij YELLOW-chunks zijn gevonden
Wie: Curator signaleert; Aandachtsfunctionaris (AF) beslist
Wat: Lijst van chunks die menselijke beoordeling vereisen vóór vrijgave
Waar: AF-dashboard (toekomstig) of tijdelijk via data/curator_review/ (zie sectie Mapstructuur en commitverantwoordelijkheid)
Actie AF: Accepteren → verplaatst naar chromadb_green/; Weigeren → afkeuring gelogd
Doorlooptijd: Maximaal 5 werkdagen; daarna automatisch vervallen
Checkpoint 3 — Curator → Schrijfagent (Vrijgavemoment)¶
Wanneer: Schrijfagent start een rapportage-sessie
Wie: Schrijfagent vraagt op; Curator levert alleen vrijgegeven chunks
Wat: Gevalideerde, zone-gecheckte kennisfragmenten
Waar: Alleen chromadb_green/; YELLOW alleen na expliciete HITL-goedkeuring
Selectiecriterium: safety_zone=green, alle UDS-velden aanwezig, similarity ≥ 0.5
Checkpoint 4 — Schrijfagent → Kerngroep (Publicatiemoment)¶
Wanneer: Conceptrapport is gereed
Wie: Schrijfagent levert concept; kerngroep/AF keurt goed
Wat: Volledig rapport conform outputschema (zie §6), inclusief bronvermelding
Waar: docs/reports/ (als Markdown) of via SharePoint (toekomstig)
Goedkeuringsproces: PR aanmaken → kerngroep review → merge = definitief gepubliceerd
Commit-verantwoordelijkheid: Schrijfagent opent PR; menselijke reviewer merget
📋 Intake/outputschema voor kerngroep-rapporten¶
Rapportage-header (verplicht)¶
---
titel: "Rapporttitel"
domein: "Autisme | GGZ | LVB | Jeugd"
datum: "2026-03-15"
auteur: "Schrijfagent + AF naam"
versie: "1.0"
status: "concept | goedgekeurd | gepubliceerd"
kennisbronnen:
- chunk_id: "scout-abc123"
zone: "green"
domein: "Autisme"
datum_gevalideerd: "2026-03-14"
safety_zone: "GREEN" # hoogste zone van gebruikte chunks
hitl_required: false # true als YELLOW-chunks zijn gebruikt
audience: "kerngroep"
---
Rapportstructuur¶
- Aanleiding — Wat is onderzocht en waarom?
- Bronnen — Welke kennisbronnen zijn gebruikt (intern/extern/survey)?
- Bevindingen — Gevalideerde inzichten, gebaseerd op vrijgegeven chunks
- Aanbevelingen — Concrete acties voor de kerngroep
- Beperkingen — Wat ontbreekt nog, welke YELLOW/RED-zones zijn gesignaleerd?
- Bijlagen — Chunk-IDs en metadata ter verificatie
🗂️ Mapstructuur en commitverantwoordelijkheid¶
buurts-ecosysteem/
│
├── agents/
│ ├── scout.py ← ScoutAgent (Onderzoeksagent)
│ ├── curator.py ← CuratorAgent
│ ├── hub.py ← HubOrchestrator (pipeline-regisseur)
│ ├── synthesizer.py ← MockSynthesizer (test)
│ └── ollama_synthesizer.py ← OllamaSynthesizer (productie Schrijfagent)
│
├── data/
│ ├── chromadb_green/ ← vrijgegeven kennisbank (Curator → Schrijfagent)
│ ├── chromadb_yellow/ ← staging voor HITL-review
│ ├── chromadb_red/ ← geblokkeerde content (nooit vrijgegeven)
│ └── curator_review/ ← tijdelijk YAML-overzicht voor AF-review
│ └── pending_YYYYMMDD.yaml
│
├── docs/
│ ├── ai/
│ │ ├── README_agents.md ← dit document
│ │ ├── ARCHITECTURE.md ← technische architectuur
│ │ └── SPRINT.md ← actieve sprintstatus
│ └── reports/
│ └── <naam>_rapport_YYYYMMDD.md ← eindrapport kerngroep (Schrijfagent PR)
│
├── rag/
│ ├── vector_store.py ← ZonedVectorStore (beheerd door Curator)
│ ├── chunker.py ← SmartChunker
│ └── document_registry.py ← SQLite ingest-tracking
│
└── sharepoint/
├── connector.py ← Mock + GraphAPI connector
└── ingest_pipeline.py ← ingest-pipeline (bron voor Onderzoeksagent)
Wie commit wat, wanneer?¶
| Actor | Wat | Wanneer | Waar |
|---|---|---|---|
| Onderzoeksagent | Ruwe chunks via ingest-pipeline | Na elke sweep/survey | data/chromadb_yellow/ via API |
| Curator (automatisch) | Goedgekeurde chunks | Na succesvolle validatie | data/chromadb_green/ via vector_store |
| Curator (log) | Afkeuringen + waarschuwingen | Continu | data/document_registry.db |
| AF (menselijk) | HITL-beslissing YELLOW | Wekelijks (max. 5 werkdagen) | data/curator_review/ + chromadb via API |
| Schrijfagent | Conceptrapport (PR) | Na afsluiting rapportage-sessie | docs/reports/ via Pull Request |
| Menselijk reviewer | Goedkeuring rapport | Binnen 5 werkdagen na PR | GitHub PR-review → merge |
| CI/CD | MkDocs-publicatie | Na elke merge naar main | GitHub Pages (automatisch) |
Regel: Niemand commit rechtstreeks naar
data/chromadb_green/ofdocs/reports/zonder het bijbehorende validatieproces te doorlopen. Alle wijzigingen verlopen via de ingest-API of een Pull Request.
🚦 Safety-zones en HITL-bewaking¶
| Zone | Betekenis | Curator-actie | Schrijfagent mag gebruiken? |
|---|---|---|---|
| 🟢 GREEN | Automatisch veilig | Direct vrijgeven | ✅ Ja |
| 🟡 YELLOW | Menselijke validatie vereist | Signaleer AF, wacht op goedkeuring | ✅ Alleen na HITL-goedkeuring |
| 🔴 RED | Altijd blokkeren | Blokkeer en registreer | ❌ Nooit |
Zie
safety/policy.pyvoor de volledige zone-beslissingslogica.
📅 Aanbevolen werkritme¶
| Frequentie | Actie | Verantwoordelijke |
|---|---|---|
| Dagelijks | Onderzoeksagent-sweep (automatisch) | System / Cron |
| Wekelijks | HITL-review YELLOW-chunks door AF | Aandachtsfunctionaris |
| Per rapport | Schrijfagent haalt gevalideerde kennis op | Schrijfagent + AF |
| Per rapport | PR aanmaken voor kerngroep-rapportage | Schrijfagent |
| Tweewekelijks | Curator-statistieken reviewen (ratio goedgekeurd/afgekeurd) | AF + Niels |
| Per sprint | Afstemming Trinity (Onderzoeksagent, Curator, Schrijfagent) over kennisbehoeften kerngroep | Niels + AF |
🔗 Gerelateerde documenten¶
docs/ai/ARCHITECTURE.md— Technische architectuur (MCP, FastAPI, RAG-pipeline)docs/architecture/AGENT_ECOSYSTEM.md— Volledig agent-ecosysteem (VERA, LUMEN, SCOUT, CURATOR)docs/architecture/Kennis_Oogsten_Strategie.md— Strategie voor privacy-veilig kennis oogstendocs/compliance/AI_CONSTITUTION.md— AI Grondwet (Art. 1 HITL, Art. 5 Guardian Layer)safety/policy.py— Zone-beslissingslogica (single source of truth)agents/curator.py— CuratorAgent implementatieagents/scout.py— ScoutAgent implementatie