@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,236 @@
+---
+title: "Tracking und Analyse"
+description: "Serverseitige Analysen mit austauschbaren Anbietern – PostHog, Mixpanel, Amplitude oder benutzerdefinierter Webhook"
+---
+
+# Analytics-Tracking
+
+Eine Funktion, mehrere Ziele. Rufen Sie `track()` von jedem serverseitigen Code aus auf – actions, Plugins, Serverrouten – und das Ereignis wird an jeden registrierten Analyseanbieter verteilt. Keine SDK-Abhängigkeiten, keine clientseitigen Skripte, keine Blockierung. Derselbe `track()` ist auch in [browser/app code](#client) verfügbar und leitet an dieselben Anbieter.
+
+Das ist _Produkt_-Analyse – die Ereignisse Ihrer App, die an PostHog/Mixpanel/Amplitude fließen. Informationen zu \_Agentenqualitätsmetriken (Ablaufverfolgungen, Kosten, Bewertungen, Feedback), die in Ihrer eigenen Datenbank gespeichert sind, finden Sie unter [Observability](/docs/observability).
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Eingebaute Anbieter {#built-in}
+
+Legen Sie eine Umgebungsvariable fest und der Anbieter registriert sich automatisch beim Serverstart. Keine Codeänderungen erforderlich.
+
+| Anbieter  | Umgebungsvariablen                                                                                              |
+| --------- | --------------------------------------------------------------------------------------------------------------- |
+| PostHog   | `POSTHOG_API_KEY` (erforderlich), `POSTHOG_HOST` (optional, Standardeinstellung ist `https://us.i.posthog.com`) |
+| Mixpanel  | `MIXPANEL_TOKEN`                                                                                                |
+| Amplitude | `AMPLITUDE_API_KEY`                                                                                             |
+| Webhook   | `TRACKING_WEBHOOK_URL` (erforderlich), `TRACKING_WEBHOOK_AUTH` (optionaler `Authorization`-Header)              |
+
+Mehrere Anbieter können gleichzeitig aktiv sein. Jede Veranstaltung geht an alle.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+Lösen Sie ein Analyseereignis aus. Fans an alle registrierten Anbieter.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+Identifizieren Sie einen Benutzer anhand von Merkmalen. Weiterleitung an Anbieter, die dies unterstützen (PostHog, Mixpanel, Amplitude, Webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+Benötigen Sie ein benutzerdefiniertes Backend, die Anbieterregistrierung API oder die Batch-/Singleton-Interna? Siehe [Advanced: custom providers & internals](#advanced) am Ende.
+
+## Track() in Vorlagen verwenden {#templates}
+
+Rufen Sie `track()` von Aktionshandlern auf, um Benutzer- oder Agentenaktivitäten aufzuzeichnen:
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+Track-Aufrufe sind „Fire-and-Forget“ – sie kehren sofort zurück und blockieren niemals die Aktionsantwort.
+
+## Clientseitiges Tracking {#client}
+
+`track()` funktioniert auch über Browser-/App-Code. Importieren Sie den Client-Zwilling aus `@agent-native/core/client` und rufen Sie ihn auf die gleiche Weise auf – er postet das Ereignis an die Framework-Route bei `POST /_agent-native/track`, die es an die **gleichen** registrierten serverseitigen Anbieter (PostHog, Mixpanel, Amplitude, Webhook) weiterleitet. Keine Analysen werden von SDK an den Browser gesendet und auf der Clientseite werden keine Anbieterschlüssel offengelegt.
+
+```an-api title="The client tracking route"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "Forward a browser event to the registered server-side providers",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+Hauptunterschiede zum [server `track()`](#track):
+
+- **Kein Identitätsargument.** Das Ereignis wird serverseitig dem angemeldeten Benutzer (und der aktiven Organisation, als `org_id` in `properties`) zugeordnet. Der Browsercode übergibt niemals einen `userId`.
+- **`source: "client"`** wird den Eigenschaften jedes Ereignisses hinzugefügt, damit Sie vom Client stammende Ereignisse von denen des Servers unterscheiden können.
+- **Fire-and-forget.** Es blockiert niemals den UI, löst niemals Netzwerkfehler aus und verschluckt sie.
+- **Authentifiziert, nur Erstanbieter.** Die Route erfordert eine Sitzung und einen Same-Origin/CSRF-Marker (vom Helfer automatisch festgelegt), sodass sie nicht als offenes Analyse-Relay verwendet werden kann. `name` ist auf 200 Zeichen und `properties` auf ~16 KB begrenzt; Übergroße oder fehlerhafte Nutzlasten werden abgelehnt.
+
+Dies unterscheidet sich von der internen Browser-Telemetrie des Frameworks (`trackEvent()` / automatische Seitenaufrufe – siehe [Browser defaults](#browser-defaults) unten), die die eigene Produktanalyse von Agent Native unterstützt. Verwenden Sie `track()` für die eigenen Analyseereignisse Ihrer App, die Ihre konfigurierten Anbieter erreichen sollen.
+
+## Erweitert: benutzerdefinierte Anbieter und Interna {#advanced}
+
+Die meisten Apps benötigen nur `track()` / `identify()` und einen integrierten Anbieter. Der Rest der Oberfläche – Registrierung benutzerdefinierter Anbieter, die `TrackingProvider`-Schnittstelle, Batch-Interna und die eigene Browser-Telemetrie des Frameworks – finden Sie unten.
+
+<details>
+<summary><strong>Provider-Registrierung API, Schnittstelle, Interna und Browser-Standardeinstellungen</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+Registrieren Sie einen benutzerdefinierten Anbieter für jedes Analyse-Backend.
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+Alle Anbieter leeren. Rufen Sie vor dem Beenden des Prozesses auf, um sicherzustellen, dass ausstehende Ereignisse gesendet werden.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+Entfernen Sie einen Anbieter nach Namen. Gibt `true` zurück, wenn der Anbieter gefunden und entfernt wurde.
+
+### `listTrackingProviders()` {#list}
+
+Gibt die Namen aller registrierten Anbieter zurück.
+
+### Die TrackingProvider-Schnittstelle {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+Nur `name` und `track` sind erforderlich. `identify` und `flush` sind optional – implementieren Sie sie, wenn Ihr Backend Benutzeridentität und Batch-Zustellung unterstützt.
+
+### Wie es funktioniert {#internals}
+
+- **Batched HTTP** – integrierte Anbieter stellen Ereignisse alle 10 Sekunden in die Warteschlange und leeren sie, oder wenn sich 50 Ereignisse ansammeln, je nachdem, was zuerst eintritt. Dadurch werden ausgehende Anfragen minimiert, ohne dass Daten verloren gehen.
+- **Keine SDK-Abhängigkeiten** – alle integrierten Anbieter verwenden rohes `fetch()`. Kein PostHog SDK, kein Mixpanel SDK, kein Amplitude SDK. Hält das Framework leichtgewichtig.
+- **Best-Effort-Zustellung** – Anbieterfehler werden abgefangen und protokolliert. Eine fehlerhafte Analyseintegration führt niemals zum Absturz des Anrufers oder blockiert die Anforderungsverarbeitung.
+- **Globaler Singleton** – die Registrierung verwendet einen `Symbol.for`-Schlüssel auf `globalThis`, sodass mehrere ESM-Diagramminstanzen (Entwicklungsmodus Vite + Nitro, Symlinks) einen Anbietersatz gemeinsam nutzen.
+
+### Browser-Standardeinstellungen {#browser-defaults}
+
+Dies deckt die eigene interne Telemetrie des Frameworks ab – hauptsächlich relevant für Framework-Mitwirkende und fortgeschrittene Vorlagenautoren.
+
+Template Roots rufen `configureTracking()` einmal beim Start auf. Mit `trackEvent()` gesendete Browserereignisse enthalten automatisch den App-/Vorlagenkontext sowie die aktuelle LLM-Verbindung, wenn die App diese auflösen kann:
+
+- `llm_connection` – normalisierte Anbieterbezeichnung wie `builder`, `anthropic`, `openai`, `google` oder `none`
+- `llm_engine` – die Engine-ID, zum Beispiel `builder` oder `ai-sdk:openai`
+- `llm_model` – das ausgewählte/Standardmodell, sofern bekannt
+- `llm_connection_source` – `app_secrets`, `settings` oder `env`
+- `llm_connection_configured` – ob eine LLM-Verbindung verfügbar ist
+
+Das Framework verfolgt auch `builder connect clicked` von Connect Builder-CTAs und die serverseitigen Builder-Connect-Routen verfolgen gestartete/erfolgreiche/fehlgeschlagene Lebenszyklusereignisse. `configureTracking()` wird vom Framework automatisch aufgerufen; Sie müssen es nicht in Ihrem eigenen Vorlagencode aufrufen.
+
+</details>
+
+## Was kommt als nächstes?
+
+- [**Actions**](/docs/actions) – woher die meisten Tracking-Aufrufe kommen
+- [**Server Plugins**](/docs/server) – `registerBuiltinProviders()` wird beim Start im Core-Routes-Plugin ausgeführt
+- [**Secrets**](/docs/security) – API-Schlüssel für Tracking-Anbieter verwalten

package/docs/content/locales/de-DE/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "Mit Ihrem Agenten"
+description: "Die tägliche Arbeit mit dem Agenten: Er sieht, was Sie sehen, Sie steuern es, betten es ein, gehen auf UI-light und bearbeiten es gemeinsam."
+---
+
+# Mit Ihrem Agenten
+
+Die entscheidende Idee hinter agent-native ist, dass der Agent und der UI **gleichberechtigte Partner** sind – siehe [What Is Agent-Native?](/docs/what-is-agent-native) für das Warum. In diesem Abschnitt geht es um die andere Hälfte dieses Versprechens: Wie es sich anfühlt, tatsächlich mit dem Agenten zu arbeiten, sobald er neben Ihrer App angedockt ist.
+
+Es gibt eine einfache Durchgangslinie. Der Agent **sieht**, was Sie gerade sehen, Sie **lenken** es auf das, was Sie möchten, Sie können es überall **einbetten**, Sie können vollständig **UI-light** verwenden, wenn das besser passt, und Sie können dieselben Dokumente gleichzeitig **mitbearbeiten**. Jede davon ist eine Seite in diesem Abschnitt.
+
+```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## Es sieht, was Sie sehen {#it-sees}
+
+Der Agent ist für Ihren Bildschirm nicht blind. Öffnen Sie eine E-Mail und es weiß, um welchen Thread es sich handelt. Wählen Sie ein Diagramm aus und es weiß, welches Diagramm. Markieren Sie einen Absatz und die Aktion kann genau auf diesen Bereich angewendet werden. Dieses gemeinsame Bewusstsein ermöglicht es Ihnen, „Antworten“ oder „Auswahl zusammenfassen“ zu sagen, ohne jedes Mal den Kontext buchstabieren zu müssen.
+
+Dies funktioniert, weil die aktuelle Navigation und Auswahl in `application_state` SQL gespeichert ist, die der Agent als Teil seines Kontexts liest. Der Agent kann denselben Status auch zurücksetzen – Öffnen einer Ansicht, Auswählen einer Zeile – sodass Sie sehen können, wie es im echten UI und nicht in einem Transkript funktioniert.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+→ [**Context Awareness**](/docs/context-awareness) – Navigationsstatus, Bildschirmansicht, Navigationsbefehle und wie der Agent mit Ihrem Bildschirm synchron bleibt.
+
+## Du leitest es {#you-direct-it}
+
+Meistens steuern Sie den Agenten durch Eingaben in den Chat. Zwei Dinge machen das schneller.
+
+**Erwähnungen.** Markieren Sie einen benutzerdefinierten Agenten, einen verbundenen Agenten oder eine Datei mit `@`, um sie in die Konversation einzubeziehen – „Lassen Sie `@analytics` die Zahlen der letzten Woche abrufen und erstellen Sie dann die Zusammenfassung.“ Durch Erwähnungen erreichen Sie den richtigen Spezialisten oder fügen den richtigen Kontext hinzu, ohne den Komponisten zu verlassen.
+
+**Stimme.** Der Komponist hat ein Mikrofon. Diktieren Sie eine Anfrage, anstatt sie einzugeben. Die Anbieteroptionen reichen von der gehosteten Transkription von Builder über Bring-Your-Own-Key bis hin zu einem Browser-Fallback.
+
+→ [**Agent Mentions**](/docs/agent-mentions) – `@` – benutzerdefinierte Agenten, verbundene Agenten und Dateien im Chat erwähnen.
+→ [**Voice Input**](/docs/voice-input) – Diktat im Chat Composer und wie die Transkription weitergeleitet wird.
+
+## Sie betten es ein {#you-embed-it}
+
+Der Agent ist keine separate App, zu der Sie wechseln. Es wird als eine Handvoll React-Komponenten geliefert – eine Seitenleiste, ein Rohpanel und ein `sendToAgentChat()`-Aufruf – die Sie in jede App einfügen können. Rendern Sie `<AgentSidebar>`, um jedem Bildschirm einen umschaltbaren Agenten zu geben, oder verbinden Sie eine Schaltfläche, um eine bestimmte Aufgabe an den Chat zu übergeben, anstatt einen einmaligen LLM-Anruf auszuführen.
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) – Mounten Sie `<AgentPanel>`, `<AgentSidebar>` und `sendToAgentChat()` in jede React-App.
+→ [**Agent Surfaces**](/docs/agent-surfaces) – Wählen Sie, ob der Workflow Headless, Chat-First, eingebettet oder eine vollständige App sein soll.
+
+## Sie können UI-light wählen {#ui-light}
+
+Nicht jede App benötigt ein vollständiges Dashboard. Wenn der Agent das Produkt ist, können Sie die meisten benutzerdefinierten UI überspringen: Öffnen Sie die App, fragen Sie nach, was Sie möchten, und lassen Sie den Agenten den Rest erledigen. Der Agent verfügt immer noch über seine Verwaltungsoberfläche – Verlauf, Arbeitsbereich, Einstellungen –, aber die primäre Interaktion besteht aus Gesprächen und nicht aus Klicks.
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) – Apps, bei denen der Agent das gesamte Produkt ist.
+
+## Sie sind Mitherausgeber {#you-co-edit}
+
+Wenn Sie und der Agent an demselben Dokument arbeiten, wechseln Sie sich nicht ab. Bei der Zusammenarbeit in Echtzeit werden die Bearbeitungen des Agenten parallel zu Ihren eingeblendet – Live-Cursor, kein Überschreiben – genau wie die Bearbeitungen eines Teamkollegen. Sie können weiter tippen, während es funktioniert, und Ihre Änderungen werden sofort angezeigt.
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) – gemeinsame Bearbeitung durch mehrere Benutzer mit Live-Cursor und Agentenbearbeitungen im selben Dokument.
+
+## Was kommt als nächstes? {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) – der Agent weiß, was Sie sehen
+- [**Agent Mentions**](/docs/agent-mentions) – leiten Sie es mit `@`-Erwähnungen
+- [**Voice Input**](/docs/voice-input) – steuern Sie es durch Sprechen
+- [**Drop-in Agent**](/docs/drop-in-agent) – in jede React-App einbetten
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) – gehen Sie zu UI-light, wenn der Agent das Produkt ist
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) – gemeinsam dasselbe Dokument bearbeiten

