Capabilities und Ausführung

Eine Capability ist eine Aktion, die für eine bestimmte Benutzer-Verbindung zurückgegeben wird. Sie kombiniert die modellseitige Beschreibung und das JSON Schema mit der Verbindungsroute, die zur Ausführung der Aktion benötigt wird.

Verwenden Sie die aggregierte Benutzer-Methode, wenn ein Assistent über mehrere Connectors hinweg arbeiten kann, oder einen Connector-Handle, wenn nur ein verbundenes Konto Aktionen beitragen soll.

Capabilities für einen Benutzer aggregieren

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

Dabei wird eine Anfrage an den Capability-Endpunkt des Benutzers gestellt und jedes zurückgegebene Element in eine ausführbare Capability umgewandelt. Der Endpunkt bestimmt, welche Verbindungen Aktionen beitragen; der Client führt keine zweite Bereitschaftsprüfung durch.

Ein leerer CapabilitySet ist gültig. Er kann bedeuten, dass der Benutzer keine verfügbaren Aktionen hat, dass keine Verbindung dem angeforderten Filter entspricht oder dass der Dienst keine zurückgegeben hat. Behandeln Sie diesen Fall explizit:

if (capabilities.length === 0) {
  return { tools: [], message: 'Connect an account before requesting this action.' };
}

Connector-Umfang einschränken

const selected = await user.capabilities({
  include: ['github', 'slack'],
  exclude: ['slack'],
});

include wird als Connector-Filter an den Server gesendet. exclude wird vom SDK nach der Antwort angewendet. In diesem Beispiel fordert die Anfrage GitHub und Slack an und entfernt Slack anschließend lokal.

Verwenden Sie für einen einzelnen Connector dessen Handle:

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

Der Connector-bezogene Lookup erfordert eine bestehende Verbindung und listet möglicherweise zuerst die Verbindungen auf, um deren ID zu ermitteln. Er löst ConnectorNotConnectedError aus, wenn keine Übereinstimmung existiert.

Den Capability-Vertrag prüfen

for (const capability of capabilities) {
  console.log({
    name: capability.name,
    rawName: capability.rawName,
    connector: capability.connector,
    connectionId: capability.connectionId,
    title: capability.title,
    description: capability.description,
    inputSchema: capability.inputSchema,
  });
}

Standardmäßig ist name gleich ${connector}__${rawName}, zum Beispiel github__create_issue. rawName ist der Aktionsname des Connectors und wird genau so vom SDK zur Ausführung gesendet. Sie können die Funktion für den Anzeigenamen im Client-Konstruktor durch namespaceCapability ersetzen, aber Adapter validieren keine anbieterspezifischen Namensregeln.

Auswählen, ohne Verfügbarkeit anzunehmen

CapabilitySet erweitert Array<Capability> um zwei Hilfsfunktionen:

const githubOnly = capabilities.forConnector('github');
const createIssue = githubOnly.findCapability('github__create_issue');

forConnector() vergleicht Connector-Slugs exakt. findCapability() akzeptiert einen Anzeigenamen oder einen rohen Namen und gibt die erste Übereinstimmung zurück. Rohe Namen können kollidieren; zum Beispiel können zwei Connectors beide search bereitstellen. Bevorzugen Sie einen eindeutigen Anzeigenamen oder filtern Sie zuerst nach Connector.

Mit dem zurückgegebenen Schema ausführen

if (!createIssue) {
  throw new Error('The requested action is not available for this user');
}

const result = await createIssue.execute(
  { owner: 'acme', repo: 'product', title: 'Document retries' },
  {
    idempotencyKey: 'create-issue:operation-8042',
    signal: request.signal,
  },
);

const output = result.content.map((part) => part.text).join('\n');
if (result.isError) {
  console.error(output);
}

Die Argumente sind Record<string, unknown>, da Schemas zur Laufzeit ermittelt werden. Validieren oder erstellen Sie die Eingabe vor der Ausführung aus inputSchema, wenn Ihre Anwendung strengere Garantien benötigt.

Verwenden Sie für Seiteneffekte einen nicht leeren Schlüssel, der aus der logischen Operation abgeleitet ist. Verwenden Sie ihn nur erneut, wenn Sie dieselbe Operation wiederholen. Das SDK weist einen leeren Schlüssel nicht zurück; die Validierung in der Anwendung ist erforderlich. Ohne Schlüssel erhält die Capability-Ausführung genau einen Transportversuch.

Ergebnis- und Ausnahmepfade verstehen

execute() wird wie folgt aufgelöst:

interface CapabilityResult {
  content: Array<{ type: string; text: string }>;
  isError: boolean;
}

isError: true bedeutet, dass die Capability ein fehlgeschlagenes Aktionsergebnis zurückgegeben hat. HTTP-, Authentifizierungs-, Validierungs-, Rate-Limit-, Quota-, Timeout- und Netzwerkfehler lösen stattdessen normalerweise einen SDK-Fehler aus.

Dispatch-Helper von Adaptern und fabrikgebundene Funktionen akzeptieren keine ExecuteOptions. Wenn eine Operation Abbruch oder einen Idempotenzschlüssel benötigt, lösen Sie die Capability auf und rufen Sie execute() direkt auf.

Nur an der Modellgrenze konvertieren

Adapter behalten Anzeigenamen, Beschreibungen und Eingabeschemas in Provider- bzw. Framework-Formen bei. Behalten Sie das ursprüngliche CapabilitySet für Dispatch, Benutzerabgrenzung und direkte Ausführung bei; versuchen Sie nicht, Capabilities aus den konvertierten Tool-Definitionen zu rekonstruieren.

Nächste Schritte

• Compare adapter outputs and result handling
• Discover the architecture behind every capability
• Handle retries and both failure channels