Wie nutzt man Agent-Native? Installations- und Entwicklungstutorial für das TypeScript-AI-Agent-Framework

Agent-Native installieren: Für gemeinsame UI- und Agent-Aktionen geeignet

Die offizielle Dokumentation beschreibt Agent-Native als Framework, in dem Benutzeroberfläche und Agent gemeinsame Actions, Daten und Anwendungszustände verwenden können (zentrale Konzepte von Agent-Native). Für TypeScript-Teams, die überprüfbare Geschäftsaktionen sowohl über die UI als auch über einen Agent anbieten wollen, ist Agent-Native daher ein geeigneter Ausgangspunkt. Erstellen Sie zunächst mit dem offiziellen CLI ein minimales Projekt; erweitern Sie es erst, wenn Eingabeprüfung, Berechtigungen, gemeinsamer Zustand und die benötigte Datenbank im eigenen Ablauf nachvollziehbar funktionieren. Agent-Native ist dabei keine Chat-Komponente, die sich ohne weitere Architekturprüfung in eine vorhandene Oberfläche stecken lässt.

Dieser Leitfaden eignet sich für Entwicklerinnen und Entwickler, die eine TypeScript-Agent-Anwendung anlegen und eine erste gemeinsame Action aufbauen möchten.
Produktteams können damit testen, ob UI und Agent dieselben Geschäftsobjekte unter klar abgegrenzten Berechtigungen bearbeiten.
Technische Verantwortliche erhalten Prüfpunkte für Abhängigkeiten, Remote-Entwicklung und den Weg zu einer ersten Bereitstellung.

Stand: 25.09.2026. Die Angaben zu CLI, Actions, Daten und Bereitstellung wurden anhand des offiziellen Agent-Native-Repositories und der verlinkten Dokumentation geprüft. Für die konkrete Installation sind die dort aktuell ausgewiesenen Befehle und Voraussetzungen maßgeblich.

Vor dem Projektstart: Passt Agent-Native zur Anwendung?

Agent-Native ist dann interessant, wenn ein Agent nicht bloß Text ausgeben, sondern nachvollziehbare Operationen in derselben Anwendung ausführen soll wie ein Mensch. Dazu zählen etwa das Ändern eines Vorgangsstatus, das Aktualisieren eines Entwurfs oder das Anlegen eines Eintrags. Das Architekturziel ist, Geschäftsaktionen nicht parallel für UI und Agent zu implementieren, sondern sie über dieselbe Anwendungslogik zugänglich zu machen. Die offiziellen Konzepterläuterungen sind hier die maßgebliche Grundlage.

Das ist ein anderer Zuschnitt als ein Chatfenster, das Antworten anzeigt, aber keine fachlichen Aktionen ausführt. Er bedeutet zugleich nicht, dass eine Action automatisch sicher ist, nur weil UI und Agent denselben Einstieg verwenden. Identität, Eingabevalidierung, Autorisierung und Protokollierung müssen weiterhin für den eigenen Anwendungsfall festgelegt werden.

Agent-Native ist einen Versuch wert, wenn:

• Benutzer und Agent dieselben Geschäftsobjekte bearbeiten, aber unterschiedliche Rechte besitzen können müssen.
• Ein Team Zustandsänderungen über eine einheitliche Geschäftslogik bündeln und überprüfen möchte.
• TypeScript bereits die zentrale Sprache der Anwendung ist und ein eigener Agent-gestützter Produktablauf entwickelt wird.

Ein anderes Vorgehen ist oft sinnvoller, wenn:

• lediglich ein Chatbereich benötigt wird, der keine Aktionen in der Anwendung ausführt;
• ein bestehendes Backend und eine fertige UI unverändert bleiben müssen und kein neues Anwendungsgerüst erwünscht ist;
• eine Anwendung nur einmalig oder mit sehr begrenztem Funktionsumfang erstellt wird und ein Framework zusätzliche Architekturarbeit verursachen würde.

Option	Geeignet, wenn …	Vor der Entscheidung prüfen
Agent-Native als Anwendungsgrundlage	UI und Agent dieselben Geschäftsaktionen aufrufen und denselben fachlichen Zustand nutzen sollen	CLI, Framework-Schnittstellen, Datenhaltung, Rechte und Deployment müssen zum Projekt passen
Vorhandene Anwendung mit separater Agent-Anbindung	Backend und UI bereits stehen und nur gezielt Agent-Funktionen ergänzt werden sollen	Es braucht eine belastbare gemeinsame API; ansonsten können Regeln in Agent und UI auseinanderlaufen
Chat ohne Geschäftsaktionen	Antworten oder Unterstützung im Vordergrund stehen, nicht Änderungen an Anwendungsdaten	Ein Agent-Framework mit gemeinsamem Anwendungszustand könnte unnötige Komplexität hinzufügen