package/docs/content/locales/de-DE/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "Spracheingabe"
+description: "Sprachdiktat im Agent Chat Composer – Builder Gemini, BYOK-Anbieter und Browser-Web-Speech-Fallback."
+---
+
+# Spracheingabe
+
+Jede agentennative App verfügt über ein Mikrofon im Chat Composer. Klicken Sie darauf, sprechen Sie und Ihre Worte werden in die Eingabeaufforderung übertragen. Nützlich auf Mobilgeräten, nützlich für lange Eingabeaufforderungen, nützlich, wenn Sie etwas anderes in der Hand haben.
+
+Das Framework erledigt das alles automatisch. Mit Builder verbundene Benutzer erhalten standardmäßig das von Builder gehostete Gemini Flash-Lite. Andernfalls können Benutzer ihren eigenen Anbieterschlüssel mitbringen oder auf die Spracherkennung des Browsers zurückgreifen.
+
+## Wie es funktioniert {#how-it-works}
+
+Die Sprachtaste des Komponisten zeichnet Audio im Browser auf und wählt dann einen Anbieter aus:
+
+1. **Builder Gemini Flash-Lite (Standard, wenn Builder verbunden ist).** Der Browser sendet Audio an `/_agent-native/transcribe-voice`, das mithilfe von Gemini Flash-Lite über Builder.io weitergeleitet wird. Kein Google API-Schlüssel erforderlich.
+2. **BYOK Cloud-Anbieter.** Benutzer können in den Einstellungen Google Gemini, Groq Whisper oder OpenAI Whisper auswählen. Die Route löst benutzerbezogene verschlüsselte Geheimnisse vor gemeinsam genutzten Anmeldeinformationen für die Bereitstellung auf.
+3. **Browser Web Speech API (Fallback).** Wenn kein Serveranbieter verfügbar ist, kann der Composer die integrierte Spracherkennung des Browsers verwenden. Funktioniert in Chromium-basierten Browsern (Chrome, Edge, Arc) und Safari. Weniger genau; Live-Streams.
+
+Die Anbieterauswahl wird im Anwendungsstatus unter `voice-transcription-prefs` gespeichert, sodass der Benutzer `"auto"` (Standard – wählt den besten verfügbaren Anbieter), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"` oder `"browser"` in den Seitenleisteneinstellungen erzwingen kann.
+
+```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Die Route ist **nur Same-Origin** – Site-übergreifende POSTs werden abgelehnt, sodass ein Angreifer keine Transkriptions-Credits von einer externen Seite brennen kann.
+
+## Anbieter aktivieren {#enabling-providers}
+
+Builder ist der einfachste Weg: Verbinden Sie Builder.io über die Einstellungen und der Standardanbieter wird Builder Gemini Flash-Lite. Für BYOK-Anbieter fügen Sie den passenden Schlüssel unter Einstellungen → API-Schlüssel hinzu.
+
+### Pro Benutzer (empfohlen für SaaS)
+
+Der Benutzer legt seinen eigenen Schlüssel über die Agent-Seitenleisteneinstellungen UI fest. Es wird als benutzerbezogenes verschlüsseltes Geheimnis gespeichert (über `readAppSecret`). Jeder Benutzer zahlt für seine Transkription selbst; Keine Kosten für den Host.
+
+### Freigegeben (für interne Tools)
+
+Legen Sie `GEMINI_API_KEY`, `GROQ_API_KEY` oder `OPENAI_API_KEY` als Umgebungsvariable oder in der Tabelle `settings` fest. Die Transkription jedes Benutzers trifft auf den gemeinsamen Schlüssel.
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Credential resolution order:** the route checks the user's own encrypted secret first, then the shared deployment key. A power user with their own key always overrides the shared one. If neither exists, the route returns a 400 the composer recognizes and silently falls back to browser Web Speech."
+}
+```
+
+## Die Route {#route}
+
+```an-api title="Voice transcription route"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "Transcribe a recorded audio clip into prompt text",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+Sie müssen dies nicht direkt aufrufen – der Composer tut dies. Wenn Sie eine benutzerdefinierte Eingabeoberfläche erstellen, verwenden Sie zunächst die gemeinsam genutzten Composer-/Voice-Client-Teile von `@agent-native/core/client` wieder. Behandeln Sie diese Route als Low-Level-Transportgrenze für benutzerdefinierte Helfer, die mehrteiliges Audio senden müssen.
+
+## Anpassen des Anbieters {#customizing}
+
+Das Anbieterfeld ist ein einfacher Anwendungsstatusschlüssel, sodass der Agent ihn auf Anfrage ändern kann (`"use the browser speech recognizer instead"`). Wenn Sie eine Vorlage mit unterschiedlichen Anforderungen erstellen – beispielsweise eine lokale Whisper-Bereitstellung – tauschen Sie den Routenhandler aus, indem Sie Ihre eigene `transcribe-voice`-Route registrieren, bevor das Framework die Standardroute bereitstellt.
+
+## Was kommt als nächstes?
+
+- [**Drop-in Agent**](/docs/drop-in-agent) – der Komponist, der die Sprachtaste verfügbar macht
+- [**Onboarding**](/docs/onboarding) – Anbieterschlüssel als Einrichtungsschritte registrieren
+- [**Security & Data Scoping**](/docs/security) – wie verschlüsselte Geheimnisse pro Benutzer gespeichert werden

package/docs/content/locales/de-DE/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Was ist Agent-Native?"
+description: "Warum sich die meisten KI-Apps halb fertig anfühlen, was eine App wirklich agentennativ macht und wie Ihr Alltagserlebnis dadurch aussieht."
+---
+
+# Was ist Agent-Native?
+
+Agent-nativ ist eine Methode zum Erstellen von Software, bei der der KI-Agent und die ihn umgebende Produktoberfläche **gleichberechtigte Partner** sind. Diese Oberfläche kann ein Headless-Agent mit einer benutzerdefinierten Aktion, ein Rich-Chat oder ein vollständiger UI sein. Der wichtige Teil ist, dass Agenten und Menschen denselben actions, dieselbe Datenbank und denselben Status teilen.
+
+Wenn Sie sich nur an eine Sache von dieser Seite erinnern, denken Sie daran: Die meisten KI-Apps sind heute einen Schritt davon entfernt, nützlich zu sein, und diese Lücke ist derzeit der größte Fehler auf diesem Gebiet.
+
+## Wie es als Benutzer aussieht {#what-it-looks-like}
+
+Stellen Sie sich einen Hintergrundarbeiter, einen Posteingang, einen Kalender, einen Formularersteller oder ein Analyse-Dashboard vor. Manchmal gibt es noch keinen benutzerdefinierten Bildschirm: Sie führen eine Aktion oder eine kopflose App-Agent-Eingabeaufforderung aus. Manchmal ist der erste Bildschirm ein Chat: Sie fragen, was Sie möchten, der Agent führt Sie durch die Einrichtung, zeigt eine Tabelle oder ein Diagramm und öffnet die richtige App-Ansicht. Manchmal ist der Chat auf der rechten Seite einer vollständigen Anwendung angedockt. Über diese Formen hinweg können Sie Folgendes tun:
+
+- **Beginnen Sie mit dem eigentlichen Vorgang.** Eine dauerhafte Aktion kann von CLI, HTTP, MCP, A2A, der App-Agent-Schleife und später von UI ausgeführt werden.
+- **Klicken Sie auf alles, was Sie normalerweise anklicken würden, wenn ein UI vorhanden ist.** Alle Schaltflächen, Listen, Dashboards, Tastaturkürzel – sie alle rufen dieselben Vorgänge auf, die der Agent aufrufen kann.
+- **Oder fragen Sie einfach.** Geben Sie „Antwort auf die E-Mail von Sara, dass ich um 15 Uhr da sein werde“ in den Agenten ein. Es öffnet den richtigen Thread, entwirft die Antwort und zeigt sie Ihnen zur Genehmigung an – genau so, als ob Sie es von Hand gemacht hätten.
+- **Sehen Sie, was es sieht.** Öffnen Sie eine E-Mail und der Agent weiß, welche. Wählen Sie ein Diagramm aus, und der Agent weiß, welches Diagramm. Markieren Sie einen Absatz und drücken Sie Befehl+I. Der Agent bearbeitet dann nur diesen Absatz.
+- **Beobachten Sie, wie es funktioniert.** Während der Agent Dinge tut – Ansichten öffnet, Entwürfe bearbeitet, Berichte ausführt – wird der UI in Echtzeit aktualisiert. Sie können es jederzeit stoppen, umleiten oder mit der Maus übernehmen.
+- **Steuern Sie es wie ein Teamkollege.** Geben Sie Feedback, stellen Sie eine andere Aufgabe in die Warteschlange, bearbeiten Sie ihre Anweisungen, prüfen Sie, was sie gestern getan hat. Es merkt sich Ihre Arbeitsabläufe und verbessert sie mit der Zeit.
+
+Das ist die Erfahrung, für die Agent-Native entwickelt wurde. Hier erfahren Sie, warum die meisten Produkte dort nicht ankommen.
+
+## Warum die meisten „KI-Apps“ zu kurz kommen (Das Leiterprinzip) {#the-ladder}
+
+Es gibt einen Fortschritt, den die meisten Teams erklimmen, ähnlich einer Leiter, und die meisten stoppen eine Sprosse zu früh.
+
+### Rung 1 – ein einzelner LLM-Aufruf (das Anti-Muster) {#rung-one}
+
+Ein Textfeld sendet eine Eingabeaufforderung, die KI gibt eine Zeichenfolge zurück und Sie zeigen sie an. Vielleicht mit einem Spinner. Es gibt keine Möglichkeit für den Benutzer, den Kurs zu korrigieren, keine Möglichkeit für die KI, Maßnahmen zu ergreifen, keine Möglichkeit zu sehen, was passiert ist oder warum.
+
+Das sieht man überall: „KI-Funktionen“, bei denen es sich im Grunde um eine „Zusammenfassen“-Schaltfläche handelt, die an ein SaaS-Produkt geschraubt ist. Sie sehen in Demos beeindruckend aus und zerbrechen, sobald die Realität durcheinander gerät. Das ist kein Produkt; Das ist ein Spielzeug.
+
+### Rung 2 – ein Chat mit Tools {#rung-two}
+
+Jetzt kann die KI _Dinge erledigen_. Es verfügt über Tools – „E-Mail entwerfen“, „Kontakte suchen“, „Abfrage ausführen“ – und eine Chat-Oberfläche, auf der es direkt vor Ihnen funktioniert und Tool-Aufrufe und Ergebnisse anzeigt, während es ausgeführt wird. So sehen Claude, ChatGPT und Cursor unter der Haube aus.
+
+Das ist ein echter Fortschritt. Aber für sich genommen ist es immer noch ein Chatfenster. Es gibt kein richtiges UI. Keine Dashboards, keine Listen, keine Formulare, keine Tastaturkürzel, keine Zusammenarbeit im Team. Wenn die KI verwirrt ist, bleiben Sie beim erneuten Tippen hängen, anstatt einfach auf die rechte Schaltfläche zu klicken. Nicht-Entwickler haben Schwierigkeiten, in diesem Format echte Arbeit zu leisten.
+
+### Rung 3 – Agent + UI als gleichberechtigte Partner {#rung-three}
+
+Dies ist agentennativ. Sie fügen rund um den Agenten eine echte, voll funktionsfähige App hinzu – und entscheidend ist, dass jede Aktion, die der Agent ausführen kann, auch eine Schaltfläche im UI ist und jede Schaltfläche, auf die der Benutzer klickt, die gleiche Logik ausführt, die der Agent verwendet. Eine Implementierung, zwei Wege hinein.
+
+Drei Dinge ändern sich, wenn Sie Stufe 3 erreichen:
+
+- **Sie haben das Hinzufügen von Schaltflächen zu einem Chatbot eingestellt. Sie haben einer App einen Agenten hinzugefügt.** Das ist auf beiden Seiten ein viel hochwertigeres Produkt.
+- **Der Agent hat echten Kontext.** Er sieht, was Sie sehen, was Sie ausgewählt haben, was Sie gerade getan haben. Es schreibt in dieselbe Datenbank, aus der UI liest, sodass seine Arbeit sofort angezeigt wird.
+- **Externe Agenten können es auch verwenden.** Andere agentennative Apps können dieses actions über das [A2A protocol](/docs/a2a-protocol) aufrufen. Claude-Code, Codex, ChatGPT benutzerdefinierte MCP-Apps, Cursor und andere MCP-Hosts können es als [MCP server](/docs/mcp-protocol) steuern. Eine App, viele Einstiegspunkte.
+
+Das ist Rang 3. Das ist Agent-nativ.
+
+```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+Siehe [Key Concepts — Protocols](/docs/key-concepts#protocols), um zu erfahren, wie dies alles von derselben Aktionsdefinition abhängt.
+
+## Warum jeder Agent einen UI braucht {#why-every-agent-needs-a-ui}
+
+Selbst wenn der Agent die ganze schwere Arbeit übernimmt, müssen Menschen dennoch Folgendes tun:
+
+- **Sehen Sie, was es tut** – Fortschritt, Zwischenausgabe, was es berührt hat
+- **Steuern** – Feedback geben, unterbrechen, die nächste Aufgabe in die Warteschlange stellen
+- **Verwalten** – Bearbeiten Sie seine Anweisungen, skills, Speicher, geplante Jobs, verbundene Konten
+- **Inspizieren Sie die Arbeit** – überprüfen Sie Entwürfe, prüfen Sie den Verlauf und machen Sie Fehler rückgängig.
+- **Teilen Sie die Ausgabe** – Dashboards, Berichte, Formulare, Links zum Senden an Teamkollegen
+
+Zumindest ist „ein UI für den Agenten“ ein Observability- und Management-Dashboard. Im Maximum handelt es sich um eine vollständige SaaS-App, in die der Agent als Co-Pilot eingebettet ist. Beide Enden gelten als agentennativ, und die Oberfläche kann ohne Umschreiben aus einem heraus wachsen.
+
+Sie müssen nicht im Voraus eine Form auswählen. Der Agent kann kopflos arbeiten, hinter einem Rich-Chat sitzen oder in einer vollständigen Anwendung auf derselben Aktionsoberfläche leben – siehe [Agent Surfaces](/docs/agent-surfaces) für die konkreten Formen und APIs.
+
+## Warum jede App von einem Agenten profitiert {#why-every-app-benefits-from-an-agent}
+
+Die Kehrseite ist genauso wichtig. Bestehende SaaS-Produkte stoßen immer wieder an dieselben Probleme: 80 % dessen, was Sie benötigen, funktionieren hervorragend, und 20 % können Sie einfach nicht ändern. Das Hinzufügen einer Chat-Seitenleiste behebt das selten – der Chat kann normalerweise nicht die Dinge tun, die der UI kann.
+
+Agent-native macht das umgekehrt. Da jede Aktion in der App einmal definiert und sowohl als Schaltfläche als auch als Agententool verfügbar gemacht wird, kann der Agent alles tun, was die Schaltflächen können – und noch mehr –, ohne dass eine separate „KI-Welt“ verwaltet werden muss. Natürliche Sprache wird neben Klicks zu einem erstklassigen Input.
+
+Das Argument lautet nicht „Agenten ersetzen UI“. Es heißt: „**Agenten gehören in Anwendungen, mit einem UI an der Spitze, als gleichberechtigte Partner**.“ Selbst eine App, bei der der Agent das Produkt ist, benötigt immer noch einen UI, damit Menschen ihn überwachen, konfigurieren und steuern können – siehe [Agent Surfaces — Headless](/docs/agent-surfaces#headless).
+
+## Agent + UI-Parität {#agent-ui-parity}
+
+Dies ist das bestimmende Prinzip.
+
+> **Aus UI** – Schaltflächen anklicken, Formulare ausfüllen, durch Ansichten navigieren. Der UI schreibt in die Datenbank; Der Agent sieht die Ergebnisse.
+>
+> **Vom Agent** – natürliche Sprache, andere Agenten über A2A, Slack, Telegram. Der Agent schreibt in die Datenbank; Der UI wird automatisch aktualisiert.
+
+```an-diagram title="One system, two ways in" summary="The agent and the UI write to the same actions and the same database. Whatever one does, the other sees."
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">clicks, forms, shortcuts</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">natural language · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL database</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">UI updates live</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+Wenn der Agent einen E-Mail-Entwurf erstellt, wird dieser im UI angezeigt. Wenn Sie auf „Senden“ klicken, weiß der Agent, dass die Nachricht gesendet wurde. Es gibt keine getrennte „Agentenwelt“ und „UI-Welt“ – es ist ein einziges System. Siehe [Key Concepts](/docs/key-concepts) für die Architektur, die dies ermöglicht.
+
+## Anpassungen sind normalerweise Elektrowerkzeugen vorbehalten {#workspace-customization}
+
+Der Grund dafür, dass sich Tools wie Claude Code so leistungsstark anfühlen, ist nicht das Modell – es ist die **Anpassungsebene**: Anweisungen pro Projekt, skills, Speicher, Unteragenten, verbundene Dienste. Sie können den Agenten an Ihre Codebasis, Ihre Vorlieben und Ihr Team anpassen.
+
+Agent-native bietet jedem Benutzer die gleiche Anpassungsebene – ohne die App jemals zu verlassen. Jede App verfügt über einen persönlichen **Arbeitsbereich**, in dem Sie (oder jeder in Ihrem Team) Folgendes tun kann:
+
+- Bearbeiten Sie teamweite Regeln, die jeder Agent liest
+- Lassen Sie den Agenten die Einstellungen automatisch speichern, wenn Sie sie korrigieren
+- Schreiben Sie wiederverwendbare Anleitungen als `/slash`-Befehle
+- Behalten Sie benutzerdefinierte Subagenten für bestimmte Aufgaben bei (aufgerufen mit `@mentions`)
+- Planen Sie Jobs so, dass sie auf einem Cron ausgeführt werden (z. B. „jeden Montagmorgen, letzte Woche zusammenfassen“)
+- Verbinden Sie externe Dienste (Gmail, Stripe, Slack, interne APIs) über benutzerspezifische MCP-Server
+
+Der Clou: Es wird alles in der Datenbank gespeichert, nicht im Dateisystem. Es muss keine Entwicklungsumgebung eingerichtet werden, kein Container pro Benutzer. Jeder Benutzer erhält seinen eigenen vollständigen Arbeitsbereich – persönlichen Speicher, persönliche Verbindungen, persönliche skills – praktisch kostenlos, da es sich um alle Zeilen einer Tabelle handelt. Das macht die Flexibilität auf Claude-Codeebene in einem echten mandantenfähigen SaaS-Produkt realisierbar.
+
+Das vollständige Konzept finden Sie unter [Workspace](/docs/workspace).
+
+## Was es anders macht {#what-makes-it-different}
+
+| Ansatz                                     | Beschreibung                                                                                                                                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Traditionelle Apps mit integrierter KI** | Die KI ist ein nachträglicher Einfall. Beschränkt auf automatische Vervollständigung, Zusammenfassungen oder eine Chat-Seitenleiste, die in der App eigentlich nichts bewirken kann.        |
+| **Reine Chat-/Agentenschnittstellen**      | Leistungsstark, aber unzugänglich. Keine Dashboards, keine Workflows, keine Persistenz. Nicht-Entwickler können sie nicht effektiv nutzen.                                                  |
+| **Claude Code / Codex für SaaS**           | Ideal für Entwickler auf ihren eigenen Maschinen. Lässt sich nicht auf mandantenfähiges SaaS übertragen – eine Codebasis pro Benutzer auf einer Entwicklungsbox lässt sich nicht skalieren. |
+| **Agent-native Apps**                      | Der Agent ist ein erstklassiger Bürger. Es nutzt dieselbe Datenbank, denselben Status und kann alles, was UI kann – und umgekehrt.                                                          |
+
+## Entwicklung des gesamten Teams {#whole-team-development}
+
+Agent-native ist nicht nur für Entwickler. Da der Agent den eigenen Code der App bearbeiten kann, ist die Weiterentwicklung einer App keine reine Entwickleraktivität mehr:
+
+- **Designer** aktualisieren Designs direkt in der laufenden App über den Agent
+- **Produktmanager** fügen Funktionalität hinzu und aktualisieren Abläufe, indem sie sie beschreiben
+- **QA** testet die App und bittet den Agenten, den Fehler zu beheben
+- **Jeder im Team** trägt durch natürliche Sprache bei
+
+Die Vision: weniger Übergaben, eine Person erledigt die Arbeit eines kleinen Teams.
+
+## Forken und anpassen {#fork-and-customize}
+
+Agent-native Apps folgen einem Fork-and-Customize-Modell. Sie beginnen mit einer **Vorlage** – Kalender, Inhalt, Folien, Analysen, E-Mail, Clips, Design, Formulare, Versand – und machen sie zu Ihrer eigenen. Bei jedem handelt es sich um ein vollständiges, funktionierendes SaaS-Produkt, das Sie im Großhandel entwickeln können, und nicht um ein leeres Gerüst:
+
+1. Wählen Sie eine Vorlage auf [agent-native.com/templates](/templates)
+2. Sofort als gehostete App verwenden (z. B. mail.agent-native.com)
+3. Forken Sie es, wenn Sie es anpassen möchten – „Verbinden Sie unser Stripe-Konto“, „fügen Sie ein Kohortendiagramm hinzu“
+4. Der Agent ändert den Code entsprechend Ihren Anforderungen
+5. Stellen Sie Ihren Fork in Ihrer eigenen Domain bereit – oder bleiben Sie auf agent-native.com
+
+Da es sich um _Ihre_ App und nicht um eine gemeinsam genutzte Infrastruktur handelt, kann der Agent den Code sicher weiterentwickeln. Ihre App verbessert sich ständig, während Sie sie verwenden. Die ganze Geschichte finden Sie unter [Templates](/docs/cloneable-saas).
+
+Sie sind nicht bereit, eine ganze Vorlage zu teilen? Sie können Agent-nativ auch ausprobieren, indem Sie einen **Skill** zu einem Codierungsagenten hinzufügen, den Sie bereits verwenden – installieren Sie den Plans-Skill mit `npx @agent-native/core@latest skills add visual-plan`. Siehe [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## Zusammensetzbare Agenten {#composable-agents}
+
+Agent-native Apps können miteinander kommunizieren. In der E-Mail-App können Sie den Analyseagenten markieren, um Daten abzufragen und das Ergebnis in einen E-Mail-Entwurf aufzunehmen. Die Agenten ermitteln, welche anderen Agenten verfügbar sind, geben die Arbeit untereinander ab und zeigen die Ergebnisse in der UI an, in der Sie sich bereits befinden.
+
+Dies wird von [A2A](/docs/a2a-protocol) und [MCP](/docs/mcp-protocol) unter der Haube unterstützt – gleiche Definition, mehrere Oberflächen – aber als Benutzer müssen Sie nur wissen: „Ich kann jede meiner Apps um Hilfe bei allem bitten, was sie tun können.“
+
+## Wie sieht das im Code aus? {#what-does-it-look-like-in-code}
+
+Wenn Sie eine agentennative App erstellen oder erweitern, ist hier das zentrale Muster: Jeder Vorgang in der App ist eine **Aktion** – einmal definiert und sowohl für den Agenten als auch für UI verfügbar.
+
+```an-annotated-code title="One action, defined once"
+{
+  "filename": "actions/reply-to-email.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this as a tool." },
+    { "lines": "6", "label": "Typisierter Vertrag", "note": "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A." },
+    { "lines": "7-10", "label": "One implementation", "note": "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+Eine Aktion, viele Oberflächen: Der Agent ruft es als Tool auf, der UI nennt es eine typsichere Mutation, [native chat](/docs/native-chat-ui) kann explizite Widget-Ergebnisse rendern, externe Agenten erreichen es über [A2A](/docs/a2a-protocol) und MCP-Hosts rufen es über den [MCP server](/docs/mcp-protocol) der App auf, optional mit MCP Apps UI-Ressourcen und Standard-Remote-MCP OAuth gehandhabt durch den Rahmen. Die vollständige Referenz finden Sie unter [Actions](/docs/actions).
+
+## Was kommt als nächstes? {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) – Beginnen Sie mit einer Aktion, wählen Sie eine Vorlage aus oder installieren Sie einen Skill
+- [**Agent Surfaces**](/docs/agent-surfaces) – wählen Sie Headless, Rich Chat, eingebettetes Sidecar oder vollständige App
+- [**Key Concepts**](/docs/key-concepts) – die Architektur: SQL, actions, Polling-Synchronisierung, Kontextbewusstsein, Portabilität
+- [**Templates**](/docs/cloneable-saas) – Vorlagen als vollständige Produkte, die Sie besitzen
+- [**Workspace**](/docs/workspace) – die benutzerspezifische Anpassungsschicht (skills, Speicher, Anweisungen, MCP), unterstützt durch SQL, nicht durch Dateien
+- [**Dispatch**](/docs/dispatch) – die Workspace-Steuerungsebene: Geheimspeicher, Slack/E-Mail-Posteingang, anwendungsübergreifende Delegierung
+- [**Extensions**](/docs/extensions) – Sandbox-Mini-Apps, die der Agent sofort ohne Codeänderungen erstellt
+- [**Drop-in Agent**](/docs/drop-in-agent) – Mounten Sie `<AgentPanel>` in jede React-App