Ir para conteúdo
be-human.ai
← Voltar ao blog

Ferramentas e integrações

Limites de API para agentes de IA: regras de retry que se sustentam

Como lidar com limites de API em um agente de IA: quais erros repetir, como aplicar backoff com jitter, limitar tentativas e evitar duplicidades.

Capa tipográfica do Be Human com o título: Limites de API para agentes de IA: regras de retry que se sustentam
Ilustração conceitual criada com IA · Be Human

Um agente de IA respeita os limites de API quando trata a resposta de limite como um sinal para desacelerar, e não como uma falha a ser forçada. Repita apenas os erros que podem dar certo depois, espere cada vez mais entre as tentativas frustradas, com alguma aleatoriedade, respeite o tempo de espera que o servidor indicar e limite o total de tentativas de cada tarefa. Antes de permitir qualquer repetição automática, torne toda escrita segura para ser repetida, porque um timeout não diz se a primeira requisição chegou a ser processada.

Principais pontos

  • Repita apenas erros que podem funcionar depois, como limite de taxa, timeouts e falhas temporárias do servidor.
  • Respeite o tempo de espera indicado pelo fornecedor e adicione jitter aleatório a todo atraso de backoff.
  • Limite as tentativas por tarefa e por janela de tempo, depois pare e entregue a tarefa a uma pessoa.
  • Torne cada escrita idempotente antes que qualquer repetição automática possa tocá-la.
  • Conte as respostas de limite como métrica operacional, para revisar os limites antes que o acesso seja cortado.

Por que o tráfego de um agente é diferente dos cliques de uma pessoa

Uma pessoa que trabalha em um portal de software faz poucas requisições por vez e depois lê a tela. Um agente que percorre uma fila pode enviar dezenas de requisições em uma rajada curta: listar os itens abertos, buscar os detalhes de cada um, consultar registros relacionados e, por fim, gravar os resultados de volta. Muitos fornecedores contam o uso por chave de API, por conta ou por minuto. Assim, vários agentes e tarefas agendadas que compartilham a mesma credencial podem esgotá-la juntos, sem que nenhum deles pareça fora do normal.

Agentes também tendem a repetir passos. Uma etapa de planejamento pede mais uma consulta, uma chamada que falhou é tentada de novo e um segundo processo inicia o mesmo trabalho porque ninguém registrou que o primeiro ainda estava em execução. Os limites existem para proteger o serviço do fornecedor. O papel do agente é se comportar como um cliente bem-educado, e esse comportamento precisa ser projetado na integração, e não deixado ao julgamento do modelo no momento da execução. Os limites variam por fornecedor e por plano, então consulte a documentação do fornecedor para os valores exatos em vez de presumi-los.

Leia os sinais antes de repetir

Nem todo erro merece uma segunda tentativa, e repetir os errados é a forma como um problema pequeno vira um problema de acesso. Uma resposta de limite de taxa, normalmente HTTP 429, significa que quem chamou pediu demais em pouco tempo. Muitas APIs também enviam um cabeçalho Retry-After ou uma dica semelhante que informa quanto tempo esperar. Erros de servidor como 500, 502, 503 e 504 costumam refletir instabilidade temporária do lado do fornecedor. Erros de validação como 400 ou 422 indicam que a própria requisição está incorreta, e reenviá-la com o mesmo conteúdo vai falhar de novo. Erros de autenticação e permissão, 401 e 403, exigem cuidado especial, porque tentativas repetidas com uma credencial inválida ou expirada podem bloquear a conta.

