SDKs

Die CLI- und SDK-Pakete für angebundene Unternehmensservices.

Weldall veröffentlicht die npm-CLI sowie SDKs für TypeScript und Python. Die CLI läuft auf dem Gerät eines Mitarbeiters. Ein SDK läuft im angebundenen Service.

`@weldall/cli`

@weldall/cli installiert den Befehl weldall. Node.js 22.15 oder neuer ist erforderlich.

npm (empfohlen)

npm install --global @weldall/cli@latest
weldall --version

Experimentelle Standalone-Binaries

Standalone-Binaries benötigen kein Node.js, npm oder Bun. Unterstützt werden zunächst Linux x64, Windows x64 und macOS ARM64/x64. Die macOS-Binaries sind mit einem Developer-ID-Zertifikat signiert und von Apple notarisiert, Gatekeeper startet sie ohne Warnung. Die Linux- und Windows-Binaries sind noch nicht signiert; daran wird gearbeitet. Lade das passende Archiv aus den GitHub Releases.

# macOS und Linux
chmod +x ./weldall

Windows PowerShell: Unblock-File .\weldall.exe.

`@weldall/sdk`

@weldall/sdk prüft Requests, bevor ein Service Daten liest oder Änderungen ausführt. Es stellt eine Fetch-API und Adapter für Hono, Next.js und Astro bereit.

pnpm add @weldall/sdk

Erzeuge beim Start des Services eine Weldall-Instanz:

import { initWeldall } from "@weldall/sdk";

const weldall = initWeldall("https://weldall.example.com", {
  resource: "https://contracts.example.com/api",
  publicOrigin: "https://contracts.example.com",
  clientId: "weldall-cli-at-contracts",
  supportedScopes: ["contracts:read", "contracts:update"],
  signingKey,
  replayStore,
});

In einem Fetch-Handler prüft weldall.verify(request, { scopes: [...] }) den Request vor der Geschäftslogik. Die Framework-Adapter stellen dafür Middleware oder Handler-Wrapper bereit:

@weldall/sdk/hono
@weldall/sdk/next
@weldall/sdk/astro

Das SDK benötigt Node.js 22.15 oder neuer. Next.js-Routen müssen die Node.js-Runtime verwenden.

Einen Python-Service schützen

Verwende weldall-sdk für Services ab Python 3.11. Das SDK prüft Requests von Mitarbeitenden und Maschinen, bevor die Anwendung Daten verarbeitet. Es stellt außerdem die Protokollrouten bereit, die Weldall benötigt.

Installiere nur den Kern oder ergänze das Extra für dein Framework:

pip install weldall-sdk
pip install 'weldall-sdk[fastapi]'
pip install 'weldall-sdk[django]'

from weldall import in_memory
from weldall.adapters.fastapi import init_weldall

weldall = init_weldall(
    "https://weldall.example.com",
    {
        "resource": "https://contracts.example.com/api",
        "public_origin": "https://contracts.example.com",
        "client_id": "weldall-cli-at-contracts",
        "supported_scopes": ["contracts:read"],
        "signing_key": signing_key,
        "replay_store": in_memory(),
    },
)
weldall.register_routes(app)

register_routes() fügt der FastAPI-Anwendung die Weldall-Protokollrouten hinzu. Schütze die eigenen Routen mit require_auth() und lies die geprüfte Identität aus dem Request-State. Django-Projekte verwenden stattdessen die mitgelieferte Middleware, Views und URL-Patterns.

Die Python-SDK-Referenz beschreibt Maschinenzugriffe, veröffentlichte Skills, Signaturschlüssel, Replay-Schutz und die Checkliste für den Produktivbetrieb.

Skills aus einem Service veröffentlichen

Eine Resource kann ihre Agentenanweisungen selbst veröffentlichen. Ergänze dazu einen skills-Provider in derselben SDK-Konfiguration:

const weldall = initWeldall("https://weldall.example.com", {
  resource: "https://contracts.example.com/api",
  publicOrigin: "https://contracts.example.com",
  clientId: "weldall-cli-at-contracts",
  supportedScopes: ["contracts:read"],
  signingKey,
  replayStore,
  skills: {
    items: [
      {
        id: "list",
        title: "Verträge auflisten",
        requiredScopes: ["contracts:read"],
        visibility: "HIDDEN_IF_UNALLOWED",
        content:
          "# Verträge auflisten\n\nFühre `weldall request --scope contracts:read https://contracts.example.com/api/contracts` aus.",
      },
    ],
  },
});

Skill-IDs gelten lokal für die Resource. Hat die registrierte Resource den Key contracts, stellt Weldall diesen Skill als contracts.list bereit.

Wenn der Katalog aus einer Datenbank oder einer anderen lokalen Quelle kommt, verwende skills.load statt skills.items:

skills: {
  load: async () => loadPublishedSkills(),
}

Der Provider erhält keine Identität eines Mitarbeiters. Er muss für alle Aufrufer denselben Katalog liefern.

DEFAULT lässt einen Skill sichtbar und weist auf fehlende Scopes hin. HIDDEN_IF_UNALLOWED blendet ihn aus, solange dem Mitarbeiter ein benötigter Scope fehlt. Die Sichtbarkeit steuert nur die Discovery, nicht die Autorisierung: Die API-Route benötigt weiterhin eine eigene Schutzregel, und Skill-Anweisungen gewähren keinen Zugriff. Die Scopes müssen bereits in Weldall existieren; das gilt auch für geschützte System-Scopes. Unbekannte Scopes werden Nutzern nicht angezeigt und erscheinen als Warnung für Administratoren.

Der Hono-Adapter registriert die Katalogroute mit weldall.registerRoutes(app). Bei Fetch, Next.js und Astro muss weldall.handlers.skills unter /.well-known/weldall-skills erreichbar sein – neben den Handlern für OAuth-Metadaten, Token und JWKS.

Die TypeScript-Anleitung zeigt eine vollständige Hono-Einrichtung. Die Python-Anleitung beschreibt FastAPI und verweist auf das Django-Beispiel. Beide verlinken den SDK-Quellcode und die Beispielverzeichnisse auf GitHub. Hintergründe zu Schlüsseln, Replay-Schutz und Protokollen stehen unter Sicherheit.

How to: Service integrieren