Die Tabelle ist eine Architekturhilfe, keine Aussage über garantierte Funktionen oder Leistung. Die konkrete Unterstützung von Vorlagen, Schnittstellen und Hosts muss vor einer Entscheidung in der aktuellen Dokumentation geprüft werden.

Erster Schritt: Projekt mit dem offiziellen CLI anlegen

Die richtige Installationsanleitung für Agent-Native ist die jeweils aktuelle Quickstart-Dokumentation, nicht ein aus älteren Blogbeiträgen kopierter Befehl. Die dort beschriebene CLI-Sequenz kann sich ändern; deshalb sollten weder ein vermeintlich universeller npx-Aufruf noch eine nicht bestätigte Mindestversion von Node.js oder einem Paketmanager übernommen werden. Öffnen Sie den offiziellen Quickstart und verwenden Sie die dort für ein neues Projekt ausgewiesene Vorlage und Befehlsfolge unverändert.

Ein zuverlässiger Start besteht aus diesen Arbeitsschritten:

1. Laufzeit und Paketmanager erfassen. Halten Sie fest, welche Node.js-Version und welcher Paketmanager auf dem Entwicklungsrechner tatsächlich installiert sind. Vergleichen Sie sie mit den Anforderungen, die der Quickstart aktuell nennt. Fehlt dort eine eindeutige Mindestversion, erfinden Sie keine; dokumentieren Sie stattdessen die verwendete Umgebung und prüfen Sie, ob Installation und Start sauber durchlaufen.

2. Ein leeres Arbeitsverzeichnis vorbereiten. Trennen Sie das neue Framework-Projekt von bestehenden Anwendungen. So lässt sich später erkennen, ob ein Fehler durch die Vorlage, lokale Konfiguration oder eine schon vorhandene Abhängigkeit entsteht.

3. Das CLI aus der Dokumentation verwenden. Führen Sie den dort aufgeführten Erstellungsbefehl mit der vorgesehenen Vorlage aus. Benennen Sie das Projekt und speichern Sie den ausgeführten Befehl in den Projektnotizen, damit sich der Start reproduzieren lässt.

4. Installationsausgabe und Lockfile prüfen. Achten Sie auf fehlgeschlagene Pakete, Warnungen und unerwartete Änderungen an Abhängigkeitsdateien. Übernehmen Sie ein erzeugtes Lockfile in die Versionsverwaltung, wenn es zum Paketmanager des Projekts gehört.

5. Die vorgesehenen Entwicklungsbefehle ausführen. Starten Sie das Projekt so, wie es die Vorlage beschreibt. Prüfen Sie nicht nur, ob eine Seite sichtbar wird, sondern auch, ob Serverprozesse starten und die Anwendung erwartete Daten oder Konfiguration laden kann.

6. Den Start in einer zweiten Sitzung wiederholen. Stoppen Sie den lokalen Prozess, starten Sie ihn erneut und prüfen Sie, ob das Ergebnis mit derselben Abhängigkeitskonfiguration reproduzierbar ist. Ein einzelner erfolgreicher Start belegt noch keine stabile Entwicklungsumgebung.

Hinweis: Wenn Quickstart und generierte Vorlage unterschiedliche Befehle oder Voraussetzungen nahelegen, behandeln Sie das nicht als harmlose Abweichung. Prüfen Sie die zum installierten Stand passende offizielle Anleitung, bevor Sie eigene Versionsangaben oder Workarounds festschreiben.

Dieser Ablauf beantwortet auch die praktische Frage, wie ein Agent-Native-TypeScript-Projekt angelegt wird: über das offizielle CLI und die aktuelle Vorlage, mit einer dokumentierten lokalen Laufzeit. Ein Befehl, der ohne Prüfung aus einer älteren Anleitung kopiert wird, kann dagegen eine andere Vorlagen- oder API-Version erzeugen.

Zweiter Schritt: Eine gemeinsame Action für UI und Agent entwerfen