O timeout é o caso ambíguo. O cliente desistiu de esperar, mas o servidor pode ter concluído o trabalho. Em leituras, repetir costuma ser inofensivo. Em escritas, uma repetição pode criar uma segunda fatura, reserva ou mensagem. Trate uma escrita que sofreu timeout como resultado desconhecido e verifique o sistema de destino antes de fazer qualquer outra coisa.

  • 429 ou 503 com indicação de espera: aguarde pelo menos o tempo informado e tente novamente.
  • 429 ou 503 sem indicação: aplique backoff exponencial com jitter, como descrito abaixo.
  • Timeout ou conexão interrompida em leitura: repita dentro do limite de tentativas.
  • Timeout ou conexão interrompida em escrita: verifique se a alteração existe antes de qualquer repetição.
  • 400, 404 ou 422: não repita. Envie a tarefa e o conteúdo da requisição para uma pessoa.
  • 401 ou 403: interrompa todas as chamadas feitas com aquela credencial e dispare um alerta.

Regras de retry que se sustentam

As regras abaixo pertencem à camada de integração, o código que fica entre o agente e o fornecedor. O agente decide que trabalho fazer. A camada de integração decide quando e com que frequência cada chamada é enviada.

  • Defina um limite de concorrência para cada fornecedor e cada credencial. Comece baixo e só aumente depois de observar as respostas durante um período normal de trabalho.
  • Use backoff exponencial. Cada espera deve ser maior que a anterior, até um teto, para que uma tarefa nunca fique parada por horas sem que ninguém perceba.
  • Adicione jitter. Sorteie cada espera dentro de uma faixa, para que vários processos que falharam juntos não tentem de novo no mesmo instante.
  • Limite as tentativas por chamada. Um número pequeno e fixo costuma bastar. Se a chamada falhar após o limite, a tarefa vai para um estado de revisão com o erro registrado.
  • Defina um orçamento total de tempo por tarefa. Mesmo com poucas tentativas, uma tarefa não deve ocupar um processo indefinidamente.
  • Registre cada tentativa com o identificador da tarefa, o código de resposta, o tempo de espera e o resultado, para que uma pessoa consiga ver o padrão depois.

O modelo não deve decidir sozinho chamar de novo uma ferramenta que falhou. Deixado para improvisar, um agente pode repetir a mesma requisição com uma redação levemente diferente, o que o fornecedor entende como uma requisição nova e acaba dobrando a pressão. Regras fixas de retry no código são mais fáceis de testar e revisar do que instruções escritas em um prompt.

Uma política de retry que você não consegue explicar ao responsável pela operação ainda não está pronta.

Evite que as repetições dupliquem o trabalho

Retries e duplicidades são o mesmo problema visto por dois lados. Quando a escrita é concluída, mas a resposta se perde, a tentativa seguinte cria um segundo registro. A solução padrão é uma chave de idempotência: um identificador único enviado com a requisição, para que o fornecedor reconheça a repetição e devolva o resultado original em vez de agir duas vezes. A documentação da Stripe descreve esse padrão para a API dela, e o princípio vale para a maioria dos sistemas de negócio que o oferecem.

Quando o fornecedor aceita chaves de idempotência, gere a chave a partir do identificador da tarefa, e não a partir de um valor aleatório criado a cada tentativa. Uma chave aleatória anula o propósito, porque cada repetição parece nova. Quando o fornecedor não oferece essa chave, leia o registro de destino antes de repetir uma escrita e só grave de novo se o registro não existir. O desenho completo dessa verificação está em Idempotência em agentes de IA: evite ações duplicadas, leitura útil antes de permitir que um agente crie faturas, reservas ou mensagens automaticamente.

Enfileire, limite e alerte antes que o acesso seja cortado

Uma fila é a proteção mais simples contra rajadas. Em vez de enviar tudo assim que chega, os itens de trabalho esperam na fila e um processo os retira na velocidade que o fornecedor tolera. Trabalhos de baixa prioridade, como relatórios em lote ou sincronizações de arquivo, podem ser agendados para horários de menor movimento, enquanto pedidos sensíveis ao tempo mantêm uma faixa própria. Cada credencial deve ter sua própria fila, para que uma tarefa muito intensa não deixe as outras sem vez.

