Tratamento de Erros

A execução de capacidades tem dois canais de falha, e tratar ambos é a diferença entre um agente que se recupera e um que trava.

Verifique falhas de capacidade como dados retornados

Uma execução resolvida com isError: true significa que a requisição foi concluída e o conector relatou uma ação com falha. É um resultado, não um lançamento, então o seu loop de agente pode devolver o texto do erro ao modelo e deixá-lo se recuperar:

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
}

Restrinja os erros lançados do mais específico ao mais geral

Tudo o que está fora dos resultados de capacidade (autenticação, HTTP, validação, limite de taxa, cota, timeout, rede, configuração) lança:

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

Todo VinkiusError tem code, status, requestId e details. Erros locais e de transporte usam status 0. requestId só está presente quando o servidor fornece um valor.

A taxonomia de erros

Saiba quais requisições o SDK repete

O máximo padrão é a tentativa inicial mais duas repetições. Erros de rede, timeouts e HTTP 429, 502, 503 ou 504 são considerados transitórios, mas apenas requisições repetíveis são repetidas: GET, PUT e DELETE por padrão; criação de usuário e criação de conexão porque seus contratos são upsert/get-or-create; e execução de capacidade somente quando idempotencyKey é fornecida.

Gere e valide chaves de execução na sua aplicação

O transporte trata uma chave de idempotência undefined como "não habilitar repetição" e só envia o cabeçalho Idempotency-Key para uma string truthy. Uma string vazia, portanto, habilita a repetição sem enviar o cabeçalho. Derive as chaves da operação lógica, valide que não estão vazias e reutilize uma chave somente ao repetir essa mesma operação:

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

Não dependa do despacho do adapter para opções de execução

Helpers de despacho de adapters e funções vinculadas por fábrica chamam capability.execute(args) sem ExecuteOptions: sem chave, sem sinal do chamador, uma única tentativa de transporte. Nomes desconhecidos passados aos dispatchers de adapters lançam Error simples, não VinkiusError. Resolva a Capability e chame execute() diretamente quando precisar de cancelamento ou idempotência.

Registre diagnósticos sem registrar segredos

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

Os hooks de observabilidade recebem visualizações redigidas (cabeçalhos de autorização e nomes de campos de segredos conhecidos removidos), mas o seu próprio registro ainda deve tratar valores de credenciais enviados como segredos. Callbacks de hooks podem lançar seus erros originais, e abortar durante o backoff de repetição pode propagar o motivo do sinal diretamente. Mantenha uma ramificação final unknown em vez de presumir que todo valor lançado é um VinkiusError.

Próximos passos

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