@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,368 @@
+---
+title: "Komponente API"
+description: "Öffentliche React-Bausteine für den benutzerdefinierten Agenten UI, Chatfelder, Konversationsrendering, Echtzeitpräsenz, Freigabe, Fortschritt und umfangreiche Editoren."
+---
+
+# Komponente API
+
+Agent-Native liefert eine vollständige Seitenleiste, aber die Seitenleiste ist nicht der Vertrag. Die
+Vertrag ist die Laufzeit: Chat-Streaming, Thread-Status, actions, Kontext,
+Anhänge, Modellauswahl, Läufe und SQL-gestützte Synchronisierung. Verwenden Sie die Brühe
+Komponenten, wenn Sie können, und eine Ebene herunterklappen, wenn Sie ein benutzerdefiniertes Produkt UI benötigen.
+
+Browser UI aus fokussierten Client-Unterpfaden importieren:
+
+```tsx
+import { AgentSidebar } from "@agent-native/core/client";
+import { PromptComposer } from "@agent-native/core/client/composer";
+import { AgentConversation } from "@agent-native/core/client/conversation";
+import { usePresence } from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+```
+
+Vermeiden Sie den Import von UI-Komponenten aus dem bloßen `@agent-native/core`-Paket. Verwenden Sie
+`@agent-native/core/client` oder ein fokussierter `@agent-native/core/client/*`-Unterpfad
+daher wählen Bundler den browsersicheren Eintrag.
+
+```an-diagram title="Drop down a layer, not out of the framework" summary="Each layer keeps the same runtime — actions, thread state, and SQL-backed sync — while giving you more control over the chrome."
+{
+  "html": "<div class=\"diagram-layers\"><div class=\"diagram-card layer\"><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><small class=\"diagram-muted\">Whole sidebar around your app. The 80% case.</small></div><div class=\"diagram-card layer l2\"><span class=\"diagram-pill\">&lt;AgentPanel&gt; &middot; &lt;AgentChatSurface&gt;</span><small class=\"diagram-muted\">The panel or a chat page in your own layout.</small></div><div class=\"diagram-card layer l3\"><span class=\"diagram-pill\">&lt;AssistantChat&gt; + runtime</span><small class=\"diagram-muted\">Own the chrome; optionally pass a BYO AgentChatRuntime.</small></div><div class=\"diagram-card layer l4\"><span class=\"diagram-pill\">&lt;PromptComposer&gt; &middot; &lt;AgentConversation&gt;</span><small class=\"diagram-muted\">Composer and transcript primitives only.</small></div><div class=\"diagram-rail\" data-rough>Same runtime: actions &middot; thread state &middot; SQL-backed sync</div></div>",
+  "css": ".diagram-layers{display:flex;flex-direction:column;gap:10px}.diagram-layers .layer{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-layers .l2{margin-inline-start:24px}.diagram-layers .l3{margin-inline-start:48px}.diagram-layers .l4{margin-inline-start:72px}.diagram-layers .diagram-rail{margin-top:6px;padding:10px 14px;text-align:center}"
+}
+```
+
+## Agent und Chat UI {#agent-chat-ui}
+
+| API                                  | Importpfad                                      | Verwenden, wenn                                                                                                                        |
+| ------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `<AgentSidebar>`                     | `@agent-native/core/client` oder `/client/chat` | Sie möchten die vollständige Seitenleiste rund um Ihre App.                                                                            |
+| `<AgentToggleButton>`                | `@agent-native/core/client` oder `/client/chat` | Sie rendern Ihre eigene Kopfzeilenschaltfläche für die Seitenleiste.                                                                   |
+| `<AgentPanel>`                       | `@agent-native/core/client` oder `/client/chat` | Sie möchten das vollständige Panel in Ihrem eigenen Layout, Ihrer eigenen Route, Ihrem eigenen Dialog oder Ihrer eigenen Seitenspalte. |
+| `<AgentChatSurface>`                 | `@agent-native/core/client` oder `/client/chat` | Sie möchten im Panel- oder Seitenmodus ohne den Seitenleisten-Wrapper chatten.                                                         |
+| `<AssistantChat>`                    | `@agent-native/core/client` oder `/client/chat` | Sie möchten das umgebende Chrome besitzen und gleichzeitig die Standard-Konversations- und Composer-Laufzeit beibehalten.              |
+| `<MultiTabAssistantChat>`            | `@agent-native/core/client` oder `/client/chat` | Sie möchten die Thread-Registerkarten des Frameworks ohne `AgentPanel` Chrome.                                                         |
+| `createHttpAgentChatRuntime()`       | `@agent-native/core/client` oder `/client/chat` | Sie verfügen über einen BYO-Agentenendpunkt, der normalisierte Chat-Ereignisse streamt.                                                |
+| `createOpenAIAgentsChatRuntime()`    | `@agent-native/core/client` oder `/client/chat` | Sie haben einen OpenAI Agents SDK-Stream und möchten den Standard-Chat UI darum herum.                                                 |
+| `createOpenAIResponsesChatRuntime()` | `@agent-native/core/client` oder `/client/chat` | Sie haben einen OpenAI Responses-Ereignisstrom und möchten ihn in den Chat UI normalisieren.                                           |
+| `createAgUiChatRuntime()`            | `@agent-native/core/client` oder `/client/chat` | Sie haben einen AG-UI-Ereignisstrom und möchten ihn in den Chat UI normalisieren.                                                      |
+| `createClaudeAgentChatRuntime()`     | `@agent-native/core/client` oder `/client/chat` | Sie haben einen Claude Agent SDK-Stream und möchten ihn in den Chat UI normalisieren.                                                  |
+| `createVercelAiChatRuntime()`        | `@agent-native/core/client` oder `/client/chat` | Sie haben einen Vercel AI SDK-Stream und möchten ihn in den Chat UI normalisieren.                                                     |
+| `createAgentChatRuntimeAdapter()`    | `@agent-native/core/client` oder `/client/chat` | Sie müssen einen `AgentChatRuntime` selbst in die Assistant-UI umwandeln.                                                              |
+| `createAgentChatAdapter()`           | `@agent-native/core/client` oder `/client/chat` | Sie benötigen den integrierten Agent-Native SSE-Transport als Low-Level-Assistent-UI-Adapter.                                          |
+| `useChatThreads()`                   | `@agent-native/core/client` oder `/client/chat` | Sie benötigen eine benutzerdefinierte Thread-Liste, eine Verlaufsauswahl oder einen begrenzten Chat UI.                                |
+| `sendToAgentChat()`                  | `@agent-native/core/client` oder `/client/chat` | Eine Produktaktion sollte dem Agenten-Chat Arbeit überlassen.                                                                          |
+
+`AgentChatRuntime` ist der BYO-Agentenvertrag für die Standard-Chat-Shell. Bestehen
+`runtime` bis `<AssistantChat>`, wenn ein externer Agent den
+Konversation, während Agent-Native den Komponisten, das Transkript, die Werkzeugkarten usw. behält.
+natives Widget-Rendering. Die Anschlüsse oben sind die API-Oberfläche; die Laufzeit
+Vertrags- und Ereignisformen werden eingelernt
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+Wenn Sie zwischen Headless Agents, Rich Chat, eingebettetem Sidecar und
+Vollständige App-Formen finden Sie unter [Agent Surfaces](/docs/agent-surfaces).
+
+Die kürzeste benutzerdefinierte Route ist immer noch eine vorverdrahtete Oberfläche:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+Für benutzerdefiniertes Chrome rund um die Standardlaufzeit:
+
+```tsx
+import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
+
+function CustomChat({ projectSlug }: { projectSlug: string }) {
+  const threads = useChatThreads(undefined, projectSlug);
+  const threadId = threads.activeThreadId ?? undefined;
+
+  return (
+    <section className="grid h-full grid-cols-[260px_1fr]">
+      <ThreadList
+        threads={threads.threads}
+        activeThreadId={threadId}
+        onSelect={threads.switchThread}
+      />
+      <AssistantChat threadId={threadId} />
+    </section>
+  );
+}
+```
+
+Für einen Bring-Your-Own-Agent-Endpunkt erstellen Sie einen `AgentChatRuntime` mit einem der
+Anschlüsse oben und übergeben Sie es an `<AssistantChat runtime={...} />`. Siehe
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+für die Connector-Nutzung, den normalisierten Ereignisstrom und wann Sie darauf zugreifen sollten
+`createHttpAgentChatRuntime()` im Vergleich zu einem protokollspezifischen Anschluss.
+
+## Chat-Feld und Komponist {#composer}
+
+Verwenden Sie `@agent-native/core/client/composer`, wenn Sie denselben Chat platzieren müssen
+Feld, das von der Seitenleiste im benutzerdefinierten UI verwendet wird.
+
+| API                               | Verwenden wenn                                                                                                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PromptComposer>`                | Sie benötigen ein zum Senden bereites Chatfeld mit Anhängen, Schrägstrichbefehlen, Referenzen, Handhabung von eingefügtem Text, Entwurfspersistenz, Spracheingabe und Übermittlungssemantik. |
+| `<AgentComposerFrame>`            | Sie möchten die standardmäßige visuelle Hülle um einen benutzerdefinierten Composer-Körper herum.                                                                                            |
+| `<TiptapComposer>`                | Sie benötigen das Rich-Chat-Feld der untersten Ebene. Es muss innerhalb einer Assistant-UI `ThreadPrimitive.Root` / Composer-Laufzeitumgebung gerendert werden.                              |
+| `buildPromptComposerSubmission()` | Sie benötigen die gleiche Normalisierung von Anhängen und eingefügtem Text, bevor Sie Ihren eigenen Submit-Handler aufrufen.                                                                 |
+| `formatPromptWithAttachments()`   | Sie müssen versteckte Anhangsmetadaten in eine Eingabeaufforderungszeichenfolge rendern.                                                                                                     |
+
+Die meisten benutzerdefinierten UIs sollten mit `PromptComposer` beginnen:
+
+```tsx
+import { PromptComposer } from "@agent-native/core/client/composer";
+
+<PromptComposer
+  placeholder="Ask the agent..."
+  onSubmit={async (text, files, references, options) => {
+    await sendMessageToYourRuntime({ text, files, references, options });
+  }}
+/>;
+```
+
+Verwenden Sie `TiptapComposer` nur, wenn Sie bereits Assistant-UI-Primitive verdrahten
+selbst. Es ist das Feld, nicht die gesamte Chat-Laufzeit.
+
+## Konversations-Rendering {#conversation}
+
+Verwenden Sie `@agent-native/core/client/conversation` für die Wiedergabe im Transkriptstil
+außerhalb der vollständigen Agentenlaufzeit.
+
+| API                                             | Verwenden wenn                                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------------------------- |
+| `<AgentConversation>`                           | Rendern Sie eine Liste normalisierter Agent-Nachrichten.                        |
+| `<AgentConversationMessageView>`                | Eine normalisierte Nachricht rendern.                                           |
+| `normalizeCodeAgentTranscriptForConversation()` | Konvertieren Sie Code-Agent-Transkriptereignisse in Konversationsnachrichten.   |
+| `useNearBottomAutoscroll()`                     | Behalten Sie ein benutzerdefiniertes Transkript beim Streamen unten angeheftet. |
+
+Diese Ebene ist bewusst datenorientiert: Sie bestimmen, woher die Nachrichten kommen und
+Der Renderer besitzt konsistente Markdowns, Anhänge, Hinweise, Artefakte usw.
+Tool-Call-Anzeige.
+
+## Native Tool-Widgets {#native-tool-widgets}
+
+Verwenden Sie native Tool-Widgets, wenn ein Aktionsergebnis als UI in App-Qualität gerendert werden soll
+Innerer Chat statt einfach JSON. Zu den integrierten wiederverwendbaren Ausgängen gehören
+`DataTableWidget`, `DataChartWidget` und `DataWidgetResult`; sie werden exportiert
+von `@agent-native/core/client/chat` und dem Root-Client-Eintrag. Siehe
+[Native Chat UI](/docs/native-chat-ui) für den Aktionsergebnisvertrag.
+
+| API                              | Verwenden wenn                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `DataTableWidget`                | Sie möchten, dass ein Aktionsergebnis Zeilen und Spalten im nativen Chat rendert.                          |
+| `DataChartWidget`                | Sie möchten eine kompakte Ausgabe von Balken-, Linien- oder Flächendiagrammen im nativen Chat.             |
+| `DataWidgetResult`               | Sie möchten eine typisierte Ergebnisform für `"data-table"`, `"data-chart"` oder `"data-insights"`.        |
+| `registerActionChatRenderer()`   | Sie benötigen einen aktionsdeklarierten Renderer, der genau nach `chatUI.renderer` ausgewählt wird.        |
+| `registerToolRenderer()`         | Für ein Ergebnis, das nicht zum Kerntool gehört, benötigen Sie einen produktspezifischen nativen Renderer. |
+| `registerReservedToolRenderer()` | Framework-Code benötigt einen reservierten Renderer, der vor Vorlagen-Renderern gewinnt.                   |
+
+## Zusammenarbeit und Präsenz in Echtzeit {#collab-presence}
+
+Verwenden Sie `@agent-native/core/client/collab` für Präsenz im Liveblocks-Stil und
+Hooks für kollaborative Dokumente.
+
+| API                                                 | Verwenden wenn                                                                                                               |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `useCollaborativeDoc()`                             | Binden Sie einen Rich-Text-Editor oder eine benutzerdefinierte Yjs-Oberfläche an `/_agent-native/collab`.                    |
+| `usePresence()`                                     | Beliebige Bewusstseinsfelder veröffentlichen und rendern: Cursor, Auswahl, Ansichtsfenster, Modus.                           |
+| `<PresenceBar>`                                     | Aktive Mitarbeiter und Agenten anzeigen.                                                                                     |
+| `<LiveCursorOverlay>`                               | Remote-Cursor-Beschriftungen über einem positionierten Container rendern.                                                    |
+| `<RemoteSelectionRings>`                            | Remote-Auswahlkonturen über DOM-Elementen rendern.                                                                           |
+| `useFollowUser()`                                   | Folgen Sie dem Ansichtsfenster oder der Auswahl eines anderen Teilnehmers.                                                   |
+| `useCollaborativeMap()` / `useCollaborativeArray()` | Experimentieren Sie mit dem strukturierten Y.Map/Y.Array-Status, wenn die Zusammenführung von Rich-Text-Körpern nicht passt. |
+| `dedupeCollabUsersByEmail()`                        | Erstellen Sie einen benutzerdefinierten Avatar-Stapel ohne doppelte Registerkarten für denselben Benutzer.                   |
+
+```an-diagram title="Presence: humans and the agent share one awareness layer" summary="useCollaborativeDoc owns the awareness instance; client hooks publish cursors and selections; server helpers let an agent action appear as a live participant."
+{
+  "html": "<div class=\"diagram-presence\"><div class=\"diagram-col\"><div class=\"diagram-node\">Humans<br><small class=\"diagram-muted\">usePresence &middot; cursors, selection</small></div><div class=\"diagram-node diagram-accent\">Agent action<br><small class=\"diagram-muted\">agentUpdateSelection()</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">useCollaborativeDoc</span><small class=\"diagram-muted\">awareness layer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;PresenceBar&gt; &middot; &lt;LiveCursorOverlay&gt;<br><small class=\"diagram-muted\">render everyone, agent included</small></div></div>",
+  "css": ".diagram-presence{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-presence .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-presence .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-presence .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Serverseitige Agenten actions, die als Live-Teilnehmer auftreten möchten, verwenden die
+`@agent-native/core/collab` Agent Presence-Helfer auf niedrigerer Ebene:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+```
+
+## Rich-Editor {#rich-editor}
+
+Verwenden Sie `@agent-native/core/client/editor`, wenn Sie den gemeinsamen Markdown-Editor benötigen
+Oberfläche, die von Plänen, Inhalten, Ressourcen und kollaborativen Dokumenten verwendet wird
+Erfahrungen.
+
+| API                              | Verwenden wenn                                                                                                                         |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `<SharedRichEditor>`             | Sie benötigen den aktuellen, konfigurierbaren Editor mit Markdown-Serialisierung, optionalen Yjs und App-Extras.                       |
+| `<RichMarkdownEditor>`           | Sie benötigen den abwärtskompatiblen Alias für den gemeinsam genutzten Rich-Editor.                                                    |
+| `createSharedEditorExtensions()` | Sie erstellen Ihren eigenen Tiptap-Editor, benötigen aber das Framework-Schema und die Markdown-Dialekte.                              |
+| `<SlashCommandMenu>`             | Für eine benutzerdefinierte Tiptap-Oberfläche benötigen Sie den gemeinsamen Schrägstrich-Befehl UI.                                    |
+| `<BubbleToolbar>`                | Sie benötigen die gemeinsame Auswahlsymbolleiste für Markierungen, Links und benutzerdefinierte Inline-actions.                        |
+| `createRegistryBlockNode()`      | Sie benötigen registrierungsgestützte Blockknoten in einem Rich-Editor.                                                                |
+| `uploadEditorImage()`            | Sie möchten die Framework-Upload-Image-Aktion hinter dem freigegebenen Bildblock des Editors haben.                                    |
+| `useCollabReconcile()`           | Sie binden eine benutzerdefinierte Editoroberfläche an ein Yjs-Dokument und behalten dabei den Markdown als gespeicherten Zustand bei. |
+
+Der grundlegende kontrollierte Editor besteht nur aus Markdown-In und Markdown-Out:
+
+```tsx
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  placeholder="Write notes..."
+  features={{ tables: true, tasks: true, link: true }}
+/>;
+```
+
+Für die Bearbeitung in Echtzeit koppeln Sie es mit dem Collab-Unterpfad:
+
+```tsx
+import {
+  emailToColor,
+  useCollaborativeDoc,
+} from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+const editorUser = {
+  name: user.name,
+  email: user.email,
+  color: emailToColor(user.email),
+};
+const collab = useCollaborativeDoc({
+  docId,
+  user: editorUser,
+});
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  ydoc={collab.ydoc}
+  awareness={collab.awareness}
+  user={editorUser}
+/>;
+```
+
+## Arbeitsbereichsressourcen {#resources}
+
+Verwenden Sie `@agent-native/core/client/resources`, wenn Sie dasselbe verfügbar machen möchten
+Workspace-Ressourcenmodell, das die Registerkarte „Workspace“ des Agentenbereichs unterstützt.
+
+| API                                                                   | Verwenden wenn                                                                                                                  |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `<ResourcesPanel>`                                                    | Sie möchten die vollständige Registerkarte „Arbeitsbereich“ als Seite, Schublade oder benutzerdefiniertes Bedienfeld verwenden. |
+| `<ResourceTree>`                                                      | Sie möchten Ihren eigenen Ressourcenbrowser rund um Framework-Daten rendern.                                                    |
+| `<ResourceEditor>`                                                    | Sie möchten den Framework-Editor für eine ausgewählte Ressource.                                                                |
+| `useResourceTree()`                                                   | Sie benötigen einen bereichsbezogenen Baum für persönliche, freigegebene oder geschäftliche Ressourcen.                         |
+| `useResource()`                                                       | Sie benötigen den Inhalt und die Metadaten für eine ausgewählte Ressource.                                                      |
+| `useCreateResource()` / `useUpdateResource()` / `useDeleteResource()` | Sie benötigen benutzerdefinierte Kontrollen rund um den Ressourcenlebenszyklus.                                                 |
+| `useUploadResource()`                                                 | Sie müssen die Datei in den Framework-Ressourcenspeicher hochladen.                                                             |
+
+Das komplette Panel benötigt keine Requisiten:
+
+```tsx
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+
+<ResourcesPanel />;
+```
+
+Halten Sie für benutzerdefiniertes Ressourcen-Chrom die Hooks und Grundelemente zusammen:
+
+```tsx
+import { useState } from "react";
+import {
+  ResourceEditor,
+  ResourceTree,
+  useResource,
+  useResourceTree,
+  useUpdateResource,
+} from "@agent-native/core/client/resources";
+
+function WorkspaceResources() {
+  const tree = useResourceTree("workspace");
+  const updateResource = useUpdateResource();
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const resource = useResource(selectedId);
+
+  return (
+    <div className="grid h-full grid-cols-[260px_1fr]">
+      <ResourceTree
+        tree={tree.data ?? []}
+        selectedId={selectedId}
+        onSelect={(item) => setSelectedId(item.id)}
+        onCreateFile={() => {}}
+        onCreateFolder={() => {}}
+        onDelete={() => {}}
+        onRename={() => {}}
+        onDrop={() => {}}
+      />
+      {resource.data ? (
+        <ResourceEditor
+          resource={resource.data}
+          onSave={(content) =>
+            updateResource.mutate({ id: resource.data.id, content })
+          }
+        />
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Andere öffentliche UI {#other-ui}
+
+| Bereich            | APIs                                                   | Importpfad                                |
+| ------------------ | ------------------------------------------------------ | ----------------------------------------- |
+| Teilen             | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`  | `@agent-native/core/client/sharing`       |
+| Benachrichtigungen | `<NotificationsBell>`                                  | `@agent-native/core/client/notifications` |
+| Fortschritt        | `<RunsTray>`, Fortschritts-Hooks und -Typen            | `@agent-native/core/client/progress`      |
+| Onboarding         | `useOnboarding()`, Onboarding-Panel-Haken              | `@agent-native/core/client/onboarding`    |
+| Beobachtbarkeit    | `<ObservabilityDashboard>`, `<ThumbsFeedback>`         | `@agent-native/core/client/observability` |
+| Ressourcen         | `<ResourcesPanel>`, `<ResourceTree>`, Ressourcen-Hooks | `@agent-native/core/client/resources`     |
+| Rich-Editor        | `<SharedRichEditor>`, Slash-Befehle, Blockknoten-Hooks | `@agent-native/core/client/editor`        |
+
+## Einmalige Textvervollständigung {#one-off-text-completion}
+
+Wenn Sie wirklich rohen Text-In/Text-Out benötigen, behalten Sie ihn serverseitig bei und verwenden Sie ihn
+`completeText()` von `@agent-native/core/server`. Schließen Sie die benutzerbezogene Nutzung in ein
+Aktion, damit UI und Agent die gleiche Funktion nutzen.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`completeText()` is the escape hatch, not the default. Reach for it only for true text-in/text-out (a label, a one-line rewrite). Anything needing tools, state, auditability, or steering belongs in an action plus `sendToAgentChat({ background: true })`."
+}
+```
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { completeText } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Classify a short message",
+  run: async ({ body }: { body: string }) => {
+    const result = await completeText({
+      systemPrompt: "Return exactly one label.",
+      input: body,
+      maxOutputTokens: 12,
+      temperature: 0,
+    });
+    return { label: result.text.trim() };
+  },
+});
+```
+
+Verwenden Sie stattdessen `sendToAgentChat({ background: true, openSidebar: false })`, wenn
+Die Arbeit erfordert Tools, Status, Überprüfbarkeit, Benutzersteuerung oder mehrere Schritte
+Begründung.