Manejo de Errores

La ejecución de capacidades tiene dos canales de fallo, y gestionar ambos es la diferencia entre un agente que se recupera y uno que se bloquea.

Compruebe los fallos de capacidades como datos devueltos

Una ejecución resuelta con isError: true significa que la solicitud se completó y el conector informó de una acción fallida. Es un resultado, no una excepción, por lo que su bucle de agente puede devolver el texto del error al modelo y permitirle recuperarse:

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
}

Acote los errores lanzados del más específico al más general

Todo lo que está fuera de los resultados de capacidades (autenticación, HTTP, validación, límite de solicitudes, cuota, tiempo de espera, red, configuración) lanza:

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
  }
}

Cada VinkiusError tiene code, status, requestId y details. Los errores locales y de transporte usan el estado 0. requestId solo está presente cuando el servidor proporciona uno.

La taxonomía de errores

Sepa qué solicitudes repite el SDK

El máximo predeterminado es el intento inicial más dos reintentos. Los errores de red, los tiempos de espera y los estados HTTP 429, 502, 503 o 504 se consideran transitorios, pero solo se reintentan las solicitudes repetibles: GET, PUT y DELETE de forma predeterminada; la creación de usuarios y de conexiones porque sus contratos son upsert/get-or-create; y la ejecución de capacidades solo cuando se proporciona idempotencyKey.

Genere y valide claves de ejecución en su aplicación

El transporte trata una clave de idempotencia undefined como "no habilitar reintento" y solo envía el encabezado Idempotency-Key para una cadena truthy. Una cadena vacía, por tanto, habilita el reintento sin enviar el encabezado. Derive las claves de la operación lógica, valide que no estén vacías y reutilice una clave solo cuando reintente esa misma operación:

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

No dependa del despacho del adaptador para las opciones de ejecución

Los auxiliares de despacho de adaptadores y las funciones vinculadas por fábrica llaman a capability.execute(args) sin ExecuteOptions: sin clave, sin señal del llamador, un único intento de transporte. Los nombres desconocidos pasados a los despachadores de adaptadores lanzan un Error simple, no un VinkiusError. Resuelva la Capability y llame a execute() directamente cuando necesite cancelación o idempotencia.

Registre diagnósticos sin registrar secretos

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

Los hooks de observabilidad reciben vistas censuradas (se eliminan los encabezados de autorización y los nombres de campos de secretos conocidos), pero su propio registro todavía debe tratar los valores de credenciales enviados como secretos. Las funciones de retorno de los hooks pueden lanzar sus errores originales, y cancelar durante la espera entre reintentos puede propagar directamente el motivo de la señal. Mantenga una rama final unknown en lugar de suponer que todo valor lanzado es un VinkiusError.

Próximos pasos

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