Eine Action sollte eine klar begrenzte Geschäftsoperation darstellen. Für ein Beispiel wie „Projektbezeichnung ändern“ gehören dazu ein Eingabeschema, eine fachliche Ausführung und eine Berechtigungsprüfung. Die offizielle Anleitung zum Definieren von Actions beschreibt die dafür vorgesehene Agent-Native-Schnittstelle. Da deren konkrete API und Typen von der aktuellen Framework-Version abhängen, sollte die Registrierung exakt nach dieser Dokumentation erfolgen, statt eine nicht verifizierte Signatur nachzubauen.

Unabhängig von der Framework-Registrierung lässt sich die Geschäftslogik zunächst als TypeScript-Funktion entwerfen. Das folgende Muster ist bewusst eine Anwendungslogik-Skizze, keine behauptete Agent-Native-API:

type Actor = {
  id: string;
  canRenameProject: boolean;
};

type RenameInput = {
  projectId: string;
  name: string;
};

function validateRenameInput(value: unknown): RenameInput {
  if (typeof value ! "object" || value = null) {
    throw new Error("Ungültige Eingabe.");
  }

  const input = value as Record<string, unknown>;

  if (typeof input.projectId ! "string" || input.projectId.trim() = "") {
    throw new Error("Eine Projektkennung ist erforderlich.");
  }

  if (typeof input.name ! "string" || input.name.trim() = "") {
    throw new Error("Ein Projektname ist erforderlich.");
  }

  return {
    projectId: input.projectId.trim(),
    name: input.name.trim(),
  };
}

async function renameProject(
  actor: Actor,
  rawInput: unknown,
  projects: {
    rename(projectId: string, name: string): Promise<{ id: string; name: string }>;
  },
) {
  const input = validateRenameInput(rawInput);

  if (!actor.canRenameProject) {
    throw new Error("Für diese Änderung fehlt die Berechtigung.");
  }

  return projects.rename(input.projectId, input.name);
}

Das Beispiel prüft, dass die erwarteten Felder vorhanden und nicht leer sind, und führt eine einfache Berechtigungsentscheidung durch. Für eine reale Anwendung muss zusätzlich geklärt werden, ob die handelnde Person Zugriff auf genau dieses Projekt hat. Eine allgemeine Fähigkeit wie canRenameProject reicht nicht aus, wenn der Zugriff vom Mandanten, einer Teammitgliedschaft oder dem Objektbesitz abhängt. Diese Prüfung gehört serverseitig an die Stelle, die tatsächlich über die Datenänderung entscheidet.

Die UI sollte die fachliche Operation ebenfalls über eine kontrollierte Anwendungsschnittstelle auslösen, statt eine zweite, leicht abweichende Umbenennungslogik zu implementieren. Der Agent erhält dieselbe Operation über die in der Action-Dokumentation beschriebene Registrierung. So können beide Oberflächen denselben fachlichen Ablauf anstoßen, während Identität und Kontext je Aufruf korrekt übergeben werden. Die gemeinsame Action bedeutet nicht, dass UI und Agent dieselben Rechte haben müssen.

Für den Datenfluss sind drei Fragen entscheidend: Woher kommt die Identität? An welcher Stelle wird die Eingabe validiert? Welche Komponente darf die Änderung dauerhaft speichern? Halten Sie die Antworten im Code und in Tests fest. Eine Validierung nur im UI schützt nicht vor ungültigen Eingaben durch den Agenten; eine Berechtigungsprüfung nur in einem Agent-Prompt ist keine Zugriffskontrolle.

Dritter Schritt: Berechtigungen und gemeinsamen Status nachvollziehbar prüfen

Die Dokumentation zur Zugriffskontrolle sollte beim Entwurf der Action neben der Definition der Action gelesen werden. Ein Test, in dem ein berechtigter Benutzer erfolgreich eine Änderung ausführt, beweist nur diesen einzelnen Pfad. Er belegt weder, dass unberechtigte Aufrufe zuverlässig blockiert werden, noch dass Daten anderer Benutzer oder Mandanten geschützt sind.

Planen Sie die Prüfung als getrennte Fälle:

• Änderung über die UI: Eine berechtigte Person ändert einen Wert. Anschließend wird geprüft, ob die Oberfläche den gespeicherten Zustand anzeigt und ein erneutes Laden denselben Wert liefert.
• Abfrage durch den Agenten: Der Agent erhält denselben fachlichen Kontext und fragt den aktualisierten Wert ab. Die Antwort muss sich aus dem tatsächlich verfügbaren Zustand ergeben und darf keine veraltete lokale Kopie widerspiegeln.
• Änderung durch den Agenten: Der Agent fordert eine gültige Operation an. Danach werden gespeicherter Datensatz, UI-Anzeige und Rückmeldung an den Agenten miteinander verglichen.
• Verweigerte Operation: Ein Benutzer ohne erforderliche Berechtigung versucht dieselbe Änderung. Die Änderung muss ausbleiben; die Fehlermeldung darf keine vertraulichen Details preisgeben.
• Ungültige und veraltete Eingabe: Leere Pflichtfelder, unbekannte IDs und ein inzwischen geänderter Datensatz müssen zu einem kontrollierten Fehler führen, nicht zu einem stillen Erfolg.

