diff --git a/Agent-Operating-Model.md b/Agent-Operating-Model.md new file mode 100644 index 0000000..a8e2384 --- /dev/null +++ b/Agent-Operating-Model.md @@ -0,0 +1,283 @@ +# Agent Operating Model + +## 1. Overzicht + +Dit document beschrijft het voorstel voor de inrichting van agentrollen, hun samenwerking, autonomiegrenzen en het werkmodel voor de ontwikkeling en werking van het innovatieplatform. + +Er zijn twee lagen van agents: + +1. **Bouwagents** — agents die helpen bij het ontwerpen en bouwen van het platform +2. **Platformagents** — agents die in het uiteindelijke platform opereren als onderdeel van de AI-laag + +--- + +## 2. Bouwagents: Agentrollen voor ontwikkeling + +### 2.1 Orchestrator + +**Rol:** Coördinatie, planning, kwaliteitsbewaking + +**Verantwoordelijkheden:** +- Vertaalt opdrachten naar taken voor specialistische agents +- Bewaakt samenhang en consistentie tussen outputs +- Consolideert resultaten +- Signaleert conflicten en open vragen +- Escaleert beslissingen die mensvalidatie vereisen + +**Autonomie:** Mag taken verdelen en coördineren; mag geen architectuurbeslissingen nemen zonder validatie + +### 2.2 Domein- & Productarchitect + +**Rol:** Domeinmodellering, productvisie, functioneel ontwerp + +**Verantwoordelijkheden:** +- Uitwerking domeinmodel en informatiemodel +- Functionele decompositie +- Gebruikersscenario's +- Acceptatiecriteria + +**Autonomie:** Mag voorstellen doen; definitieve domeinbeslissingen vereisen mensvalidatie + +### 2.3 Solution Architect + +**Rol:** Technische architectuur, integratieontwerp, technologiekeuzes + +**Verantwoordelijkheden:** +- Systeemarchitectuur ontwerp +- Technologieselectie en -motivering +- Integratiepatronen +- Performance- en schaalbaarheidsontwerp +- Security-architectuur + +**Autonomie:** Mag technische keuzes maken op basis van best practices; fundamentele architectuurwijzigingen vereisen mensvalidatie + +### 2.4 Backend Engineer + +**Rol:** Laravel-ontwikkeling, API-ontwerp, domeinimplementatie + +**Verantwoordelijkheden:** +- Laravel-applicatie bouwen +- Database-migraties en models +- API-endpoints +- Business logic en services +- Tests + +**Autonomie:** Mag code schrijven conform goedgekeurd ontwerp; architectuurafwijkingen vereisen review + +### 2.5 Frontend / UX Engineer + +**Rol:** Vue-ontwikkeling, interface-implementatie, interactieontwerp + +**Verantwoordelijkheden:** +- Vue-componenten bouwen +- Layout en navigatie +- Interactiepatronen +- Responsive design +- Component tests + +**Autonomie:** Mag bouwen conform goedgekeurd design; visuele keuzes volgen de stijlgids uit het designinterview + +### 2.6 Data & Informatiemodelleur + +**Rol:** Database-ontwerp, datamigratie, informatiestructuur + +**Verantwoordelijkheden:** +- Database-schema ontwerp +- Migratiescripts +- Seed data +- Query-optimalisatie +- pgvector-configuratie + +**Autonomie:** Mag schema-wijzigingen voorstellen; destructieve wijzigingen vereisen review + +### 2.7 AI / Agent Engineer + +**Rol:** AI-service ontwikkeling, RAG-pipeline, agentlogica + +**Verantwoordelijkheden:** +- Python AI-service bouwen +- LangGraph-workflows ontwerpen +- RAG-pipeline implementeren +- Prompt engineering +- Agent-tools ontwikkelen + +**Autonomie:** Mag AI-logica implementeren; prompts en agentgedrag vereisen review vanwege impact op gebruikerservaring + +### 2.8 DevOps / Platform Engineer + +**Rol:** Infrastructuur, deployment, monitoring + +**Verantwoordelijkheden:** +- Docker-configuratie +- Deployment-scripts +- Monitoring opzetten +- Backup-strategie +- CI/CD (wanneer relevant) + +**Autonomie:** Mag infra-configuratie maken; productie-wijzigingen vereisen validatie + +### 2.9 Security / Governance Specialist + +**Rol:** Beveiligingsreview, compliance, autorisatieontwerp + +**Verantwoordelijkheden:** +- Security review van code en architectuur +- Autorisatiemodel ontwerp +- Audit logging +- Compliance-check + +**Autonomie:** Mag security-issues signaleren en fixes voorstellen; blokkeert niet-veilige releases + +### 2.10 Document & Overdrachtsontwerper + +**Rol:** Documentstructuur, overdrachtsprocessen, kennisontwerp + +**Verantwoordelijkheden:** +- Documentatiestructuur ontwerpen +- Overdrachtsprocessen definiëren +- Templates voor projectdocumentatie +- Kennistaxonomie + +**Autonomie:** Mag structuurvoorstellen doen; proceswijzigingen vereisen mensvalidatie + +--- + +## 3. Werkmodel + +### 3.1 Orchestrator-model + +``` + ┌──────────┐ + │ MENS │ + │(opdracht-│ + │ gever) │ + └────┬─────┘ + │ opdracht + validatie + ▼ + ┌──────────┐ + │ORCHESTR. │ + └────┬─────┘ + │ taken + review + ┌─────────────┼─────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │Specialist│ │Specialist│ │Specialist│ + │ Agent │ │ Agent │ │ Agent │ + └──────────┘ └──────────┘ └──────────┘ +``` + +### 3.2 Workflow per taak + +1. **Opdracht ontvangen** — Orchestrator ontvangt opdracht van mens of vanuit plan +2. **Decompositie** — Orchestrator splitst in deeltaken per specialisatie +3. **Uitvoering** — Specialistische agents voeren uit (parallel waar mogelijk) +4. **Review** — Orchestrator reviewt outputs op samenhang en kwaliteit +5. **Consolidatie** — Resultaten worden samengebracht +6. **Validatie** — Output wordt voorgelegd aan mens indien nodig +7. **Integratie** — Goedgekeurde output wordt verwerkt + +### 3.3 Wat door mensvalidatie moet lopen + +| Categorie | Voorbeeld | Waarom | +|-----------|----------|--------| +| Architectuurbeslissingen | Keuze voor framework, database-schema wijziging | Langetermijnimpact | +| Domeinmodelwijzigingen | Nieuwe entiteiten, gewijzigde relaties | Beïnvloedt hele applicatie | +| UX/designkeuzes | Kleurenpalet, navigatiestructuur, layoutkeuzes | Subjectief, merkidentiteit | +| Scopewijzigingen | Features toevoegen of schrappen | Strategisch | +| AI-gedrag | Prompttemplates, autonomiegrenzen | Gebruikerservaring | +| Security-bevindingen | Kwetsbaarheden, autorisatiewijzigingen | Risico | +| Overdrachtsprocessen | Criteria, workflows | Organisatorisch | + +### 3.4 Wat autonoom mag worden uitgevoerd + +| Categorie | Voorbeeld | Voorwaarde | +|-----------|----------|-----------| +| Code schrijven | Implementatie conform ontwerp | Binnen goedgekeurd design | +| Tests schrijven | Unit, feature, integratie | Altijd | +| Bugfixes | Duidelijke bugs in bestaande code | Geen architectuurwijziging | +| Documentatie | Code-documentatie, README's | Altijd | +| Refactoring | Kleine verbeteringen | Geen functionele wijziging | +| Dependency-updates | Minor/patch updates | Geen breaking changes | + +--- + +## 4. Platformagents: Agents in het uiteindelijke product + +### 4.1 Overzicht + +Zie [AI- en Agentstrategie](AI-en-Agentstrategie) voor de volledige beschrijving. Samengevat: + +| Agent | Doel | Autonomie | +|-------|------|----------| +| Projectassistent | Samenvatten, analyseren, signaleren | Laag | +| Kennisassistent | Zoeken, ophalen, presenteren | Laag | +| Documentassistent | Structureren, suggereren, concept-generatie | Midden | +| Analysator | Portfolioanalyse, trends, checks | Laag | +| Systeemtaken | Embeddings, tagging, caching | Hoog | + +### 4.2 Beslisbaarheid en uitlegbaarheid + +Elk agentisch resultaat moet: + +- **Traceerbaar** zijn — welke agent, welke input, welke bronnen +- **Uitlegbaar** zijn — waarom dit resultaat, op basis van wat +- **Controleerbaar** zijn — mens kan altijd verifiëren en overrulen +- **Gelogd** worden — voor audit en kwaliteitsverbetering + +--- + +## 5. Logging en terugkoppeling + +### Bouwproces + +- Alle agenttaken worden gelogd (wat, wie, wanneer, resultaat) +- Elke validatiestap wordt vastgelegd +- Beslissingen worden gedocumenteerd met motivatie +- Afgewezen voorstellen worden bewaard (met reden) + +### Platformoperatie + +- Alle AI-interacties worden gelogd +- Gebruikersfeedback wordt gekoppeld aan AI-responses +- Periodieke review van AI-kwaliteit en -gedrag +- Anomaliedetectie op agent-output + +--- + +## 6. Grenzen en escalatie + +### Escalatiepaden + +``` +Agent detecteert onzekerheid + │ + ├── Technische onzekerheid ──▶ Orchestrator ──▶ Solution Architect + │ + ├── Domeinonzekerheid ──▶ Orchestrator ──▶ Mensvalidatie + │ + ├── Designonzekerheid ──▶ Orchestrator ──▶ Designinterview + │ + └── Securityconcern ──▶ Direct naar mens + Security specialist +``` + +### Nooit door agents + +- Productie-deployment zonder menselijke trigger +- Data-verwijdering zonder expliciete bevestiging +- Communicatie naar externen +- Budgettaire beslissingen +- Wijzigingen aan autorisatiemodel zonder review + +--- + +## 7. Evolutie van het model + +Dit operating model is een startpunt. Na de MVP-fase wordt geëvalueerd: + +- Welke rollen daadwerkelijk waarde toevoegen +- Waar autonomie kan worden vergroot +- Waar extra menscontrole nodig blijkt +- Welke agents in het platform het meest worden gebruikt +- Waar de kwaliteit van AI-output verbeterd moet worden + +Het model groeit mee met het platform en het team.