SDK einrichten und aufrufen

Diese Seite richtet sich an Entwickler. Sie beschreibt, wie das Paket @ai-systems-manager/sdk in eine Anwendung eingebunden und ein freigegebenes AI-Feature aus dem Code heraus aufgerufen wird. Technisches Vokabular (Paket, Repository, Import, Promise) ist hier ausdrücklich erlaubt. Wer zuerst wissen will, was das SDK grundsätzlich tut, liest SDK — Überblick.

Paket installieren

Das SDK ist das Paket @ai-systems-manager/sdk. Installiere es im Anwendungs-Repository:

pnpm add @ai-systems-manager/sdk

Voraussetzungen:

• Node.js >= 22.12.0
• pnpm >= 10.33

Hinweis

Das Paket ist noch nicht auf npmjs.org veröffentlicht; das öffentliche Publishing kommt später. V1 zieht die zugehörigen Schemas über GitHub Packages. Dafür wird ein klassischer Personal Access Token (PAT) mit dem Scope read:packages benötigt, abgelegt in ~/.npmrc.

Umgebungsvariablen setzen

Der Client braucht zwei Werte. Beide werden über Umgebungsvariablen übergeben, damit weder Adresse noch Token im Code stehen:

Variable	Inhalt
ASM_BASE_URL	Adresse der Plattform — eine absolute https://-URL.
ASM_FEATURE_TOKEN	Das von der Plattform gemintete Feature-Token, mit dem sich das SDK gegenüber der Plattform authentifiziert.

ASM_BASE_URL=https://asm.example.com
ASM_FEATURE_TOKEN=<Feature-Token>

Woher das Feature-Token kommt und wie es erzeugt wird, erklärt Master-Tokens und Feature-Tokens.

Achtung

Das Feature-Token ist ein Geheimnis. Es gehört in die Umgebungs- oder Secret-Verwaltung, nicht in den Quellcode.

Client erstellen

Der Client wird einmal erzeugt und für alle weiteren Aufrufe wiederverwendet. createAsmClient nimmt die Plattform-Adresse (baseUrl) und das Feature-Token (token) entgegen. Das Token stammt üblicherweise aus einer Umgebungsvariable:

import { createAsmClient } from '@ai-systems-manager/sdk'

const asm = createAsmClient({
  baseUrl: process.env.ASM_BASE_URL!,
  token: process.env.ASM_FEATURE_TOKEN!,
})

Die Erzeugung löst keinen Netzaufruf aus.

Achtung

Das in der App erzeugte Start-Snippet (Publish-Dialog beziehungsweise Tab Developer) nutzt aktuell den Platzhalter-Feldnamen serviceToken. Das ausgelieferte SDK-Konfigfeld heißt jedoch token. Beim Übernehmen des Snippets serviceToken durch token ersetzen.

Feature aufrufen

asm.invoke ruft ein Feature über seine ID auf und übergibt den Eingabewert. Der Typ-Parameter (OutputType) bestimmt den statischen Typ des Ergebnisses und entspricht dem Output-Schema des aktiven Contracts. Der eigentliche Wert wird über das Feld data gelesen:

const result = await asm.invoke<OutputType>('feat_0123456789ABCDEFGHJKMNPQRS', input)

console.log(result.data) // result.data ist vom Typ OutputType

Die featureId muss dem Format feat_ gefolgt von einer 26-Zeichen-ULID entsprechen; andernfalls wirft das SDK einen AsmError mit code VALIDATION_ERROR. input ist ein beliebiger Wert, meist ein Objekt.

Der erste Aufruf eines Features lädt den aktiven Contract von der Plattform und legt ihn im Cache ab (contractTtlMs, Default 5 Minuten; staleMaxMs, Default 24 Stunden). Wiederholte Aufrufe innerhalb der Cache-Gültigkeit lösen keinen erneuten Abruf aus. Außerdem führt das SDK einmalig einen Kompatibilitäts-Check der SDK-Version gegen die Plattform aus. Die eigentliche Inferenz läuft direkt gegen den im Contract hinterlegten Provider — die Plattform sieht die Inferenz-Inhalte nicht.

Wichtige Konfig-Optionen

createAsmClient akzeptiert neben baseUrl und token weitere optionale Felder:

Option	Default	Zweck
contractTtlMs	5 Minuten	Wie lange ein gefetchter Contract aus dem Cache bedient wird, bevor neu geladen wird.
staleMaxMs	24 Stunden	Oberes Alter, bis zu dem ein zwischengespeicherter Contract überhaupt noch genutzt werden darf.
invokeTimeoutMs	30 Sekunden	Harte Obergrenze pro Provider-Aufruf.
failoverDeadlineMs	5 Sekunden	Frist, nach der vom primären Provider auf den nächsten gewechselt wird. Siehe Routing und Failover.
schemaRetryBudget	3	Wie oft derselbe Provider bei einer Schema-Verletzung erneut versucht wird (Maximum 10; 0 schaltet ab).
otel	—	OpenTelemetry-Anbindung über eigenen tracer oder otlpUrl. Siehe Observability.
bufferDir	—	Verzeichnis für den Disk-Persist der Usage-Events. Siehe Observability.
bufferMaxSize	1000	Maximale Größe der In-Memory-FIFO für Usage-Events.

Validierung und Fehler beim Erstellen

baseUrl und token sind Pflichtfelder. Fehlt eines oder ist es leer, wirft createAsmClient einen AsmError mit code VALIDATION_ERROR. Dasselbe gilt, wenn baseUrl keine absolute http://- oder https://-URL ist.

Zeigt baseUrl per http:// auf einen nicht-lokalen Host, warnt das SDK, dass die Zugangsdaten im Klartext übertragen werden — in Produktion https:// verwenden. Eine vollständige Übersicht der Fehlercodes steht unter Fehlerbehandlung.

Weiter

• Was das SDK insgesamt übernimmt, fasst SDK — Überblick zusammen.
• Woher das Feature-Token kommt, erklärt Master-Tokens und Feature-Tokens.
• Wie eine Version veröffentlicht wird, steht unter Ein Feature veröffentlichen.