O monitoramento transforma essas regras em algo que você consegue revisar. A OpenTelemetry descreve a telemetria em três formas: traces, que acompanham uma tarefa por todas as etapas; métricas, que contam eventos ao longo do tempo; e logs, que registram os detalhes. Para um agente sujeito a limites, sinais úteis incluem a quantidade de respostas 429 por hora, o número de tarefas enviadas para revisão após esgotar as tentativas, a quantidade de falhas de autenticação e o tamanho da fila no início de cada dia de trabalho. Um alerta deve ir para uma pessoa nomeada sempre que algum desses indicadores sair da faixa normal. A mecânica das execuções agendadas e dos alertas que chegam a uma pessoa está descrita em Tarefas agendadas para agentes de IA: execuções, retentativas e alertas.

Cenário ilustrativo e como a Be Human trata o caso

Cenário ilustrativo: uma empresa quer que um agente sincronize a cada hora os chamados abertos de um sistema de atendimento para um quadro compartilhado da operação. Na primeira execução, o agente pede todo o histórico de chamados de uma vez. O sistema de atendimento passa a devolver respostas de limite, o agente tenta de novo imediatamente e a sincronização falha no fim da tarde, com metade dos chamados copiados e nenhum registro de quais foram. Um desenho corrigido envia a primeira importação completa pela fila, em ritmo lento e constante, guarda um cursor após cada página, pausa em qualquer resposta 429 e retoma a partir do cursor depois do tempo informado. As execuções seguintes buscam apenas as mudanças desde o último cursor, e qualquer execução que esgote as tentativas envia um alerta para o canal da operação, com a posição do cursor.

A Be Human desenha esse tipo de integração como parte de uma operação gerenciada. A primeira etapa define o papel do agente, as ferramentas de que ele precisa, as configurações de ritmo e retry para cada credencial e o ponto em que uma pessoa deve assumir. A operação contínua inclui acompanhar os padrões de resposta, revisar permissões quando um fornecedor muda seus limites e responder a incidentes, para que um problema de limite seja identificado como tendência antes que a credencial seja bloqueada. Se você não tem certeza de qual das suas tarefas recorrentes seria a melhor para começar, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

Quantas vezes um agente de IA deve repetir uma chamada de API que falhou? Não existe um número universal, porque o limite certo depende do fornecedor, da tarefa e do custo de um atraso. Um número pequeno e fixo de tentativas, com esperas crescentes entre elas, é um ponto de partida sólido para a maioria das integrações de negócio. Ao atingir o limite, a tarefa deve parar e ir para um estado de revisão com o erro registrado, em vez de continuar tentando em segundo plano.

O agente deve repetir quando recebe uma resposta 429? Sim, mas só depois de esperar. Uma resposta 429 significa que a requisição é válida e que o fornecedor quer que quem chamou desacelere. Por isso a repetição é adequada depois do tempo informado ou, se nenhum tempo for dado, após um atraso exponencial com jitter. Repetir imediatamente costuma gerar mais respostas 429 e pode tornar o limite ainda mais apertado.

É seguro um agente repetir uma escrita, como a criação de uma fatura? É seguro somente quando a escrita é idempotente, ou seja, quando uma requisição repetida não consegue criar um segundo registro. Use a chave de idempotência do fornecedor, se ela existir, com uma chave ligada à tarefa e não gerada do zero a cada tentativa. Se não houver essa chave, leia primeiro o registro de destino e grave novamente apenas se ele não existir.

O que acontece quando um agente bate em limites de API todos os dias? Um padrão diário indica que a integração pede mais do que a credencial permite, então a correção é estrutural. Reduza o volume com sincronizações incrementais, distribua trabalhos de baixa prioridade para horários de menor movimento, divida a carga entre credenciais quando os termos do fornecedor permitirem ou pergunte ao fornecedor sobre um plano com limites maiores. Revise o padrão com o responsável pela operação antes que a credencial seja restringida ou suspensa.

Seu próximo passo

Descubra primeiro onde um agente de IA cabe na sua empresa.

Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →