Architektur

AI Connect bietet eine Fläche für Ihren Code und zwei Ebenen darunter. Sie schreiben gegen eine kurze Kette von Handles: Anwendung, Benutzer, Connector, Capability. Die Plattform betreibt eine Kontrollebene, die bereitstellt, wer was darf, und eine Ausführungsebene, eine MCP-Runtime, die jede Capability auflistet und ausführt. Sobald die Aufteilung klar ist, wird jedes Verhalten des SDK vorhersehbar.

Die Kette: Anwendung, Benutzer, Connector, Capability

const user = vinkius.user('alice_123');
const github = user.connector('github');
const capabilities = await user.capabilities();

Jedes Objekt ergänzt nur den Geltungsbereich. Der Vinkius-Client trägt die Identität Ihrer Anwendung: der Application Key ist das einzige Geheimnis, das Sie verwalten, und er kann ausschließlich für die eigene App handeln. user() bindet einen Ihrer Benutzer über die ID Ihres eigenen Authentifizierungssystems: es gibt keine Vinkius-Benutzer-ID aufzulösen, zu synchronisieren oder zu speichern; die Plattform adressiert alles über Ihre externalId. connector() bindet einen Connector, und eine Capability ist eine konkrete Aktion, die dieser Benutzer ausführen kann.

Handles zu erzeugen ist lokal und billig: nichts kontaktiert die Plattform, bis Sie eine Operation wie connect(), status(), schema(), capabilities() oder execute() aufrufen. Eine frische Kette pro Anfrage hält den Geltungsbereich Ihres Codes offensichtlich.

Zwei Ebenen: Kontrolle und Ausführung

Bereitstellung und Zustand leben auf der Kontrollebene:

await user.ensure({ plan: 'pro' });           // provision the user
await github.credentials.set({ TOKEN: 'x' }); // write credentials
await github.status();                        // derived readiness
await vinkius.catalog.list();                 // discover connectors

Die Ausführung lebt in einer eigenen Ebene. Wenn connect() die Verbindung des Benutzers anlegt (oder findet), stellt AI Connect genau ein Daten-Token dafür aus, eine vk_live_*-Credentiale, und liefert einmalig die Runtime-URL, die es einbettet. Jede später aus dieser Verbindung gebaute Capability trägt ihre Runtime vorgebunden, Ihre Aufrufstellen übergeben daher niemals Routing-Koordinaten: keine Tokens, keine Verbindungs-IDs, keine Endpunkte.

Das Token ist das Herz des Designs. Tools aufzulisten ist kostenlos; jede Ausführung wird gegen es gemessen, sodass Ausgaben, Traffic und Fehler pro Benutzerverbindung zuordenbar sind. Es ist auch ein Kill Switch: deaktiviert oder löscht der Benutzer die Verbindung, stirbt das Token mit ihr, und Aufrufe schlagen fehl, statt durchzugleiten. Das SDK stellt ein widerrufenes Token niemals still neu aus; eine widerrufene Verbindung kann nicht leise wieder Gebühren verursachen.

Jede Verbindung ist ein MCP-Server

Die Runtime spricht Standard-MCP. Das macht jede verbundene Person zu einem echten MCP-Endpunkt: Dieselbe Fläche, über die das SDK Capabilities auflistet und aufruft, verbinden beliebige MCP-fähige Clients, Claude Desktop, Cursor, Ihre anderen Agenten, direkt an. Speichern Sie die von connect() zurückgegebene URL, wenn Sie diesen Endpunkt einem anderen Client geben möchten.

Dieselbe Portabilität durchzieht die Modell-Ebene. Neun abhängigkeitsfreie Adapter-Subpfade, von OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex und Cloudflare Workers AI bis zu einer neutralen JSON-Schema-Ausgabe, wandeln ein CapabilitySet in das Tool-Format Ihres Anbieters, mit Factory-Injection statt Peer Dependencies. Wechseln Sie Modell, Client oder Framework: Ihre Capabilities bleiben Ihre.

Capabilities tragen ihren Besitzer und ihre Route

Wenn die Plattform Capabilities auflistet, kennt jede bereits ihren Connector, die Verbindung dieses Benutzers, ihren Anzeigenamen und ihr Eingabeschema:

const capability = capabilities.findCapability('github__create_issue');

console.log(capability?.rawName);      // create_issue
console.log(capability?.connector);    // github
console.log(capability?.inputSchema);  // JSON Schema of the arguments