Für jeden Fall sind mindestens Ergebnis, Benutzerkontext und Fehlerweg zu protokollieren. Prüfen Sie außerdem, ob Wiederholungen einer Anfrage doppelte Nebenwirkungen auslösen können. Ob eine Operation wiederholbar, idempotent oder transaktional sein muss, hängt vom jeweiligen Geschäftsfall ab; die gemeinsame Action nimmt diese Entscheidung nicht ab.

Erfahrung aus der Architekturprüfung: Ein sichtbarer UI-Fehler und eine verweigerte Agent-Antwort sind nicht automatisch derselbe Sicherheitsfall. Die serverseitige Berechtigungsentscheidung muss auch dann greifen, wenn ein Aufruf die Oberfläche umgeht.

Vierter Schritt: Datenbank und Agent-Funktionen anbinden

Bevor eine Action produktive Daten verändert, muss klar sein, wie Agent-Native Anwendungsdaten und Agent-Konversationen behandelt. Die offizielle Dokumentation zu Datenbank und Synchronisierung ist dafür der Ausgangspunkt. Sie sollten dort prüfen, welche Datenmodelle das Framework selbst verwaltet, welche Daten aus der Anwendung stammen und welche Synchronisierungsannahmen gelten. Verwechseln Sie Gesprächsverlauf, fachlichen Datensatz und aktuellen UI-Zustand nicht: Sie können unterschiedlichen Lebenszyklen und Zugriffsregeln unterliegen.

In der Entwicklung empfiehlt sich zunächst ein harmloser Datensatz, den sich über UI und Agent lesen und verändern lässt. Erst wenn beide Pfade denselben persistenten Zustand anzeigen, sollte die Action auf fachlich relevante Daten erweitert werden. Dabei sind Schemaänderungen, Datenbankverbindungen, Fehler bei nicht erreichbaren Speichern und die Behandlung von Migrationen zu berücksichtigen. Welche Datenbank oder Infrastruktur unterstützt wird, muss aus der aktuellen Dokumentation hervorgehen; aus einem TypeScript-Beispiel lässt sich keine pauschale Anbieterkompatibilität ableiten.

Für ein externes Modell oder ein Werkzeug gilt dieselbe Vorsicht. Prüfen Sie zunächst, welche Integrationspunkte die offizielle Dokumentation ausdrücklich beschreibt. Danach testen Sie die Verbindung in einer isolierten Umgebung, verwalten Zugangsdaten über die dokumentierte Konfiguration und kontrollieren, welche Nutzdaten an den externen Dienst übermittelt werden. Die Unterstützung eines beliebigen Modellanbieters oder Tools sollte nicht vorausgesetzt werden, wenn sie nicht ausdrücklich belegt ist. Für personenbezogene Daten sind zusätzlich Zweck, Aufbewahrung, Zugriff und die Anforderungen der DSGVO zu klären.

Fünfter Schritt: Deployment und laufenden Betrieb vorbereiten

Die Anleitung zur Bereitstellung einer einzelnen Anwendung und die allgemeine Deployment-Dokumentation geben den Rahmen für unterstützte Hosts und Anforderungen vor. Prüfen Sie vor einer Host-Auswahl, ob die Anwendung dort mit ihren Laufzeit-, Datenbank- und Netzwerkabhängigkeiten betrieben werden kann. Ein erfolgreicher Entwicklungsserver ist kein Beleg dafür, dass derselbe Prozess für einen dauerhaft laufenden Dienst geeignet ist.

Vor der Veröffentlichung sollten diese Punkte abgehakt werden:

