Fehlerbehandlung

Die Ausführung einer Capability hat zwei Fehlerkanäle, und beide zu behandeln ist der Unterschied zwischen einem Agenten, der sich erholt, und einem, der abstürzt.

Capability-Fehler als zurückgegebene Daten behandeln

Eine aufgelöste Ausführung mit isError: true bedeutet, dass die Anfrage abgeschlossen wurde und der Connector eine fehlgeschlagene Aktion gemeldet hat. Es ist ein Ergebnis, kein Wurf, daher kann Ihre Agentenschleife den Fehlertext an das Modell zurückgeben und ihm die Erholung überlassen:

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

if (result.isError) {
  const text = result.content.map((part) => part.text).join('\n');
  // return the text to the model as the tool result
}

Geworfene Fehler von der spezifischsten zur allgemeinsten Klasse eingrenzen

Alles außerhalb von Capability-Ergebnissen (Authentifizierung, HTTP, Validierung, Ratenlimit, Kontingent, Timeout, Netzwerk, Konfiguration) wird geworfen:

import {
  VinkiusError,
  AuthError,
  RateLimitError,
  QuotaError,
  ConnectorNotConnectedError,
} from '@vinkius/connect';

try {
  const result = await capability.execute(args, { idempotencyKey });
  if (result.isError) {
    // connector-level failure: feed result.content back to the model
  }
} catch (error) {
  if (error instanceof ConnectorNotConnectedError) {
    // send the user through the connector setup flow
  } else if (error instanceof RateLimitError) {
    // back off using the response's retry information
  } else if (error instanceof QuotaError || error instanceof OverageError) {
    // plan limit reached: surface an upgrade path
  } else if (error instanceof AuthError) {
    // application key rejected: check rotation and environment
  } else if (error instanceof VinkiusError) {
    // any other API error
  } else {
    // hooks can throw their own errors; keep an unknown branch
  }
}

Jeder VinkiusError hat code, status, requestId und details. Lokale und Transportfehler verwenden den Status 0. requestId ist nur vorhanden, wenn der Server einen geliefert hat.

Die Fehler-Taxonomie

Wissen, welche Anfragen das SDK wiederholt

Das Standardmaximum ist der erste Versuch plus zwei Wiederholungen. Netzwerkfehler, Timeouts und HTTP 429, 502, 503 oder 504 gelten als vorübergehend, aber nur wiederholbare Anfragen werden wiederholt: GET, PUT und DELETE standardmäßig; Benutzer- und Verbindungserstellung, weil ihre Verträge Upsert/Get-or-Create sind; und Capability-Ausführung nur, wenn ein idempotencyKey angegeben ist.

Ausführungsschlüssel in Ihrer Anwendung erzeugen und validieren

Der Transport behandelt einen undefined-Idempotenzschlüssel als "Wiederholung nicht aktivieren" und sendet den Idempotency-Key-Header nur für einen truthy String. Ein leerer String aktiviert die Wiederholung also, ohne den Header zu senden. Leiten Sie Schlüssel aus der logischen Operation ab, prüfen Sie, dass sie nicht leer sind, und verwenden Sie einen Schlüssel nur dann wieder, wenn Sie dieselbe Operation wiederholen:

const key = `create-issue:${operationId}`;
if (!key.trim()) throw new Error('idempotency key required');

Verlassen Sie sich bei Ausführungsoptionen nicht auf den Adapter-Dispatch

Adapter-Dispatch-Helfer und fabriksgebundene Funktionen rufen capability.execute(args) ohne ExecuteOptions auf: kein Schlüssel, kein Abbruchsignal des Aufrufers, ein einziger Transportversuch. Unbekannte Namen, die an Adapter-Dispatcher übergeben werden, werfen ein einfaches Error, kein VinkiusError. Lösen Sie die Capability auf und rufen Sie execute() direkt auf, wenn Sie Abbruch oder Idempotenz benötigen.

Diagnosen ohne Geheimnisse aufzeichnen

try {
  // ...
} catch (error) {
  if (error instanceof VinkiusError) {
    logger.error({ code: error.code, status: error.status, requestId: error.requestId });
  }
  throw error;
}

Observability-Hooks erhalten geschwärzte Ansichten (Autorisierungs-Header und bekannte Geheimnis-Feldnamen werden entfernt), aber Ihre eigene Protokollierung muss übermittelte Anmeldedaten weiterhin als Geheimnisse behandeln. Hook-Callbacks können ihre ursprünglichen Fehler werfen, und ein Abbruch während des Retry-Backoffs kann den Signalgrund direkt weiterreichen. Behalten Sie einen abschließenden unknown-Zweig bei, statt anzunehmen, dass jeder geworfene Wert ein VinkiusError ist.

Nächste Schritte

• Understand the architecture behind error handling
• Execute with idempotency and cancellation
• Keep the application key server-side