11 – WhatsApp-Agent

Reifegrad: 🟡 Rebuild (Infrastruktur produktiv, Capabilities größtenteils Stubs) · Schicht: packages/agent/* (@work7/agent), src/lib/whatsapp/*, src/app/api/whatsapp/*, Tabellen whatsapp_sessions/whatsapp_messages/agent_schedules/agent_media

USP von Work7: Monteure/Disponenten bedienen die Software per WhatsApp – derselbe Domain-Layer wie das Web (siehe adr-0002-shared-domain-layer, adr-0003-whatsapp-agent-rebuild). Aktueller Stand: queue-basierter Neuaufbau (@work7/agent), löst die ältere LangChain/MCP-Variante ab (siehe work7-agent-infra-rebuild).

Laufzeit & Datenfluss

• Eingang: 360dialog ruft POST /api/whatsapp/webhook an. Next.js (src/lib/whatsapp/webhook-proxy.ts, queue.ts) validiert und enqueued den Inbound-Job in die BullMQ-Queue wa-inbound (Prefix work7:bull, Redis DB 1).
• Verarbeitung: @work7/agent läuft als eigener Prozess (AGENT_HTTP_PORT 3100, /health+/ready), zieht Jobs und ruft handleInboundJob.
• Antwort: D360Client (channel/d360-client.ts) sendet Text/Buttons; Read-Receipt + Typing-Indicator als sofortiges UX-Feedback.

Orchestrator (orchestrator/handle-inbound.ts)

1. Read-Receipt + Typing.
2. Identität: resolveUserByPhone (Tabelle users.phone_number). Unbekannte Nummer → Onboarding-Hinweis (de/en), Stopp.
3. resolveCompanyDbId, Session laden/erstellen (whatsapp_sessions), letzte 10 Nachrichten als Historie.
4. Medien: Audio → Transkription (media/transcribe.ts, Azure Whisper), Datei/Bild → Tenant-Blob (media/tenant-store.ts) + Registry agent_media (Projektbezug).
5. Aktives Projekt auflösen (project-context.ts): „sticky project" pro Session; älter als AGENT_STICKY_PROJECT_MAX_AGE_MS (Default 12 h) → erneut bestätigen.
6. Agent-Loop (agent/loop.ts): Tool-Calling gegen Azure OpenAI (Default Deployment gpt-5-mini, Fallback gpt-4o-mini), max. AGENT_MAX_STEPS (Default 8). System-Prompt in agent/prompt.ts.
7. Rendern der Antwort (channel/render.ts), Logging in whatsapp_messages, Session-Kontext speichern.

Capabilities-Pattern (Erweiterungspunkt)

Tools werden via defineTool() definiert und in capabilities/index.ts registriert – ohne Eingriffe in Loop/Registry/Channel (agent/registry.ts, agent/types.ts).

⚠️ Update 2026-08-13 — dieser Abschnitt war überholt. Die Capabilities sind längst keine Stubs mehr: 62 registrierte Tools (Angebote, Rechnungen, Rapport-Diktat, Zeiterfassung, Urlaub, Katalog, Kunden, Projekte, Anfragen-Triage, Medien-Upload, Umsatz-Auskunft, Reminder) plus deterministische Commands (Hauptmenü „menü"/„hilfe", /inbox, /whoami, /abbrechen, Zeit-Befehle) und Notification-Actions (leave.approve, anfrage.confirm). Vollständiger, pflegepflichtiger Katalog: 21-agent-tools. Das frühere Rapport-Stub-Problem (P1-1) ist gelöst: rapport.ts persistiert via Domain createRapport in einer Transaktion, Versand an Kunden mit Empfänger-Vorschau (Schutzstufe 2). Der Agent bedient zusätzlich den Web-Assistenten /assistent über /api/agent/chat (gleiche Registry, SSE).

Scheduler / Reminders

• Tabelle agent_schedules (Migration 033) ist Source of Truth für Reminder/Recurring (schedule_kind once/cron, next_run_at); BullMQ-Jobs werden daraus abgeleitet (scheduler/reminders.ts syncSchedules, scheduler/worker.ts).

Datenmodell

• whatsapp_sessions (Migration 001/003): Telefon ↔ User/Company, context JSONB, Status.
• whatsapp_messages: vollständiges Nachrichtenprotokoll (Richtung, Typ, Medien, Status).
• agent_schedules / agent_media (Migration 033): Reminder bzw. Inbound-Medien (Blob-Pfad, Transkript, Projektbezug).
• Domain-Funktionen für Sessions: getOrCreateWhatsappSession, storeWhatsappMessage, getWhatsappSessionHistory, endInactiveWhatsappSessions, listWhatsappSessions u. a.

API-Endpunkte (Next.js-Seite)

Endpoint	Funktion
POST /api/whatsapp/webhook	360dialog-Webhook (Inbound → Queue)
GET /api/whatsapp/health	Health/Diagnose
POST /api/whatsapp/test-send	Test-Versand

Webhook-Auth ohne Session: HMAC/Channel-Token/state (siehe src/lib/webhook-auth.ts, adr-0002-shared-domain-layer).

Konfiguration (packages/agent/src/config.ts)

WHATSAPP_D360_API_KEY/_API_URL, AZURE_OPENAI_* (Deployment 5mini/4omini), AZURE_OPENAI_TRANSCRIPTION_* (Whisper), AZURE_STORAGE_* (Blob-Container work7-media), REDIS_*, BULLMQ_PREFIX, AGENT_MAX_STEPS, AGENT_STICKY_PROJECT_MAX_AGE_MS.

Bekannte Befunde / offene Punkte

• Geschäfts-Capabilities sind noch Stubs — erledigt: Rapport per Sprache (P1-1), Zeitbuchung und Urlaubsantrag laufen über Domain-Tools; Katalog siehe 21-agent-tools.
• Der frühere LangChain-Agent + zentraler MCP-Server sind abgelöst (Archiv-Referenz in work7-agent-architecture); Memory-Tabellen ai_agent_memory/ai_audit existieren weiter.
• Agent & App releasen gemeinsam (ein Image, start-all.js).

Verwandte Notes

• 12-ai-speech-realtime · 07-urlaub-abwesenheit · 08-zeiterfassung · 09-rapport
• adr-0002-shared-domain-layer · adr-0003-whatsapp-agent-rebuild
• work7-agent-infra-rebuild · work7-agent-architecture