• [ ] Die lokale Laufzeit, der Paketmanager und die Abhängigkeiten entsprechen den aktuellen Projektanforderungen.
• [ ] Ein frischer Checkout kann mit dokumentierten Schritten installiert und gestartet werden.
• [ ] Für Produktionsbetrieb erforderliche Variablen sind anhand der offiziellen Umgebungsvariablen-Dokumentation identifiziert und sicher hinterlegt.
• [ ] Zugangsdaten stehen weder im Quellcode noch in öffentlich auslieferbaren Frontend-Dateien.
• [ ] Der gewählte Host passt zu Datenbank, Netzwerkzugriff und Anforderungen an dauerhaft laufende Prozesse.
• [ ] Persistente Daten bleiben bei einem Neustart erhalten; dieser Ablauf ist für die konkrete Hosting- und Datenbankkonfiguration geprüft.
• [ ] Protokolle enthalten ausreichend Kontext für Fehlersuche, vermeiden aber unnötige Geheimnisse und personenbezogene Daten.
• [ ] UI- und Agent-Aufrufe werden mit erlaubten, verweigerten und fehlerhaften Eingaben getestet.
• [ ] Ein Rückweg für fehlgeschlagene Releases und eine Zuständigkeit für Wartung sind festgelegt.

Die Dokumentation zur Deployment-Umgebung und ihren Variablen sollte nicht durch pauschale Umgebungsvariablenlisten aus fremden Vorlagen ersetzt werden. Übernehmen Sie nur Variablen, die für die konkrete Anwendung und die aktuelle Framework-Version dokumentiert sind. Für die Wartung zählen außerdem Aktualisierungen der Abhängigkeiten, Änderungen an Action-Schnittstellen und die Überprüfung von Berechtigungsregeln nach Schemaänderungen.

Ein sinnvoller Übergang in den Betrieb ist ein begrenzter Pilot: zunächst mit Testdaten und kontrolliertem Benutzerkreis, dann mit ausgewählten Geschäftsaktionen und dokumentierten Fehlerfällen. Erst wenn Logs, Datenpersistenz, Berechtigungen und Wiederanlaufverhalten geprüft sind, sollte die Anwendung auf weitere Abläufe ausgeweitet werden. Die offiziellen Unterlagen beschreiben den Rahmen; sie ersetzen keinen Test der eigenen Datenbank, des eigenen Hosts und des eigenen Sicherheitsmodells.

Welche Entwicklungsumgebung passt zum nächsten Schritt?

Vergleichen Sie die Optionen anhand der tatsächlichen Arbeitslast, nicht anhand einer pauschalen Leistungsbehauptung. Ein lokaler Rechner ist für ein kleines Projekt oft die einfachste Wahl, solange alle Entwickler dieselbe Laufzeit und dieselben Abhängigkeiten reproduzieren können. Eine gemietete Mac-Umgebung kann dagegen interessant sein, wenn ein Team eine separate, zugängliche Entwicklungsumgebung benötigt oder Tests auf macOS Teil des Arbeitsablaufs sind. Ob sie für Agent-Native passt, hängt von der benötigten Datenbank, den Laufzeitprozessen, dem Speicherbedarf und den Zugriffsregeln ab.

Ein Mac ist nicht automatisch die richtige Wahl, wenn ein dauerhaft hoch ausgelasteter Dienst, spezielle physische Schnittstellen oder ein bestimmter Linux-Host erforderlich sind. Dann sind ein eigener Rechner oder eine passende Serverumgebung möglicherweise sachgerechter. Bei kurzfristigen Tests und einem zeitlich begrenzten Pilotprojekt vermeidet eine Mietumgebung dagegen unter Umständen, sofort eigene Hardware zu beschaffen und dauerhaft zu betreiben. Die Kosten und Anforderungen sind vor der Auswahl anhand des jeweiligen Angebots und der Projektarchitektur zu prüfen.

Nach dem lokalen Start und dem ersten erfolgreichen Test gemeinsamer Actions kann eine separate Remote-Umgebung den nächsten Schritt erleichtern, sofern sie zu Datenbank, Laufzeit und kontinuierlichem Betrieb passt. Wenn dafür ein Mac benötigt wird, kann eine Mac-mini-Umgebung zur Miete geprüft werden; für Fragen zu Zugang und Nutzung steht außerdem das deutschsprachige Hilfezentrum bereit. Agent-Native sollte jedoch erst dann auf dieser Umgebung ausgebaut werden, wenn der offizielle Deployment-Rahmen und die projektspezifischen Abhängigkeiten dazu passen.

Weiterlesen

• Agent-Frameworks nach Orchestrierung, Zustandskontrolle und Einsatzzweck vergleichen
• Function Calling verstehen: Tool-Schemas, Runtime und sichere Seiteneffekte
• Praktischer Tool-Loop für APIs und Datenbanken mit Allowlist und Rechteprüfung