@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/observability.md

@@ -0,0 +1,294 @@
+---
+title: "Beobachtbarkeit"
+description: "Agentenverfolgungen, Auswertungen, Feedback, A/B-Experimente und das integrierte Dashboard – alles ohne Konfiguration."
+---
+
+# Beobachtbarkeit des Agenten
+
+Jede agentennative App ist sofort beobachtbar. Traces, automatisierte Auswertungen, Benutzerfeedback und A/B-Experimente funktionieren ohne Konfiguration – alle Daten werden in der SQL-Datenbank der App gespeichert.
+
+Diese Seite behandelt Metriken zur Agentenqualität: Spuren, Kosten, Auswertungen und Feedback, die in Ihrer Datenbank gespeichert sind. Informationen zu \_Produktanalysen (die Ereignisse Ihrer App, die an PostHog/Mixpanel/Amplitude fließen) finden Sie unter [Tracking](/docs/tracking).
+
+## Drei Dinge namens „Bewertungen“/„Beobachtbarkeit“ – was will ich? {#which}
+
+Diese drei Seiten sind leicht zu verwechseln. Wählen Sie die Frage aus, die Sie stellen:
+
+| Seite                                                                            | Die Frage, die es beantwortet                           | Wenn es läuft                                 | Bedenken       |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------- | -------------- |
+| **Beobachtbarkeitsbewertungen** (diese Seite, die Registerkarte „_Bewertungen_“) | „Wie liefen meine tatsächlichen Produktionsläufe?“      | Passiv, nach jedem Lauf (LLM-Richter geprüft) | Qualität       |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)                                    | „Tut der Agent bei dieser festen Eingabe das Richtige?“ | Aktiv, deterministisch, ein CI/Deploy-Gate    | Qualität       |
+| **[Observational Memory](/docs/observational-memory)**                           | „Bleibt dieser lange Faden billig und im Fenster?“      | Hintergrundkomprimierung bei langen Threads   | Kosten/Kontext |
+
+Observability und das CI Eval Gate bewerten beide _Qualität_, allerdings von entgegengesetzten Enden – passive Post-hoc-Bewertung des realen Datenverkehrs im Vergleich zu aktiven Pass/Fail-Prüfungen an festen Eingaben. Das Beobachtungsgedächtnis hat nichts mit der Qualität zu tun; Es geht um Tokenkosten und Kontextfensterdruck.
+
+## Was automatisch erfasst wird {#captured}
+
+Wenn ein Benutzer eine Nachricht sendet, zeichnet das Framework automatisch Folgendes auf:
+
+- **Token-Nutzung** – Eingabe, Ausgabe, Cache-Lesen, Cache-Schreiben
+- **Kosten** – berechnet aus Tokenanzahl und Modellpreisen
+- **Latenz** – Gesamtdauer und Zeit pro Tool-Aufruf
+- **Tool-Aufrufe** – welche actions aufgerufen wurden, Erfolgs-/Fehlerstatus, Dauer
+- **Automatisierte Auswertungen** – 5 Qualitätsbewertungen werden nach jedem Lauf berechnet
+
+Keine Codeänderungen erforderlich. Die Instrumentierung wird transparent in `production-agent.ts` eingebunden.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Das Dashboard {#dashboard}
+
+Fügen Sie das Dashboard mit einer einzigen Route zu jeder Vorlage hinzu:
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+Alle Daten beziehen sich auf den angemeldeten Benutzer. Es gibt heute keine benutzerübergreifende Admin-Ansicht.
+
+Das Dashboard verfügt über 5 Registerkarten:
+
+| Tab             | Was es zeigt                                                                                             |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| **Übersicht**   | Wichtige Kennzahlen – Ausführungen, Kosten, Latenz, Tool-Erfolgsquote, Zufriedenheit, Bewertungsergebnis |
+| **Gespräche**   | Trace-Liste mit Drilldown auf einzelne Spans (agent_run, llm_call, tool_call)                            |
+| **Bewertungen** | Automatisierte Bewertungsergebnisse nach Kriterien und Trends im Zeitverlauf                             |
+| **Experimente** | A/B-Testliste mit Statusabzeichen, Variantenergebnisse mit Konfidenzintervallen                          |
+| **Feedback**    | Daumen hoch/abwärts Stream, Aufschlüsselung nach Kategorien, Frustrationswerte                           |
+
+## Benutzerfeedback {#feedback}
+
+### Explizites Feedback
+
+Daumen-hoch/runter-Schaltflächen werden in jeder Agentennachricht im Chat angezeigt UI. Mit dem Daumen nach unten wird ein Kategorie-Popover geöffnet (Ungenau, Nicht hilfreich, Falsches Tool, Zu langsam). Dies wird automatisch mit `AssistantChat.tsx` verkabelt.
+
+### Implizites Feedback (Frustrationsindex)
+
+Das Framework berechnet einen Frustrationsindex (0-100) aus Gesprächssignalen:
+
+| Signal              | Gewicht | Was es erkennt                                         |
+| ------------------- | ------- | ------------------------------------------------------ |
+| Umformulierung      | 30%     | Benutzer wiederholt ähnliche Nachrichten               |
+| Wiederholungsmuster | 20%     | „Versuchen Sie es noch einmal“, „Nein, das ist falsch“ |
+| Abbruch             | 20%     | Sitzung endet kurz nach der Antwort                    |
+| Stimmung            | 15%     | Negative Sprachmuster                                  |
+| Längentrend         | 15%     | Abnehmende Nachrichtenlängen                           |
+
+Bewertungsinterpretation: 0–20 = gesund, 20–40 = Reibung, 40–60 = unzufrieden, 60+ = abgebrochene Sitzung.
+
+## Automatisierte Auswertungen {#evals}
+
+Fünf deterministische Scorer werden nach jedem Agentenlauf ausgeführt:
+
+| Kriterien           | Was es misst                                                   | Bewertungsbereich |
+| ------------------- | -------------------------------------------------------------- | ----------------- |
+| `tool_success_rate` | % der Toolaufrufe ohne Fehler                                  | 0-1               |
+| `step_efficiency`   | Straft übermäßige LLM-Iterationen für Tool-verwendende Läufe   | 0-1               |
+| `latency_score`     | Normalisiert gegenüber der Basislinie von 10 Sekunden/Werkzeug | 0-1               |
+| `cost_efficiency`   | Normalisiert gegenüber der Kostenbasis                         | 0-1               |
+| `error_recovery`    | Hat sich der Agent nach Toolfehlern erholt?                    | 0 oder 1          |
+
+### LLM-als-Richter (optional)
+
+Aktivieren Sie die auf Stichproben basierende LLM-Auswertung, indem Sie `evalSampleRate` festlegen:
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+Benutzerdefinierte Kriterien verwenden Rubriken in natürlicher Sprache:
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## A/B-Experimente {#experiments}
+
+Testen Sie verschiedene Modelle, Temperaturen oder Agentenkonfigurationen:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+Verwenden Sie anstelle von `<your-model-id>` / `<other-model-id>` die tatsächlichen Modellkennungen, die Ihre Engine akzeptiert (Modellnamen ändern sich häufig – überprüfen Sie Ihren Anbieter/Ihre Engine auf die aktuellen IDs). Die Agentenschleife löst automatisch die Variante des Benutzers auf und wendet die Konfigurationsüberschreibung an. Die Zuweisung verwendet konsistentes Hashing – derselbe Benutzer erhält immer die gleiche Variante.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Konfiguration {#config}
+
+Alle Einstellungen werden im `observability-config`-Schlüssel gespeichert:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## API Endpunkte {#api}
+
+Alle automatisch montiert bei `/_agent-native/observability/`:
+
+| Methode | Pfad                       | Zweck                                     |
+| ------- | -------------------------- | ----------------------------------------- |
+| GET     | `/`                        | Übersichtsstatistiken                     |
+| GET     | `/traces`                  | Trace-Zusammenfassungen auflisten         |
+| GET     | `/traces/:runId`           | Trace-Details (Zusammenfassung + Spannen) |
+| GET     | `/traces/:runId/evals`     | Bewertungen für einen Lauf                |
+| POST    | `/feedback`                | Feedback abgeben                          |
+| GET     | `/feedback`                | Feedback auflisten                        |
+| GET     | `/feedback/stats`          | Feedback-Aggregation                      |
+| GET     | `/satisfaction`            | Zufriedenheitswerte                       |
+| GET     | `/evals/stats`             | Bewertungsstatistiken                     |
+| POST    | `/experiments`             | Experiment erstellen                      |
+| GET     | `/experiments`             | Experimente auflisten                     |
+| GET     | `/experiments/:id`         | Testdetails abrufen                       |
+| PUT     | `/experiments/:id`         | Experiment aktualisieren                  |
+| POST    | `/experiments/:id/results` | Ergebnisse berechnen                      |
+| GET     | `/experiments/:id/results` | Ergebnisse erhalten                       |
+
+Alle Endpunkte unterstützen die Abfrageparameter `?since=N` (ms-Zeitstempel) und `?limit=N`.
+
+## Auf externe Plattformen exportieren {#export}
+
+Senden Sie Traces an Langfuse, Datadog, Grafana oder ein beliebiges OTel-kompatibles Backend:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+Das Framework gibt `gen_ai.*`-Semantikkonventionsbereiche aus, die mit der OpenTelemetry GenAI-Spezifikation kompatibel sind.
+
+## OpenTelemetry-Bereiche {#otel}
+
+Getrennt von der oben genannten `exporters`-Konfiguration (die die internen Traces an einen OTLP-Endpunkt sendet) kann die Agentenschleife auch **Live-OpenTelemetry-Spans** für jede Ausführung, jeden Modellaufruf und jeden Tool-Aufruf ausgeben – so sieht ein Host, der bereits einen OTel-Collector ausführt, die Agentenaktivität neben dem Rest seiner verteilten Traces.
+
+Diese Ebene ist **optional und standardmäßig nicht aktiv**:
+
+- `@opentelemetry/api` ist eine **optionale Abhängigkeit**. Wenn es nicht installiert ist, degradieren die Helfer zu stillen No-Ops – hier wird nichts jemals in die Agentenschleife geworfen.
+- Selbst wenn das API-Paket vorhanden ist, wird ein standardmäßiger No-Op-Tracer mitgeliefert. Spans werden erst dann real, wenn der **Host einen `TracerProvider`** registriert (über `@opentelemetry/sdk-node` oder ähnliches). Das Framework ist bewusst **nicht** auf die umfangreichen SDK/Exporter-Pakete angewiesen und registriert auch keinen Anbieter selbst – die Instrumentierung erfolgt durch die Einbettungs-App.
+
+Wenn Sie OTel nicht verkabelt haben, betragen die Kosten also ein paar zwischengespeicherte Eigenschaftsablesungen pro Anruf. Um es zu aktivieren, installieren Sie das API-Paket und Ihr SDK und registrieren Sie beim Serverstart einen Anbieter, genau wie Sie es für jeden anderen Knotendienst tun würden.
+
+Die Agentenschleife gibt drei Span-Typen aus:
+
+| Spanne      | Wann                     | Attribute                                                         |
+| ----------- | ------------------------ | ----------------------------------------------------------------- |
+| `agent.run` | einmal pro Agentenlauf   | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | einmal pro Aktionsaufruf | `tool.name`, plus Erfolgs-/Fehlerstatus                           |
+| `llm.call`  | pro Modellaufruf         | Timing + OK/Fehlerstatus                                          |
+
+Spans werden mit dem Status „OK/ERROR“ abgeschlossen und bei einem Fehler wird eine Fehlermeldung aufgezeichnet. Null-/Sentinel-Attributwerte werden bereinigt, damit Spannen nicht mit Rauschen überfrachtet werden. Diese OTel-Schicht ist eine reine Ergänzung zu den hauseigenen `agent_trace_spans`-/`agent_trace_summaries`-Tabellen, die das obige Dashboard unterstützen – beide werden aus den gleichen Laufereignissen erstellt.
+
+## Fehlerberichterstattung (Sentry) {#sentry}
+
+Serverseitige Fehler, die Nitro-Routenhandlern entgehen, werden an Sentry gemeldet, wenn ein DSN konfiguriert wird. Ohne sie funktioniert der SDK stillschweigend nicht, daher ist es sicher, die Env-Variablen in Dev nicht gesetzt zu lassen. Browser- und Serverereignisse können zum selben Sentry-Projekt gehen; Teilen Sie sie nur dann in separate Projekte auf, wenn Sie eine betriebliche Trennung für Eigentum, Volumen, Kontingente oder Alarmweiterleitung wünschen.
+
+| Oberfläche         | SDK               | Umgebungsvariable                                               | Notizen                                                                                     |
+| ------------------ | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Browser / SPA      | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN` oder `SENTRY_DSN` | Erfasst nicht behandelte Fehler und Routenänderungs-Breadcrumbs im Client.                  |
+| Nitro-Server       | `@sentry/node`    | `SENTRY_SERVER_DSN` oder `SENTRY_DSN`                           | Erfasst 5xx-Antworten und Nitro-Lebenszyklusfehler. Benutzer pro Anfrage.                   |
+| `agent-native` CLI | `@sentry/node`    | _hardcoded_                                                     | Absturzberichte aus der veröffentlichten CLI-Binärdatei; nicht vom Benutzer konfigurierbar. |
+
+### Serverseitige Konfiguration {#sentry-config}
+
+Legen Sie `SENTRY_SERVER_DSN` oder das freigegebene `SENTRY_DSN` in der Bereitstellungsumgebung fest (Netlify-Dashboard, Cloudflare-Geheimnisse usw.). Das Framework mountet automatisch ein Nitro-Plugin, das:
+
+1. Ruft `Sentry.init` einmal beim Start auf (idempotent – sicherer Aufruf von mehreren Plugins).
+2. Löst den Benutzer über `getSession(event)` bei jeder API/Framework-Anfrage auf und fügt `id` / `email` / `username` plus ein `orgId`-Tag an den anforderungsspezifischen Isolationsbereich von Sentry an. Statische Asset-Pfade werden übersprungen, um zusätzliche DB-Treffer zu vermeiden.
+3. Erfasst jede Framework-Route 5xx mit durchsuchbaren `route`-, `method`- und `userAgent`-Tags.
+
+Optionale Knöpfe:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (float `0`–`1`) – Aktivieren Sie die Leistungsverfolgung. Standardmäßig ist `0` (nur Fehler). Ungültige Werte gelten für `0`.
+- `AGENT_NATIVE_RELEASE` – überschreibt das `release`-Tag. Standardmäßig ist `agent-native-server@<core-version>`.
+
+### Vorlagen
+
+Jede Vorlage erbt dies automatisch – es gibt nichts zu importieren. Bei SSR-Apps fügt der Server ein kleines Browser-Konfigurationsskript ein, wenn `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN` oder freigegebenes `SENTRY_DSN` zur Laufzeit verfügbar ist, sodass die Browsererfassung nicht auf die Vite-Build-Time-Umgebung beschränkt ist. Vorlagen, die ein benutzerdefiniertes Verhalten wünschen (zusätzliche Tags, unterschiedliche DSN pro Vorlage, feste Deaktivierung von Sentry), können überschreiben, indem sie ihr eigenes Plugin aus `server/plugins/sentry.ts` exportieren:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+Der fest codierte DSN des CLI ist beabsichtigt – die veröffentlichte Binärdatei muss Abstürze beheben, unabhängig davon, in welcher Umgebung sie ausgeführt wird. Das Servermodul codiert niemals einen DSN fest, da es in Kundenumgebungen ausgeführt wird, in denen Bediener entscheiden, ob Fehler überhaupt Sentry erreichen sollen.
+
+### Datenschutz & PII {#privacy}
+
+Sowohl Server als auch CLI werden mit `sendDefaultPii: false` und einem `beforeSend`-Hook initialisiert, der Folgendes entfernt:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (automatisch ohne Zustimmung erfasst)
+- `contexts.runtime_env` (Prozessumgebungs-Snapshot)
+- Jedes Ereignis, dessen Ausnahmetyp der obersten Ebene `ValidationError` ist (wird als erwartete Ablehnung von Benutzereingaben behandelt, nicht als Fehler).
+
+Identitätsfelder, die explizit über `setUser({ id, email, username })` festgelegt wurden, bleiben erhalten.
+
+## Was kommt als nächstes?
+
+- [**Tracking**](/docs/tracking) – Produktanalysen (PostHog, Mixpanel, Amplitude) für die eigenen Ereignisse Ihrer App
+- [**Actions**](/docs/actions) – die Vorgänge, die als Werkzeugaufrufe in Traces erscheinen
+- [**Security**](/docs/security) – Datenumfang und Umgang mit Anmeldeinformationen

package/docs/content/locales/de-DE/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "Beobachtungsgedächtnis"
+description: "Dreistufige Hintergrundkomprimierung (aktuelle Rohdaten → Beobachtungen → Reflexionen), die lange Agent-Threads kostengünstig und stabil im Prompt-Cache hält, ohne kurze Konversationen zu beeinträchtigen."
+---
+
+# Beobachtungsgedächtnis
+
+Ein Agent-Thread mit langer Laufzeit sammelt ein riesiges Transkript: jede Nachricht, jeder Tool-Aufruf, jedes Ergebnis. Das erneute Abspielen des gesamten Verlaufs in das Modell bei jeder Runde ist teuer und führt schließlich dazu, dass das Kontextfenster zerstört wird. **Observational Memory (OM)** komprimiert den älteren Teil eines langen Threads in einer veralteten, geschichteten Zusammenfassung, sodass das Modell immer noch weiß, was passiert ist – nur zu einem Bruchteil der Token-Kosten –, während die letzten Wendungen wörtlich bleiben.
+
+OM ist völlig automatisch und inhaberabhängig. **Kurze Threads sind davon nicht betroffen**: Bis ein Thread den ersten Komprimierungsschwellenwert überschreitet, ist OM ein No-Op und der Kontext ist Byte für Byte so, wie er ohne ihn wäre.
+
+## Die drei Ebenen {#tiers}
+
+OM stellt einen langen Thread mit drei Schichten dar, vom am meisten destillierten zum aktuellsten:
+
+| Stufe                      | Was es ist                                                                                                                            |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **Reflexionen**            | Höchste Ebene, komprimiert aus dem Beobachtungsprotokoll, sobald es groß wird. Die lange Zusammenfassung.                             |
+| **Beobachtungen**          | Dichte, datierte Einträge, die eine Reihe von Rohnachrichten zu einer kompakten Aufzeichnung dessen zusammenfassen, was passiert ist. |
+| **Neueste Rohnachrichten** | Die letzten N Runden werden **wörtlich** beibehalten – nie gefaltet –, sodass der Agent immer den neuesten Kontext sieht.             |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+Bei jeder Runde fügt die Leseseite diese in einem einzigen selbstbeschrifteten `[Observational Memory]`-Block zusammen, der das rohe ältere Präfix ersetzt, das aktuelle Rohfenster intakt hält und das Modell anweist, den komprimierten Datensatz als maßgeblich zu behandeln (fertige Arbeiten nicht wiederholen, den aufgezeichneten Entscheidungen, Namen, Daten und Status vertrauen).
+
+## Wie die Komprimierung ausgeführt wird {#compaction}
+
+Zwei Durchgänge werden als **Fire-and-Forget-Best-Effort-Schritt** _nach_ einer sauberen Drehung ausgeführt, sodass sie der für den Benutzer sichtbaren Reaktion niemals Latenz hinzufügen und Fehler verschluckt werden:
+
+1. **Beobachter** – sobald die _unbeobachteten_ Nachrichten eines Threads den Beobachtungstoken-Schwellenwert überschreiten, werden sie zu einem einzigen dichten Beobachtungseintrag zusammengefasst.
+2. **Reflektor** – sobald das persistente Beobachtungsprotokoll selbst den Reflexions-Token-Schwellenwert überschreitet, werden die Beobachtungen in einer Reflexion höherer Ebene zusammengefasst.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Beide passieren unter ihren Schwellenwerten keinen Betrieb, daher ist es günstig, den Verdichter nach jeder Runde anzurufen. Da OM das flüchtige Rohpräfix durch stabilen komprimierten Text ersetzt, bleibt die Eingabeaufforderung auch über die Windungen eines langen Threads hinweg **cachestabil**.
+
+OM-Daten befinden sich in der eigenen SQL-Datenbank der App und sind auf den Besitzer (und die Organisation, falls vorhanden) beschränkt – das gleiche Scoping-Modell wie der Rest des Frameworks. Es wird niemals von mehreren Benutzern geteilt.
+
+## Konfiguration {#config}
+
+Standardeinstellungen sind konservativ. Ein Bediener kann die Komprimierung zum Zeitpunkt der Bereitstellung mit `AGENT_NATIVE_OM_*`-Umgebungsvariablen wählen (keine erneute Bereitstellung des App-Codes erforderlich); Bei einem ungültigen oder fehlenden Wert wird immer auf den genannten Standardwert zurückgegriffen.
+
+| Umgebungsvariable                             | Standard | Was es steuert                                                                                                       |
+| --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`  | Token für unbeobachtete Nachrichten, die den Beobachter dazu veranlassen, sie zu einer Beobachtung zusammenzufassen. |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`  | Beobachtungsprotokolltoken, die den Reflektor dazu veranlassen, sich zu einer Reflexion zu verdichten.               |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`     | Wie viele der aktuellsten Nachrichten bleiben wörtlich (werden nie zu einer Beobachtung zusammengefasst).            |
+
+Die Ausgabeobergrenzen für Observer und Reflector (4000/2000 Token) verhindern, dass ein einziger Verdichtungsdurchgang das Budget sprengt. Sie sind im Code über `resolveObservationalMemoryConfig({ ... })` einstellbar, aber nicht umgebungsexponiert.
+
+> [!TIP]
+> Senken Sie die Schwellenwerte für eine frühere Komprimierung (günstigere lange Threads, etwas mehr Zusammenfassung); Erhöhen Sie sie, um vor dem Komprimieren mehr Rohgeschichte im Kontext zu behalten. Stellen Sie `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` höher ein, wenn Ihre Workflows ein längeres wörtliches Ende benötigen.
+
+## Wenn es losgeht {#when}
+
+OM ändert das Verhalten nur für Threads, die lange genug sind, um mindestens eine Beobachtung oder Reflexion zu erzeugen. Konkret:
+
+- Ein brandneuer oder kurzer Thread: noch keine OM-Einträge → der Kontext ist das reine Transkript, unverändert.
+- Ein langer Thread, der den Beobachtungsschwellenwert überschritten hat: Das ältere Präfix wird durch den komprimierten `[Observational Memory]`-Block ersetzt, das aktuelle Rohende bleibt unverändert und die Token-Nutzung sinkt erheblich.
+
+Die Injektion erfolgt nach bestem Aufwand und grenzensicher – wenn kein sicherer Trimmpunkt gefunden werden kann (z. B. ein ausstehendes Tool-Nutzungs-/Ergebnispaar am Fensterrand liegt), injiziert OM den Speicherblock _additiv_ ohne Trimmen, anstatt das Risiko einzugehen, ein ausstehendes Tool-Ergebnis fallen zu lassen.
+
+## Verwandt
+
+- [**Using Your Agent**](/docs/using-your-agent) – die tägliche Schleife der Arbeit mit dem Agent, der neben Ihrer App angedockt ist.
+- [**Observability**](/docs/observability) – Token- und Kostenmetriken pro Lauf, in denen die Einsparungen von OM angezeigt werden.
+- [**Custom Agents & Teams**](/docs/agent-teams) – lange Subagent-Läufe profitieren von der gleichen Komprimierung.

package/docs/content/locales/de-DE/onboarding.md

@@ -0,0 +1,216 @@
+---
+title: "Onboarding- und API-Schlüssel"
+description: "Setup-Checkliste für die Erstkonfiguration – API-Schlüssel, OAuth und Anbieterverbindungen"
+---
+
+# Onboarding
+
+Wenn Sie zum ersten Mal eine App öffnen, die auf dem agentennativen Framework basiert, wird ein
+**Setup**-Checkliste in der Agent-Seitenleiste. Die Erstausführungskonfiguration bleibt geschlossen
+zum Agenten-Chat: Verbinden Sie eine KI-Engine, verweisen Sie die App optional auf „Freigegeben“
+Infrastruktur und fügen Sie Anbieter nur dann hinzu, wenn Sie sie benötigen.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## Für Endbenutzer
+
+### Was Sie sehen werden
+
+- Ein **Setup**-Panel über dem Agenten-Chat mit einer Checkliste wie „Eine KI verbinden
+  Engine“, „E-Mail-Versand“ usw.
+- Ein Zähler oben (z. B. „1 von 4“) zeigt an, wie viele Schritte bereit sind.
+- Der aktuelle Schritt wird erweitert; Abgeschlossene Schritte werden mit einem grünen Häkchen angezeigt und bleiben bestehen
+  lesbar, wenn Sie sie öffnen.
+- Erforderliche Schritte zeigen eine kleine rote **erforderliche** Pille an. Das Panel bleibt sichtbar
+  bis alle erforderlichen Schritte abgeschlossen sind.
+- Sobald alles Erforderliche erledigt ist, wird das Panel automatisch ausgeblendet.
+- Das gesamte Panel kann mit dem Chevron oben rechts minimiert werden, oder
+  komplett ausgeblendet mit **Setup ausblenden** unten.
+
+### So führen Sie die einzelnen Schritte aus
+
+Schritte bieten eine oder mehrere **Methoden** – verschiedene Möglichkeiten, dasselbe zu erfüllen
+Anforderung. Der primäre Pfad wird zuerst angezeigt; Sekundärpfade werden kompakt gehalten
+hinter einem Picker oder einer Offenlegung, wenn ein Schritt mehrere gleichwertige Anbieter hat.
+
+- **Verbinden Sie einen Dienst (ein Klick)** – z. B. _Verbinden Sie Builder_ für die verwalteten
+  KI-Gateway. Klicken Sie auf die Schaltfläche, ein Fenster wird geöffnet, Sie melden sich an, das Fenster wird geschlossen,
+  und der Schritt wird als abgeschlossen markiert. Keine Schlüssel zum Kopieren.
+- **Fügen Sie einen API-Schlüssel ein oder füllen Sie ein Formular aus** – z. B. Wählen Sie einen LLM-Anbieter, eine Datenbank
+  OAuth Anbieter oder E-Mail-Anbieter, fügen Sie die Werte ein und klicken Sie auf **Speichern**.
+  Geheime Felder verwenden eine Passworteingabe, sodass der Wert nicht auf dem Bildschirm angezeigt wird. Gespeichert
+  Werte gehen in Ihre lokalen `.env` (oder Arbeitsbereichseinstellungen) – siehe
+  [Security](/docs/security) für den Ort, an dem sie leben.
+- **Link öffnen** – einige Schritte verweisen auf eine Anmeldeseite oder Dokumente. Klicken Sie auf
+  **Weiter** und beenden Sie den Ablauf im neuen Tab.
+- **Fragen Sie den Agenten** – ein paar Schritte bieten die Option „Dem Agenten die Einrichtung überlassen“.
+  Klicken Sie darauf und der Agent greift im Chat auf und führt Sie durch alle Schritte
+  Externes Setup (Erstellen von OAuth-Anmeldeinformationen usw.).
+
+### Die integrierten Schritte, die Sie normalerweise sehen
+
+- **Anschließen einer KI-Engine** (erforderlich) – der einzige obligatorische Schritt. Verbinden
+  Builder für ein mit einem Klick verwaltetes Gateway, oder öffnen Sie den sekundären Anbieterschlüssel
+  Wählen Sie Ihren eigenen LLM-Schlüssel aus und fügen Sie ihn ein.
+- **Datenbank** (optional) – legen Sie `DATABASE_URL` fest, wenn Sie eine bestimmte verwenden möchten
+  SQL Datenbankverbindungszeichenfolge.
+- **Authentifizierung** (optional) – integrierte E-Mail-/Passwortkonten funktionieren per
+  Standard. Fügen Sie OAuth oder die Zugriffstoken-Anmeldung nur hinzu, wenn Sie diese Pfade benötigen.
+- **E-Mail-Zustellung** (optional) – nützlich vor der Bereitstellung für das Zurücksetzen von Passwörtern
+  Teameinladungen und Freigabebenachrichtigungen. Nutzen Sie den Anbieter, den Sie bereits nutzen;
+  Lokale Entwicklung kann ohne ausgeführt werden.
+
+Vorlagen können darüber hinaus eigene Schritte hinzufügen – z. B. Eine CRM-Vorlage könnte
+Fügen Sie „Gmail verbinden“ hinzu. Eine Dokumentvorlage fügt möglicherweise „Standardarbeitsbereich auswählen“ hinzu. Siehe
+[Authentication](/docs/authentication) für Details zur Anmeldeeinrichtung.
+
+### Zurück zur Checkliste
+
+Wenn Sie auf **Setup ausblenden** klicken, wird das Panel für diese Browsersitzung ausgeblendet.
+Erforderliche Schritte, die noch nicht abgeschlossen sind, werden beim nächsten Laden erneut angezeigt. Einmal
+Alles Erforderliche ist erledigt, das Bedienfeld wird endgültig automatisch ausgeblendet – es gibt nichts
+noch zu erledigen.
+
+## Für Entwickler
+
+Wenn Sie eine Vorlage erstellen, registrieren Sie Onboarding-Schritte, damit sie in angezeigt werden
+die Checkliste für die Seitenleiste des Benutzers. Das Framework übernimmt das Rendern und die Fertigstellung
+Nachverfolgung und Entlassung – Sie erklären einfach, was der Schritt ist und wie er abläuft
+zufrieden.
+
+Das System wird **automatisch gemountet**. Vorlagen müssen nichts verkabelt werden, um
+die vier integrierten Schritte (LLM, Datenbank, Authentifizierung, E-Mail). Zum Hinzufügen von App-spezifischen
+Schritte (Gmail, Slack, Notion usw.), `registerOnboardingStep()` von einem aufrufen
+Server-Plugin.
+
+### Automatisch bereitgestellte Routen
+
+Alle Routen live unter `/_agent-native/onboarding/`:
+
+| Route                                               | Zweck                                               |
+| --------------------------------------------------- | --------------------------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | Schritte mit Abschlussstatus auflisten              |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Schritt als abgeschlossen markieren (überschreiben) |
+| `POST /_agent-native/onboarding/dismiss`            | Onboarding-Banner schließen                         |
+| `POST /_agent-native/onboarding/reopen`             | Eindeutige Entlassung (Panel erneut zeigen)         |
+| `GET /_agent-native/onboarding/dismissed`           | Entlassung + AllComplete-Flag lesen                 |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### Einen Schritt aus einer Vorlage hinzufügen
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### Arbeitsbereichsverbindungen beim Onboarding prüfen
+
+Beim Erstellen von Vorlagen, die mit externen Diensten (wie Slack, Google Workspace, GitHub oder HubSpot) interagieren, sollten Sie prüfen, ob der Arbeitsbereich bereits eine Verbindung hergestellt und diesem Anbieter eine Verbindung zu Ihrer Anwendung gewährt hat. Dies verhindert, dass Benutzer Anmeldeinformationen (wie API-Schlüssel oder Aktualisierungstoken) in ihren lokalen Umgebungsvariablen duplizieren müssen, wenn eine zentrale, verwaltete Verbindung besteht.
+
+Sie können die Verbindungsbereitschaft in Ihrem `isComplete`-Callback mithilfe des Verbindungskatalogs APIs überprüfen:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+Eine vollständige Liste der Verbindungsanbieter-Katalogmethoden finden Sie in der [Workspace Connections](/docs/workspace-connections)-Dokumentation.
+
+### Methodenarten
+
+| Freundlich         | Nutzlast                                              | Verwenden für                                                        |
+| ------------------ | ----------------------------------------------------- | -------------------------------------------------------------------- |
+| `link`             | `{ url, external? }`                                  | Benutzer zu einem OAuth-Flow oder einer Dokumentenseite weiterleiten |
+| `form`             | `{ fields, writeScope? }`                             | Env-Variablen sammeln (Schlüssel, Geheimnisse, URLs)                 |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)                               |
+| `agent-task`       | `{ prompt }`                                          | Senden Sie eine Aufforderung an den Agenten-Chat zur Bearbeitung     |
+
+Das `primary: true`-Flag markiert eine Methode als das große CTA für ihren Schritt.
+Verwenden Sie `badge: "soon"` plus `disabled: true`, wenn ein Setup-Pfad sichtbar sein soll
+bevor es verfügbar ist.
+
+### Eingebaute Schritte
+
+| ID         | Erforderlich | Beschreibung                                             |
+| ---------- | ------------ | -------------------------------------------------------- |
+| `llm`      | Ja           | Builder-Verbindung oder ein Provider-LLM-Schlüssel       |
+| `database` | nein         | Standarddatenbank oder eine beliebige SQL `DATABASE_URL` |
+| `auth`     | nein         | Eingebaute Konten, optional OAuth oder Zugriffstoken     |
+| `email`    | nein         | Erneut senden oder SendGrid für Transaktions-E-Mails     |
+
+Any of these can be overridden by re-registering with the same `id` after the
+Standardlast.
+
+### Client-Nutzung
+
+Das Panel befindet sich bereits im `<AgentPanel>`. So erstellen Sie ein benutzerdefiniertes Layout:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+Hintergrundinformationen dazu, wo Schrittwerte gespeichert werden und wie Geheimnisse gehandhabt werden,
+siehe [Security](/docs/security). Für Endbenutzer-Messaging-Touchpoints (Einladungen,
+Passwort-Resets), die vom Schritt **E-Mail-Zustellung** abhängen, siehe
+[Messaging](/docs/messaging).