Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

HTTP- und OpenAPI-Kompatibilität

Status: Aktiv Umfang: aktueller Stand Zuletzt geprüft: 2026-09-02 Verantwortlich: AX-Code-SDK

AX Code hat zwei Integrationspfade:

Der JSR-Paketname unten ist releasebereit, hat aber noch keine erste öffentliche Version erhalten.

Verwenden Sie @defai-digital/ax-code-sdk für die eigene App-Integration in TypeScript und JavaScript.
Verwenden Sie @defai-digital/ax-code-sdk/headless oder @defai-digital/ax-code-sdk/grpc für eigene App- und Desktop-GUI-Arbeit.
Verwenden Sie ax-code serve plus den OpenAPI-Vertrag, wenn eine andere Sprache oder eine Kompatibilitätsprozessgrenze nötig ist.
Verwenden Sie Nativer SDK-Transport für eigene Desktop-GUI-Arbeit, bei der AX Code beide Enden des Transports besitzt.

Der Pfad HTTP/OpenAPI ist Infrastruktur für Kompatibilität und erzeugte Clients. Er lässt Python, Go, Java, Rust und andere Clients dieselbe Server-API aufrufen, ohne dass AX Code ein volles offizielles Paket für jede Sprache pflegt. Er sollte nicht als bevorzugte privilegierte Brücke in einer eigenen Desktop-GUI behandelt werden, wenn der Vertrag gRPC oder nativ verfügbar ist, und er wird nicht mehr als Teilpfade des eigenen JavaScript-SDK bereitgestellt.

Einen Pfad wählen

Bedarf	Empfohlener Pfad	Warum
TypeScript oder JavaScript im selben Prozess	Adapter `createAgent()` des Quell-Workspace	Nur verfügbar, wenn das private Laufzeitquellpaket von AX Code absichtlich auflösbar ist
Eigene Desktop- oder native GUI	`@defai-digital/ax-code-sdk/grpc`	Engerer Headless-Vertrag, Server-Streaming, freundlich für Metadaten und Fristen und weniger WebView-Exposition
TypeScript oder JavaScript mit lokalem Backend	`@defai-digital/ax-code-sdk/headless`	Hält Lebenszyklus und Ereignisprojektion typisiert, ohne die volle HTTP-SDK-Oberfläche freizugeben
Python, Go, Java, Rust oder eine andere Laufzeit	Einen Client aus `packages/sdk/openapi.json` erzeugen	Verwendet den HTTP-Vertrag wieder, ohne Pflege eigener Pakete für jede Sprache
CI, Automatisierung oder einmalige Skripte	HTTP-Aufrufe gegen `ax-code serve`	Einfaches Bereitstellungsmodell und leichte Prozessisolation

Was heute offiziell ist

@defai-digital/ax-code-sdk ist das eigene SDK für TypeScript und JavaScript. Seine öffentlichen App-Grenzen sind headless und grpc.
@defai-digital/ax-code-sdk/grpc ist die eigene optionale Fassade für den Headless-Transport von Desktop und nativ.
@defai-digital/ax-code-sdk/headless ist das eigene SDK für Lebenszyklus und Ereignisse in TypeScript und JavaScript an lokalen Backend-Prozessgrenzen.
packages/sdk/openapi.json ist der OpenAPI-Schnappschuss für erzeugte HTTP-Clients.
Erzeugte Clients außerhalb von JavaScript werden als Integrationen über HTTP unterstützt, sind aber keine veröffentlichten eigenen Pakete, solange kein Paketverantwortlicher, Tests und ein Release-Ablauf existieren.

Grundlegender HTTP-Ablauf

Starten Sie den Server:

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

Die Lebenszyklus-Hilfe @defai-digital/ax-code-sdk/headless erzeugt ein einmaliges Basic-Auth-Passwort und verdrahtet den zurückgegebenen Client automatisch mit dem passenden Header Authorization. Manuelle Nutzer von ax-code serve sollten AX_CODE_SERVER_PASSWORD ausdrücklich setzen und den entsprechenden Basic-Auth-Header senden. Live OpenAPI-Dokumentation unter /doc und alle Serverendpunkte sind nur Loopback.

SDK-verwaltete Backend-Hilfen lehnen Netzhostnamen wie 0.0.0.0 immer ab. Die ältere Option allowNetworkBind bleibt aus Quellkompatibilität, umgeht die Nur-lokal-Richtlinie aber nicht mehr. Desktop-GUI-Hüllen sollten @defai-digital/ax-code-sdk/grpc oder eine SDK-Grenze im Prozess bevorzugen.

HTTP-Laufzeithilfen sind keine öffentlichen Teilpfade des JavaScript-SDK mehr. Das Paket enthält weiterhin interne erzeugte Clients, weil @defai-digital/ax-code-sdk/headless, der gRPC-HTTP-Rückfall und älterer AX-Code-Laufzeitcode sie verwenden. Externe Integrationen sollten Headless, gRPC oder aus dem OpenAPI-Schnappschuss erzeugte Clients verwenden, statt HTTP-Laufzeitwerte aus @defai-digital/ax-code-sdk zu importieren.

Prüfen Sie die Servergesundheit:

curl http://127.0.0.1:4096/global/health

Erzeugen Sie Clients aus dem OpenAPI-Schnappschuss, nachdem Sie den Schnappschuss als JSON und OpenAPI validiert haben:

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

Leitplanken der Erzeugung

Behandeln Sie das OpenAPI-Dokument als sprachneutralen Vertrag. Pflegen Sie keine großen Hüllen um einzelne Routen von Hand, außer eine kleine ergonomische Schicht ist nötig.

Halten Sie die AX-Code-Version und die Version des erzeugten Clients gemeinsam fest. Wenn sich das Routenschema des Servers ändert, erzeugen Sie den Client neu und veröffentlichen Sie ihn mit einem klaren Kompatibilitätshinweis.

Halten Sie erzeugten Code von handgeschriebenen Hilfen getrennt. Erzeugte Dateien sollten leicht ersetzbar sein, während handgeschriebene Dateien nur Authentifizierung, Vorgaben, Wiederholungen und bequemere APIs höherer Ebene enthalten sollten.

Bewahren Sie das Verhalten der Dienstgrenze. Clients außerhalb von JavaScript verwenden den HTTP-Serverpfad und erhalten kein prozessinternes createAgent(), keine Ausführung eigener JavaScript-Tools und keine Hilfen @defai-digital/ax-code-sdk/testing.

Decken Sie die schwierigen Teile ab, bevor Sie einen erzeugten Client zum eigenen Status befördern:

Die OpenAPI-Validierung läuft in CI.
Ein Vertragstest startet ax-code serve und ruft repräsentative Routen auf.
Streaming- oder SSE-Verhalten wird getestet, wenn der Client Ereignis-APIs bereitstellt.
Header für die Verzeichniseingrenzung und das Authentifizierungsverhalten sind dokumentiert.
Veröffentlichung, Versionierung und Verantwortung sind ausdrücklich.

Das SDK-Paket enthält eine leichte lokale Sicherung für den aktuellen Schnappschuss:

pnpm run check:openapi

Der Befehl auf Paketebene ist auch verfügbar, wenn Sie im SDK-Paket arbeiten:

pnpm --dir packages/sdk/js run validate:openapi

Das prüft, dass packages/sdk/openapi.json parsebares JSON ist, OpenAPI 3.x erklärt und die Kernrouten enthält, die erzeugte Clients brauchen.