SDK - Überblick

Diese Seite richtet sich an Entwickler, die ein veröffentlichtes AI-Feature aus ihrem Code heraus aufrufen. Sie beschreibt keine Oberfläche, sondern eine Bibliothek. Technisches Vokabular (Paket, Repository, Import, Promise, Span) ist hier ausdrücklich erlaubt.

Was das SDK ist

In der Plattform werden Agent Contracts (die versionierten Definitionen eines AI-Features aus Prompt, Output-Schema, Tools, Provider-Konfiguration, Eval-Kriterien und Risikoklasse) zentral verwaltet, geprüft und freigegeben. Ausgeführt wird ein freigegebenes Feature aber nicht auf der Plattform, sondern lokal in der eigenen Umgebung - dort, wo die Anwendung ohnehin läuft und wo die Daten liegen. Das SDK ist die Bibliothek, die diese lokale Ausführung übernimmt.

Das Prinzip dahinter: Governance zentral, Execution dezentral. Die Plattform entscheidet, welche Version eines Contracts gilt. Das SDK holt sich diese freigegebene Definition und führt das Feature damit aus. Der Modell-Aufruf geht direkt vom SDK an den Provider; es gibt keinen Inferenz-Hop über die Plattform. Nur der Contract-Abruf und die Usage-Meldung gehen an die Plattform - die Inhalte des Aufrufs (Prompt, Eingabe, Ergebnis) sieht sie nicht.

Das SDK ist provider-agnostisch. Welcher Provider und welches Modell verwendet werden, steht im Contract, nicht im Anwendungscode. Unterstützt werden OpenAI, Anthropic, Google, xAI sowie OpenAI-kompatible bzw. self-hosted Provider. Ein Wechsel des Providers ist eine neue Version des Contracts, keine Code-Änderung.

Das Paket

Das SDK ist das Paket @ai-systems-manager/sdk. Es ist in TypeScript geschrieben und baut intern auf dem Vercel AI SDK 6 auf. Die Lizenz ist Apache-2.0. Status: V1 ist implementiert. Ein Java-SDK ist für später geplant.

Was das SDK übernimmt

Der Anwendungscode beschränkt sich auf Client-Erstellung und Aufruf. Alles Weitere erledigt das SDK:

Contract-Abruf und Caching. Das SDK lädt die aktive Contract-Version über die Plattform-API und hält sie in einem In-Memory-Cache mit Ablaufzeit (Standard fünf Minuten).
Schema-Validierung des Ergebnisses. Das Output-Schema des Contracts wird zu einem Laufzeit-Validator (Zod) kompiliert; das Modell-Ergebnis wird dagegen geprüft, bevor es zurückgegeben wird.
Multi-Provider-Routing, Failover und Phased-Rollout. Aus dem Contract kommen ein primärer Provider und eine Fallback-Kette; bei 5xx oder Zeitüberschreitung wird transparent umgeschaltet, und ein konfigurierter Traffic-Split wird deterministisch verteilt (Routing und Failover).
Multi-Modal-Eingaben. Binäre Felder im Input (Buffer, URL oder Objekt mit mimeType und data) erkennt das SDK und nutzt den Messages-Pfad des AI SDK (Routing und Failover).
OpenTelemetry-Instrumentierung und Usage-Meldung. Das SDK erzeugt Spans nach den GenAI Semantic Conventions und puffert Usage-Events, die es an die Plattform meldet (Observability).
Strukturierte Fehler. Fehler werden als AsmError mit stabilem code geworfen, sodass der Anwendungscode gezielt darauf reagieren kann (Fehlerbehandlung).

Das minimale Aufrufmuster

Beim Veröffentlichen einer Contract-Version liefert die Plattform ein passendes Start-Snippet. Der grundlegende Aufruf sieht so aus:

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

const client = createAsmClient({
  baseUrl: 'https://asm.example.com',
  token: process.env.ASM_FEATURE_TOKEN!,
})

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

// Das Ergebnis liegt im data-Feld:
const output = result.data

createAsmClient erzeugt den Client mit der Adresse der Plattform (baseUrl) und dem Feature-Token (token); beide kommen üblicherweise aus Umgebungsvariablen. client.invoke ruft ein Feature über seine ID auf (Format feat_ plus 26-Zeichen-ULID) und liefert ein Promise. Der Typ-Parameter (OutputType) bestimmt den statischen Typ des Ergebnisses und entspricht dem Output-Schema des Contracts. Der eigentliche Wert wird über result.data gelesen.

Public-API

Der öffentliche Umfang des Pakets ist klein:

Export	Zweck
`createAsmClient(config)`	Erzeugt einen `AsmClient`.
`AsmClient`	Der Client mit `version` (String) und `invoke(featureId, input, options?)`.
`AsmError`, `ASM_ERROR_CODES`	Fehlerklasse mit stabilem `code` und die Liste der Fehlercodes.
`SDK_VERSION`	Die installierte SDK-Version als String (gleich `client.version`).

Voraussetzungen und Installation

Node.js ≥ 22.12.0
pnpm ≥ 10.33

Das Paket ist noch nicht auf npmjs.org veröffentlicht; das öffentliche Publishing kommt später. V1 zieht die Schemas aus GitHub Packages, wofür ein klassischer PAT mit read:packages-Scope in ~/.npmrc nötig ist. Die Installation, das Setzen der Umgebungsvariablen und der erste Aufruf sind in SDK einrichten und aufrufen Schritt für Schritt beschrieben.

Bezug zur Plattform

Das SDK hängt an genau zwei Stellen an der Plattform:

Das Feature-Token für token wird zentral erzeugt und von einem Master-Token abgeleitet (Master-Tokens).
Das Start-Snippet mit baseUrl und featureId entsteht beim Veröffentlichen einer Contract-Version.