Dokumentation

AI Connect/Get started/Installation

Installation

Frag die KI über Vinkius

Fügen Sie @vinkius/connect zu einer Server-Runtime hinzu, konfigurieren Sie die Anwendungs-Zugangsdaten und prüfen Sie die API-Verbindung.

Installieren Sie das Paket in Ihrem Backend und erstellen Sie eine wiederverwendbare Vinkius-Instanz. Der Client speichert Konfiguration auf Anwendungsebene, keinen benutzerspezifischen Zustand, daher kann dieselbe Instanz Anfragen vieler Benutzer bedienen.

Voraussetzungen

  • Node.js 18 oder höher, oder eine andere Server-Runtime, die fetch bereitstellt (Node 18+, Bun, Deno und Edge-Runtimes)
  • Eine Vinkius App ID, die mit vk_app_ beginnt
  • Ein Vinkius Application Key, der mit vk_app_sk_ beginnt

Ihre API-Zugangsdaten abrufen

Vinkius Connect authentifiziert sich mit zwei Werten aus einer Vinkius Cloud Application:

WertPräfixWas es ist
appIdvk_app_...Die öffentliche ID der Application, die Ihren Tenant identifiziert
apiKeyvk_app_sk_...Ein Application Key: das Secret, mit dem Ihr Backend im Namen seiner Benutzer handelt

So erstellen Sie sie im Dashboard von Vinkius Cloud:

  1. Öffnen Sie Build AI Apps (/ai-agents) und klicken Sie auf New AI Application. Geben Sie ihr einen Namen (zum Beispiel Acme Copilot) und erstellen Sie sie.
  2. Öffnen Sie die Anwendung. Ihre App ID (vk_app_...) wird unter dem App-Namen und in der Seiten-URL angezeigt. Kopieren Sie sie in appId.
  3. Wechseln Sie zum Tab App Keys und klicken Sie auf New Key. Wählen Sie die Berechtigungen, die Ihr Backend benötigt, und klicken Sie dann auf Create Key.
  4. Der Application Key (vk_app_sk_...) wird einmalig in einem Dialog "Copy this key now" angezeigt. Kopieren Sie ihn in apiKey. Er kann danach nicht mehr abgerufen werden.

Sie können einen Schlüssel jederzeit im selben Tab App Keys rotieren oder widerrufen. Rotieren macht den alten Schlüssel sofort ungültig und zeigt den neuen einmalig an.

Halten Sie vk_app_sk_... ausschließlich serverseitig: in einer Umgebungsvariablen oder Ihrem Secrets-Manager. Senden Sie ihn nie an einen Browser, eine mobile App oder einen anderen Client, den der Benutzer kontrolliert.

Paket installieren

bash
npm install @vinkius/connect

Äquivalente Befehle sind pnpm add @vinkius/connect, yarn add @vinkius/connect und bun add @vinkius/connect. Das Paket wird als duales ESM + CommonJS mit gebündelten TypeScript-Typen ausgeliefert und hat keine Laufzeitabhängigkeiten.

Umgebungsvariablen des Servers konfigurieren

bash
VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Ein serverseitiges Modul erstellen

typescript
// lib/vinkius.ts — import this module only from server code
import { Vinkius } from '@vinkius/connect';

function required(name: 'VINKIUS_APP_ID' | 'VINKIUS_APP_KEY'): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export const vinkius = new Vinkius({
  appId: required('VINKIUS_APP_ID'),
  apiKey: required('VINKIUS_APP_KEY'),
});

Der Konstruktor prüft die Präfixe von App ID und Schlüssel, parst baseUrl, wenn angegeben, und verlangt eine fetch-Implementierung. Er sendet keine Anfrage. Er validiert zur Laufzeit nicht den Wertebereich jeder optionalen Zahl oder jedes Callbacks; halten Sie daher timeoutMs, maxRetries, Hooks und benutzerdefinierte Namensfunktionen unter der Kontrolle Ihrer Anwendung.

Wenn Ihre Runtime kein globales fetch hat, übergeben Sie eine kompatible Implementierung:

typescript
const vinkius = new Vinkius({
  appId,
  apiKey,
  fetch: customFetch,
});

Client-Optionen

typescript
new Vinkius({
  appId: 'vk_app_...',
  apiKey: 'vk_app_sk_...',
  baseUrl: 'https://api.vinkius.com', // default
  timeoutMs: 30_000, // default
  maxRetries: 2, // default (idempotent requests only)
  fetch: globalThis.fetch, // override for tests/edge
  userAgent: 'acme-ai/1.0', // appended to the default User-Agent
  namespaceCapability: (connector, name) => `${connector}__${name}`, // default
  hooks: {
    onRequest: ({ method, url }) => {}, // headers/body are redacted
    onResponse: ({ status, requestId }) => {},
  },
});

Zugangsdaten mit einer Anfrage prüfen

Eine Prüfung, die nur einen Handle erstellt, kontaktiert die API nicht. Nutzen Sie eine Katalog-Lektüre als echten Smoke-Test:

typescript
import { VinkiusError } from '@vinkius/connect';
import { vinkius } from './lib/vinkius';

async function checkVinkiusConnection(): Promise<void> {
  try {
    const page = await vinkius.catalog.list({ page: 1 });
    console.log(`Vinkius API reachable; received ${page.data.length} connectors`);
  } catch (error: unknown) {
    if (error instanceof VinkiusError) {
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
      });
    }
    throw error;
  }
}

await checkVinkiusConnection();

Diese Prüfung bestätigt, dass die Runtime die API erreichen kann und dass die Anwendungs-Zugangsdaten akzeptiert werden. Ein lokaler ConfigError tritt vor jeder Anfrage auf; AuthError steht für eine HTTP-Antwort 401 oder 403.

Einen Benutzer-Handle erstellen

typescript
const user = vinkius.user('alice_123');

user() sendet keine Anfrage. Die ID muss der stabile Benutzerbezeichner Ihrer Anwendung sein: 1 bis 255 Zeichen, darf nicht mit vk_app_user_ beginnen und darf keine Leerzeichen, Schrägstriche oder umgekehrten Schrägstriche enthalten.

user.ensure(metadata) ist optional. Rufen Sie es auf, wenn Sie ein explizites API-Upsert benötigen oder nicht sensible Metadaten anhängen wollen, nicht nur, um einen Handle zu erhalten.

Nächste Schritte