Der Aufruf von execute() auf diesem Objekt führt die Aktion im GitHub dieses Benutzers mit seinen Zugangsdaten aus; Sie übergeben niemals ein Token, eine Verbindungs-ID oder einen Endpunkt. Anzeigenamen sind pro Connector namespace-kodiert (github__create_issue) und über namespaceCapability anpassbar. Ein CapabilitySet ist ein echtes Array mit ergonomischen Helfern (findCapability, forConnector), es komponiert sich also mit allem, was Sie bereits mit Arrays tun. Und da eine Capability an den Benutzer gebunden ist, der sie erzeugt hat, verwenden Sie Capability-Objekte eines Benutzers nie für die Anfrage eines anderen.

Aggregation ist fehlertolerant by design

user.capabilities() ist kein einzelner API-Aufruf. Die Plattform listet die Tools jeder Verbindung in deren eigener Runtime, die Aggregation ist also ein begrenzter Fan-out über die bereiten Verbindungen des Benutzers, zusammengeführt in eine Menge. Das Design schützt in beide Richtungen: ein instabiler Connector versenkt nicht das ganze Ergebnis (Teilfehler werden übersprungen und über onConnectorError sichtbar, und nur wenn alle Verbindungen scheitern, wirft der Aufruf), und viele Connectoren öffnen nicht unbegrenzt gleichzeitige Sockets.

Begrenzen Sie günstig mit include/exclude, und für einen einzelnen Connector gehen Sie direkt mit user.connector(slug).capabilities(): das überspringt den vollständigen Fan-out.

Zugangsdaten sind nur schreibbar, Status wird abgeleitet

Sie können Zugangsdaten setzen, abfragen, was ein Connector verlangt (credentials.schema()) und sehen, welche Felder konfiguriert sind (credentials.status()), aber Geheimwerte kommen niemals zurück. Sie leben im Tresor der Plattform, und das Modell erhält nie rohe Geheimnisse. Die Einsatzbereitschaft gehört zum Backend und erscheint in genau vier Zuständen: not_connected, needs_credentials, ready, disabled. Nur bereite Connectoren liefern Capabilities, sodass eine halb konfigurierte Verbindung nie ein kaputtes Tool in die Schleife Ihres Agenten leakt.

Was die Plattform bei jedem Aufruf tut

• Ausführung wird normalisiert. Egal welches Protokoll der Connector unter der Haube spricht, REST, GraphQL oder Streaming, execute() liefert ein einziges strukturiertes Ergebnis: { content, isError }.
• Sichere Wiederholungen passieren automatisch. Vorübergehende Instabilität wird bei idempotenten Operationen automatisch wiederholt; für eine Aktion, die höchstens einmal laufen darf, übergeben Sie einen stabilen, nicht leeren idempotencyKey an execute().
• Governance ist eingebaut. Jede Ausführung wird gemessen und von der AI-Governance-Fläche der Konsole beobachtet: Traffic, Ausgaben, Fehler und Sicherheitslage pro Connector und pro Benutzer.

Zwei Fehlerkanäle, eine Regel

execute() trennt die Aktion, die lief und ein Problem meldete, von dem Aufruf, der nie abschloss:

const result = await capability.execute(args, { idempotencyKey });

if (result.isError) {
  // Die Capability lief und meldete Fehler: geben Sie sie an den Agenten zurück.
}

Plattform-Probleme werfen eine VinkiusError-Unterklasse: AuthError, ConnectorNotConnectedError, RateLimitError, QuotaError, ValidationError und Verwandte, jede mit status, code und requestId. Geben Sie isError-Ergebnisse an Ihr Modell zurück, damit es sich erholt; fangen Sie geworfene Fehler, um zu entscheiden, was Ihre Anwendung tut. Vermischen Sie beide, verbergen Sie, ob die Aktion wirklich die reale Welt erreichte.

Zustand ist lokal zum Handle

Ein Handle löst die Verbindung des Benutzers und deren Runtime bei der ersten Operation auf, die sie braucht, und verwendet beides für den Rest seines Lebens: wiederholte Aufrufe auf demselben Handle überspringen die Auflösung. Es gibt keinen globalen Cache. Ein brandneues Handle löst erneut auf, disconnect() löscht, was das Handle merkte, und ResolverCache ist ein optionales Hilfsmittel, das Sie in Ihre eigene Memoisierung einbinden können. Deshalb ist das sichere Muster eine frische Handle-Kette pro Anfrage; sie innerhalb derselben Anfrage wiederzuverwenden, ist ein reiner Gewinn.

Nächste Schritte

• Inspect capability lookup and filtering
• Understand both error channels
• Keep the application key behind a server boundary