2467 sintomas catalogados
Cada sintoma com causa provável e correção, ligado à lição da trilha IA que explica o porquê. Descreva o sintoma para filtrar.
| Sintoma | Causa provável | Correção | Lição |
|---|---|---|---|
| O agente responde e-mails fora do escopo definido. | Prompt de sistema mal definido ou não versionado. | Revisar e restringir o prompt, garantindo versionamento e teste. | A caixa de e-mail que se responde sozinha: um agente com fer |
| A resposta não segue o formato JSON exigido. | Prompt não especifica formato obrigatório. | Incluir exemplo de formato JSON no prompt e validar na revisão. | A caixa de e-mail que se responde sozinha: um agente com fer |
| Ferramenta externa retorna erro ou dados incompletos. | Contrato de entrada/saída da função não seguido. | Padronizar interface das ferramentas e adicionar logs detalhados. | A caixa de e-mail que se responde sozinha: um agente com fer |
| A resposta é enviada automaticamente sem revisão. | Fluxo de aprovação humana não implementado. | Separar geração de resposta do envio e exigir aprovação manual. | A caixa de e-mail que se responde sozinha: um agente com fer |
| A IA não retorna o custo ou diz que não pode calcular | Pedido ambíguo ou faltando modelo/resolução/duração | Refaça o pedido especificando todos os parâmetros. | A conta antes de gerar: pedir a estimativa de créditos e bai |
| O custo retornado não bate com a tabela oficial | Tabela desatualizada ou erro na simulação | Peça para recalcular e detalhar cada item, incluindo mínimos e adicionais. | A conta antes de gerar: pedir a estimativa de créditos e bai |
| A IA não reconhece o formato avançado | Formato não suportado pelo modelo escolhido | Peça para listar apenas formatos suportados pelo modelo. | A conta antes de gerar: pedir a estimativa de créditos e bai |
| A IA não informa o saldo de créditos | Pedido não incluiu a checagem de saldo | Peça explicitamente: 'Verifique se tenho créditos suficientes para este pedido antes de rodar.' | A conta antes de gerar: pedir a estimativa de créditos e bai |
| Transcrição com erros ou frases truncadas | Áudio de baixa qualidade ou blocos muito longos | Garanta áudio limpo e divida em blocos menores | A reunião vira ata, tarefas e e-mails antes de a sala esvazi |
| Agente extrai tarefas irrelevantes ou inventadas | Prompt do agente pouco restritivo | Refine as instruções do agente para limitar a saída ao que foi dito | A reunião vira ata, tarefas e e-mails antes de a sala esvazi |
| E-mails enviados sem revisão | Fluxo de aprovação não implementado corretamente | Implemente checagem obrigatória antes do envio | A reunião vira ata, tarefas e e-mails antes de a sala esvazi |
| Logs incompletos ou ausentes | Falta de registro em cada etapa | Inclua logging detalhado desde a transcrição até o envio | A reunião vira ata, tarefas e e-mails antes de a sala esvazi |
| Ação irreversível executada sem aprovação | Permissão ou guardrail mal configurado | Revise contratos de tool e regras de aprovação | Ações irreversíveis exigem aprovação: desenho de permissões |
| Logs de auditoria ausentes ou incompletos | Tracing não ativado ou mal implementado | Ative e teste o tracing conforme documentação | Ações irreversíveis exigem aprovação: desenho de permissões |
| Aprovação humana não bloqueia execução | Workflow de aprovação não integrado corretamente | Garanta que a execução só ocorra após resposta positiva do endpoint de aprovação | Ações irreversíveis exigem aprovação: desenho de permissões |
| O agente não gera alertas mesmo quando o critério não é atendido | Critério de sucesso mal definido ou erro no caso de teste | Revisar o prompt e os testes automatizados. | Acompanhamento de apostas estratégicas: do insight à revisão |
| Ferramenta MCP retorna erro de autenticação | Chave de API ausente ou inválida | Verificar variáveis de ambiente e permissões. | Acompanhamento de apostas estratégicas: do insight à revisão |
| Registros de tracing não aparecem | Tracing não habilitado no SDK ou diretório de logs incorreto | Ajustar configuração do SDK e permissões de escrita. | Acompanhamento de apostas estratégicas: do insight à revisão |
| Métricas não estão sendo coletadas | Tracing ou registro manual não implementado corretamente | Reveja a configuração do SDK e os pontos de coleta de dados | Acompanhamento de campanhas: análise de resultados e feedbac |
| Feedback não altera o comportamento do agente | Prompt não está sendo atualizado ou feedback não está integrado ao fluxo | Confirme o versionamento do prompt e a aplicação do feedback | Acompanhamento de campanhas: análise de resultados e feedbac |
| Dados pessoais aparecem nos registros | Anonimização insuficiente | Implemente rotina de anonimização conforme LGPD antes de salvar dados | Acompanhamento de campanhas: análise de resultados e feedbac |
| O agente não detecta atrasos mesmo com datas reais posteriores. | A função de detecção pode estar usando o campo errado ou o formato de data não está compatível. | Verifique se data_real está preenchida e se o cálculo de diferença de dias está correto. | Acompanhamento e replanejamento: caso EXEMPLO com dados oper |
| O cronograma não é ajustado após detectar atraso. | A função de ajuste pode não estar sendo chamada pelo agente ou não está modificando as datas. | Confirme a ligação entre detecção, ajuste e atualização dos dados. | Acompanhamento e replanejamento: caso EXEMPLO com dados oper |
| Logs não aparecem no arquivo. | Configuração do logging pode estar errada ou o caminho do arquivo não tem permissão de escrita. | Ajuste o logging.basicConfig e garanta permissão de escrita no diretório. | Acompanhamento e replanejamento: caso EXEMPLO com dados oper |
| O agente não atende chamadas pelo SIP | Configuração incorreta do SIP trunk ou credenciais inválidas | Revise usuário, senha, servidor e portas SIP na plataforma ElevenLabs. | Agente de voz que atende o telefone da empresa com ElevenAge |
| Respostas imprecisas ou fora do contexto | Prompt mal definido ou base de conhecimento desatualizada | Revise e atualize o prompt e os documentos da base de conhecimento. | Agente de voz que atende o telefone da empresa com ElevenAge |
| Ferramentas não são acionadas | IDs de ferramentas ausentes ou incorretos no JSON de criação | Confirme os IDs das ferramentas e inclua corretamente no campo 'tool_ids'. | Agente de voz que atende o telefone da empresa com ElevenAge |
| O agente classifica documentos errados | Prompt ou função de classificação ambíguos | Refine o prompt, adicione exemplos negativos e ajuste a lógica | Agente especialista do administrativo: prompt de sistema, fe |
| Ferramenta não aparece para o agente | Não registrada corretamente no SDK | Verifique a lista de ferramentas ao instanciar o agente | Agente especialista do administrativo: prompt de sistema, fe |
| Testes automatizados falham após ajuste | Mudança no contrato de entrada/saída | Atualize casos de teste e documentação das ferramentas | Agente especialista do administrativo: prompt de sistema, fe |
| Logs não registram ações | Falta de chamada explícita de log nas funções | Implemente logging em cada ferramenta | Agente especialista do administrativo: prompt de sistema, fe |
| O agente sugere decisão final sem pedir revisão humana | Prompt de sistema mal definido ou ferramenta sem restrição | Reforce a orientação no prompt e ajuste o código das ferramentas | Agente especialista do apoio à decisão executiva: prompt de |
| Ferramenta retorna erro de tipo ou valor inesperado | Parâmetros mal validados ou tipos inconsistentes | Implemente validação de entrada e saída nas funções | Agente especialista do apoio à decisão executiva: prompt de |
| Testes automatizados falham de forma intermitente | Cenários de teste não determinísticos ou dependentes de dados externos | Use dados de teste estáticos e controle o ambiente de execução | Agente especialista do apoio à decisão executiva: prompt de |
| Logs incompletos ou ausentes | Falta de configuração de tracing ou registro no agente | Habilite tracing no SDK e revise pontos de log | Agente especialista do apoio à decisão executiva: prompt de |
| O agente retorna dados inconsistentes ou inventados | Prompt de sistema ambíguo ou ferramenta sem contrato claro | Reescreva o prompt e revise os contratos das ferramentas | Agente especialista do comercial e vendas: prompt de sistema |
| Testes automatizados falham em casos simples | Função implementada fora do contrato ou erro de tipo | Corrija a assinatura e os tipos das funções | Agente especialista do comercial e vendas: prompt de sistema |
| Propostas são enviadas sem aprovação | Falta de lógica de revisão humana no fluxo | Implemente verificação obrigatória antes de ações críticas | Agente especialista do comercial e vendas: prompt de sistema |
| O agente sugere classificações erradas ou inconsistentes | Prompt de sistema mal definido ou ferramentas com contratos ambíguos | Revise o prompt e os contratos das ferramentas, ajuste os testes. | Agente especialista do contabilidade: prompt de sistema, fer |
| Erros de integração entre agente e backend | Parâmetros ou retorno das ferramentas não padronizados | Padronize os contratos e valide com testes automatizados. | Agente especialista do contabilidade: prompt de sistema, fer |
| Dados inválidos processados pelo agente | Guardrails ausentes ou mal implementados | Implemente validações automáticas robustas para entrada e saída. | Agente especialista do contabilidade: prompt de sistema, fer |
| O agente retorna respostas vagas ou fora do escopo | Prompt de sistema genérico ou permissivo demais | Refine o prompt, detalhando limites e exemplos | Agente especialista do desenvolvimento de negócios: prompt d |
| Função de ferramenta lança exceção inesperada | Entrada inválida ou não tratada | Adicione validação de parâmetros e mensagens de erro claras | Agente especialista do desenvolvimento de negócios: prompt d |
| Testes automáticos falham após ajuste no agente | Mudança não refletida nos casos de teste ou contrato da ferramenta | Atualize os testes e contratos para refletir a nova lógica | Agente especialista do desenvolvimento de negócios: prompt d |
| O agente retorna respostas vagas ou genéricas | Prompt de sistema pouco específico ou ferramentas mal definidas | Reescreva o prompt e revise os contratos das ferramentas | Agente especialista do estratégia: prompt de sistema, ferram |
| Ferramenta não retorna dados esperados | Parâmetros incorretos ou API externa fora do ar | Valide os parâmetros e implemente mocks para testes | Agente especialista do estratégia: prompt de sistema, ferram |
| Respostas com termos proibidos ou decisões críticas | Guardrails ausentes ou mal implementados | Adicione ou corrija funções de validação de saída | Agente especialista do estratégia: prompt de sistema, ferram |
| Erros de autenticação nas APIs | Chave de API ausente ou inválida | Configure as variáveis de ambiente corretamente | Agente especialista do estratégia: prompt de sistema, ferram |
| O agente retorna erro de parsing em todo XML | Estrutura do XML diferente do esperado ou caminho XPath incorreto | Revise os caminhos dos campos no XML e ajuste a função de parsing | Agente especialista do fiscal: prompt de sistema, ferramenta |
| Campos obrigatórios vêm vazios na saída | Campos ausentes no XML de teste ou erro de extração | Inclua exemplos completos e revise a lógica de busca dos campos | Agente especialista do fiscal: prompt de sistema, ferramenta |
| Agente ignora erros e segue o fluxo | Falta de tratamento de exceções ou registro de erros | Implemente captura de exceções e logging detalhado | Agente especialista do fiscal: prompt de sistema, ferramenta |
| O agente aceita dados inválidos ou incompletos. | Validação de entrada ausente ou mal configurada. | Reforce os guardrails com validação de tipos e limites antes de processar. | Agente especialista do gestão de equipes e operações: prompt |
| Respostas do agente não seguem o formato esperado. | Schema de saída não está sendo aplicado. | Implemente validação de saída usando pydantic ou schema JSON. | Agente especialista do gestão de equipes e operações: prompt |
| Ações irreversíveis são executadas sem revisão. | Falta de checagem de aprovação humana. | Inclua etapa obrigatória de revisão antes de executar ações críticas. | Agente especialista do gestão de equipes e operações: prompt |
| Logs não registram todas as ações. | Configuração de logging incompleta. | Ajuste o logging para capturar entradas, saídas e erros de todas as ferramentas. | Agente especialista do gestão de equipes e operações: prompt |
| O agente ignora cláusulas de risco óbvias | Prompt de sistema pouco específico ou exemplos insuficientes | Refine o prompt e adicione exemplos de cláusulas críticas nos testes | Agente especialista do jurídico: prompt de sistema, ferramen |
| Ferramenta retorna erro de parâmetro | Tipo ou nome de parâmetro divergente do contrato definido | Corrija a assinatura da função e valide os parâmetros | Agente especialista do jurídico: prompt de sistema, ferramen |
| Relatório final está incompleto | Retorno inconsistente das ferramentas ou falta de testes automáticos | Padronize o formato de saída e aumente a cobertura dos testes | Agente especialista do jurídico: prompt de sistema, ferramen |
| Logs não registram todas as ações | Falta de tracing ou configuração inadequada do logger | Implemente logging detalhado em cada etapa do agente | Agente especialista do jurídico: prompt de sistema, ferramen |
| O agente responde em inglês ou formato errado | Prompt de sistema mal definido ou não carregado | Revise o prompt e garanta que está versionado e carregado corretamente | Agente especialista do marketing: prompt de sistema, ferrame |
| Ferramenta retorna erro de tipo | Contrato de parâmetros ou retorno inconsistente | Ajuste o tipo e descrição dos parâmetros e retorno na definição da ferramenta | Agente especialista do marketing: prompt de sistema, ferrame |
| Teste automatizado falha sem motivo aparente | Entrada de teste não cobre exceções ou limites | Amplie os casos de teste para cobrir exceções e entradas inválidas | Agente especialista do marketing: prompt de sistema, ferrame |
| O agente tenta executar runbook sem aprovação humana. | Prompt de sistema ou lógica da ferramenta mal definida. | Reforce a instrução no prompt e bloqueie execução sem parâmetro de aprovação. | Agente especialista do NOC (centro de operações de rede): pr |
| Respostas do agente contêm dados pessoais sem justificativa. | Falta de guardrail de saída ou validação de conteúdo. | Implemente filtro de dados sensíveis e exija base legal explícita. | Agente especialista do NOC (centro de operações de rede): pr |
| Casos de teste automatizados falham de forma intermitente. | Funções com comportamento não determinístico ou ambiente inconsistente. | Garanta dados de teste fixos e isolamento dos testes. | Agente especialista do NOC (centro de operações de rede): pr |
| O agente retorna valores errados no orçamento | Erro na lógica da ferramenta ou parâmetros mal definidos | Revisar a função Python e os tipos dos parâmetros | Agente especialista do planejamento: prompt de sistema, ferr |
| O agente sugere tarefas sem sentido ou cronogramas impossíveis | Prompt de sistema ambíguo ou casos de teste insuficientes | Ajustar o prompt e ampliar os testes | Agente especialista do planejamento: prompt de sistema, ferr |
| Logs ou tracing não aparecem | Tracing não habilitado ou ambiente mal configurado | Verificar importação e chamada de enable_tracing() | Agente especialista do planejamento: prompt de sistema, ferr |
| O agente retorna erro inesperado ao consultar saldo | Contrato de ferramenta inconsistente ou parâmetro ausente | Revise a assinatura da função e os parâmetros esperados | Agente especialista do RH (DP, folha e benefícios): prompt d |
| Dados pessoais aparecem na resposta | Prompt ou guardrails insuficientes | Reforce as instruções do prompt e valide a saída | Agente especialista do RH (DP, folha e benefícios): prompt d |
| Testes automatizados falham para matrículas inválidas | Validação de entrada ausente ou incorreta | Implemente ou corrija os guardrails de entrada | Agente especialista do RH (DP, folha e benefícios): prompt d |
| Logs não registram chamadas de ferramenta | Tracing não habilitado no SDK | Ative tracing e revise a configuração do agente | Agente especialista do RH (DP, folha e benefícios): prompt d |
| O agente sugere promoção sem registro de avaliação | Prompt ou guardrail insuficiente | Reforce a regra no prompt e implemente validação na saída | Agente especialista do RH (R&S, T&D e PDC): prompt de sistem |
| Dados pessoais aparecem no log | Ferramenta expondo informações sensíveis | Ajuste o contrato da ferramenta para nunca retornar dados pessoais | Agente especialista do RH (R&S, T&D e PDC): prompt de sistem |
| Testes automatizados falham após alteração no prompt | Mudança de critério não refletida nos testes | Atualize os casos de teste para refletir o novo critério | Agente especialista do RH (R&S, T&D e PDC): prompt de sistem |
| Logs não mostram a versão do prompt | Código não registra hash ou versão do prompt | Inclua a versão do prompt em cada log de decisão | Agente especialista do RH (R&S, T&D e PDC): prompt de sistem |
| O agente retorna respostas vagas ou sem fonte. | Prompt de sistema incompleto ou mal escrito. | Reescreva o prompt, exigindo fonte legal e limites claros. | Agente especialista do tributário: prompt de sistema, ferram |
| Ferramenta retorna erro de tipo ou formato inesperado. | Contrato de entrada/saída não seguido na implementação. | Valide tipos e formatos nas funções das ferramentas. | Agente especialista do tributário: prompt de sistema, ferram |
| Testes automatizados falham em entradas inválidas. | Faltam validações de entrada nas ferramentas. | Implemente validação e tratamento de erro explícito. | Agente especialista do tributário: prompt de sistema, ferram |
| Respostas incoerentes ou fora do escopo | Prompt de sistema mal definido ou ferramentas com contratos ambíguos | Revise o prompt e os contratos de entrada/saída das funções | Agentes autônomos multimodais: Claude Managed Agents, OpenAI |
| Latência alta em voz ou integração | Orquestração ineficiente entre APIs ou sobrecarga de rede | Otimize chamadas assíncronas e monitore recursos | Agentes autônomos multimodais: Claude Managed Agents, OpenAI |
| Logs ausentes ou incompletos | Tracing não habilitado ou configuração incorreta | Ative tracing detalhado e revise permissões de escrita | Agentes autônomos multimodais: Claude Managed Agents, OpenAI |
| O agente executa comandos inesperados | Prompt ou permissões mal definidas | Revise o escopo e restrinja permissões | Agentes autônomos: tendências, riscos e oportunidades |
| Faltam logs de ações do agente | Configuração de logging ausente ou insuficiente | Implemente logging detalhado em todos os módulos | Agentes autônomos: tendências, riscos e oportunidades |
| O agente trava em tarefas longas | Timeouts ou limitações do modelo | Ajuste limites de tempo e divida tarefas complexas | Agentes autônomos: tendências, riscos e oportunidades |
| O agente não registra decisões no log. | Tracing não habilitado ou erro na configuração do SDK. | Verifique se o tracing está ativado e revise a implementação do agente. | Agentes de IA: por que automatizar o monitoramento de mercad |
| Fontes de mercado não são monitoradas. | Fontes não foram mapeadas ou ferramenta não implementada. | Revise a lista de fontes e implemente as ferramentas necessárias. | Agentes de IA: por que automatizar o monitoramento de mercad |
| Alertas de variação não são emitidos. | Critério de alerta mal definido no prompt do agente. | Ajuste as instruções para incluir o critério correto de alerta. | Agentes de IA: por que automatizar o monitoramento de mercad |
| O agente retorna erro genérico sem detalhamento | Prompt de sistema ou validação de saída mal definidos | Reforce instruções e use guardrails para estruturar erros | Agentes multiagente: coordenação, especialização e fallback |
| Dados sensíveis vazam entre agentes | Passagem de contexto sem minimização | Implemente filtros de contexto e revise permissões | Agentes multiagente: coordenação, especialização e fallback |
| Fallback não aciona revisão humana | Handler de exceção ausente ou mal configurado | Implemente função de fallback explícita para humanos | Agentes multiagente: coordenação, especialização e fallback |
| O vídeo não é gerado ou fica com status 'waiting' indefinidamente | Áudio não disponível por URL pública ou formato incompatível | Verifique se o arquivo mp3 está acessível e no formato aceito pelo HeyGen | Agentes multimodais: voz, vídeo e texto no administrativo |
| O áudio gerado está incompleto ou com falhas | Texto excedeu o limite de caracteres do modelo ElevenLabs | Divida o texto em partes menores e gere múltiplos áudios | Agentes multimodais: voz, vídeo e texto no administrativo |
| O avatar do vídeo não sincroniza com o áudio | Diferença de duração ou configuração de avatar inadequada | Ajuste o áudio para corresponder à duração esperada e revise as opções de avatar | Agentes multimodais: voz, vídeo e texto no administrativo |
| Agente não executa ferramenta MCP | Contrato da ferramenta não segue o padrão MCP ou permissão ausente | Revise a assinatura e permissões da função/tool | Agentes, multiagentes e MCP: como Claude, OpenAI, ElevenLabs |
| Áudio não é gerado pelo ElevenLabs | voice_id inválido ou chave de API incorreta | Confirme voice_id e credenciais | Agentes, multiagentes e MCP: como Claude, OpenAI, ElevenLabs |
| Vídeo HeyGen não finaliza | Parâmetros obrigatórios ausentes ou payload inválido | Verifique se avatar_id, script e voice_id estão corretos | Agentes, multiagentes e MCP: como Claude, OpenAI, ElevenLabs |
| O agente toma decisões sem passar por aprovação humana | Checkpoint ou handoff não configurado corretamente | Revisar a definição dos handoffs e checkpoints no código | Agentes, multiagentes e orquestração: conceitos essenciais p |
| Saídas inconsistentes ou fora do escopo | Prompt de sistema mal definido ou falta de guardrails | Ajustar o prompt e reforçar validações de entrada e saída | Agentes, multiagentes e orquestração: conceitos essenciais p |
| Logs incompletos ou ausentes | Tracing ou sessões não ativados | Habilitar tracing e garantir persistência dos registros | Agentes, multiagentes e orquestração: conceitos essenciais p |
| Respostas superficiais ou vagas | Effort baixo ou contexto insuficiente | Aumente o effort ou amplie o contexto até o resultado melhorar | Ajustando parâmetros: esforço, contexto e ferramentas na prá |
| Tempo de resposta alto | Contexto excessivo ou effort muito alto | Reduza o contexto e teste effort médio | Ajustando parâmetros: esforço, contexto e ferramentas na prá |
| Acesso negado a dados ou funções | Permissões das ferramentas restritas demais | Revise as permissões e habilite apenas o necessário | Ajustando parâmetros: esforço, contexto e ferramentas na prá |
| Custo inesperadamente alto | Contexto ou effort acima do necessário | Reduza ambos e monitore o impacto | Ajustando parâmetros: esforço, contexto e ferramentas na prá |
| Voz soa artificial ou robótica | Parâmetros de estabilidade ou estilo extremos | Reduza style e ajuste stability para valores intermediários | Ajustando vozes, idiomas e parâmetros nos SDKs |
| Pronúncia errada de nomes próprios | Modelo ou idioma incompatível | Troque o model_id ou ajuste o texto para fonética | Ajustando vozes, idiomas e parâmetros nos SDKs |
| Vídeo do HeyGen não reflete idioma escolhido | Campo language incorreto ou voice_id incompatível | Confirme campos e use voice_id que suporte o idioma | Ajustando vozes, idiomas e parâmetros nos SDKs |
| Áudio muito rápido ou lento | Parâmetro speed fora do ideal | Ajuste speed para mais próximo de 1.0 | Ajustando vozes, idiomas e parâmetros nos SDKs |
| O fundo não mudou | O modelo não aplicou a troca ou a imagem inicial fixa a composição | Peça explicitamente para trocar o fundo e refazer a cena | Ajustar em conversa: mais perto, mais lento, corta antes, tr |
| A duração não bate com o pedido | O modelo cortou antes ou depois do ponto | Peça para cortar exatamente no segundo desejado | Ajustar em conversa: mais perto, mais lento, corta antes, tr |
| O ritmo não desacelerou | O pedido foi ambíguo ou o modelo não entendeu | Peça 'reduza a velocidade da ação pela metade' ou especifique o ritmo | Ajustar em conversa: mais perto, mais lento, corta antes, tr |
| O vídeo ficou repetitivo | Iterações longas sem extrair o último quadro | Peça para usar o último quadro como entrada do próximo clipe | Ajustar em conversa: mais perto, mais lento, corta antes, tr |
| Erros de Out Of Memory (OOM) | Batch size ou heap excessivo | Reduza batch size ou heap do Elasticsearch | Ajuste fino de recursos: tuning de memória, CPU e indexação |
| Busca lenta no FAISS | nprobe muito alto | Reduza nprobe e teste o impacto no recall | Ajuste fino de recursos: tuning de memória, CPU e indexação |
| Indexação travando o Elasticsearch | refresh_interval muito baixo | Aumente o refresh_interval durante a ingestão | Ajuste fino de recursos: tuning de memória, CPU e indexação |
| CPU saturada durante queries | top_k alto demais no Retriever | Reduza top_k e monitore o impacto | Ajuste fino de recursos: tuning de memória, CPU e indexação |
| Alertas não aparecem no dashboard | Falha na integração ou no envio de eventos pelo agente | Verifique se os hooks/callbacks estão ativos e se o endpoint do dashboard está acessível | Alertas e dashboards: monitoramento ativo do fluxo multiagen |
| Métricas não atualizam em tempo real | Problema no push ou coleta de métricas | Confirme se o serviço de métricas (ex: Prometheus) está rodando e coletando do endpoint correto | Alertas e dashboards: monitoramento ativo do fluxo multiagen |
| Aprovações pendentes não bloqueiam o fluxo | Lógica de bloqueio/espera não implementada corretamente no agente | Ajuste o código para exigir confirmação humana antes de prosseguir | Alertas e dashboards: monitoramento ativo do fluxo multiagen |
| Métricas não aparecem no painel | Exportação HTTP não configurada ou porta bloqueada | Verifique se o servidor de métricas está rodando e acessível | Alertas e métricas: detectando falhas antes do usuário |
| Alertas não disparam | Regras de alerta mal configuradas ou limites muito altos | Revise as condições e baixe os thresholds para teste | Alertas e métricas: detectando falhas antes do usuário |
| Erros não são registrados | Exceções não capturadas no código | Garanta que todo erro incremente o contador de erros | Alertas e métricas: detectando falhas antes do usuário |
| Custo não é monitorado | Tokens não são contabilizados por requisição | Use as funções de contagem de tokens dos SDKs oficiais | Alertas e métricas: detectando falhas antes do usuário |
| Alertas não aparecem no Alertmanager | Regras de alerta mal configuradas ou Prometheus não está coletando métricas. | Revise as regras e confirme que o endpoint de métricas está acessível. | Alertas e respostas a incidentes em serving de IA |
| Alertas não chegam ao Slack ou e-mail | Configuração incorreta dos receivers no Alertmanager. | Cheque tokens, URLs e permissões. Teste envio manual. | Alertas e respostas a incidentes em serving de IA |
| Respostas automáticas não executam | Webhook ou script de resposta está com erro ou indisponível. | Verifique logs do Alertmanager e do serviço de resposta. | Alertas e respostas a incidentes em serving de IA |
| Alerta não é disparado na exclusão de contrato | Critério de alerta não implementado corretamente | Revise a função de validação ou hook responsável | Alertas e revisão humana: quando intervir no agente |
| Ação executada sem revisão humana | Fluxo de intervenção não está bloqueando execução automática | Garanta que a execução só ocorra após aprovação explícita | Alertas e revisão humana: quando intervir no agente |
| Registro da intervenção não aparece no log | Falha na integração com sistema de logging | Verifique permissões e chamadas de log no código | Alertas e revisão humana: quando intervir no agente |
| Watchdog dispara alerta falso | Timeout muito curto ou endpoint não responde sob carga | Aumentar timeout e revisar endpoint para resposta rápida | Alertas sobre alertas: monitorando o próprio agente |
| Incidentes não aparecem no log | Permissão de escrita ou erro no formato do registro | Verificar permissões e validar formato JSON | Alertas sobre alertas: monitorando o próprio agente |
| Auto-teste nunca falha, mesmo com erro simulado | Caso de teste mal definido ou comparação errada | Revisar lógica do auto-teste e resultado esperado | Alertas sobre alertas: monitorando o próprio agente |
| Alertas não chegam ao responsável | Configuração de e-mail ou webhook incorreta | Revisar parâmetros de envio e testar manualmente. | Alertas, logs e revisão: como agir rápido diante de falhas |
| Logs não registram falhas | Nível de logging inadequado ou handler ausente | Ajustar logger para nível INFO ou ERROR e garantir handler ativo. | Alertas, logs e revisão: como agir rápido diante de falhas |
| Dados sensíveis vazaram no log | Falta de anonimização ou filtragem | Implementar mascaramento e revisar pontos de logging. | Alertas, logs e revisão: como agir rápido diante de falhas |
| Backup não restaura corretamente | Permissões de arquivo ou caminho incorreto | Verifique permissões com 'ls -l' e ajuste com 'chown' ou 'chmod' | Alta disponibilidade: redundância, backup e failover |
| Failover não ativa o IP virtual | Keepalived mal configurado ou interface errada | Revise o arquivo de configuração e o nome da interface de rede | Alta disponibilidade: redundância, backup e failover |
| Qdrant não inicia após restauração | Dados corrompidos ou versão incompatível | Confirme a integridade do backup e a versão do Qdrant | Alta disponibilidade: redundância, backup e failover |
| O agente responde com dados inventados mesmo após erro de ferramenta. | Faltou validação automática de contrato ou o hook de recusa não está ativo. | Implemente validação de entrada e hooks de bloqueio para toda ferramenta. | Alucinação de ferramenta: casos de teste que pegam o erro an |
| O agente trava ao receber argumento inesperado. | Assinatura da ferramenta não está protegida por Pydantic ou tipos explícitos. | Defina input_schema com tipos obrigatórios e trate exceções. | Alucinação de ferramenta: casos de teste que pegam o erro an |
| Tentativas de uso de ferramentas inexistentes não aparecem nos logs. | Faltou registro estruturado de chamadas bloqueadas. | Adicione logging detalhado nos hooks de validação. | Alucinação de ferramenta: casos de teste que pegam o erro an |
| O agente retorna erro de autenticação ao acessar a API. | Variável de ambiente da chave de API não definida ou nome incorreto. | Verifique se exportou a variável corretamente e se o nome está igual ao esperado pelo SDK. | Ambiente seguro: variáveis de ambiente, segredos e LGPD na p |
| Chave de API aparece em logs ou outputs do agente. | Logging mal configurado ou segredos usados em mensagens de erro. | Revise o código para nunca incluir variáveis sensíveis em logs ou outputs. | Ambiente seguro: variáveis de ambiente, segredos e LGPD na p |
| Dados pessoais reais aparecem no prompt ou output sem necessidade. | Falta de minimização ou anonimização dos dados. | Reescreva o fluxo para usar IDs ou pseudônimos, e revise a base legal. | Ambiente seguro: variáveis de ambiente, segredos e LGPD na p |
| O agente retorna erro de autenticação | Variável de ambiente da chave de API não definida ou incorreta | Verifique se a variável está exportada corretamente e contém a chave válida | Ambiente seguro: variáveis de ambiente, segredos e permissõe |
| Logs mostram dados sensíveis | Mascaramento de dados não implementado em ambiente de teste | Implemente mascaramento e revise os pontos de log | Ambiente seguro: variáveis de ambiente, segredos e permissõe |
| Agente acessa arquivos não autorizados | Permissões de diretório amplas demais | Restrinja permissões com chmod e revise a configuração do agente | Ambiente seguro: variáveis de ambiente, segredos e permissõe |
| Dados de produção aparecem em ambiente de teste | Ambientes não estão isolados | Separe variáveis, bancos e diretórios para cada ambiente | Ambiente seguro: variáveis de ambiente, segredos e permissõe |
| O agente retorna erro de autenticação ao chamar a API | Variável de ambiente não carregada ou chave inválida | Verifique se o .env está correto e carregado antes de iniciar o agente | Ambiente seguro: variáveis, segredos e isolamento dos agente |
| Logs mostram dados sensíveis ou segredos | Configuração de logging inadequada | Ajuste o código para filtrar campos sensíveis antes de registrar | Ambiente seguro: variáveis, segredos e isolamento dos agente |
| Um agente acessa arquivos de outro agente | Permissões de pasta ou usuário mal configuradas | Reveja permissões de arquivos e execute cada agente sob usuário dedicado | Ambiente seguro: variáveis, segredos e isolamento dos agente |
| O agente retorna erro de autenticação ao chamar a API. | Variável de ambiente não definida ou valor incorreto. | Verifique se a variável foi exportada corretamente antes de rodar o processo. | Ambiente seguro: variáveis, segredos e minimização de dados |
| Dados sensíveis aparecem em logs ou prompts. | Falta de anonimização ou mascaramento no código. | Implemente funções de mascaramento e revise pontos de log. | Ambiente seguro: variáveis, segredos e minimização de dados |
| Rollback não restaura o funcionamento anterior. | Snapshot de variáveis incompleto ou script de restauração com erro. | Mantenha backups atualizados e teste os scripts periodicamente. | Ambiente seguro: variáveis, segredos e minimização de dados |
| O agente retorna erro de autenticação | Variável de ambiente ausente ou chave inválida | Verifique se a variável está definida e a chave é válida | Ambiente seguro: variáveis, segredos e permissões mínimas |
| Outro usuário do sistema acessa segredos | Permissões de arquivo incorretas | Aplique chmod 600 nos arquivos de configuração | Ambiente seguro: variáveis, segredos e permissões mínimas |
| Ações inesperadas em produção | Mistura de ambientes ou chave de dev em prod | Confira se cada ambiente usa suas próprias variáveis e chaves | Ambiente seguro: variáveis, segredos e permissões mínimas |
| Ambiente de produção rodando código antigo após rollback | Dependências não foram reinstaladas após checkout da tag | Rode 'pip install -r requirements.txt' após cada rollback | Ambientes e versionamento: nunca rode tudo no mesmo lugar |
| Prompt inesperado sendo usado em produção | Prompt não versionado ou variável de ambiente errada | Versione prompts e confira a variável PROMPT_VERSION por ambiente | Ambientes e versionamento: nunca rode tudo no mesmo lugar |
| Chave de API de teste usada em produção | Arquivo .env misturado ou variável de ambiente não carregada corretamente | Separe arquivos .env e revise o carregamento por ambiente | Ambientes e versionamento: nunca rode tudo no mesmo lugar |
| Skill não aparece para o agente | Arquivo não está no diretório correto ou não foi versionado. | Verifique o caminho e o versionamento do skill/plugin. | Ambientes, skills e plugins: expandindo seu agente sem perde |
| Erro de dependência ao rodar skill/plugin | Dependência não instalada ou conflito de versões. | Reinstale dependências no ambiente virtual ou ajuste o requirements.txt. | Ambientes, skills e plugins: expandindo seu agente sem perde |
| Logs ou tracing não registram execuções | Tracing não habilitado ou configuração incorreta. | Revise a configuração de tracing no SDK e habilite hooks necessários. | Ambientes, skills e plugins: expandindo seu agente sem perde |
| Requisito funcional não atendido | Fluxo mal modelado ou componente inadequado | Revise o mapeamento do fluxo e ajuste a escolha dos componentes | Análise de requisitos: do problema ao fluxo de IA |
| Dúvidas recorrentes entre as equipes | Documentação inicial insuficiente | Detalhe melhor os objetivos, fluxos e critérios de sucesso | Análise de requisitos: do problema ao fluxo de IA |
| Integração com sistema legado falha | Levantamento incompleto de dependências externas | Inclua todas as integrações e APIs na documentação inicial | Análise de requisitos: do problema ao fluxo de IA |
| O agente executa ação crítica sem revisão humana. | Guardrail de saída ausente ou mal configurado. | Revise a função de validação e teste com casos que exigem bloqueio. | Anatomia de um agente de desenvolvimento de negócios: do pro |
| Mudanças no prompt alteram o comportamento sem rastreabilidade. | Prompt não versionado ou não controlado por Git. | Implemente cabeçalho de versão e controle de código imediatamente. | Anatomia de um agente de desenvolvimento de negócios: do pro |
| Logs ausentes ou incompletos. | Tracing não ativado ou diretório de logs com permissão inadequada. | Ative o tracing e ajuste permissões de escrita no diretório. | Anatomia de um agente de desenvolvimento de negócios: do pro |
| Erro 401 ou 403 ao chamar API | Chave de API inválida ou ausente | Verifique variáveis de ambiente e permissões da chave | APIs, SDKs e MCP: costurando agentes, ferramentas e orquestr |
| Latência alta ou timeouts em chamadas WebSocket | Rede instável ou endpoint incorreto | Confirme URL, portas e qualidade da conexão | APIs, SDKs e MCP: costurando agentes, ferramentas e orquestr |
| SDK Python não encontra função desejada | Versão desatualizada do SDK | Atualize com 'pip install --upgrade' e consulte a documentação | APIs, SDKs e MCP: costurando agentes, ferramentas e orquestr |
| A ferramenta executa mesmo sem aprovação. | O hook não está associado corretamente ou não lança exceção na recusa. | Verifique a associação do hook e se a exceção é lançada no caminho de recusa. | Aprovação humana obrigatória: hooks e permissões do Claude A |
| O agente trava aguardando aprovação. | O método de aprovação está bloqueando o fluxo ou não há integração com workflow externo. | Implemente mecanismo assíncrono ou integração adequada para ambientes sem terminal. | Aprovação humana obrigatória: hooks e permissões do Claude A |
| O tracing não registra eventos de aprovação. | O Tracer não foi chamado no hook ou não está configurado. | Inclua chamadas explícitas ao Tracer dentro do hook. | Aprovação humana obrigatória: hooks e permissões do Claude A |
| Output do LLM não corresponde ao esperado | Prompt de sistema mal definido ou ferramenta MCP com contrato inconsistente | Revise o prompt e os contratos de entrada/saída das ferramentas. | Arquitetura de agentes jurídicos: Claude, OpenAI, ElevenLabs |
| Áudio ou vídeo não gerado | Chave de API inválida ou parâmetros obrigatórios ausentes | Verifique as credenciais e os campos obrigatórios nas chamadas à ElevenLabs ou HeyGen. | Arquitetura de agentes jurídicos: Claude, OpenAI, ElevenLabs |
| Dados pessoais expostos em logs | Falta de anonimização ou excesso de logging | Implemente minimização e anonimização conforme LGPD, revise políticas de logging. | Arquitetura de agentes jurídicos: Claude, OpenAI, ElevenLabs |
| Ação crítica foi executada sem aprovação | Fluxo de handoff não implementado ou bypassado | Rever implementação de handoff e exigir aprovação obrigatória | Arquitetura de agentes para RH: blocos, fluxos e pontos crít |
| Dados pessoais aparecem em logs | Falta de anonimização ou erro de configuração de logging | Ajustar logs para anonimizar ou omitir campos sensíveis | Arquitetura de agentes para RH: blocos, fluxos e pontos crít |
| Agente acessa dados de outro domínio sem permissão | Permissões mal configuradas entre agentes | Reforçar isolamento e revisar contratos de ferramenta | Arquitetura de agentes para RH: blocos, fluxos e pontos crít |
| O agente não extrai decisões da ata | Prompt mal definido ou ambíguo | Revise o prompt para explicitar o formato e os campos obrigatórios | Ata de reunião e encaminhamentos: extração, resumo e acompan |
| Notificações não chegam aos responsáveis | Erro na função de notificação ou integração externa | Teste a função isoladamente e valide os parâmetros de envio | Ata de reunião e encaminhamentos: extração, resumo e acompan |
| Encaminhamentos não são atualizados após conclusão | Falta de integração entre agente e sistema de tarefas | Implemente sincronização ou atualização manual do status | Ata de reunião e encaminhamentos: extração, resumo e acompan |
| A IA responde com informações erradas ou inventadas | Prompt de sistema pouco claro ou ferramenta sem contrato rígido | Reforce as instruções no prompt e use contratos Pydantic para entrada e saída | Atendimento automatizado: IA que resolve sem enrolar |
| A IA nunca aciona handoff, mesmo quando deveria | Falta de regra de handoff ou guardrail mal configurado | Implemente e teste explicitamente os gatilhos de handoff | Atendimento automatizado: IA que resolve sem enrolar |
| Logs não registram interações corretamente | Falta de logging estruturado ou erro no código de registro | Implemente logging com formato JSON e teste cada fluxo | Atendimento automatizado: IA que resolve sem enrolar |
| Respostas lentas | Função de consulta de dados ineficiente ou timeout baixo no SDK | Otimize a consulta e ajuste timeouts conforme a documentação | Atendimento automatizado: IA que resolve sem enrolar |
| A resposta do agente demora mais de 2 segundos | Latência de rede ou uso de modelo TTS não otimizado | Troque para modelo eleven_flash_v2_5 ou otimize a rota de rede | Atendimento telefônico automatizado em uma rede de fibra ded |
| O ASR transcreve palavras erradas | Ruído de fundo ou sotaque regional não previsto | Ajuste o prompt para pedir confirmação ou teste outro modelo ASR | Atendimento telefônico automatizado em uma rede de fibra ded |
| O áudio não chega ao cliente | Erro de configuração no gateway SIP ou endpoint TTS | Verifique logs do gateway e a URL de destino | Atendimento telefônico automatizado em uma rede de fibra ded |
| Respostas incoerentes após atualização | Modelo novo incompatível ou embeddings não atualizados | Reverta para o modelo anterior e reindexe novamente | Atualização contínua de modelos e índices |
| Documentos recentes não aparecem nas buscas | Reindexação incremental falhou ou polling não detectou mudanças | Execute reindexação completa e revise lógica de detecção | Atualização contínua de modelos e índices |
| Rollback não restaura dados corretamente | Snapshot corrompido ou não atualizado | Valide snapshots periodicamente e automatize testes de restauração | Atualização contínua de modelos e índices |
| Modelo não aparece na lista do Ollama após criação | Nome ou tag inválida, ou erro no Modelfile | Revise o comando e o Modelfile; consulte logs do Ollama | Atualização e versionamento de modelos e dados |
| Coleção antiga do Qdrant não é encontrada | Nome incorreto ou exclusão acidental | Confirme nomes via API e restaure backup se necessário | Atualização e versionamento de modelos e dados |
| Rollback não retorna comportamento esperado | Dados ou modelo não correspondem à versão apontada | Valide configurações e histórico de mudanças | Atualização e versionamento de modelos e dados |
| Decisões do agente não aparecem nos logs | Tracing não está ativado ou log_dir incorreto | Revisar configuração do enable_tracing e permissões do diretório de logs | Auditoria contínua: mantendo justiça e transparência ao long |
| Testes automatizados não bloqueiam deploy mesmo com falhas | Pipeline de CI não está configurado para interromper em caso de erro | Ajustar configuração do pipeline para falhar em caso de teste não aprovado | Auditoria contínua: mantendo justiça e transparência ao long |
| Alterações de prompt não aparecem no histórico | Commits não estão sendo feitos para cada mudança | Obrigar commit e justificativa para toda alteração de prompt ou critério | Auditoria contínua: mantendo justiça e transparência ao long |
| Logs não estão sendo gerados | Permissões incorretas nos diretórios de log ou erro na configuração do logger | Ajuste permissões e revise a configuração do log_format ou do handler Python | Auditoria e compliance em LLMs locais |
| Dados sensíveis aparecem nos logs | Função de mascaramento ausente ou mal implementada | Implemente e teste a função de anonimização antes do registro | Auditoria e compliance em LLMs locais |
| Logs antigos não são removidos | Configuração incorreta do logrotate ou falta de permissão para apagar arquivos | Revise a configuração do logrotate e permissões do diretório | Auditoria e compliance em LLMs locais |
| Log incompleto ou ausente | Tracing não implementado ou não chamado em todos os fluxos | Garanta que todo início de execução abre uma sessão de tracing e todas as ações relevantes são logadas | Auditoria e ética em agentes comerciais: como não virar manc |
| Decisão crítica tomada sem revisão | Guardrail ausente ou mal configurado | Reforce validações e adicione testes automatizados para cenários de exceção | Auditoria e ética em agentes comerciais: como não virar manc |
| Chave de API exposta em log | Uso de string literal ou interpolação insegura | Revise o código para garantir que segredos só vêm de variáveis de ambiente e nunca são logados | Auditoria e ética em agentes comerciais: como não virar manc |
| O agente executou ação irreversível sem aprovação | Prompt ou workflow mal configurado | Reforce limites no prompt e revise o fluxo de aprovação | Auditoria e ética em IA tributária: limites do agente e resp |
| Logs incompletos ou ausentes | Tracer não configurado corretamente | Verifique caminho do log e permissões de escrita | Auditoria e ética em IA tributária: limites do agente e resp |
| Dados pessoais expostos em registros | Falta de minimização e anonimização | Implemente filtros e revise campos registrados | Auditoria e ética em IA tributária: limites do agente e resp |
| Logs não aparecem no arquivo | Permissão de escrita insuficiente ou configuração errada do logging | Ajuste permissões do diretório e revise o caminho do arquivo no logging. | Auditoria e rastreabilidade: como registrar tudo sem travar |
| Arquivo de log cresce demais | Falta de rotação ou retenção indefinida | Implemente rotação automática com logrotate ou scripts agendados. | Auditoria e rastreabilidade: como registrar tudo sem travar |
| Dados pessoais sensíveis nos logs | Falta de mascaramento ou filtragem nos eventos registrados | Implemente funções para anonimizar ou omitir dados sensíveis antes de registrar. | Auditoria e rastreabilidade: como registrar tudo sem travar |
| Recebe 401 mesmo com usuário e senha corretos | Senha ou usuário configurados incorretamente ou codificação errada na requisição | Revise variáveis e formato da requisição HTTP Basic. | Autenticação e autorização: protegendo pipelines e APIs Hays |
| Token JWT sempre rejeitado | Chave secreta ou algoritmo incompatível entre emissor e API | Confirme chave e algoritmo usados no JWT. | Autenticação e autorização: protegendo pipelines e APIs Hays |
| Proxy não autentica ou bloqueia requisições | Caminho do htpasswd ou regras de proxy incorretas | Verifique caminhos e sintaxe do arquivo de configuração do proxy. | Autenticação e autorização: protegendo pipelines e APIs Hays |
| Agente acessa dados de outro ambiente | Chave de API compartilhada entre ambientes | Separe as chaves e restrinja o escopo. | Autenticação, autorização e segregação entre agentes |
| Chave de API vazada em log ou erro | Falta de sanitização de logs | Nunca registre segredos em logs ou mensagens de erro. | Autenticação, autorização e segregação entre agentes |
| Agente executa comando não autorizado | Ferramenta perigosa registrada por engano | Revise a lista de ferramentas e use guardrails. | Autenticação, autorização e segregação entre agentes |
| Logs não mostram tentativas de acesso negado | Monitoramento insuficiente | Ative logs detalhados e revise configurações de auditoria. | Autenticação, autorização e segregação entre agentes |
| O agente não escala para o humano mesmo em incidentes críticos | Critérios de escalonamento mal definidos ou não implementados no prompt | Revise o prompt e os guardrails, garanta que as condições estejam explícitas | Automação assistida: limites e quando parar para o humano de |
| Decisões automatizadas não aparecem no log | Função de registro não chamada ou erro de permissão no diretório de log | Verifique permissões e chamadas da função registrar_decisao | Automação assistida: limites e quando parar para o humano de |
| Auditoria mostra decisões sem justificativa clara | Agente não está preenchendo o campo de justificativa | Inclua geração de justificativa obrigatória no fluxo do agente | Automação assistida: limites e quando parar para o humano de |
| Serviço não sobe após reinício | Permissões incorretas no volume | Ajuste permissões com 'chown' no host | Automação de deploy com Docker Compose |
| Dados sumiram após restart | Volume não nomeado ou mapeado incorretamente | Revise a seção 'volumes' no docker-compose.yml | Automação de deploy com Docker Compose |
| Erro de conexão entre serviços | Variáveis de ambiente de host mal configuradas | Corrija os nomes dos hosts nos envs | Automação de deploy com Docker Compose |
| Erro de autenticação ao chamar a API | Chave de API ausente ou inválida na variável de ambiente | Verifique se a variável está definida e a chave é válida | Automação de fluxos: scripts e orquestração com Python |
| Resposta vazia ou inesperada da IA | Prompt mal formulado ou modelo inadequado | Revise o prompt e escolha o modelo correto para a tarefa | Automação de fluxos: scripts e orquestração com Python |
| Dados não aparecem na planilha | Erro na integração com a API da planilha ou permissão insuficiente | Confirme credenciais e permissões de escrita na planilha | Automação de fluxos: scripts e orquestração com Python |
| O rollout não aplica mudanças no cluster | Sincronizador não está configurado corretamente ou não tem acesso ao repositório | Verifique logs do Argo CD/Flux e permissões do Git | Automação de rollout e rollback com GitOps |
| Rollback não acontece após falha | Pipeline de automação de rollback não está integrado ao alerta | Confirme integração entre Prometheus, webhook e Git | Automação de rollout e rollback com GitOps |
| Estado do cluster diverge do Git | Mudanças manuais feitas via kubectl | Sempre aplique mudanças via GitOps e reforce reconciliação automática | Automação de rollout e rollback com GitOps |
| A rotina não dispara no horário agendado | Scheduler não iniciado ou conflito de horário | Verifique se o scheduler está ativo e se o horário está correto | Automação de rotinas: gatilhos, agendamentos e exceções |
| E-mails não são processados | Filtro de gatilho incorreto ou falha na leitura da caixa | Revise a condição do gatilho e as permissões de acesso ao e-mail | Automação de rotinas: gatilhos, agendamentos e exceções |
| Exceções não aparecem nos logs | Tratamento de erro ausente ou registro incompleto | Implemente captura de exceções e logging detalhado | Automação de rotinas: gatilhos, agendamentos e exceções |
| Testes não são executados no pipeline | Caminho dos testes está incorreto ou pytest não instalado | Verifique o caminho e instale pytest com 'pip install pytest' | Automação de testes e deploy: cada alteração, um ciclo de va |
| Deploy executa mesmo com testes falhando | Script de deploy não verifica status dos testes | Implemente checagem do retorno dos testes antes do deploy | Automação de testes e deploy: cada alteração, um ciclo de va |
| Rollback não reverte o estado do agente | Rollback só reverte código, não configurações externas | Inclua configurações e assets no controle de versão | Automação de testes e deploy: cada alteração, um ciclo de va |
| Logs de release não aparecem | Script de deploy não salva logs | Adicione salvamento de logs ao pipeline | Automação de testes e deploy: cada alteração, um ciclo de va |
| Testes falham após alteração de prompt | Critérios de avaliação desatualizados ou prompt mudou estrutura da saída | Atualize os casos de teste e critérios de validação para refletir o novo comportamento aprovado | Automação de testes e regressão: crescer sem quebrar |
| Saídas variam demais entre execuções | Prompt pouco determinístico ou ausência de critérios objetivos | Refine o prompt e os critérios de avaliação para reduzir ambiguidade | Automação de testes e regressão: crescer sem quebrar |
| Testes não rodam no pipeline CI | Dependências não instaladas ou variáveis de ambiente ausentes | Garanta que requirements.txt e variáveis estejam configurados no ambiente de CI | Automação de testes e regressão: crescer sem quebrar |
| Testes automáticos falham mesmo com dados corretos | Mudança não versionada no prompt ou ferramenta; dados de teste desatualizados | Revisar versionamento e alinhar dados de teste ao código e prompt atuais | Automação de testes e validação contínua: sem falhas no proc |
| Falhas não são notificadas | Configuração de alerta ou log ausente | Implementar webhook, e-mail ou dashboard para alertas automáticos | Automação de testes e validação contínua: sem falhas no proc |
| Guardrails bloqueiam entradas válidas | Esquema de validação muito restritivo ou erro de configuração | Revisar input_schema/output_schema e ajustar faixas permitidas | Automação de testes e validação contínua: sem falhas no proc |
| Testes automatizados falham após alteração de prompt | Prompt incompatível com lógica do agente ou dados de teste desatualizados | Revise o prompt, ajuste os dados de teste e reexecute os testes | Automação de testes, deploy e rollback: agentes sob controle |
| Rollback não restaura comportamento anterior | Versionamento inconsistente ou rollback incompleto | Garanta que todos os arquivos de prompt e código estejam versionados e restaurados | Automação de testes, deploy e rollback: agentes sob controle |
| Monitoramento não registra execuções | Tracing não ativado ou integração com logs falhou | Verifique configuração do tracer e integração com ferramenta de logs | Automação de testes, deploy e rollback: agentes sob controle |
| Documentos não aparecem na coleção do Qdrant | Falha na autenticação ou endpoint incorreto | Confirme host, porta e credenciais do Qdrant | Automatizando ingestão de dados para RAG com Python |
| Embeddings vazios ou todos iguais | Erro no carregamento do modelo de embeddings | Revalide o caminho e a versão do modelo | Automatizando ingestão de dados para RAG com Python |
| Script para de rodar após um ciclo | Loop de agendamento não implementado corretamente | Garanta que o laço while esteja ativo e sem exceções não tratadas | Automatizando ingestão de dados para RAG com Python |
| Ajustes automáticos não são aplicados mesmo com dados corretos | Gatilhos ou guardrails estão restritivos demais | Revise os critérios e limites definidos nos guardrails | Automatizando replanejamento com dados reais: ciclo fechado |
| Ajustes são aplicados sem registro ou aprovação | Falta de implementação de feedback e workflow de aprovação | Implemente registro detalhado e revise o fluxo de aprovação | Automatizando replanejamento com dados reais: ciclo fechado |
| Dados coletados estão desatualizados | Integração com sistema de origem falhou ou está em cache | Verifique a atualização e a fonte dos dados na ferramenta de coleta | Automatizando replanejamento com dados reais: ciclo fechado |
| Teste sempre falha mesmo com dados corretos | Critério de aprovação mal definido ou divergente do esperado | Revise as regras de aprovação e os dados de teste | Automatizando testes e avaliações: como garantir que a IA en |
| Saída da IA incompleta ou inconsistente | Prompt de sistema mal especificado ou dados sintéticos pouco realistas | Ajuste o prompt e diversifique os casos de teste | Automatizando testes e avaliações: como garantir que a IA en |
| Logs não registram todas as execuções | Erro de configuração no tracing ou no salvamento dos resultados | Verifique permissões e caminhos de log | Automatizando testes e avaliações: como garantir que a IA en |
| Teste demora demais para rodar | Casos de teste excessivamente complexos ou modelo lento | Simplifique os casos ou use modelos mais rápidos para teste | Automatizando testes e avaliações: como garantir que a IA en |
| Teste automatizado falha inesperadamente | Mudança no prompt ou ferramenta alterou o comportamento do agente | Revisar o prompt, atualizar o caso de teste ou ajustar a ferramenta para alinhar ao contrato | Automatizando testes e avaliações: garantir que o agente não |
| Guardrail bloqueia entrada legítima | Validação muito restritiva ou termo proibido mal definido | Ajustar a função de guardrail para permitir exceções necessárias | Automatizando testes e avaliações: garantir que o agente não |
| Cobertura dos testes é baixa | Casos de teste insuficientes ou não representativos | Adicionar mais casos cobrindo cenários reais e extremos | Automatizando testes e avaliações: garantir que o agente não |
| Pipeline trava na etapa de deploy | Faltam variáveis de ambiente ou credenciais | Configure as variáveis de ambiente corretamente no ambiente CI/CD | Automatizando testes e deploy: CI/CD para agentes tributário |
| Rollback não restaura a versão anterior | Tag ou imagem da versão anterior não foi salva | Implemente registro automático da versão anterior a cada deploy | Automatizando testes e deploy: CI/CD para agentes tributário |
| Testes de prompt falham mesmo sem alteração | Casos de teste desatualizados ou dependentes de contexto externo | Atualize os casos de teste e isole dependências externas | Automatizando testes e deploy: CI/CD para agentes tributário |
| Deploy libera código com erro crítico | Cobertura de testes insuficiente | Aumente a cobertura dos testes e revise os critérios de aprovação | Automatizando testes e deploy: CI/CD para agentes tributário |
| Teste falha mesmo sem alteração de código | Dependência externa mudou ou prompt foi alterado sem atualizar teste | Atualize os casos de teste ou reverta alteração no prompt | Automatizando testes e validação: regressão contínua para ag |
| Pipeline CI/CD não executa os testes | Workflow mal configurado ou arquivo de testes fora do padrão | Verifique nome e localização dos arquivos de teste e configuração do pipeline | Automatizando testes e validação: regressão contínua para ag |
| Resultados inconsistentes entre execuções | Dados de entrada não isolados ou uso de variáveis aleatórias | Garanta que todos os testes usem dados EXEMPLO fixos | Automatizando testes e validação: regressão contínua para ag |
| Vídeo não é gerado ou fica com status 'failed' | Parâmetros inválidos ou áudio/script incompatíveis na HeyGen | Revise campos obrigatórios e formatos aceitos na requisição | Automatizando trilhas de treinamento: vídeo, voz e avaliação |
| Áudio gerado sem voz ou com idioma errado | Voice_id ou model_id incompatíveis na ElevenLabs | Confirme que o voice_id suporta português e o modelo está correto | Automatizando trilhas de treinamento: vídeo, voz e avaliação |
| Resultado do teste não é registrado no PDC | Falha na integração MCP ou erro de autenticação | Verifique logs de integração e credenciais de acesso | Automatizando trilhas de treinamento: vídeo, voz e avaliação |
| Testes automatizados falham sem motivo aparente | Mudança no prompt ou no modelo sem atualizar os testes | Revise e atualize os casos de teste conforme a nova versão do prompt | Avaliação automática e revisão humana: IA auditável e confiá |
| Ações críticas são executadas sem revisão | Pipeline não identifica corretamente decisões sensíveis | Ajuste a lógica de detecção e encaminhamento para revisão humana | Avaliação automática e revisão humana: IA auditável e confiá |
| Logs de tracing expõem dados pessoais | Falta de anonimização ou filtragem de logs | Implemente anonimização e revise o que é registrado | Avaliação automática e revisão humana: IA auditável e confiá |
| Teste automatizado falha inesperadamente | Mudança no prompt ou ferramenta não coberta pelo teste | Atualize os testes para refletir a nova lógica | Avaliação automatizada e revisão contínua: o ciclo virtuoso |
| Logs incompletos ou ausentes | Configuração de logging inadequada | Revise o setup do logger e paths de arquivo | Avaliação automatizada e revisão contínua: o ciclo virtuoso |
| Decisão crítica executada sem revisão | Falta de checagem de status 'pending' | Implemente validação obrigatória antes de executar ações irreversíveis | Avaliação automatizada e revisão contínua: o ciclo virtuoso |
| Teste automatizado falha após alteração de prompt | Prompt incompatível com o caso de teste | Rever prompt e ajustar para cobrir todos os casos previstos | Avaliação automatizada e revisão contínua: operando no limit |
| Logs não registram execuções de agente | Tracing não ativado ou mal configurado | Habilitar tracing no SDK e revisar configuração | Avaliação automatizada e revisão contínua: operando no limit |
| Ferramenta retorna erro inesperado | Contrato da ferramenta mudou sem atualizar casos de teste | Atualizar casos de teste e revisar documentação da ferramenta | Avaliação automatizada e revisão contínua: operando no limit |
| O teste falha mesmo com saída aparentemente correta | Critério de validação muito restritivo ou dependente de igualdade exata | Ajuste a função de validação para aceitar variações relevantes | Avaliação automatizada: casos de teste que garantem operação |
| Tempo de resposta alto nos testes | Modelo escolhido é mais lento ou há gargalo de rede | Troque para um modelo mais rápido ou revise a infraestrutura | Avaliação automatizada: casos de teste que garantem operação |
| Logs de tool use ausentes | Configuração do agente não está habilitando tracing | Ative o tracing no SDK e revise permissões | Avaliação automatizada: casos de teste que garantem operação |
| O agente retorna erro ou exceção em alguns casos de teste | Formato de entrada inesperado ou bug na ferramenta | Inclua casos de exceção e normalize entradas antes do processamento | Avaliação automatizada: casos de teste, métricas e revisão c |
| Precisão ou recall abaixo do esperado | Prompt desatualizado ou ferramenta com erro de lógica | Revise o prompt, ajuste a ferramenta e reavalie | Avaliação automatizada: casos de teste, métricas e revisão c |
| Resultados diferentes a cada rodada sem alteração no código | Agente sem controle de temperatura ou dados não determinísticos | Fixe parâmetros e use dados de teste estáveis | Avaliação automatizada: casos de teste, métricas e revisão c |
| Teste automatizado falha após atualização do modelo | Mudança no estilo ou formato da resposta do modelo | Ajuste o critério de aprovação ou o prompt para alinhar o comportamento. | Avaliação automatizada: como garantir que o agente faz o que |
| Respostas inconsistentes entre execuções | Falta de seed ou controle de aleatoriedade no agente | Configure o agente para comportamento determinístico durante os testes. | Avaliação automatizada: como garantir que o agente faz o que |
| Teste não cobre erro de integração externa | Caso de teste só cobre caminho feliz | Inclua cenários de falha e entradas inválidas nos testes. | Avaliação automatizada: como garantir que o agente faz o que |
| Testes automatizados falham após atualização do prompt | Mudança no prompt alterou o comportamento do agente | Revisar e ajustar o prompt até os testes passarem novamente | Avaliação automatizada: testes, métricas e revisão contínua |
| Tempo de resposta do agente aumentou repentinamente | Modelo mais pesado ou integração externa lenta | Avaliar logs de execução e otimizar chamadas externas | Avaliação automatizada: testes, métricas e revisão contínua |
| Taxa de revisão humana dispara | Aumento de falsos positivos/negativos ou casos não cobertos nos testes | Expandir casos de teste e ajustar regras do agente | Avaliação automatizada: testes, métricas e revisão contínua |
| Teste falha mesmo com resposta aparentemente correta | Critério de aprovação muito rígido (string exata ou regex limitada) | Ajuste o critério para aceitar variações válidas | Avaliação de prompts: casos de teste com resultado esperado |
| Respostas inconsistentes entre execuções | IA é estocástica; não há seed fixa para completions | Use critérios mais flexíveis e múltiplas execuções por teste | Avaliação de prompts: casos de teste com resultado esperado |
| Erro de autenticação na API | Chave de API ausente ou inválida | Configure a variável de ambiente com a chave correta | Avaliação de prompts: casos de teste com resultado esperado |
| Prompts duplicados no log | Cache não implementado ou batch enviado mais de uma vez | Implemente cache e controle de batch_id; evite reenvio sem necessidade | Batch, cache e paralelismo: IA em grande escala sem perder o |
| Respostas fora de ordem ou misturadas | Paralelismo sem controle de contexto ou identificadores únicos | Use prompt_id único e registre logs por prompt | Batch, cache e paralelismo: IA em grande escala sem perder o |
| Arquivo de log corrompido | Vários processos escrevendo no mesmo arquivo sem lock | Implemente lock ou use logs separados por processo | Batch, cache e paralelismo: IA em grande escala sem perder o |
| Erro de limite de tamanho no batch | Arquivo .jsonl excede 256 MB | Divida o lote em arquivos menores | Batch, cache e paralelismo: IA em grande escala sem perder o |
| Latência muito alta mesmo com poucos usuários | Modelo de embedding ou Elasticsearch subdimensionados | Aumente recursos ou otimize configuração do componente afetado | Benchmarking de pipelines: medindo throughput e latência |
| Throughput baixo apesar de CPU ociosa | Gargalo em I/O de disco ou rede | Verifique uso de SSD e configuração de rede | Benchmarking de pipelines: medindo throughput e latência |
| Recall baixo nos testes | Dados de treino insuficientes ou pipeline mal ajustado | Reveja o pipeline e melhore a base de dados anotados | Benchmarking de pipelines: medindo throughput e latência |
| O agente não encontra a ferramenta MCP. | A ferramenta não foi registrada ou está com nome incorreto. | Verifique o registro e o nome da ferramenta MCP no servidor. | Blocos da arquitetura: Claude Agent SDK, OpenAI Agents SDK, |
| Erro de autenticação ao chamar ElevenLabs ou HeyGen. | Chave de API ausente ou inválida. | Confirme se as variáveis de ambiente estão corretas e recarregue o ambiente. | Blocos da arquitetura: Claude Agent SDK, OpenAI Agents SDK, |
| O vídeo não é gerado após o áudio. | Formato de áudio ou parâmetros incompatíveis com HeyGen. | Valide o output_format e os campos exigidos pela API HeyGen. | Blocos da arquitetura: Claude Agent SDK, OpenAI Agents SDK, |
| Respostas irrelevantes ou vagas | Modelos não treinados no domínio jurídico | Ajuste ou treine modelos com dados jurídicos. | Busca semântica em bases jurídicas e compliance |
| Documentos não aparecem nos resultados | Erro na indexação ou configuração do PreProcessor | Revise logs de indexação e parâmetros de split. | Busca semântica em bases jurídicas e compliance |
| Busca lenta ou travando | Backend subdimensionado ou queries mal otimizadas | Ajuste recursos do Elasticsearch e revise parâmetros do retriever. | Busca semântica em bases jurídicas e compliance |
| Busca semântica retorna resultados irrelevantes | Modelo de embedding inadequado ou mal treinado | Troque o modelo por um mais específico ou re-treine com dados do domínio. | Busca semântica vs. busca tradicional: o que muda e por quê |
| Performance ruim na busca vetorial | Indexação de embeddings não otimizada | Ajuste parâmetros do FAISS ou use indexadores apropriados para grandes volumes. | Busca semântica vs. busca tradicional: o que muda e por quê |
| Documentos corretos não aparecem na busca tradicional | Termos diferentes entre consulta e documento | Implemente busca semântica ou amplie o dicionário de sinônimos. | Busca semântica vs. busca tradicional: o que muda e por quê |
| O cache não é acionado e o custo permanece alto. | Diferença mínima no prompt ou nos parâmetros. | Padronize e revise todos os campos enviados, inclusive espaços e pontuação. | Cache de prompt e effort: a mesma tarefa muito mais barata s |
| A resposta do cache está desatualizada após alteração do documento. | O cache só vale para entradas idênticas; qualquer alteração gera nova resposta. | Atualize o prompt e aceite o custo cheio para novas versões. | Cache de prompt e effort: a mesma tarefa muito mais barata s |
| O guardrail recusa tarefas que deveriam ser aceitas. | Hash do prompt calculado de forma inconsistente. | Garanta serialização e normalização idêntica do prompt e parâmetros. | Cache de prompt e effort: a mesma tarefa muito mais barata s |
| Respostas diferentes para prompts idênticos | Cache não considera todos os parâmetros relevantes (modelo, temperatura, etc) | Inclua todos os parâmetros na chave do cache | Cache de prompts e arquivos: reduzir custo sem perder rastre |
| Erro de tamanho ao enviar arquivo | Arquivo excede limite do endpoint | Divida o arquivo ou reduza antes do upload | Cache de prompts e arquivos: reduzir custo sem perder rastre |
| Não consegue auditar requisições antigas | Logs incompletos ou sem IDs únicos | Implemente logs estruturados com IDs e timestamps | Cache de prompts e arquivos: reduzir custo sem perder rastre |
| Erro 400 ao enviar requisição para a API | Input excedeu o limite de tokens ou caracteres do modelo | Reduza o tamanho das fontes ou divida em múltiplas requisições | Cálculo de carga: tokens, contexto e frequência de análise |
| Respostas truncadas ou incompletas | Contexto total ultrapassou o máximo do modelo | Reduza histórico, fontes ou tamanho da resposta esperada | Cálculo de carga: tokens, contexto e frequência de análise |
| Latência alta nas análises | Volume de dados ou frequência de análise acima da capacidade do pipeline | Ajuste a frequência ou otimize o processamento das fontes | Cálculo de carga: tokens, contexto e frequência de análise |
| Lembrete não chega ao responsável | Erro na geração de áudio/vídeo ou falha no canal de envio | Verifique logs, credenciais e se o canal está correto. | Calendário de obrigações: agente de lembrete e conferência |
| Obrigações não aparecem para o agente | Problema na leitura do calendário ou datas fora do intervalo | Confirme o acesso à API e o filtro de datas. | Calendário de obrigações: agente de lembrete e conferência |
| Registro de conferência não é salvo | Permissão de escrita insuficiente ou erro no formato do arquivo | Ajuste permissões e valide o JSON. | Calendário de obrigações: agente de lembrete e conferência |
| Calendário com datas inválidas | Prompt de sistema não especifica restrições de datas | Ajuste o prompt para incluir regras de datas e reexecute | Calendário editorial automatizado: do briefing à publicação |
| Publicação não registrada | Função de publicação não retorna ou não salva o ID | Implemente registro obrigatório do retorno da API | Calendário editorial automatizado: do briefing à publicação |
| Teste automatizado falha sem explicação | Caso de teste mal definido ou entrada fora do padrão | Revise o script de teste e o formato do JSON | Calendário editorial automatizado: do briefing à publicação |
| O vídeo ficou parado, sem ação | Faltou descrever o movimento do sujeito ou da câmera | Inclua no pedido o que o sujeito faz e como a câmera se move | Câmera, movimento e cenário em português simples, do jeito q |
| O fundo não corresponde ao ambiente pedido | Ambiente não foi especificado claramente | Descreva o ambiente de forma concreta, como 'escritório moderno' ou 'parque ao ar livre' | Câmera, movimento e cenário em português simples, do jeito q |
| Movimento de câmera inesperado | Não foi especificado o tipo de movimento | Peça explicitamente: 'câmera parada', 'câmera acompanha de lado', etc. | Câmera, movimento e cenário em português simples, do jeito q |
| Um dos vídeos saiu com cor ou luz diferente dos outros | Referência de estilo inconsistente ou instrução ambígua | Envie novamente as mesmas styleImages e peça alinhamento visual | Campanha inteira: a mesma direção em vários formatos, pedida |
| Formato ou proporção errada em algum vídeo | Pedido de formato não ficou claro para a IA | Reforce a proporção e resolução desejada no pedido | Campanha inteira: a mesma direção em vários formatos, pedida |
| Mensagem ou ritmo variam entre os vídeos | Direção criativa diferente por formato | Unifique o campo userConcept para todos os vídeos | Campanha inteira: a mesma direção em vários formatos, pedida |
| Exportação não veio em ProRes ou PNG | Formato não foi pedido explicitamente | Peça novamente especificando o formato de exportação desejado | Campanha inteira: a mesma direção em vários formatos, pedida |
| Vídeo não é gerado no HeyGen | Parâmetros obrigatórios ausentes ou áudio não acessível | Confirme avatar_id, audio_url e formato do payload | Campanha multimídia: texto, voz e vídeo com aprovação e anál |
| Áudio gerado sem voz ou corrompido | voice_id inválido ou texto fora do padrão | Verifique voice_id e limite de caracteres do modelo ElevenLabs | Campanha multimídia: texto, voz e vídeo com aprovação e anál |
| Roteiro não avança para próxima etapa | Falta de aprovação explícita no fluxo | Implemente revisão obrigatória antes de prosseguir | Campanha multimídia: texto, voz e vídeo com aprovação e anál |
| Métricas de campanha não aparecem | Integração com API do canal não configurada | Implemente coleta automática de métricas após publicação | Campanha multimídia: texto, voz e vídeo com aprovação e anál |
| Alertas com atraso excessivo na triagem | Fila de requisições muito grande ou workers insuficientes | Aumente o número de workers ou otimize o processamento | Capacidade, latência e gargalos: dimensionando agentes para |
| Erros 429 ou 500 nas respostas da API | Limite de requisições por segundo excedido | Implemente backoff exponencial e monitore o volume de chamadas | Capacidade, latência e gargalos: dimensionando agentes para |
| Memória do servidor esgota rapidamente | Processamento paralelo sem limitação ou vazamento de memória | Limite o número de processos e monitore uso de recursos | Capacidade, latência e gargalos: dimensionando agentes para |
| Erros 429 (Too Many Requests) | Excesso de requisições simultâneas | Reduza a concorrência e implemente retry com backoff | Capacidade, limites e gargalos: projetando para o volume rea |
| Respostas lentas ou timeouts | Sobrecarga do modelo ou infraestrutura local | Aumente recursos ou distribua a carga | Capacidade, limites e gargalos: projetando para o volume rea |
| Áudios ou vídeos incompletos | Excedeu o limite de caracteres ou duração | Divida o conteúdo em partes menores, respeitando os limites | Capacidade, limites e gargalos: projetando para o volume rea |
| Erro de conexão ao Milvus | Porta informada como string ou host incorreto | Use a porta como inteiro e verifique o endereço do host | Case: assistente de atendimento integrado a múltiplos bancos |
| Campo vetorial não encontrado ao criar índice | Nome do campo diferente do definido na collection | Confirme o nome exato do campo vetorial na collection Milvus | Case: assistente de atendimento integrado a múltiplos bancos |
| Respostas inconsistentes entre bancos | Mapeamento de campos ou tipos incompatíveis | Implemente pós-processamento e padronização dos resultados | Case: assistente de atendimento integrado a múltiplos bancos |
| Latência alta em buscas vetoriais | nprobe muito alto ou embeddings grandes demais | Reduza nprobe ou otimize o tamanho dos embeddings | Case: assistente de atendimento integrado a múltiplos bancos |
| Agent não responde ou trava | Timeout ou erro na API interna | Verifique logs, aumente timeout ou valide a disponibilidade da API. | Case: automação de processos corporativos com chains e agent |
| Dados inconsistentes no resultado | Payloads de entrada malformados ou respostas inesperadas | Valide schemas e implemente tratamento de exceções. | Case: automação de processos corporativos com chains e agent |
| Logs ausentes ou incompletos | Configuração incorreta do logging | Revise o setup do logging e permissões de escrita do arquivo. | Case: automação de processos corporativos com chains e agent |
| Pipeline retorna 500 em todas as requisições | Erro no código do pré-processador ou tokenizador | Verifique logs dos pods e revise endpoints /preprocess e /tokenize. | Case: deploy de modelos NLP com pipelines de pré-processamen |
| Latência total acima do esperado | Pré-processamento ou tokenização ineficiente | Otimize código, use profiling e monitore métricas específicas. | Case: deploy de modelos NLP com pipelines de pré-processamen |
| Métricas não aparecem no Prometheus | Endpoints /metrics não expostos ou scrape_config incorreto | Ajuste o código e revise configuração do Prometheus. | Case: deploy de modelos NLP com pipelines de pré-processamen |
| Erro de permissão ao acessar o bucket S3 | Credenciais do MinIO ausentes ou incorretas no ServiceAccount do modelo | Configure o Secret com as credenciais S3 e vincule ao ServiceAccount usado pelo InferenceService | Case: serving de modelos de visão computacional em larga esc |
| Latency alta nas respostas do modelo | Download lento do arquivo do MinIO | Verifique a rede entre o cluster e o MinIO; use buckets na mesma região | Case: serving de modelos de visão computacional em larga esc |
| Pods não escalam durante pico | Configuração incorreta do autoscaling ou métrica não suportada | Revise o bloco autoscaling do InferenceService e consulte a documentação do KServe | Case: serving de modelos de visão computacional em larga esc |
| O agente toma ações irreversíveis sem revisão | Guardrails ou hooks não configurados corretamente | Revise a implementação dos guardrails/hooks e teste com casos críticos | Casos de teste, avaliação automática e revisão humana: proce |
| Respostas inconsistentes nos testes | Prompt de sistema ou ferramentas mudaram sem atualizar os testes | Versione e atualize os casos de teste sempre que houver mudança | Casos de teste, avaliação automática e revisão humana: proce |
| Logs incompletos ou ausentes | Registro não ativado no SDK ou falta de configuração | Habilite tracing/logs detalhados e valide nos testes | Casos de teste, avaliação automática e revisão humana: proce |
| Teste automático falha sem motivo claro | Critério de aceitação ambíguo ou dependente de contexto externo | Refine os critérios e use mocks para ferramentas externas | Casos de teste, avaliação automática e revisão humana: proce |
| Callback não chega | callback_url inacessível ou bloqueado por firewall | Garanta que o endpoint esteja público e aceite POSTs do HeyGen | Cem vídeos personalizados por cliente em um lote: HeyGen stu |
| Status do vídeo não muda de 'waiting' | Fila de processamento do HeyGen sobrecarregada ou dados inválidos | Revise o payload enviado e aguarde o tempo de processamento | Cem vídeos personalizados por cliente em um lote: HeyGen stu |
| Vídeo retorna status 'failed' | Erro de dados (campo ausente, imagem inválida) ou cena fora do padrão | Valide todos os campos obrigatórios antes do envio | Cem vídeos personalizados por cliente em um lote: HeyGen stu |
| Chamada não é completada | Número inválido ou indisponível | Valide o formato e a disponibilidade dos números antes do disparo | Chamadas em lote por voz: confirmação de entregas e consulta |
| Respostas não são transcritas corretamente | Ruído ou baixa qualidade de áudio | Ajuste o prompt para pedir respostas claras e teste diferentes vozes/modelos | Chamadas em lote por voz: confirmação de entregas e consulta |
| Registros duplicados para o mesmo número | Falta de controle de repetição | Implemente o guardrail de bloqueio por histórico de chamadas | Chamadas em lote por voz: confirmação de entregas e consulta |
| Sessão fica em 'in_progress' indefinidamente | Problema na telefonia ou timeout | Monitore status e configure timeout máximo para sessões | Chamadas em lote por voz: confirmação de entregas e consulta |
| Chatbot responde "não sei" para tudo | Documentação não foi ingerida corretamente ou embeddings não foram criados. | Verifique logs do script de ingestão e reindexe os documentos. | Chatbot interno com LLM local: da documentação ao suporte |
| Respostas irrelevantes ou genéricas | Prompt mal construído ou contexto insuficiente. | Ajuste o número de trechos recuperados ou revise o template do prompt. | Chatbot interno com LLM local: da documentação ao suporte |
| Erro de conexão com Qdrant | Serviço Qdrant não está rodando ou porta incorreta. | Inicie o Qdrant e confira a URL e porta no código. | Chatbot interno com LLM local: da documentação ao suporte |
| Prompt enviado contém dados pessoais | Filtro de dados pessoais ausente ou mal configurado | Reforce validação e filtragem antes de montar o prompt | Chaves, segredos e dados pessoais: o que nunca entra no prom |
| Chave de API aparece em logs | Código logando variáveis de ambiente ou prompts completos | Remova logs sensíveis e use mascaramento | Chaves, segredos e dados pessoais: o que nunca entra no prom |
| Ação crítica executada sem revisão | Fluxo de aprovação manual não implementado | Adicione etapa de revisão humana antes da execução | Chaves, segredos e dados pessoais: o que nunca entra no prom |
| Vídeo com cortes bruscos ou movimento estranho | Prompt contradiz pistas visuais ou duração insuficiente | Peça para ajustar o prompt e aumentar a duração | Checagem final: o que revisar antes de publicar a peça |
| Arquivo não abre no destino | Formato ou codec incompatível | Peça exportação em mp4 para web, ProRes para pós-produção ou HDR10 para HDR | Checagem final: o que revisar antes de publicar a peça |
| Áudio distorcido ou com ruído | Referência de áudio ruim ou instrução ambígua | Forneça referência limpa e peça áudio limpo | Checagem final: o que revisar antes de publicar a peça |
| Imagem com artefatos ou borrões | Imagem de entrada de baixa qualidade | Troque a referência por uma de alta resolução | Checagem final: o que revisar antes de publicar a peça |
| Agente retorna erro 400 ao enviar prompt grande | Limite de contexto do modelo ultrapassado | Reduza o tamanho da entrada ou troque para modelo com contexto maior | Checklist de operação segura: erros clássicos e como evitar |
| Saída inesperada em ferramenta | Parâmetro ou retorno fora do contrato | Ajuste o contrato e reforce validação com guardrails | Checklist de operação segura: erros clássicos e como evitar |
| Logs não registram execuções | Tracing desabilitado ou caminho incorreto | Habilite tracing e corrija o caminho do log | Checklist de operação segura: erros clássicos e como evitar |
| Erro de autenticação na API | Chave de API ausente ou inválida | Confirme variável de ambiente e permissões | Checklist de operação segura: erros clássicos e como evitar |
| O agente toma decisão irreversível sem revisão humana. | Falta de implementação do handoff obrigatório. | Adicione verificação de ação crítica e retorno de handoff no código. | Checklist de operação: o que nunca pode faltar em um fluxo m |
| Testes automatizados falham após alteração no prompt. | Mudança não compatível com as ferramentas ou casos de teste. | Ajuste o prompt ou atualize os testes para refletir o novo comportamento. | Checklist de operação: o que nunca pode faltar em um fluxo m |
| Logs e traces não aparecem ou estão incompletos. | Tracing não habilitado ou configuração incorreta de logging. | Revise a configuração de tracing e logging no SDK utilizado. | Checklist de operação: o que nunca pode faltar em um fluxo m |
| O agente faz chamadas não autorizadas a APIs internas. | Permissões excessivas ou contrato de ferramenta mal definido. | Restrinja permissões e revise o contrato das ferramentas expostas. | Checklist de operação: o que revisar antes, durante e depois |
| Dados sensíveis aparecem no log ou saída do agente. | Falta de validação de saída ou erro no prompt. | Implemente guardrails de saída e revise o prompt para evitar vazamento. | Checklist de operação: o que revisar antes, durante e depois |
| Propostas são enviadas sem aprovação humana. | Fluxo de revisão não implementado ou bypassado. | Reforce a revisão obrigatória e audite o fluxo de aprovação. | Checklist de operação: o que revisar antes, durante e depois |
| O agente acessa arquivos não autorizados | Permissões excessivas no arquivo de configuração | Restrinja as permissões em .claude/permissions.json apenas ao necessário | Checklist de produção: o que revisar antes de liberar um age |
| Logs não estão sendo gerados | Tracing não ativado ou caminho de log incorreto | Verifique a chamada de enable_tracing e permissões do diretório | Checklist de produção: o que revisar antes de liberar um age |
| Dados pessoais aparecem em prompts ou logs | Falta de sanitização ou minimização de dados | Implemente filtros para remover dados pessoais antes do registro | Checklist de produção: o que revisar antes de liberar um age |
| O agente acessa dados além do necessário | Permissões mal configuradas ou ausência de minimização | Revise o arquivo de permissões e ajuste para coletar só o essencial | Checklist de produção: o que todo agente de RH precisa antes |
| Logs não aparecem ou estão incompletos | Tracing desativado ou diretório de logs incorreto | Ative tracing e confira o caminho dos logs | Checklist de produção: o que todo agente de RH precisa antes |
| Rollback não restaura o estado anterior | Backups ausentes ou sobrescritos | Implemente versionamento e teste o processo de restauração | Checklist de produção: o que todo agente de RH precisa antes |
| Teste automatizado falha sem motivo aparente | Entrada ou saída do agente mudou | Atualize o caso de teste e revise o prompt de sistema | Checklist de produção: o que todo agente de RH precisa antes |
| Saída do agente não bate com o esperado | Prompt ou ferramenta desatualizados | Revisar versão do prompt e atualizar testes | Checklist do agente fiscal: do prompt ao registro |
| Log não registra parâmetros de entrada | Implementação de logging incompleta | Ajustar função de logging para incluir todos os campos | Checklist do agente fiscal: do prompt ao registro |
| Testes automatizados falham após atualização | Mudança não refletida em todos os casos de teste | Atualizar casos de teste conforme a nova lógica | Checklist do agente fiscal: do prompt ao registro |
| O agente executa ações irreversíveis sem revisão humana. | Falta de etapa obrigatória de aprovação no fluxo. | Inclua checagem de aprovação humana antes de executar ações críticas. | Checklist do RH automatizado: do prompt à revisão humana, se |
| Entradas inválidas passam para o agente. | Guardrails de entrada não implementados ou falhos. | Reforce validações nos decorators ou funções de entrada. | Checklist do RH automatizado: do prompt à revisão humana, se |
| Logs de execução estão incompletos. | Registro automático de execuções não configurado. | Implemente logging estruturado e audite periodicamente. | Checklist do RH automatizado: do prompt à revisão humana, se |
| O agente não responde ou retorna erro de autenticação. | Chave de API ausente ou mal configurada. | Revise as variáveis de ambiente e reinicie o terminal. | Claude Agent SDK e OpenAI Agents SDK: agentes especialistas |
| Ferramenta personalizada não é chamada. | Nome ou assinatura da função incompatível com o contrato esperado. | Confira a documentação do SDK e ajuste a assinatura da função. | Claude Agent SDK e OpenAI Agents SDK: agentes especialistas |
| Sessão não persiste entre execuções. | Persistência não ativada ou diretório de histórico inacessível. | Verifique permissões de escrita e configuração do diretório .claude/ ou Session. | Claude Agent SDK e OpenAI Agents SDK: agentes especialistas |
| O agente não responde ou encerra sem erro. | Chave de API ausente ou inválida. | Confirme a variável ANTHROPIC_API_KEY e tente novamente. | Claude Agent SDK na prática: um agente de suporte interno co |
| Ferramenta não é chamada mesmo com instrução clara. | Descrição da ferramenta insuficiente ou nome conflitante. | Revise nome e descrição das ferramentas e reinicie o agente. | Claude Agent SDK na prática: um agente de suporte interno co |
| Logs de tracing não aparecem. | Diretório de tracing não criado ou permissões insuficientes. | Crie o diretório .claude/tracing/ e ajuste permissões de escrita. | Claude Agent SDK na prática: um agente de suporte interno co |
| O agente não encontra a ferramenta definida. | Nome ou assinatura da ferramenta divergente entre definição e chamada. | Revise o nome e os parâmetros na definição e na chamada do agente. | Claude Agent SDK, OpenAI Agents SDK e MCP: quem faz o quê |
| Erro de autenticação ao chamar API externa. | Variável de ambiente com chave de API ausente ou incorreta. | Confirme o valor e o nome das variáveis de ambiente. | Claude Agent SDK, OpenAI Agents SDK e MCP: quem faz o quê |
| Tracing não aparece nos logs. | Tracing não habilitado ou diretório de logs não acessível. | Habilite tracing no SDK e garanta permissão de escrita no diretório de logs. | Claude Agent SDK, OpenAI Agents SDK e MCP: quem faz o quê |
| O agente não acessa sistemas externos | MCP não configurado ou permissões ausentes | Verifique a configuração do MCP e as permissões das ferramentas. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| Guardrails bloqueiam ações válidas | Validação excessivamente restritiva | Revise as funções de guardrail para aceitar todos os casos de uso previstos. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| Vídeo não é gerado no HeyGen | Parâmetros obrigatórios ausentes ou formato inválido | Confira avatar_id, script e output_format na requisição. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| O agente não executa a ferramenta MCP. | Contrato ou parâmetros incompatíveis com a definição MCP. | Revise o contrato da ferramenta e os parâmetros enviados. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| A voz gerada pelo ElevenAgents está em inglês. | O campo language ou model_id não está configurado para português. | Ajuste para language='pt' e model_id='eleven_multilingual_v2'. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| O vídeo HeyGen não finaliza. | O status permanece 'waiting' ou 'generating' por tempo excessivo. | Verifique se o script está dentro do limite e se os campos obrigatórios foram preenchidos. | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| O agente não executa a ferramenta declarada | Contrato de parâmetros ou retorno inconsistente | Revise a definição da ferramenta e o mapeamento MCP | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| A resposta de voz não corresponde ao texto | Voice_id ou model_id incorretos no ElevenLabs | Confirme os IDs e o idioma suportado | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| O vídeo não é gerado ou fica em status 'waiting' | Parâmetros obrigatórios ausentes ou chave de API inválida | Verifique avatar_id, script e autenticação | Claude Agent SDK, OpenAI Agents SDK, ElevenAgents e HeyGen: |
| O agente ignora parte dos dados do currículo. | Contexto do prompt insuficiente ou instruções vagas. | Reforce as instruções e teste com exemplos variados. | Claude Fable 5.1, GPT-6 Astra e além: o que muda para o RH |
| Respostas incoerentes ou contraditórias. | Ausência de casos de teste ou guardrails fracos. | Implemente validação de saída e amplie os testes automatizados. | Claude Fable 5.1, GPT-6 Astra e além: o que muda para o RH |
| Decisão automatizada sem justificativa. | Prompt de sistema não exige explicação. | Adicione à instrução a obrigatoriedade de justificar cada decisão. | Claude Fable 5.1, GPT-6 Astra e além: o que muda para o RH |
| Agente não executa ferramenta MCP | Contrato de parâmetros incompatível ou handler não implementado corretamente. | Revise a assinatura da função e os tipos dos parâmetros. | Claude Fable 5.1, GPT-6 Astra e MCP: o que muda no NOC de am |
| Saída do agente não corresponde ao esperado | Prompt de sistema ambíguo ou casos de teste insuficientes. | Ajuste o prompt e amplie os testes automatizados. | Claude Fable 5.1, GPT-6 Astra e MCP: o que muda no NOC de am |
| Latência alta em voz ou vídeo | Processamento multimodal ou integração externa lenta. | Otimize o pipeline e priorize formatos leves (ex: Opus, MP3). | Claude Fable 5.1, GPT-6 Astra e MCP: o que muda no NOC de am |
| O agente executa comandos não autorizados | Permissões mal configuradas ou contrato de ferramenta ausente | Revise a lista de ferramentas e contratos, restrinja permissões na configuração do agente | Claude Managed Agents, GPT Agents API e ElevenAgents: o que |
| Respostas fora do contexto ou com erros | Prompt de sistema vago ou testes insuficientes | Refine o prompt, adicione casos de teste e ative avaliação automática | Claude Managed Agents, GPT Agents API e ElevenAgents: o que |
| Falha na integração de voz | Voice_id ou model_id incompatível, ou ausência de idioma suportado | Consulte a documentação ElevenLabs para selecionar parâmetros corretos | Claude Managed Agents, GPT Agents API e ElevenAgents: o que |
| O agente não responde a comandos de folha | Ferramenta não cadastrada ou erro no contrato da função | Revise a lista de ferramentas e os parâmetros exigidos | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| Respostas fora do escopo ou com dados sensíveis | Prompt de sistema mal definido ou guardrails ausentes | Ajuste o prompt e implemente validações de entrada/saída | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| Logs incompletos ou ausência de histórico | Tracing não habilitado ou configuração incorreta | Ative o tracing e revise permissões de registro | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| O agente não executa ferramentas externas. | Ferramentas não configuradas ou permissões ausentes. | Verifique a lista de ferramentas e permissões enviadas na criação do agente. | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| Logs de execução não aparecem no painel. | Tracing não habilitado ou erro de autenticação. | Confirme as credenciais e ative o tracing na configuração do agente. | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| A resposta do agente está fora do esperado. | Prompt de sistema ou casos de teste desatualizados. | Revise o prompt, atualize casos de teste e reavalie o agente. | Claude Managed Agents, OpenAI Agents API e ElevenAgents: o q |
| Erro 401 ao chamar API | Chave de API ausente ou inválida | Verifique variáveis de ambiente e permissões da chave | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê |
| Agente não encontra ferramenta MCP | Contrato MCP não registrado ou mal definido | Revise o registro da ferramenta e o formato dos parâmetros | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê |
| Voz gerada sem áudio ou distorcida | Parâmetros de modelo ou idioma incompatíveis | Ajuste model_id e verifique se o texto está em português | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê |
| Vídeo HeyGen não finaliza | Processamento assíncrono ou erro de configuração | Acompanhe status via GET /v3/videos/{video_id} e revise parâmetros obrigatórios | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê |
| O agente não responde ou trava | Chave de API inválida ou falta de permissão na plataforma | Verifique as variáveis de ambiente e permissões do usuário. | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê no |
| O vídeo não é gerado no HeyGen | Parâmetros obrigatórios ausentes ou avatar_id incorreto | Confirme os campos enviados na requisição e o ID do avatar. | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê no |
| A transcrição de voz está errada | Modelo TTS/ASR inadequado para o idioma ou sotaque | Ajuste o model_id para um compatível com português brasileiro. | Claude, OpenAI, ElevenLabs, HeyGen e MCP: quem faz o quê no |
| ImportError ao rodar scripts | Diretórios não estão no PYTHONPATH ou estrutura de módulos está errada | Adicione src/ ao PYTHONPATH ou corrija os imports relativos | Clean code e organização de projetos LangChain |
| Dependências não encontradas ao rodar | Ambiente virtual não ativado | Ative o ambiente virtual com 'source .venv/bin/activate' | Clean code e organização de projetos LangChain |
| Confusão entre código de produção e testes | Mistura de arquivos de teste e produção | Garanta que tests/ está fora de src/ | Clean code e organização de projetos LangChain |
| Relatório gerado com campos em branco | Indicador não retornou valor ou integração MCP falhou | Verifique se o sistema de indicadores está acessível e se os parâmetros da ferramenta MCP estão corretos | Coleta automatizada de indicadores: do input ao relatório se |
| Execução do agente não ocorre no horário esperado | Agendamento via cron mal configurado | Confirme a sintaxe do cron e o caminho do script Python | Coleta automatizada de indicadores: do input ao relatório se |
| Logs de exceção não são registrados | Falha na rotina de logging ou permissões de escrita insuficientes | Ajuste as permissões do diretório de logs e revise o código de registro | Coleta automatizada de indicadores: do input ao relatório se |
| Métricas não aparecem no Prometheus | Endpoint /metrics não habilitado ou bloqueado | Reinicie o Haystack com --metrics e revise firewall/localhost | Coleta de métricas: monitorando saúde e performance dos pipe |
| Painéis do Grafana vazios | Consulta mal configurada ou fonte de dados errada | Revise as queries e a conexão com o Prometheus | Coleta de métricas: monitorando saúde e performance dos pipe |
| Alertas não disparam | Regras de alerta ausentes ou mal definidas | Revise o arquivo de regras e reinicie o Prometheus | Coleta de métricas: monitorando saúde e performance dos pipe |
| E-mail não chega ao lead | Erro no endereço ou bloqueio do provedor | Verifique o campo 'email' e a reputação do domínio de envio | Comercial: o lead vira proposta com voz e vídeo em dez minut |
| Áudio ou vídeo não correspondem ao lead | Dados do lead trocados ou prompt mal construído | Reveja a montagem do prompt e a validação dos dados de entrada | Comercial: o lead vira proposta com voz e vídeo em dez minut |
| Proposta contém termos proibidos | Falta de guardrail no texto gerado | Implemente checagem automática de termos antes do envio | Comercial: o lead vira proposta com voz e vídeo em dez minut |
| Processo trava na geração de vídeo | API do HeyGen em processamento ou parâmetros inválidos | Monitore o status do vídeo e revise os parâmetros enviados | Comercial: o lead vira proposta com voz e vídeo em dez minut |
| O agente classifica lançamentos de forma inconsistente | Prompt de sistema ambíguo ou não versionado | Reescreva o prompt com instruções claras e salve a versão | Como agentes entendem, decidem e atuam no contábil: laço de |
| Ferramenta retorna erro inesperado | Contrato de ferramenta incompleto ou parâmetros inválidos | Revise a definição da ferramenta e adicione validação de entrada | Como agentes entendem, decidem e atuam no contábil: laço de |
| O agente executa ações irreversíveis sem revisão | Falta de guardrails no prompt ou no código | Implemente revisão humana obrigatória para essas ações | Como agentes entendem, decidem e atuam no contábil: laço de |
| Agente executa ações não permitidas | Guardrails ausentes ou mal configurados | Revise e teste todos os guardrails de entrada e saída | Como cada departamento terá seu curso: visão geral dos próxi |
| Logs incompletos ou ausentes | Tracing não habilitado ou mal implementado | Ative tracing detalhado no SDK e revise a configuração | Como cada departamento terá seu curso: visão geral dos próxi |
| Testes automatizados falham sem motivo claro | Casos de teste mal definidos ou dados inconsistentes | Revise os dados de teste e alinhe com os contratos das ferramentas | Como cada departamento terá seu curso: visão geral dos próxi |
| Pods OOMKilled durante burst | Requests/limits de memória subestimados para o pico | Aumente limits e requests de memória com base no uso máximo observado | Como calcular recursos para workloads imprevisíveis de IA |
| Latência alta durante picos | Provisionamento insuficiente ou escalonamento lento | Ajuste requests e configure autoscaling mais agressivo | Como calcular recursos para workloads imprevisíveis de IA |
| Pods não escalam mesmo com alta demanda | Limite do namespace ou nó atingido | Revise LimitRange, ResourceQuota e a capacidade dos nós | Como calcular recursos para workloads imprevisíveis de IA |
| O agente responde com dados incorretos | Prompt de sistema mal definido ou ferramenta sem teste automatizado | Revisar o prompt e criar casos de teste para cada ferramenta | Como Claude, OpenAI, ElevenLabs, HeyGen e MCP se encaixam no |
| Erro de autenticação nas APIs ElevenLabs ou HeyGen | Token inválido ou variável de ambiente não configurada | Verificar e exportar o token correto | Como Claude, OpenAI, ElevenLabs, HeyGen e MCP se encaixam no |
| O agente não acessa o sistema de folha | Contrato MCP não implementado corretamente ou endpoint inacessível | Revisar a definição MCP e testar o endpoint manualmente | Como Claude, OpenAI, ElevenLabs, HeyGen e MCP se encaixam no |
| Respostas truncadas ou incompletas | Excesso de tokens no contexto ou saída | Reduza histórico ou divida tarefas em múltiplas chamadas | Como dimensionar agentes comerciais: contexto, tokens e para |
| Erros 429 (Too Many Requests) | Excesso de requisições simultâneas à API | Diminua o número de agentes paralelos ou implemente retry com backoff | Como dimensionar agentes comerciais: contexto, tokens e para |
| Latência alta nas respostas | Sobrecarga do modelo ou rede lenta | Otimize prompts, reduza anexos e monitore uso de recursos | Como dimensionar agentes comerciais: contexto, tokens e para |
| Erro de contexto excedido | Prompt, histórico ou anexos grandes demais para o modelo escolhido. | Reduza o contexto, troque para modelo com mais capacidade ou divida a consulta. | Como dimensionar agentes para o tributário: contexto, tokens |
| Respostas lentas ou timeout | Carga de trabalho acima do planejado ou modelo inadequado para o volume. | Implemente fallback para modelo mais rápido ou aumente recursos. | Como dimensionar agentes para o tributário: contexto, tokens |
| Custo acima do previsto | Falta de batch ou cache em consultas repetidas. | Ative batch e cache, revise o fluxo para evitar redundância. | Como dimensionar agentes para o tributário: contexto, tokens |
| Respostas lentas do LLM local | CPU ou RAM insuficiente | Aumente recursos ou reduza concorrência | Como dimensionar LLMs, bancos vetoriais e APIs |
| Busca vetorial lenta | Banco vetorial subdimensionado | Aumente RAM, CPU ou particione dados | Como dimensionar LLMs, bancos vetoriais e APIs |
| Erros 429 nas APIs externas | Limite de requisições excedido | Solicite aumento de quota ou distribua requisições | Como dimensionar LLMs, bancos vetoriais e APIs |
| API interna travando | Poucos workers configurados | Ajuste o número de workers no servidor | Como dimensionar LLMs, bancos vetoriais e APIs |
| Erro de autenticação ao conectar ao banco | Credenciais incorretas ou variáveis de ambiente não carregadas | Verifique variáveis e permissões do usuário | Como LangChain se conecta a bancos, APIs e modelos |
| Timeout ao acessar Milvus | Porta ou host incorretos, firewall bloqueando | Confirme host, porta e regras de firewall | Como LangChain se conecta a bancos, APIs e modelos |
| API REST retorna 401 | Token expirado ou não enviado | Renove o token e revise headers de autenticação | Como LangChain se conecta a bancos, APIs e modelos |
| O serviço não escala mesmo com alto tráfego. | Knative Serving pode não estar instalado ou configurado corretamente. | Verifique pods no namespace knative-serving e consulte os logs do controller. | Como o KServe usa Istio, Knative e sidecars |
| Tráfego não chega ao modelo canário. | Erro na configuração de canaryTrafficPercent ou Istio não injetou o proxy. | Confirme a configuração YAML e se o sidecar Envoy está presente no pod. | Como o KServe usa Istio, Knative e sidecars |
| Logs do modelo não aparecem no sistema centralizado. | Sidecar de logging não está montando o volume corretamente. | Revise o campo podSpec e os mounts entre containers. | Como o KServe usa Istio, Knative e sidecars |
| Resultados divergentes dos casos de teste | Parâmetros de entrada errados ou função de cálculo alterada | Verifique se os valores de entrada e a lógica da função estão corretos e conforme o contrato | Comparação de regimes fiscais: agente simulador com premissa |
| Prompt não está sendo seguido pelo agente | Prompt não carregado corretamente ou sobrescrito em tempo de execução | Confirme que o prompt versionado está sendo usado e não foi alterado | Comparação de regimes fiscais: agente simulador com premissa |
| Registros de simulação ausentes ou incompletos | Tracing desativado ou diretório de logs incorreto | Habilite o tracing no SDK e configure o caminho correto para os logs | Comparação de regimes fiscais: agente simulador com premissa |
| Agente não responde a comandos externos | Função da ferramenta não está registrada corretamente ou erro de permissão no diretório .claude/ | Revise a lista de ferramentas e permissões de arquivos. | Comparativo prático: Claude Agent SDK vs OpenAI Agents SDK n |
| Logs não são gerados | Diretório de logs não existe ou falta permissão de escrita | Crie o diretório manualmente e ajuste permissões. | Comparativo prático: Claude Agent SDK vs OpenAI Agents SDK n |
| Histórico de sessão não é salvo | Configuração de memória ou sessão ausente | Garanta que o parâmetro memory_dir (Claude) ou Session (OpenAI) está configurado. | Comparativo prático: Claude Agent SDK vs OpenAI Agents SDK n |
| Open WebUI não conecta ao Ollama | Variável OLLAMA_API_BASE_URL incorreta ou porta errada | Verifique endereço e porta, ajuste para http://host.docker.internal:11434 | Componentes de uma stack de IA local: Ollama, Open WebUI, Qd |
| Qdrant não responde | Container não iniciado ou porta bloqueada | Confirme status do container e liberação da porta 6333 | Componentes de uma stack de IA local: Ollama, Open WebUI, Qd |
| Python não encontra Ollama | URL da API do Ollama errada no script | Ajuste o endpoint para http://localhost:11434 | Componentes de uma stack de IA local: Ollama, Open WebUI, Qd |
| Logs não aparecem ou estão vazios | Configuração incorreta do logger ou permissão de escrita | Verifique o caminho do arquivo e permissões do sistema operacional | Componentes e integrações: onde cada agente e sistema se enc |
| Agente acessa dados além do necessário | Permissões mal configuradas ou escopo amplo demais | Revise o escopo de dados e restrinja queries e ferramentas | Componentes e integrações: onde cada agente e sistema se enc |
| Proposta enviada sem aprovação | Falta de checagem do campo de aprovação | Inclua validação obrigatória antes do envio | Componentes e integrações: onde cada agente e sistema se enc |
| Chave de API exposta em logs | Uso indevido de variáveis em mensagens de log | Nunca logue variáveis de ambiente ou segredos | Componentes e integrações: onde cada agente e sistema se enc |
| O agent não usa a ferramenta esperada. | Descrição da ferramenta insuficiente ou prompt mal definido. | Revise a descrição da ferramenta e ajuste o prompt para direcionar o agent. | Componentes essenciais: LLMs, chains, agents e ferramentas |
| Erro de conexão com banco de dados. | URI do banco incorreta ou dependências ausentes. | Confirme a URI e instale dependências requeridas (ex: sqlite3). | Componentes essenciais: LLMs, chains, agents e ferramentas |
| Resposta incoerente do LLM. | Modelo inadequado ou prompt genérico. | Teste outro modelo suportado e refine o prompt. | Componentes essenciais: LLMs, chains, agents e ferramentas |
| InferenceService não sai do estado 'Pending' | Problema de storage ou imagem não encontrada | Verifique storageUri e permissões de acesso. | Componentes internos do KServe: Controller, Webhook e Infere |
| Erro 400 ao criar recurso | Validação do Webhook rejeitou o YAML | Revise campos obrigatórios e tipos de dados. | Componentes internos do KServe: Controller, Webhook e Infere |
| Pods do predictor não sobem | Limites de recursos incompatíveis ou imagem inválida | Ajuste requests/limits e confira a imagem. | Componentes internos do KServe: Controller, Webhook e Infere |
| Mensagem de voz não chega ao cliente | Erro na configuração do canal de entrega ou falha na API ElevenLabs | Revisar logs de envio, validar chave de API e checar status da resposta | Comunicação automatizada com clientes: voz, vídeo e pós-inci |
| Vídeo não é processado ou link não aparece | Payload incompleto ou avatar_id/voice_id incorretos na HeyGen | Conferir os campos obrigatórios e aguardar status 'completed' na API | Comunicação automatizada com clientes: voz, vídeo e pós-inci |
| Feedback do cliente não é registrado | Integração com sistema de atendimento falhou ou resposta não foi capturada | Testar fluxo de resposta e revisar integração MCP/CRM | Comunicação automatizada com clientes: voz, vídeo e pós-inci |
| O áudio não é gerado e o arquivo está vazio. | Erro de autenticação ou parâmetros incorretos. | Verifique se a variável de ambiente ELEVEN_API_KEY está definida corretamente e se os parâmetros voice_id e model_id são válidos. | Comunicados em áudio com eleven_v3 e eleven_flash_v2_5: quan |
| O áudio contém voz robótica ou truncada. | Modelo inadequado para o tipo de texto ou texto muito longo para o modelo escolhido. | Use eleven_flash_v2_5 para textos longos ou divida o texto em partes menores. | Comunicados em áudio com eleven_v3 e eleven_flash_v2_5: quan |
| Erro de permissão ao salvar o arquivo. | Diretório de destino sem permissão de escrita. | Execute o script em um diretório com permissões adequadas. | Comunicados em áudio com eleven_v3 e eleven_flash_v2_5: quan |
| A IA retorna erro de autenticação ao acessar o plugin. | Chave de API ausente ou configurada incorretamente. | Verifique se a variável de ambiente está definida e acessível pelo processo. | Conexão com dados externos: uso de MCP e plugins |
| Respostas inconsistentes entre IA e sistema externo. | Contrato do plugin desatualizado ou testes insuficientes. | Atualize o contrato MCP e reforce os testes automatizados. | Conexão com dados externos: uso de MCP e plugins |
| Logs não aparecem ou estão incompletos. | Tracing não habilitado no SDK ou permissões de escrita insuficientes. | Ative tracing no SDK e verifique permissões do diretório de logs. | Conexão com dados externos: uso de MCP e plugins |
| Pod reinicia com OOMKilled | Memória insuficiente nos requests/limits. | Aumente o valor de memory em resources. | Configuração avançada de InferenceService: recursos, timeout |
| Inferência demora ou retorna 504 | Timeout configurado abaixo do tempo real de inferência. | Ajuste o timeout para um valor maior que o tempo médio de inferência. | Configuração avançada de InferenceService: recursos, timeout |
| Alto uso de CPU sem aumento de throughput | maxBatchSize baixo ou batching desativado. | Aumente maxBatchSize ou ative batching se suportado. | Configuração avançada de InferenceService: recursos, timeout |
| A aplicação retorna erro de autenticação ao chamar a API | Variável de ambiente da chave de API não está definida ou está errada | Verifique se a variável correta está carregada no ambiente ativo | Configuração de ambientes: variáveis, segredos e controle de |
| Segredos aparecem em logs ou outputs | Código imprime variáveis sensíveis por engano | Remova prints de variáveis de ambiente; revise logs antes de liberar | Configuração de ambientes: variáveis, segredos e controle de |
| Ambiente de produção usa dados de teste | Arquivos .env ou variáveis foram misturados entre ambientes | Separe arquivos e revise o processo de deploy | Configuração de ambientes: variáveis, segredos e controle de |
| Erro: SSL: certificate verify failed | Certificado sem SAN ou CA inválida | Gere certificado com SAN e use CA correta | Configuração de bancos vetoriais e conexão segura |
| Conexão lenta ou timeouts | Falta de pooling ou excesso de conexões simultâneas | Implemente pool e monitore uso | Configuração de bancos vetoriais e conexão segura |
| Acesso negado para usuário | Permissões ou senha incorretas | Revise usuários e permissões no banco | Configuração de bancos vetoriais e conexão segura |
| Erro de autenticação ao chamar API | Chave de API inválida ou variável de ambiente não carregada | Verifique o valor e o carregamento das variáveis de ambiente. | Configuração dos modelos Claude, OpenAI, ElevenLabs e HeyGen |
| Modelo não encontrado | Model_id incorreto ou não suportado pelo SDK | Confirme o nome exato do modelo conforme documentação oficial. | Configuração dos modelos Claude, OpenAI, ElevenLabs e HeyGen |
| Proposta gerada fora do padrão | Prompt de sistema desatualizado ou não versionado | Atualize e versiona o prompt, refaça os testes. | Configuração dos modelos Claude, OpenAI, ElevenLabs e HeyGen |
| Erro de autenticação ao inicializar agente | Chave de API ausente ou inválida na variável de ambiente | Verifique se a variável está exportada corretamente e a chave é válida | Configuração dos SDKs e autenticação: Claude, OpenAI, Eleven |
| Logs não registram execuções | Tracing não habilitado ou logs direcionados para local incorreto | Ative o tracing e configure corretamente o destino dos logs | Configuração dos SDKs e autenticação: Claude, OpenAI, Eleven |
| Chave de API aparece em logs | Código registra variáveis de ambiente ou exceptions sem filtro | Nunca registre variáveis de ambiente em logs; revise handlers de erro | Configuração dos SDKs e autenticação: Claude, OpenAI, Eleven |
| Erro 'KeyError' ao acessar variável de ambiente | Variável não definida ou nome incorreto. | Defina a variável corretamente no ambiente antes de rodar. | Configuração dos SDKs e variáveis: Claude, OpenAI, ElevenLab |
| Erro de autenticação ao chamar API | Chave de API inválida ou ambiente incorreto. | Verifique se a chave está correta e corresponde ao ambiente (teste ou produção). | Configuração dos SDKs e variáveis: Claude, OpenAI, ElevenLab |
| ImportError ao importar SDK | SDK não instalado ou ambiente virtual não ativado. | Ative o ambiente virtual e reinstale o pacote. | Configuração dos SDKs e variáveis: Claude, OpenAI, ElevenLab |
| Erro de autenticação | Chave de API inválida ou variável de ambiente não carregada | Reveja o valor e exportação da variável, gere nova chave se necessário | Configuração dos SDKs: Claude, OpenAI, ElevenLabs e HeyGen n |
| ImportError ao rodar SDK | Pacote não instalado no ambiente virtual | Ative o ambiente e reinstale com pip | Configuração dos SDKs: Claude, OpenAI, ElevenLabs e HeyGen n |
| Retorno vazio ao listar modelos/vozes | Permissão insuficiente na chave de API | Gere chave com escopo adequado | Configuração dos SDKs: Claude, OpenAI, ElevenLabs e HeyGen n |
| Logs ausentes ou incompletos | Configuração incorreta do módulo logging | Ajuste o logging.basicConfig e revise handlers | Configuração dos SDKs: Claude, OpenAI, ElevenLabs e HeyGen n |
| Erro de autenticação ao rodar o agente | Variável de ambiente não carregada ou chave inválida | Verifique o nome da variável e o conteúdo do arquivo .env | Configuração segura dos SDKs: variáveis de ambiente, segredo |
| Arquivo .env exposto no repositório | Falta de .gitignore ou commit acidental | Adicione ao .gitignore e remova do histórico do git | Configuração segura dos SDKs: variáveis de ambiente, segredo |
| Outro usuário consegue ler os segredos | Permissões do arquivo estão abertas | Aplique chmod 600 no arquivo de segredos | Configuração segura dos SDKs: variáveis de ambiente, segredo |
| Erro de autenticação ao rodar o agente | Chave de API ausente ou variável de ambiente não definida | Verifique se exportou a variável correta e se a chave está válida | Configurando Claude Agent SDK, OpenAI Agents SDK e ElevenLab |
| Agente acessa arquivos fora do diretório permitido | Permissões excessivas ou ausência de restrição no permissions.yaml | Revise o arquivo de permissões e limite os caminhos autorizados | Configurando Claude Agent SDK, OpenAI Agents SDK e ElevenLab |
| Respostas do agente incluem segredos ou dados sensíveis | Prompt ou código expõe variáveis de ambiente por engano | Remova qualquer interpolação de segredos no prompt e revise logs | Configurando Claude Agent SDK, OpenAI Agents SDK e ElevenLab |
| ImportError ao importar um SDK | Pacote não instalado ou ambiente virtual não ativado | Ative o ambiente virtual e reinstale o pacote com pip | Configurando Claude Agent SDK, OpenAI Agents SDK, ElevenLabs |
| Erro de autenticação na API | Chave de API incorreta ou variável de ambiente não carregada | Revise o arquivo .env e recarregue as variáveis | Configurando Claude Agent SDK, OpenAI Agents SDK, ElevenLabs |
| Dados sensíveis aparecem em logs | Logging mal configurado ou segredos vazando em exceptions | Desative logs sensíveis e revise o tratamento de erros | Configurando Claude Agent SDK, OpenAI Agents SDK, ElevenLabs |
| Ambiente de teste acessando dados reais | Arquivo .env errado carregado ou chave de produção usada em teste | Separe arquivos de ambiente e automatize a seleção | Configurando Claude Agent SDK, OpenAI Agents SDK, ElevenLabs |
| O agente tenta usar ferramenta não cadastrada | Função não registrada corretamente no SDK | Verifique o decorador e o registro da função | Configurando ferramentas e conexões externas |
| Retorno inesperado ou erro sem mensagem amigável | Falta de tratamento de exceção ou contrato de saída mal definido | Implemente try/except e padronize o retorno | Configurando ferramentas e conexões externas |
| Logs de auditoria não aparecem | Hook de logging não implementado ou erro de permissão no arquivo | Revise a função de auditoria e permissões do diretório de logs | Configurando ferramentas e conexões externas |
| Modelo não carrega ou trava ao iniciar | Quantização ou contexto acima do suportado pelo hardware | Reduza o contexto ou use quantização menor (ex: Q4_0) | Configurando modelos e parâmetros no Ollama |
| Respostas truncadas ou incompletas | Contexto configurado muito baixo | Aumente o contexto, respeitando os limites do modelo e hardware | Configurando modelos e parâmetros no Ollama |
| Alto uso de RAM mesmo sem uso ativo | Modelos persistentes carregados sem necessidade | Descarregue modelos não utilizados com 'ollama rm' | Configurando modelos e parâmetros no Ollama |
| Buscas lentas ou travando | Timeout baixo ou pool de conexões insuficiente | Aumente timeout e pool conforme a carga | Configurando o Haystack para produção: parâmetros críticos |
| Perda de dados após reinício | Backup não configurado ou persistência local | Implemente backup automático e use volumes persistentes | Configurando o Haystack para produção: parâmetros críticos |
| Resultados inconsistentes após atualização de modelo | Versão do modelo não definida explicitamente | Sempre especifique a versão do modelo no YAML | Configurando o Haystack para produção: parâmetros críticos |
| Áudio gerado sem consentimento registrado | Processo de coleta de consentimento falhou ou não foi implementado | Reforce a exigência de consentimento obrigatório antes da geração | Consentimento, voz clonada e identidade: o que a lei e a éti |
| Usuário não percebe que fala com IA | Aviso de transparência ausente ou insuficiente | Inclua mensagem clara no início da interação | Consentimento, voz clonada e identidade: o que a lei e a éti |
| Logs incompletos ou ausentes | Configuração de logging inadequada | Revise e teste a configuração de logs para cada requisição | Consentimento, voz clonada e identidade: o que a lei e a éti |
| O vídeo corta no meio | Duração insuficiente ou conflito entre prompt e imagem | Peça duração maior e um plano contínuo, sem cortes | Consertos: corte indesejado, câmera agitada e movimento que |
| A câmera balança ou treme | Falta de instrução clara para câmera fixa | Inclua no pedido: câmera fixa, perfeitamente parada | Consertos: corte indesejado, câmera agitada e movimento que |
| O movimento não bate com a imagem | Pistas de movimento na imagem de entrada | Troque a imagem por uma em pose neutra ou peça remoção das pistas | Consertos: corte indesejado, câmera agitada e movimento que |
| O loop não fecha perfeitamente | Primeiro e último quadro diferentes | Peça explicitamente para começar e terminar no mesmo quadro | Consertos: corte indesejado, câmera agitada e movimento que |
| Erro 401 Unauthorized ao chamar API | Chave de API ausente, inválida ou exposta | Verifique variável de ambiente e permissões da chave | Console, API e SDK: caminhos para usar Claude e GPT de verda |
| Resposta vazia ou truncada | Limite de tokens excedido ou parâmetro incorreto | Ajuste max_tokens e revise prompt | Console, API e SDK: caminhos para usar Claude e GPT de verda |
| Arquivo de áudio não é reproduzido | Formato incompatível ou download corrompido | Confirme output_format e rebaixe o arquivo | Console, API e SDK: caminhos para usar Claude e GPT de verda |
| ImportError: No module named 'langchain' | LangChain não instalado ou ambiente virtual não ativado. | Ative o ambiente virtual e rode 'pip install langchain'. | Construindo uma chain simples: do prompt ao resultado |
| Erro de autenticação no LLM | Chave de API não definida ou inválida. | Defina corretamente a variável de ambiente OPENAI_API_KEY. | Construindo uma chain simples: do prompt ao resultado |
| Resposta vazia ou incoerente | Prompt mal formatado ou input errado. | Revise o template do prompt e os parâmetros passados. | Construindo uma chain simples: do prompt ao resultado |
| Erro 400 ao enviar texto ao TTS | Texto excede o limite do modelo escolhido | Divida o texto ou troque para um modelo com limite maior | Consumo de voz e vídeo: ElevenLabs e HeyGen na mesma API |
| Áudio ou vídeo retornam vazios | Chave de API inválida ou formato de resposta incorreto | Verifique variáveis de ambiente e cabeçalhos | Consumo de voz e vídeo: ElevenLabs e HeyGen na mesma API |
| Webhook não recebe notificação da HeyGen | URL do webhook inacessível ou não registrado corretamente | Confirme a URL, portas abertas e registro do webhook na requisição | Consumo de voz e vídeo: ElevenLabs e HeyGen na mesma API |
| Opção de adicionar Runway não aparece | Integração bloqueada pelo administrador | Solicite ao administrador a liberação do app Runway com a URL oficial | Conta de empresa: o que pedir ao ChatGPT e o que pedir ao ad |
| ChatGPT pede chave de API | Configuração incorreta ou app não oficial | Peça ao administrador garantir que o app Runway foi adicionado corretamente, sem exigir chave | Conta de empresa: o que pedir ao ChatGPT e o que pedir ao ad |
| Após liberação, app não aparece para todos | Administrador liberou só para parte dos usuários | Confirme com o administrador se o grupo correto recebeu acesso | Conta de empresa: o que pedir ao ChatGPT e o que pedir ao ad |
| Erro de autenticação na conta Runway | Problema de login ou permissão na conta Runway | Verifique se a conta Runway está ativa e tem créditos suficientes | Conta de empresa: o que pedir ao ChatGPT e o que pedir ao ad |
| O agente executa ações não previstas no prompt | Prompt de sistema vago ou sem limites explícitos | Reescreva o prompt detalhando limites e exemplos do que não pode ser feito | Contratos de agente: prompt de sistema, ferramentas e casos |
| Ferramenta aceita parâmetros inválidos | Falta de validação de tipos ou formatos nos contratos das funções | Implemente validação rigorosa dos parâmetros de entrada | Contratos de agente: prompt de sistema, ferramentas e casos |
| Testes automatizados falham sem motivo claro | Casos de teste mal definidos ou inconsistência entre código e contrato | Revise os casos de teste e alinhe com o contrato da ferramenta | Contratos de agente: prompt de sistema, ferramentas e casos |
| O agente tenta chamar uma ferramenta inexistente | Contrato de ferramenta não registrado ou nome divergente | Revise a lista de ferramentas e garanta que todas estão declaradas no SDK | Contratos de ferramenta e casos de teste: como garantir que |
| Testes automáticos falham em entradas inválidas | Faltam validações de parâmetro ou tratamento de erro | Inclua validação explícita nos contratos e nos testes | Contratos de ferramenta e casos de teste: como garantir que |
| Logs de execução não aparecem | Tracing não ativado ou configuração incorreta | Verifique se o parâmetro trace=True está presente na chamada do runner | Contratos de ferramenta e casos de teste: como garantir que |
| A ferramenta aceita dados fora do padrão | Faltam validações no contrato ou no código | Inclua validações explícitas para cada parâmetro | Contratos de ferramenta: como definir entradas, saídas e lim |
| O agente retorna dados incompletos | Contrato de saída mal definido | Especifique todos os campos obrigatórios no retorno | Contratos de ferramenta: como definir entradas, saídas e lim |
| A IA executa ação proibida | Guardrail ausente ou mal implementado | Implemente limites e revisão humana para ações críticas | Contratos de ferramenta: como definir entradas, saídas e lim |
| Função não aparece para o agente | Assinatura sem tipos explícitos ou falta de docstring | Adicione tipos e docstring detalhada | Contratos de ferramenta: especificando funções, parâmetros e |
| Erro de validação ao rodar o agente | Retorno fora do padrão definido no modelo | Ajuste a função para retornar exatamente o esperado | Contratos de ferramenta: especificando funções, parâmetros e |
| Agente ignora parâmetro opcional | Valor padrão não definido na assinatura | Defina valor padrão para parâmetros opcionais | Contratos de ferramenta: especificando funções, parâmetros e |
| Exceção não documentada causa falha silenciosa | Faltou descrever exceções na docstring | Documente todas as exceções possíveis | Contratos de ferramenta: especificando funções, parâmetros e |
| A ferramenta retorna erro inesperado mesmo com parâmetros corretos | Validação de tipo ou faixa está mais restritiva do que o contrato | Revise as restrições e alinhe com o contrato publicado | Contratos de ferramenta: parâmetros, retornos e limites para |
| O agente ignora erros e segue o fluxo | Retorno de erro não está sendo tratado explicitamente pelo agente | Implemente tratamento obrigatório para campo 'erro' | Contratos de ferramenta: parâmetros, retornos e limites para |
| Entradas inválidas não geram erro | Validação insuficiente nos parâmetros de entrada | Reforce validação com Pydantic ou lógica adicional | Contratos de ferramenta: parâmetros, retornos e limites para |
| Retorno inesperado da ferramenta | Contrato de retorno mal definido ou não validado | Revise o contrato e implemente validação de saída | Contratos de ferramentas e dados de teste: o que todo agente |
| Erro de parâmetro ausente ou inválido | Parâmetros obrigatórios não checados | Inclua validação de parâmetros antes da execução | Contratos de ferramentas e dados de teste: o que todo agente |
| Vazamento de dados pessoais | Retorno inclui campos desnecessários | Ajuste o contrato para minimizar dados e revise o código | Contratos de ferramentas e dados de teste: o que todo agente |
| Ação irreversível executada sem revisão | Falta de handoff para aprovação humana | Implemente revisão obrigatória antes de ações críticas | Contratos de ferramentas e dados de teste: o que todo agente |
| O agente retorna erro de autenticação | Variável de ambiente não definida ou valor incorreto | Defina a variável correta no ambiente antes de iniciar o agente | Controle de acesso, segredos e isolamento entre ambientes |
| Segredos aparecem em logs ou prompts | Código expõe variáveis diretamente ou faz print de segredos | Remova prints e nunca inclua segredos em mensagens de log ou prompt | Controle de acesso, segredos e isolamento entre ambientes |
| Agente de teste acessa dados de produção | Variáveis de ambiente ou permissões compartilhadas entre ambientes | Separe variáveis e permissões, revise configuração do orquestrador | Controle de acesso, segredos e isolamento entre ambientes |
| Usuário sem permissão consegue executar ferramenta crítica | Permissões mal configuradas ou checagem ausente | Revise permissions.json ou decorators de acesso | Controle de acesso: quem pode ver, editar e acionar o agente |
| Logs de auditoria não são gerados | Tracing não ativado ou caminho de logs incorreto | Ative tracing e corrija diretório de logs | Controle de acesso: quem pode ver, editar e acionar o agente |
| Operação crítica executada sem aprovação | Fluxo de aprovação não implementado ou bypassado | Garanta que toda ação sensível passe pelo fluxo de aprovação manual | Controle de acesso: quem pode ver, editar e acionar o agente |
| O agente aprova solicitações automaticamente | Prompt ou lógica não exige revisão humana | Reforce no prompt e código que toda decisão depende de aprovação manual | Controle de contratos e fornecedores: agente com revisão obr |
| Logs incompletos ou ausentes | Registro de ações não implementado corretamente | Implemente logging estruturado para cada etapa | Controle de contratos e fornecedores: agente com revisão obr |
| Consulta retorna erro para CNPJ válido | Dados de teste ou integração com sistema de fornecedores falha | Revise a função de consulta e dados de teste | Controle de contratos e fornecedores: agente com revisão obr |
| Dados sensíveis expostos em logs | Falta de minimização de dados | Ajuste o registro para excluir informações pessoais desnecessárias | Controle de contratos e fornecedores: agente com revisão obr |
| Ollama retorna erro de memória insuficiente | RAM menor que o necessário para o modelo escolhido | Use modelo menor ou aumente a RAM | CPU, RAM ou GPU? Dimensionando recursos para Ollama e Qdrant |
| Qdrant responde lentamente a consultas | Disco lento ou RAM insuficiente para manter os embeddings em memória | Migre para SSD ou aumente a RAM | CPU, RAM ou GPU? Dimensionando recursos para Ollama e Qdrant |
| GPU não é utilizada pelo Ollama | Driver ou CUDA não instalado corretamente | Consulte a documentação de instalação do Ollama e do CUDA | CPU, RAM ou GPU? Dimensionando recursos para Ollama e Qdrant |
| Logs não aparecem ou estão incompletos | Tracing não habilitado ou diretório incorreto | Confirme que agent.enable_tracing foi chamado e o diretório existe | Critérios auditáveis: como definir justiça e transparência n |
| Resultados diferentes para perfis idênticos exceto nome | Prompt ou código usa campos não relevantes | Revise o prompt e as funções para garantir que só critérios explícitos são usados | Critérios auditáveis: como definir justiça e transparência n |
| Relatórios sem clareza sobre critérios | Logs não estruturados ou falta de mapeamento para relatório | Padronize o formato dos logs e gere relatórios a partir deles | Critérios auditáveis: como definir justiça e transparência n |
| Custos totais muito acima do previsto | Prompts/contextos longos demais ou uso excessivo de ferramentas externas | Revisar prompts e limitar contexto; otimizar uso de ferramentas | Custo por tarefa: como estimar, controlar e otimizar o uso d |
| Diferença entre custo estimado e fatura da API | Tokens reais diferentes dos estimados ou batch não aplicado corretamente | Use a API de contagem de tokens e revise agrupamento de batches | Custo por tarefa: como estimar, controlar e otimizar o uso d |
| Logs de custos incompletos | Falha no registro automático ou exceção no código de logging | Verifique permissões de escrita e trate exceções no logger | Custo por tarefa: como estimar, controlar e otimizar o uso d |
| Consumo de energia acima do esperado | Workload mais intenso ou hardware subdimensionado | Reveja a carga e ajuste o dimensionamento | Custos ocultos: energia, armazenamento e manutenção |
| Espaço em disco esgotando rapidamente | Logs ou embeddings sem política de retenção | Implemente limpeza automática e revise frequência de backup | Custos ocultos: energia, armazenamento e manutenção |
| Backup lento ou falhando | Rede saturada ou disco lento | Agende backups fora do horário de pico e use armazenamento rápido | Custos ocultos: energia, armazenamento e manutenção |
| Indicador não aparece no relatório | Falha na coleta automática ou erro de validação | Reveja a configuração da ferramenta e os logs do agente | Da coleta à aprovação: fluxos típicos do agente na gestão de |
| Ata gerada com informações incompletas | Transcrição de reunião mal formatada ou skill de extração insuficiente | Ajuste o processamento de texto e reforce exemplos no prompt | Da coleta à aprovação: fluxos típicos do agente na gestão de |
| Alerta de desvio não foi enviado | Meta não cadastrada corretamente ou comparação mal implementada | Confirme parâmetros de meta e revise o código de comparação | Da coleta à aprovação: fluxos típicos do agente na gestão de |
| Decisão sensível foi executada sem aprovação humana | Falta de handoff obrigatório no fluxo do agente | Reforce a validação e implemente bloqueio até aprovação explícita | Da consulta à decisão: fluxos de informação e pontos de cont |
| Logs de execução não aparecem ou estão incompletos | Tracing do SDK não ativado ou integração ausente | Ative tracing nativo e direcione para o sistema de auditoria | Da consulta à decisão: fluxos de informação e pontos de cont |
| Respostas da IA omitem limitações ou fontes | Prompt de sistema insuficiente ou ferramentas sem contrato claro | Revise o prompt e especifique contratos de ferramentas | Da consulta à decisão: fluxos de informação e pontos de cont |
| Dados pessoais aparecem no output do agente | Filtro de dados pessoais incompleto ou não aplicado | Revise e amplie as expressões regulares ou métodos de anonimização | Dados pessoais e LGPD: como limitar riscos no agente de negó |
| Decisões sensíveis são executadas sem aprovação | Guardrails ou fluxo de aprovação não configurados corretamente | Ajuste as regras de saída e teste novamente | Dados pessoais e LGPD: como limitar riscos no agente de negó |
| Logs contêm informações pessoais desnecessárias | Registro automático sem filtragem prévia | Inclua o filtro de dados pessoais antes do log | Dados pessoais e LGPD: como limitar riscos no agente de negó |
| Alertas não são registrados | Webhook/API não configurado corretamente | Verifique endpoint e autenticação do agente | De alertas a runbooks: o ciclo operacional do NOC sob a ótic |
| Triagem classifica tudo como crítico | Critérios de severidade mal definidos | Revise as regras de classificação | De alertas a runbooks: o ciclo operacional do NOC sob a ótic |
| Runbook executa comandos perigosos sem aprovação | Falta de checagem de permissões | Implemente validação obrigatória antes de ações sensíveis | De alertas a runbooks: o ciclo operacional do NOC sob a ótic |
| O agente retorna respostas vagas ou fora do escopo. | Prompt de sistema mal definido ou não versionado. | Reescreva o prompt e registre a versão. | De prompt a processo: como agentes jurídicos realmente funci |
| Ferramenta é chamada com parâmetros errados. | Contrato de uso da ferramenta não está claro ou não validado. | Reforce a validação de parâmetros e revise o YAML. | De prompt a processo: como agentes jurídicos realmente funci |
| Testes automatizados falham após alteração. | Mudança de prompt ou ferramenta quebrou critério de aprovação. | Ajuste o prompt ou ferramenta até os testes passarem. | De prompt a processo: como agentes jurídicos realmente funci |
| Logs de sessões misturados entre agentes | Diretórios ou identificadores de sessão não isolados | Revisar configuração de armazenamento e garantir separação por agente | De um agente a muitos: padrões de escalabilidade no NOC |
| Agente executando ações não autorizadas | Permissões excessivas ou variáveis de ambiente compartilhadas | Restringir permissões e revisar variáveis de ambiente | De um agente a muitos: padrões de escalabilidade no NOC |
| Fila de incidentes travada | Agente travado ou exceção não tratada no worker | Adicionar tratamento de exceções e monitorar threads/processos | De um agente a muitos: padrões de escalabilidade no NOC |
| Profiling não mostra funções internas do LangChain | O código pode estar usando threads ou subprocessos. | Use profiling em cada subprocesso ou utilize ferramentas específicas para multiprocessamento. | Debug avançado: tracing e análise de fluxos complexos |
| Logs sem correlation_id em todos os serviços | Falta de padronização no logging. | Garanta que todos os serviços aceitem e loguem o correlation_id. | Debug avançado: tracing e análise de fluxos complexos |
| Deadlock não identificado | Stack trace incompleto ou locks não liberados. | Use faulthandler e revise o uso de context managers para locks. | Debug avançado: tracing e análise de fluxos complexos |
| Latência alta apenas na primeira chamada | Cold start do modelo | Aumente o minScale para manter pods ativos | Debug de performance: cold start, throttling e gargalos |
| HTTP 429 em logs ou métricas | Throttling por excesso de requisições simultâneas | Ajuste containerConcurrency ou aumente réplicas | Debug de performance: cold start, throttling e gargalos |
| Pods reiniciando com OOMKilled | Falta de memória | Aumente requests/limits de memória | Debug de performance: cold start, throttling e gargalos |
| Latência variável durante picos de uso | CPU throttling | Aumente requests/limits de CPU ou otimize o código | Debug de performance: cold start, throttling e gargalos |
| Logs incompletos ou ausentes | Tracing não implementado corretamente ou nível de log insuficiente | Ajuste o código para registrar todas as etapas e aumente o nível de log | Debug prático: tracing, casos de teste e revisão de execução |
| Erro não reproduzido | Parâmetros ou contexto diferentes do caso original | Garanta que todos os parâmetros estejam idênticos ao log da falha | Debug prático: tracing, casos de teste e revisão de execução |
| Respostas divergentes entre fornecedores | Prompt ou parâmetros não padronizados | Padronize prompts e parâmetros antes de comparar | Debug prático: tracing, casos de teste e revisão de execução |
| O agente analisou contrato fora dos tipos permitidos | Prompt de sistema mal delimitado | Reforce no prompt os tipos aceitos e bloqueie outros via validação de entrada. | Definindo o escopo do agente: contratos, conformidade e pesq |
| Respostas sem citação da fonte legal | Ferramenta de pesquisa legislativa sem campo obrigatório de fonte | Inclua campo 'fonte' obrigatório e valide na saída. | Definindo o escopo do agente: contratos, conformidade e pesq |
| Dados pessoais sensíveis apareceram em logs | Logs não filtrados ou prompts sem restrição de dados | Implemente anonimização e restrinja tipos de dados no prompt. | Definindo o escopo do agente: contratos, conformidade e pesq |
| Pipeline falha na etapa de build Docker | Dependências ausentes ou erro no Dockerfile | Revise o Dockerfile e requirements.txt; rode build localmente para depurar | Deploy automatizado: CI/CD para aplicações LangChain |
| Deploy não atualiza a aplicação | Imagem não foi puxada ou container antigo não foi removido | Confirme comandos de pull, stop e run; verifique permissões SSH | Deploy automatizado: CI/CD para aplicações LangChain |
| Rollback não funciona | Imagens antigas não disponíveis no registry | Sempre versionar e manter imagens antigas no registry | Deploy automatizado: CI/CD para aplicações LangChain |
| Deploy não atualiza o agente em produção | Chave de API inválida ou permissão insuficiente no SDK | Verifique variáveis de ambiente e permissões da conta | Deploy automatizado: testes, validação e rollback sem dor de |
| Rollback falha ou não restaura estado anterior | Versionamento incompleto ou scripts de rollback com bug | Garanta que todos os arquivos estejam versionados e revise o script de rollback | Deploy automatizado: testes, validação e rollback sem dor de |
| Testes automatizados passam localmente, mas falham no pipeline | Ambiente do pipeline diferente do local | Padronize dependências e variáveis de ambiente no pipeline | Deploy automatizado: testes, validação e rollback sem dor de |
| InferenceService fica em estado 'NotReady' | Problema de autenticação S3 ou endpoint MinIO inacessível | Verifique Secret, endpoint e conectividade do cluster ao MinIO | Deploy de um modelo aberto: do bucket ao endpoint |
| Erro 403 ao acessar o modelo | Credenciais S3 inválidas ou bucket incorreto | Cheque o Secret e o nome do bucket no ConfigMap | Deploy de um modelo aberto: do bucket ao endpoint |
| Payload rejeitado pelo endpoint | Formato JSON incompatível com o modelo | Ajuste o payload conforme esperado pelo framework/modelo | Deploy de um modelo aberto: do bucket ao endpoint |
| Deploy executa mas o serviço não responde | Healthcheck falhou ou variáveis de ambiente ausentes | Revise o healthcheck e confirme variáveis no .env.prod | Deploy seguro: do commit ao serviço rodando |
| Rollback não retorna à versão anterior | Imagem antiga não disponível ou tag incorreta | Garanta que imagens antigas estão no registry e use o hash correto | Deploy seguro: do commit ao serviço rodando |
| Logs de deploy não aparecem | Permissões de escrita insuficientes ou caminho errado | Ajuste permissões e paths dos arquivos de log | Deploy seguro: do commit ao serviço rodando |
| Chaves de API vazam em logs | Logs mal configurados ou variáveis expostas | Nunca logue variáveis de ambiente diretamente; revise scripts | Deploy seguro: do commit ao serviço rodando |
| Logs mostram eventos sem session_id. | Agente ou ferramenta não propagou o identificador único. | Ajuste o código para sempre repassar o session_id em todas as chamadas. | Depuração multiagente: identificar falhas de orquestração e |
| Erro de parâmetro obrigatório ausente em ferramenta MCP. | Agente anterior não preencheu o campo exigido. | Corrija o prompt ou a lógica do agente para garantir preenchimento dos parâmetros. | Depuração multiagente: identificar falhas de orquestração e |
| Fluxo trava sem erro aparente. | Deadlock entre agentes ou chamada MCP sem resposta. | Analise o tracing para identificar o ponto de bloqueio e revise contratos de timeout. | Depuração multiagente: identificar falhas de orquestração e |
| Logs de tracing ausentes ou incompletos | Tracing não configurado corretamente ou permissões de escrita insuficientes | Revise a configuração do Tracer e permissões do diretório de logs | Desafios abertos: limites, ética e futuro dos multiagentes |
| Agente toma decisão errada sem validação | Guardrails ausentes ou mal implementados | Implemente ou corrija as funções de validação de entrada/saída | Desafios abertos: limites, ética e futuro dos multiagentes |
| Pipeline trava ou fica lento | Deadlock, race condition ou sobrecarga de contexto | Revise a orquestração, monitore filas e ajuste limites de contexto dos modelos | Desafios abertos: limites, ética e futuro dos multiagentes |
| O vídeo mostra cenário ou clima diferente do esperado | Briefing vago ou ambíguo | Refaça a frase, detalhando o que deve aparecer e o clima desejado | Descreva o resultado, não a técnica: o briefing em uma frase |
| A IA entrega vídeo com movimento de câmera não pedido | Faltou especificar 'câmera parada' ou 'sem movimento' | Inclua na frase que a câmera deve ser fixa | Descreva o resultado, não a técnica: o briefing em uma frase |
| O produto não aparece em destaque | Briefing não deixou claro o foco no produto | Peça explicitamente que o produto esteja em destaque | Descreva o resultado, não a técnica: o briefing em uma frase |
| A cena ficou escura ou com luz artificial | Não foi especificado 'luz natural' | Inclua 'luz natural' ou 'ambiente iluminado' na frase | Descreva o resultado, não a técnica: o briefing em uma frase |
| Respostas inconsistentes ou inesperadas | Mistura de lógica determinística e adaptativa sem separação clara | Separe chains e agents em módulos distintos | Desenhando fluxos: chains, agentes e persistência vetorial |
| Busca vetorial retorna resultados irrelevantes | Embeddings mal gerados ou coleção errada | Regenere embeddings e confira o nome da coleção | Desenhando fluxos: chains, agentes e persistência vetorial |
| Agent não utiliza todas as ferramentas | Configuração incompleta do agent | Verifique se todas as tools estão registradas no agent | Desenhando fluxos: chains, agentes e persistência vetorial |
| Respostas irrelevantes ou vagas | Chunking mal calibrado ou modelo inadequado | Ajuste o tamanho dos chunks e teste outros modelos de embedding | Desenhando pipelines para documentos corporativos: desafios |
| Documentos não aparecem nos resultados | Falha no parser ou indexação incompleta | Revise logs de ingestão e valide o parser com amostras reais | Desenhando pipelines para documentos corporativos: desafios |
| Pipeline lento sob carga | Subdimensionamento de hardware ou indexador inadequado | Otimize recursos ou migre para FAISS/Elasticsearch | Desenhando pipelines para documentos corporativos: desafios |
| Erros de encoding | Documentos com charset inesperado | Garanta que parsers estejam configurados para UTF-8 | Desenhando pipelines para documentos corporativos: desafios |
| O agente retorna erro ao chamar ferramenta | Contrato de ferramenta divergente do implementado | Revise parâmetros e tipos do contrato e ajuste o código. | Desenhando prompts de sistema e contratos de ferramenta para |
| Prompt não é seguido pelo agente | Instruções vagas ou contraditórias no prompt | Reescreva o prompt com regras mais objetivas e exemplos claros. | Desenhando prompts de sistema e contratos de ferramenta para |
| Decisões do agente não aparecem no log | Tracing não ativado ou mal configurado | Ative e configure corretamente o tracing no SDK. | Desenhando prompts de sistema e contratos de ferramenta para |
| Fila de currículos travada ou lenta | Volume acima do dimensionado ou modelo atingiu limite de contexto | Divida em lotes menores e ajuste o modelo ou paralelismo | Dez perguntas para dimensionar: do volume de currículos ao t |
| Erros de contexto excedido | Prompt ou lote maior que o limite do modelo | Reduza o tamanho dos prompts ou troque de modelo | Dez perguntas para dimensionar: do volume de currículos ao t |
| Latência alta em entrevistas por voz | Modelo TTS ou rede saturados | Divida o texto em trechos menores e monitore a largura de banda | Dez perguntas para dimensionar: do volume de currículos ao t |
| Pod em CrashLoopBackOff | Erro de inicialização do modelo ou variável de ambiente ausente | Revise logs do container, corrija variáveis e reimplante | Diagnóstico de falhas em endpoints e pods do KServe |
| ImagePullBackOff | Imagem não encontrada ou sem permissão | Verifique o nome da imagem e credenciais de acesso | Diagnóstico de falhas em endpoints e pods do KServe |
| HTTP 503 ao acessar endpoint | Pod não está pronto ou Istio não roteou | Cheque readiness probe e status do pod | Diagnóstico de falhas em endpoints e pods do KServe |
| Resposta termina abruptamente | Limite de tokens atingido ou timeout | Aumente max_tokens ou divida a tarefa | Diagnóstico de respostas ruins: truncamento, alucinação e er |
| Informações inventadas na resposta | Prompt vago ou ausência de dados reais | Forneça dados reais e restrinja o prompt | Diagnóstico de respostas ruins: truncamento, alucinação e er |
| Resposta mistura tópicos ou ignora instruções | Histórico de contexto muito longo ou mal estruturado | Resuma o histórico e use sessões separadas | Diagnóstico de respostas ruins: truncamento, alucinação e er |
| Modelo retorna erro de contexto | Limite de contexto do modelo ultrapassado | Reduza o histórico ou troque para modelo com contexto maior | Diagnóstico de respostas ruins: truncamento, alucinação e er |
| Respostas vazias | Indexação incompleta ou filtros excessivos | Reindexe documentos e revise filtros do retriever | Diagnóstico rápido: identificando gargalos e falhas mais com |
| Lentidão extrema | Banco vetorial sobrecarregado ou modelo inadequado | Ajuste configuração do banco e avalie troca de modelo | Diagnóstico rápido: identificando gargalos e falhas mais com |
| Erro HTTP 500 | Falha no pipeline ou modelo | Cheque logs e atualize dependências | Diagnóstico rápido: identificando gargalos e falhas mais com |
| Consumo alto de CPU | Modelo muito pesado ou vazamento de memória | Troque por modelo mais leve ou reinicie serviço | Diagnóstico rápido: identificando gargalos e falhas mais com |
| Timeout ao acessar banco vetorial | Banco offline ou endpoint incorreto | Verifique status do serviço e URL de conexão | Diagnóstico rápido: identificando gargalos e falhas mais com |
| O log não mostra o erro detalhado | Nível de logging insuficiente ou logs desestruturados | Ajuste o nível para INFO ou DEBUG e padronize o formato dos logs | Diagnóstico rápido: identificando onde o fluxo quebrou |
| Tracing não captura todas as etapas | Tracing não ativado em todas as execuções ou agentes | Garanta que o tracer está sendo passado para cada execução | Diagnóstico rápido: identificando onde o fluxo quebrou |
| Não é possível reproduzir a falha em teste | Ambiente de teste diferente do de produção ou dados inconsistentes | Sincronize os ambientes e use dados reais (anonimizados) | Diagnóstico rápido: identificando onde o fluxo quebrou |
| Erro intermitente, difícil de isolar | Condições de corrida ou dependências externas instáveis | Aumente o volume de logs, use tracing distribuído e monitore dependências externas | Diagnóstico rápido: identificando onde o fluxo quebrou |
| Consultas lentas ou timeouts | Índice vetorial maior que a RAM disponível | Reduza dimensionalidade dos embeddings ou aumente RAM | Dimensionamento inicial: estimando recursos para QA em produ |
| Erros de out-of-memory | Modelo ou índice grande demais para o hardware | Use embeddings menores ou distribua carga em mais nós | Dimensionamento inicial: estimando recursos para QA em produ |
| Reader sobrecarregado | Muitas consultas simultâneas | Implemente fila ou adicione instâncias do reader | Dimensionamento inicial: estimando recursos para QA em produ |
| Resultados irrelevantes | Embedding inadequado para o domínio | Treine ou escolha outro modelo de embedding | Dimensionamento inicial: estimando recursos para QA em produ |
| Respostas truncadas ou incompletas | Estouro do limite de tokens de saída ou contexto | Reduza o histórico, resuma prompts ou troque para modelo com contexto maior | Dimensionando agentes: contexto, tokens, concorrência e cust |
| Requisições bloqueadas ou descartadas | Concorrência acima do permitido pela API ou backend | Implemente controle de concorrência e filas | Dimensionando agentes: contexto, tokens, concorrência e cust |
| Custos inesperadamente altos | Uso de modelo caro para tarefas simples ou falta de batch | Troque para modelo mais barato ou use batch para tarefas repetitivas | Dimensionando agentes: contexto, tokens, concorrência e cust |
| O agente demora para responder ou trava em algumas requisições | Ferramenta externa lenta ou sem timeout definido | Implemente timeout e monitore o tempo de resposta | Dimensionando ferramentas e integrações: gargalos, filas e c |
| Muitas requisições simultâneas derrubam o serviço externo | Falta de controle de concorrência | Implemente semáforos ou filas para limitar chamadas | Dimensionando ferramentas e integrações: gargalos, filas e c |
| O agente retorna erro após várias tentativas | Retries excessivos sem backoff | Reduza o número de retries e implemente backoff exponencial | Dimensionando ferramentas e integrações: gargalos, filas e c |
| Erro 'Payload Too Large' | Arquivo ou lote excedeu o limite da API | Divida o lote em partes menores e valide o tamanho antes de enviar | Dimensionando infraestrutura: limites de requisição, arquivo |
| Sessão travada ou lenta | Histórico ou contexto muito grande | Limite o tempo de vida e o tamanho do histórico da sessão | Dimensionando infraestrutura: limites de requisição, arquivo |
| Dados de um departamento vazando para outro | Sessões ou variáveis de ambiente compartilhadas | Separe configuração e segredos por departamento | Dimensionando infraestrutura: limites de requisição, arquivo |
| Alertas não disparam | Monitoramento mal configurado ou thresholds errados | Revise scripts de monitoramento e ajuste limites de alerta | Dimensionando infraestrutura: limites de requisição, arquivo |
| O agente não responde ao webhook | Endpoint HTTP inacessível ou falha de autenticação | Verifique firewall, rota e token de autenticação. | Disparo por evento: agentes reativos e proativos em produção |
| Mensagens da fila não são processadas | Configuração errada da fila ou permissão insuficiente | Confirme nome da fila, permissão e conexão. | Disparo por evento: agentes reativos e proativos em produção |
| Execução agendada não dispara | Scheduler não iniciado ou conflito de horário | Verifique logs do scheduler e ajuste a configuração. | Disparo por evento: agentes reativos e proativos em produção |
| O agente só responde, não executa ações | Ferramentas não registradas corretamente ou prompt de sistema incompleto | Revise o registro das ferramentas e o prompt; consulte a documentação do SDK. | Do assistente ao agente: por que só responder não basta |
| Erros ao chamar funções Python | Assinatura da função incompatível com o contrato do SDK | Ajuste as funções para seguir o padrão exigido pelo SDK. | Do assistente ao agente: por que só responder não basta |
| Logs incompletos ou ausentes | Tracing não habilitado ou mal configurado | Ative o tracing conforme a documentação oficial do SDK. | Do assistente ao agente: por que só responder não basta |
| O agente começa a errar tarefas que antes acertava | Prompt ou modelo atualizado sem testes completos | Rode a suíte de testes de regressão e reverta para a versão anterior se necessário | Do laboratório à produção: como manter agentes de gestão sem |
| Logs de tracing não aparecem | Tracing não habilitado ou configuração incorreta | Verifique a inicialização do tracer no código | Do laboratório à produção: como manter agentes de gestão sem |
| Dados sensíveis aparecem em logs | Falta de filtragem ou má configuração de variáveis de ambiente | Implemente filtros e revise o uso de variáveis de ambiente | Do laboratório à produção: como manter agentes de gestão sem |
| Pedidos ficam presos na fila e não são processados | Worker de batch não está rodando ou travou por exceção não tratada | Reinicie o worker e implemente tratamento de exceções no loop | Do notebook à fila: agentes atendendo mil pedidos por dia co |
| Erro 429 ao enviar pedidos | Fila atingiu o limite máximo (guardrail ativo) | Reduza a taxa de envio ou aumente o MAX_QUEUE com cautela | Do notebook à fila: agentes atendendo mil pedidos por dia co |
| Respostas não aparecem no endpoint de consulta | IDs dos pedidos não estão sendo mapeados corretamente ao resultado do batch | Verifique o código que associa cada resposta ao identificador do pedido | Do notebook à fila: agentes atendendo mil pedidos por dia co |
| Erro 500 da Claude API ao enviar batch | Formato do payload incorreto ou tamanho do batch excedeu o limite | Revise o payload e o tamanho do lote conforme a documentação oficial | Do notebook à fila: agentes atendendo mil pedidos por dia co |
| Ações do agente não aparecem no log | Tracing não configurado corretamente ou caminho de log sem permissão | Verifique configuração do tracing e permissões do diretório de log | Do prompt à aprovação: arquitetura de um agente auditável |
| Ferramenta retorna erro de parâmetro | Contrato da ferramenta mal definido ou parâmetros ausentes | Revise a definição da função e os testes automatizados | Do prompt à aprovação: arquitetura de um agente auditável |
| Aprovação humana não é registrada | Lógica de pausa e registro de aprovação ausente ou mal implementada | Implemente registro explícito do responsável e timestamp | Do prompt à aprovação: arquitetura de um agente auditável |
| O agente executa ação sensível sem aprovação humana | Guardrail ausente ou mal implementado | Revise os validadores e bloqueios antes de comandos críticos | Do prompt à entrega: ciclo de vida de um agente fiscal |
| Logs incompletos ou ausentes | Configuração de logging insuficiente | Ajuste logging para registrar todas as etapas e entradas/saídas | Do prompt à entrega: ciclo de vida de um agente fiscal |
| Testes automatizados falham após alteração de prompt | Mudança não compatível com contratos de ferramentas | Atualize contratos e testes para refletir a nova lógica | Do prompt à entrega: ciclo de vida de um agente fiscal |
| O agente gera relatórios com dados desatualizados | Fonte de dados mudou ou prompt não foi ajustado | Revisar fontes e atualizar prompt e ferramentas | Do prompt à operação contínua: ciclo completo com revisão e |
| Testes automatizados falham após atualização | Mudança em contrato de ferramenta ou entrada/saída | Atualizar casos de teste e schemas de validação | Do prompt à operação contínua: ciclo completo com revisão e |
| Decisão crítica foi executada sem revisão humana | Workflow de aprovação não implementado ou bypassado | Corrigir workflow e reforçar obrigatoriedade de aprovação manual | Do prompt à operação contínua: ciclo completo com revisão e |
| O agente publica conteúdo sem revisão humana | Workflow de aprovação não implementado ou bypassado | Reforce a checagem de aprovação antes de ações irreversíveis. | Do prompt à operação: ciclo de vida do agente de marketing |
| Testes automáticos falham após atualização do prompt | Mudança não compatível com casos de teste antigos | Revise o prompt e ajuste os testes ou reverta a alteração. | Do prompt à operação: ciclo de vida do agente de marketing |
| Logs incompletos ou ausentes | Tracing não configurado corretamente | Implemente logging detalhado em cada etapa do agente. | Do prompt à operação: ciclo de vida do agente de marketing |
| O agente usa uma ferramenta não prevista no prompt | Prompt de sistema desatualizado ou contrato de ferramenta ausente | Atualize o prompt e registre a ferramenta antes de liberar para produção | Do prompt ao dashboard: arquitetura de agentes para inteligê |
| Dados pessoais aparecem sem justificativa | Falta de filtro ou ausência de base legal | Implemente checagem de base legal e minimize a coleta | Do prompt ao dashboard: arquitetura de agentes para inteligê |
| Dashboard não mostra logs completos | Tracing não está ativado ou não foi integrado ao dashboard | Ative o tracing no SDK e ajuste o dashboard para consumir os registros | Do prompt ao dashboard: arquitetura de agentes para inteligê |
| Ação crítica executada sem aprovação | Prompt ou fluxo de aprovação mal definido | Revisar prompt e lógica de aprovação; garantir bloqueio antes da execução | Do prompt ao runbook: arquitetura de agentes para operações |
| Comando falha por parâmetro inválido | Falta de validação nos guardrails | Implementar validação rigorosa de tipos e valores | Do prompt ao runbook: arquitetura de agentes para operações |
| Registro incompleto ou ausente | Falha no tracing ou log estruturado | Revisar código de registro; garantir persistência após cada ação | Do prompt ao runbook: arquitetura de agentes para operações |
| Agente retorna erro inesperado | Contrato de ferramenta mal definido ou prompt ambíguo | Revise o contrato e o prompt; adicione testes para o caso | Do requisito ao fluxo: mapeando processos empresariais para |
| Dados sensíveis aparecem nos logs | Falta de sanitização ou uso indevido de variáveis | Implemente minimização e revise variáveis de ambiente | Do requisito ao fluxo: mapeando processos empresariais para |
| Mudança em prompt quebra fluxo downstream | Falta de testes automatizados ou versionamento | Implemente suíte de testes e versionamento de prompts | Do requisito ao fluxo: mapeando processos empresariais para |
| Áudio gerado com voz robótica ou errada | Modelo TTS inadequado ou parâmetros incorretos | Confirme o model_id e ajuste voice_settings conforme a documentação | Do texto ao avatar: por que IA generativa mudou a comunicaçã |
| Latência alta na geração de vídeo | Sobrecarga no endpoint HeyGen ou rede lenta | Implemente consulta assíncrona ao status e use webhooks | Do texto ao avatar: por que IA generativa mudou a comunicaçã |
| Transcrição imprecisa | Áudio de baixa qualidade ou idioma não suportado | Garanta áudio limpo e use o modelo ASR correto | Do texto ao avatar: por que IA generativa mudou a comunicaçã |
| Mudança não registrada no histórico | Falta de disciplina no versionamento | Exija commits e atualização do CHANGELOG.md para toda alteração | Documentação e governança: histórico, revisão e credencial U |
| Prompt alterado sem revisão | Processo de revisão falho ou inexistente | Implemente checklist obrigatório e revisão dupla | Documentação e governança: histórico, revisão e credencial U |
| Logs de alteração ausentes | Deploy manual sem script de logging | Automatize o deploy e registre logs de revisão | Documentação e governança: histórico, revisão e credencial U |
| O agente responde com lógica antiga após atualização de prompt | Prompt novo não foi carregado ou arquivo não foi versionado corretamente | Verifique se o arquivo correto está em produção e se o commit foi feito | Documentação viva: mantendo agentes tributários auditáveis e |
| Ferramenta retorna erro de parâmetro inesperado | Contrato da ferramenta desatualizado ou divergente do código | Atualize a documentação e os exemplos de chamada | Documentação viva: mantendo agentes tributários auditáveis e |
| Responsável técnico não recebe notificação de alteração | Sistema de notificação não integrado ao fluxo de commits | Implemente trigger de notificação após merge ou alteração relevante | Documentação viva: mantendo agentes tributários auditáveis e |
| Erro de autenticação na API | Chave de API inválida ou não definida na variável de ambiente. | Confirme as variáveis ANTHROPIC_API_KEY e OPENAI_API_KEY. | Dois fornecedores, um cliente: Claude e GPT se revisam antes |
| Respostas não são registradas no log | Configuração incorreta do logging ou permissão de escrita no diretório. | Verifique o caminho do arquivo e permissões. | Dois fornecedores, um cliente: Claude e GPT se revisam antes |
| Respostas sempre recusadas | Prompt do revisor excessivamente restritivo ou modelo configurado com temperatura alta. | Ajuste o prompt e os parâmetros do modelo. | Dois fornecedores, um cliente: Claude e GPT se revisam antes |
| Erro 400 ao enviar o batch | O lote ultrapassou o limite de 256 MB ou algum arquivo tem formato não suportado. | Divida o batch em lotes menores e revise os formatos dos arquivos. | Duzentos contratos numa noite pela metade do preço: Files AP |
| Arquivo rejeitado na Files API | Arquivo maior que 500 MB ou corrompido. | Reduza o tamanho do arquivo ou recupere uma versão íntegra. | Duzentos contratos numa noite pela metade do preço: Files AP |
| Saída inesperada ou vazia para um contrato | Prompt mal formulado ou arquivo ilegível pelo modelo. | Revise o prompt de sistema e o conteúdo do arquivo. | Duzentos contratos numa noite pela metade do preço: Files AP |
| Falsos negativos na validação automática | Diferenças de formatação, espaços ou maiúsculas/minúsculas. | Implemente normalização de texto antes da comparação. | Duzentos contratos numa noite pela metade do preço: Files AP |
| Respostas vagas ou erradas | Prompt de sistema genérico ou sem exemplos | Adicione exemplos reais e restrinja o escopo no prompt | E-mail, planilha e atendimento: três fluxos de IA que funcio |
| Planilha com dados inventados | IA sem validação ou prompt aberto demais | Implemente scripts de validação automática e revise o prompt | E-mail, planilha e atendimento: três fluxos de IA que funcio |
| Áudio com pronúncia errada | Texto ambíguo ou voz não ajustada | Ajuste o texto de entrada e escolha voz adequada no ElevenLabs | E-mail, planilha e atendimento: três fluxos de IA que funcio |
| Erros de autenticação na API | Chave de API inválida ou variável de ambiente não definida | Confirme as variáveis de ambiente e permissões | E-mail, planilha e atendimento: três fluxos de IA que funcio |
| O vídeo saiu completamente diferente do original | Prompt vago ou pedido de alteração estrutural | Refaça o pedido detalhando que só deseja mudar o fundo e manter todo o resto igual | Editar o que já existe pedindo à IA: Aleph 2.0 sem regerar d |
| O ajuste não aparece no vídeo final | Pedido pouco claro ou contraditório | Reescreva o prompt focando apenas no ajuste desejado, sem instruções ambíguas | Editar o que já existe pedindo à IA: Aleph 2.0 sem regerar d |
| A qualidade do vídeo piorou após edição | Vídeo de entrada com artefatos ou baixa qualidade | Use um vídeo base de melhor qualidade antes de editar | Editar o que já existe pedindo à IA: Aleph 2.0 sem regerar d |
| A IA removeu detalhes importantes | Pedido excessivamente restritivo ou detalhado | Simplifique o prompt para não limitar demais a liberdade do modelo | Editar o que já existe pedindo à IA: Aleph 2.0 sem regerar d |
| Latência crescente sob carga | Número insuficiente de workers ou pods | Aumente minReplicas/maxReplicas no HPA ou workers no Gunicorn | Elasticidade e tolerância a falhas: mantendo o fluxo sob dem |
| Erros 429 das APIs de LLM | Limite de requisições excedido | Implemente retries com backoff e reduza a taxa de chamadas | Elasticidade e tolerância a falhas: mantendo o fluxo sob dem |
| Falhas não aparecem nos logs | Configuração incorreta do logging ou tracing | Revise o nível e destino dos logs | Elasticidade e tolerância a falhas: mantendo o fluxo sob dem |
| Decisões perdidas sem registro | Falta de fallback ou de persistência de falhas | Implemente fallback e fila de reprocessamento | Elasticidade e tolerância a falhas: mantendo o fluxo sob dem |
| Áudio gerado em idioma errado | Parâmetro model_id incorreto ou voice_id não compatível | Use model_id e voice_id suportados para português | ElevenLabs e HeyGen: voz e vídeo como canais de agentes |
| Vídeo não finaliza na HeyGen | Campos obrigatórios ausentes ou erro de autenticação | Confira a documentação dos endpoints e valide a chave de API | ElevenLabs e HeyGen: voz e vídeo como canais de agentes |
| Resposta do agente não sincroniza com áudio/vídeo | session_id ou identificador único não utilizado | Implemente identificadores únicos em cada requisição | ElevenLabs e HeyGen: voz e vídeo como canais de agentes |
| Erro 401 nas APIs | Chave de API inválida ou expirada | Atualize as variáveis de ambiente com chaves válidas | ElevenLabs e HeyGen: voz e vídeo como canais de agentes |
| Respostas irrelevantes ou genéricas | Embeddings de baixa qualidade ou banco vetorial mal indexado | Troque o modelo de embeddings e reindexe os documentos | Embeddings, bancos vetoriais e RAG: como LLMs realmente busc |
| Busca muito lenta | Banco vetorial sem indexação adequada ou hardware insuficiente | Ajuste a configuração do banco vetorial e revise o hardware | Embeddings, bancos vetoriais e RAG: como LLMs realmente busc |
| LLM ignora contexto recuperado | Prompt mal estruturado ou contexto insuficiente | Inclua mais exemplos reais no prompt e reforce a instrução | Embeddings, bancos vetoriais e RAG: como LLMs realmente busc |
| Timeout recorrente ao chamar LLM | Timeout padrão do cliente é baixo ou rede instável | Aumente o timeout no SDK e monitore a latência de rede | Erros clássicos: timeouts, falhas de conexão e respostas ine |
| Erro de conexão com Milvus | Porta bloqueada ou endpoint incorreto | Ajuste firewall e valide host/porta | Erros clássicos: timeouts, falhas de conexão e respostas ine |
| Respostas do LLM não parseáveis | Parâmetros de geração muito altos ou prompt mal formatado | Reduza temperature/top_p e revise o prompt | Erros clássicos: timeouts, falhas de conexão e respostas ine |
| Erro HTTP 429 do LLM | Limite de requisições excedido | Implemente backoff e monitore uso de tokens | Erros clássicos: timeouts, falhas de conexão e respostas ine |
| Respostas lentas ou timeout do modelo | Contexto excessivo ou histórico não truncado | Implemente truncamento e monitore uso de tokens | Erros comuns em multiagentes: aprendendo com falhas reais |
| Execução de comandos inesperados ou perigosos | Guardrails ausentes ou mal configurados | Reveja e teste as funções de validação | Erros comuns em multiagentes: aprendendo com falhas reais |
| Dificuldade para rastrear decisões ou falhas | Tracing desativado ou logs incompletos | Ative tracing conforme a documentação oficial e revise a política de logs | Erros comuns em multiagentes: aprendendo com falhas reais |
| Ollama encerra logo após iniciar | Falta de AVX2 na CPU ou RAM insuficiente | Use modelos menores ou troque de hardware | Erros comuns no Ollama e como depurar de verdade |
| Erro de download de modelo | Proxy, firewall ou conexão instável | Configure variáveis de proxy e tente novamente | Erros comuns no Ollama e como depurar de verdade |
| Respostas lentas ou travamento | Uso excessivo de RAM ou swap | Feche outros aplicativos ou aumente swap | Erros comuns no Ollama e como depurar de verdade |
| Erro 400 com mensagem de campo ausente | Payload JSON não segue o esquema esperado | Valide com Pydantic antes de enviar | Erros comuns: do bad request ao hallucination |
| Erro 401 Unauthorized | Chave de API ausente ou inválida | Confirme variável de ambiente e formato do cabeçalho Authorization | Erros comuns: do bad request ao hallucination |
| Erro 429 Too Many Requests | Limite de requisições excedido | Implemente backoff exponencial e monitore uso da API | Erros comuns: do bad request ao hallucination |
| Resposta 200 mas saída sem sentido | Prompt mal definido ou modelo alucinou | Refine o prompt de sistema e valide a saída com Pydantic | Erros comuns: do bad request ao hallucination |
| Resposta truncada ou incompleta | Limite de tokens de saída atingido | Reduza a entrada ou aumente o parâmetro de saída, se suportado | Erros comuns: do bad request ao hallucination |
| Logs vazios ou incompletos | Tracing não habilitado ou caminho de log incorreto | Revise a configuração de tracing e permissões de escrita | Erros de integração: rastreando falhas entre agente e sistem |
| Erros 401 recorrentes | Token expirado ou inválido | Implemente renovação automática do token | Erros de integração: rastreando falhas entre agente e sistem |
| Timeout em integrações | Rede instável ou endpoint lento | Ajuste timeouts e implemente retries com limites | Erros de integração: rastreando falhas entre agente e sistem |
| Respostas inesperadas do MCP | Mudança na API externa ou no contrato | Atualize o contrato da ferramenta e ajuste validações | Erros de integração: rastreando falhas entre agente e sistem |
| Buscas vetoriais lentas após crescimento dos dados | Partições ou shards desbalanceados | Reveja o critério de particionamento e distribua dados de forma mais uniforme | Escalabilidade de bancos vetoriais: PostgreSQL e Milvus em c |
| Falhas de leitura em PostgreSQL standby | Replicação incompleta ou atrasada | Verifique logs de replicação e aumente max_wal_senders se necessário | Escalabilidade de bancos vetoriais: PostgreSQL e Milvus em c |
| Cluster Milvus não inicializa | Configuração incorreta de Docker Compose ou falta de recursos | Revise docker-compose.yml e aloque mais CPU/memória | Escalabilidade de bancos vetoriais: PostgreSQL e Milvus em c |
| Erros HTTP 429 (rate limit) frequentes | Excesso de requisições simultâneas para a API | Reduza o número de sessões paralelas ou implemente backoff exponencial | Escalando agentes comerciais: paralelismo, filas e limites p |
| Respostas trocadas entre leads | Compartilhamento de contexto entre sessões | Garanta isolamento total de variáveis e histórico por sessão | Escalando agentes comerciais: paralelismo, filas e limites p |
| Fila cresce sem diminuir | Capacidade de processamento insuficiente | Aumente o número de workers ou otimize o tempo de cada tarefa | Escalando agentes comerciais: paralelismo, filas e limites p |
| Erros 429 (rate limit) nas APIs | Excesso de chamadas simultâneas | Reduza o número de threads ou aumente o intervalo entre chamadas | Escalando agentes e multiagentes: limites práticos e estraté |
| Sessões misturadas entre clientes | Diretório ou banco de sessão compartilhado | Configure session_dir ou identificadores exclusivos por agente | Escalando agentes e multiagentes: limites práticos e estraté |
| Fila de tarefas travada | Integração MCP lenta ou indisponível | Implemente timeout, retries e fallback para casos de erro | Escalando agentes e multiagentes: limites práticos e estraté |
| Logs incompletos ou ausentes | Falta de configuração de logging por agente | Garanta que cada agente escreva logs em local isolado | Escalando agentes e multiagentes: limites práticos e estraté |
| Fila de vídeos HeyGen cresce sem parar | Workers insuficientes ou limite da API atingido | Reduza a taxa de envio ou aumente a capacidade dos workers, sem ultrapassar o limite da API | Escalando agentes e vídeos: limites das APIs e estratégias d |
| Erros 429 frequentes na ElevenLabs | Excesso de requisições simultâneas | Reduza o número de workers ou implemente backoff exponencial | Escalando agentes e vídeos: limites das APIs e estratégias d |
| Agentes de voz travam ou caem | Sobrecarga do pool ou falta de recursos | Ajuste o pool e monitore uso de CPU/memória | Escalando agentes e vídeos: limites das APIs e estratégias d |
| Tempo de resposta aumenta subitamente | Saturação da fila ou lentidão na API | Aumente o número de workers com cautela e monitore limites | Escalando agentes e vídeos: limites das APIs e estratégias d |
| Agentes processando a mesma tarefa mais de uma vez | Fila de tarefas sem controle de exclusão ou lock | Implemente locks ou marque tarefas como processadas após execução | Escalando agentes jurídicos: múltiplos processos, times e vo |
| Logs misturados entre diferentes times | Falta de isolamento de ambiente ou variáveis de contexto | Separe logs por time e processo, usando namespaces ou diretórios distintos | Escalando agentes jurídicos: múltiplos processos, times e vo |
| Tempo de resposta alto em horários de pico | Poucas instâncias de agentes para o volume de tarefas | Aumente o número de instâncias ou otimize o balanceamento de carga | Escalando agentes jurídicos: múltiplos processos, times e vo |
| Consultas ficam presas na fila | ThreadPoolExecutor com poucos workers ou deadlock | Aumente max_workers e revise locks. | Escalando agentes tributários: filas, batches e paralelismo |
| Resultados duplicados ou fora de ordem | Falta de controle de concorrência ou uso de batches sem rastreio | Implemente IDs únicos e registre ordem de processamento. | Escalando agentes tributários: filas, batches e paralelismo |
| Uso excessivo de CPU ou memória | Paralelismo descontrolado ou vazamento de objetos | Limite o número de threads e monitore objetos persistentes. | Escalando agentes tributários: filas, batches e paralelismo |
| Agente responde com erro de permissão ao acessar ferramenta | Ferramenta não registrada ou permissões mal configuradas no SDK | Revise a lista de ferramentas do agente e ajuste o contrato | Escalando agentes: de um setor para toda a empresa |
| Dados de um setor aparecem em logs de outro | Ambientes virtuais ou diretórios de trabalho compartilhados | Separe ambientes e caminhos de log por setor | Escalando agentes: de um setor para toda a empresa |
| Tempo de resposta alto em horários de pico | Falta de balanceamento de carga ou agentes insuficientes | Implemente filas e distribua tarefas entre mais instâncias | Escalando agentes: de um setor para toda a empresa |
| Fila de jobs crescendo sem parar | Concorrência baixa ou gargalo em uma etapa | Aumente workers na etapa lenta ou otimize o processamento | Escalando agentes: filas, concorrência e limites práticos |
| Erros 429 frequentes | Excesso de requisições simultâneas para a API | Reduza concorrência ou implemente backoff | Escalando agentes: filas, concorrência e limites práticos |
| Jobs de vídeo nunca completam | Polling insuficiente ou falha de callback | Ajuste o intervalo de polling ou revise configuração de webhook | Escalando agentes: filas, concorrência e limites práticos |
| Respostas inconsistentes dos agentes | Jobs processados fora de ordem ou perda de contexto | Garanta ordenação e isolamento de contexto por job | Escalando agentes: filas, concorrência e limites práticos |
| Respostas de agentes misturadas ou fora de ordem | Falta de fila ou contexto isolado por agente | Implemente fila e IDs únicos por execução | Escalando agentes: paralelismo, filas e controle de concorrê |
| Erros de limite de API (429) | Concorrência excessiva | Reduza o número de agentes simultâneos com semáforo | Escalando agentes: paralelismo, filas e controle de concorrê |
| Logs truncados ou incompletos | Mistura de logs entre execuções | Garanta logger isolado por execução | Escalando agentes: paralelismo, filas e controle de concorrê |
| Tarefas travando indefinidamente | Deadlock por má configuração de fila ou semáforo | Revise await/async e uso correto do queue.task_done() | Escalando agentes: paralelismo, filas e controle de concorrê |
| Respostas lentas mesmo com múltiplos workers | Backend (LLM ou banco) saturado | Reduza concorrência ou aumente recursos do backend | Escalando chains e agents: paralelismo e balanceamento |
| Erros 502/504 no nginx | Timeout entre nginx e FastAPI | Ajuste timeouts no nginx e otimize o tempo de resposta do backend | Escalando chains e agents: paralelismo e balanceamento |
| Workers FastAPI morrem sob carga | Excesso de tasks ou memory leak | Limite o número de tasks simultâneas e monitore uso de memória | Escalando chains e agents: paralelismo e balanceamento |
| Cluster Elasticsearch não forma ou fica em estado vermelho | IPs errados em discovery.seed_hosts ou portas bloqueadas | Corrija os IPs e libere as portas 9200/9300 no firewall | Escalando Document Stores: clusters Elasticsearch e sharding |
| Consultas lentas em FAISS sharded | Desbalanceamento entre shards ou gargalo de rede/disco | Redistribua dados e monitore I/O dos hosts | Escalando Document Stores: clusters Elasticsearch e sharding |
| Shards do Elasticsearch não são realocados após falha de nó | Faltam réplicas ou configuração de rebalanceamento automática | Aumente o número de réplicas e revise as configurações de allocation | Escalando Document Stores: clusters Elasticsearch e sharding |
| Respostas do Ollama estão lentas ou travando sob carga | Instância sobrecarregada ou falta de GPU suficiente | Distribua carga com mais instâncias e balanceador; monitore uso de GPU | Escalando Ollama e Qdrant: limites reais e estratégias |
| Consultas ao Qdrant retornam erro 503 | Shard ou nó indisponível | Verifique status dos nós no cluster e reinicie serviços | Escalando Ollama e Qdrant: limites reais e estratégias |
| Dados inconsistentes entre réplicas do Qdrant | Problemas de sincronização ou rede lenta | Revisite configuração de replicação e monitore logs de sincronização | Escalando Ollama e Qdrant: limites reais e estratégias |
| Erro de incompatibilidade de versão ao carregar modelo ONNX | Opset do modelo maior que o suportado pelo runtime ONNX no KServe | Exporte o modelo com opset suportado ou atualize o runtime. | Escolha de modelos, formatos e pipelines de inferência |
| Resultado incoerente na inferência | Pré-processamento ausente ou incorreto | Valide o pipeline de transformação com dados reais. | Escolha de modelos, formatos e pipelines de inferência |
| Falha ao carregar modelo SKLearn | Diferença de versão do Python ou da biblioteca | Garanta ambientes idênticos na serialização e no deploy. | Escolha de modelos, formatos e pipelines de inferência |
| A resposta do agente é superficial ou incompleta | Modelo com raciocínio insuficiente para a tarefa | Troque para um modelo mais avançado (ex: de Haiku para Sonnet ou Opus) | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e GPT-5 |
| Tempo de resposta alto demais | Modelo escolhido é pesado para a carga | Avalie usar um modelo mais rápido (ex: Sonnet ou Haiku) | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e GPT-5 |
| Custo operacional fora do previsto | Uso excessivo de modelos caros em tarefas simples | Reclassifique tarefas e use modelos mais econômicos onde possível | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e GPT-5 |
| A resposta do modelo demora muito | Modelo escolhido é mais lento (ex: Fable) ou prompt está grande demais | Use modelo mais rápido (Haiku/Sonnet) ou reduza o contexto | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e outro |
| Erro de limite de contexto | Prompt ou histórico excede o limite de tokens do modelo | Resuma ou divida a entrada; consulte o limite do modelo | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e outro |
| Custo inesperado na conta | Uso de modelo caro para tarefa simples ou prompts longos demais | Troque para modelo mais barato e otimize prompts | Escolha do modelo: Fable, Opus, Sonnet, Haiku, GPT-6 e outro |
| O agente retorna respostas inconsistentes entre execuções | Prompt de sistema genérico ou contexto excessivo | Divida em subagentes e revise os prompts para cada função | Escolhendo entre agente único e multiagente: critérios para |
| Dados de uma etapa não chegam corretamente à próxima | Erro na orquestração ou no contrato de saída/entrada | Padronize o formato dos dados e valide antes do handoff | Escolhendo entre agente único e multiagente: critérios para |
| Aprovação humana não é registrada | Falta de logging ou de hooks de revisão | Implemente hooks ou guardrails para capturar e registrar decisões | Escolhendo entre agente único e multiagente: critérios para |
| O agente acessa dados sensíveis sem necessidade | Permissões mal configuradas ou prompt excessivo | Restrinja variáveis de ambiente e revise o escopo de cada agente | Escolhendo entre agente único e multiagente: critérios para |
| Resposta cortada ou incompleta | Contexto ou saída excedeu o limite do modelo | Reduza a entrada ou divida a tarefa entre agentes | Escolhendo modelo e contexto: Fable, Opus, Sonnet, Haiku, GP |
| Erro de API ao enviar dados | Tamanho do payload acima do permitido | Remova dados desnecessários ou troque para modelo com contexto maior | Escolhendo modelo e contexto: Fable, Opus, Sonnet, Haiku, GP |
| Recomendações superficiais | Prompt de sistema pouco claro ou contexto irrelevante | Refine o prompt e selecione dados essenciais | Escolhendo modelo e contexto: Fable, Opus, Sonnet, Haiku, GP |
| Respostas incompletas ou truncadas | Modelo com contexto insuficiente para o tamanho do contrato | Troque para um modelo com maior capacidade de contexto, como Claude Fable 5.1 | Escolhendo modelos e recursos: Claude, GPT e voz/vídeo para |
| Custo acima do esperado | Uso de modelo avançado em tarefas simples | Redirecione tarefas rápidas para modelos mais econômicos, como Haiku 4.5 ou GPT-5.6 Luna | Escolhendo modelos e recursos: Claude, GPT e voz/vídeo para |
| Latência alta em geração de voz ou vídeo | Fila de processamento ou uso simultâneo elevado | Implemente filas assíncronas e monitore o uso de recursos | Escolhendo modelos e recursos: Claude, GPT e voz/vídeo para |
| Erro de contexto excedido | O volume de dados enviado ultrapassa o limite do modelo escolhido. | Divida os dados em lotes menores ou troque para um modelo com contexto maior. | Escolhendo modelos e recursos: Fable, Opus, Sonnet, Haiku, G |
| Respostas truncadas ou incompletas | Saída máxima do modelo foi atingida. | Reduza o tamanho da entrada ou ajuste a configuração de saída. | Escolhendo modelos e recursos: Fable, Opus, Sonnet, Haiku, G |
| Custo elevado em tarefas simples | Modelo avançado usado onde não era necessário. | Troque para um modelo mais econômico para essas etapas. | Escolhendo modelos e recursos: Fable, Opus, Sonnet, Haiku, G |
| O agente retorna valores inesperados nos cálculos | Prompt ou contrato da ferramenta desatualizado | Revisar a versão do prompt e os parâmetros da ferramenta | Especificando agentes: prompt de sistema versionado, ferrame |
| Ações críticas são executadas sem revisão humana | Critérios de handoff ausentes ou mal implementados | Adicionar regras de handoff explícitas no contrato e nos guardrails | Especificando agentes: prompt de sistema versionado, ferrame |
| Dados sensíveis aparecem nos logs | Falta de restrição de campos acessados | Reforçar restrições de dados no prompt e nos contratos | Especificando agentes: prompt de sistema versionado, ferrame |
| Respostas truncadas ou erro de contexto | Prompt ou histórico excedeu o limite de tokens do modelo | Reduza o tamanho do histórico ou resuma anexos antes de enviar | Estimando carga e recursos: tokens, chamadas e paralelismo |
| Erros de rate limit na API | Número de chamadas simultâneas excedeu o permitido | Implemente controle de paralelismo e retry exponencial | Estimando carga e recursos: tokens, chamadas e paralelismo |
| Custo diário acima do previsto | Tarefas consumindo mais tokens que o estimado | Revise prompts, otimize respostas e use batch/caching quando possível | Estimando carga e recursos: tokens, chamadas e paralelismo |
| Pods não escalam mesmo com aumento de tráfego | Configuração incorreta de minReplicas, maxReplicas ou autoscaling desativado | Revise as configurações do InferenceService e do Knative | Estratégias de escalabilidade horizontal e vertical com KSer |
| Pods entram em CrashLoopBackOff ao escalar | Limites de recursos muito baixos ou modelo pesado demais | Ajuste os limites de CPU/memória ou otimize o modelo | Estratégias de escalabilidade horizontal e vertical com KSer |
| Escalabilidade vertical não altera performance | Workload limitado por paralelismo, não por recursos individuais | Prefira escalabilidade horizontal | Estratégias de escalabilidade horizontal e vertical com KSer |
| Proposta não aparece no funil | Falha na integração ou erro na função registrar_funil | Verifique logs e teste a função isoladamente com dados de exemplo | Estudo de caso: agente de propostas e acompanhamento de funi |
| Proposta enviada sem revisão acima do limite | Guardrail mal implementado ou bypassado | Reforce validação no código e revise casos de teste | Estudo de caso: agente de propostas e acompanhamento de funi |
| Campos obrigatórios ausentes na proposta | Prompt de sistema incompleto ou parsing falho | Ajuste o prompt e valide a saída com testes automatizados | Estudo de caso: agente de propostas e acompanhamento de funi |
| Leads não recebem resposta do agente | Erro na configuração da API ou chave inválida | Verifique as variáveis de ambiente e permissões da API | Estudo de caso: agente de prospecção e qualificação em opera |
| Scoring não é atribuído corretamente | Prompt de scoring mal definido ou dados incompletos | Revise o prompt e garanta que todos os campos necessários estão presentes | Estudo de caso: agente de prospecção e qualificação em opera |
| Decisões automatizadas sem justificativa | Falta de guardrail de saída | Implemente validação obrigatória da saída do agente | Estudo de caso: agente de prospecção e qualificação em opera |
| Relatório aponta divergências falsas | Diferença de formato ou atraso na atualização de dados | Padronize tipos de retorno e valide datas de atualização antes de comparar | Estudo de caso: conferência automatizada de folha e benefíci |
| Timeout em consulta a benefícios | API lenta ou indisponível | Implemente retry com backoff e alerta para revisão manual | Estudo de caso: conferência automatizada de folha e benefíci |
| Erro de arredondamento nos valores | Regras diferentes entre sistemas | Padronize arredondamento para duas casas decimais antes da comparação | Estudo de caso: conferência automatizada de folha e benefíci |
| Ação automática sem aprovação | Prompt de sistema mal configurado | Reforce a instrução de aguardar aprovação humana antes de executar alterações | Estudo de caso: conferência automatizada de folha e benefíci |
| Documento válido rejeitado pelo agente | Contrato da ferramenta não cobre todos os formatos | Amplie os formatos aceitos e revise os casos de teste | Estudo de caso: onboarding automatizado com voz, vídeo e apr |
| Vídeo de boas-vindas não é entregue | Erro na chamada da API HeyGen ou formato não suportado | Verifique logs, valide parâmetros e implemente fallback em áudio | Estudo de caso: onboarding automatizado com voz, vídeo e apr |
| Logs ausentes ou incompletos | Tracing insuficiente ou falha de configuração do logger | Ajuste o nível de log e revise pontos de registro em cada etapa | Estudo de caso: onboarding automatizado com voz, vídeo e apr |
| A IA retorna respostas inconsistentes para a mesma pergunta | Prompt ambíguo ou ferramenta sem contrato claro | Reescreva o prompt e defina contratos explícitos | Evite armadilhas: erros clássicos ao automatizar RH com IA |
| Mudanças quebram rotinas que funcionavam antes | Falta de teste de regressão | Implemente e rode casos de teste automatizados a cada alteração | Evite armadilhas: erros clássicos ao automatizar RH com IA |
| Dados sensíveis aparecem em logs ou prompts | Mau uso de variáveis ou falta de anonimização | Use variáveis de ambiente e minimize dados pessoais | Evite armadilhas: erros clássicos ao automatizar RH com IA |
| A IA aprova desligamentos ou pagamentos sem revisão | Fluxo sem etapa de aprovação humana | Inclua obrigatoriamente a revisão manual nas ações críticas | Evite armadilhas: erros clássicos ao automatizar RH com IA |
| O agente acessa arquivos fora do escopo | Permissões mal configuradas | Revise o arquivo de permissões e restrinja o allow/deny. | Evite os 7 pecados do agente de gestão: erros clássicos e co |
| Relatórios apresentam dados inventados | Prompt sem delimitar fonte de dados | Inclua instrução explícita para usar apenas ferramentas autorizadas. | Evite os 7 pecados do agente de gestão: erros clássicos e co |
| Não há logs das execuções | Tracing/log desativado no ambiente | Habilite tracing no SDK e configure persistência dos logs. | Evite os 7 pecados do agente de gestão: erros clássicos e co |
| O agente apresenta comportamento inesperado após atualização | Mudança no prompt ou ferramenta sem teste regressivo suficiente | Reverta para a versão anterior e revise os testes. | Evolução controlada: como atualizar sem perder controle |
| Rollback não restaura o comportamento anterior | Versionamento incompleto ou deploy manual inconsistente | Centralize tudo no Git e padronize o processo de deploy. | Evolução controlada: como atualizar sem perder controle |
| Responsável técnico não foi avisado da mudança | Falta de processo formal de comunicação | Implemente checklist de comunicação obrigatória antes do deploy. | Evolução controlada: como atualizar sem perder controle |
| Erro 422 ao chamar o endpoint | Entrada não segue o schema pydantic | Verifique se o JSON enviado contém todos os campos obrigatórios e tipos corretos | Expondo fluxos LangChain com FastAPI |
| Erro 401 Unauthorized | Chave de API ausente ou incorreta | Inclua o header x-api-key com o valor correto na requisição | Expondo fluxos LangChain com FastAPI |
| Timeout ou lentidão nas respostas | Chain muito pesada ou modelo LLM lento | Otimize o fluxo ou use modelos mais rápidos | Expondo fluxos LangChain com FastAPI |
| Busca lenta no FAISS | Dataset muito grande para a RAM | Reduza o volume ou use Elasticsearch. | FAISS, Elasticsearch e bancos vetoriais: quando usar cada um |
| Erro de conexão no Elasticsearch | Cluster não iniciado ou configuração incorreta | Verifique se o serviço está rodando e as credenciais estão corretas. | FAISS, Elasticsearch e bancos vetoriais: quando usar cada um |
| Documentos não aparecem nas buscas | Embeddings não indexados corretamente | Confirme se os embeddings foram gerados e indexados. | FAISS, Elasticsearch e bancos vetoriais: quando usar cada um |
| TTS demora mais de 2 segundos | Modelo pesado ou texto longo | Troque para modelo Flash ou divida o texto | Falhas comuns: latência, áudio ruim, vídeos travando e respo |
| Áudio distorcido ou cortado | Clipping por volume alto ou compressão | Normalize volume e use formato WAV | Falhas comuns: latência, áudio ruim, vídeos travando e respo |
| Vídeo não finaliza ou trava | Polling excessivo ou vídeo muito longo | Use webhooks e divida o vídeo | Falhas comuns: latência, áudio ruim, vídeos travando e respo |
| Transcrição com muitos erros | Áudio ruim ou idioma errado | Melhore a qualidade do áudio e ajuste idioma | Falhas comuns: latência, áudio ruim, vídeos travando e respo |
| Respostas incoerentes do agente | Prompt inconsistente ou contexto perdido | Versione prompt e revise histórico de sessão | Falhas comuns: latência, áudio ruim, vídeos travando e respo |
| Agente não responde após chamada externa | Timeout ou resposta inválida da API/MCP | Implemente timeout, validação e fallback para erros de integração | Falhas de integração e dados: como não cair no óbvio |
| Dados processados incorretamente (proposta errada, lead incompleto) | Falta de validação de entrada/saída | Adicione validação estrutural e semântica com Pydantic | Falhas de integração e dados: como não cair no óbvio |
| Logs ausentes ou pouco informativos | Logging/tracing desativado ou mal configurado | Ative logs detalhados e tracing nos SDKs | Falhas de integração e dados: como não cair no óbvio |
| Tarefas duplicadas após reprocessamento | Falta de controle de idempotência | Implemente identificador único por tarefa e cheque antes de reprocessar | Falhas de integração e dados: como não cair no óbvio |
| Logs vazios ou incompletos | Configuração incorreta do logging ou falta de captura de exceções | Revisar handlers e pontos de captura de erro | Falhas de integração e dados: detectando e corrigindo erros |
| Retry infinito causando sobrecarga | Falta de limite de tentativas no retry | Configurar stop_after_attempt adequado | Falhas de integração e dados: detectando e corrigindo erros |
| Fallback não aciona em falha real | Exceções não tratadas corretamente | Garantir try/except englobando toda a chamada externa | Falhas de integração e dados: detectando e corrigindo erros |
| O agente retorna erro de parâmetro ausente ao chamar ferramenta MCP. | Contrato da ferramenta divergente: nome ou tipo de parâmetro incompatível. | Revise a assinatura da função e alinhe com o contrato MCP. | Falhas de integração e limites de modelo: como isolar e reso |
| Erro de limite de tokens ou arquivo ao enviar dados grandes. | Prompt ou arquivo excede o limite do modelo. | Implemente validação prévia e divida o conteúdo em lotes menores. | Falhas de integração e limites de modelo: como isolar e reso |
| Respostas inesperadas ou vazias do agente. | Falha de integração com API externa ou timeout. | Cheque logs, status HTTP e tente isolar a chamada da ferramenta. | Falhas de integração e limites de modelo: como isolar e reso |
| Agente retorna resposta vazia | Timeout ou endpoint MCP inacessível | Verifique conectividade e endpoint | Falhas de integração, ferramentas e limites: diagnóstico ráp |
| Erro 'Tool response does not match contract' | Tipo de retorno divergente | Ajuste o tipo de retorno da função | Falhas de integração, ferramentas e limites: diagnóstico ráp |
| Erro 413 (payload too large) | Entrada excede limite do modelo | Divida a entrada em blocos menores | Falhas de integração, ferramentas e limites: diagnóstico ráp |
| Erro de autenticação MCP | Chave de API inválida ou ausente | Atualize a chave de API nas variáveis de ambiente | Falhas de integração, ferramentas e limites: diagnóstico ráp |
| Timeout ao chamar API externa | Problema de rede ou endpoint fora do ar | Verifique conectividade, DNS e tempo de resposta do endpoint | Falhas de integração: como isolar e resolver problemas com M |
| Erro 401 Unauthorized | Chave de API inválida ou expirada | Atualize a chave e revise permissões | Falhas de integração: como isolar e resolver problemas com M |
| Erro 400 Bad Request | Parâmetros enviados fora do contrato | Revise o payload e o schema da API | Falhas de integração: como isolar e resolver problemas com M |
| Resposta vazia ou incompleta | Mudança no formato de resposta da API | Atualize o validador de schema e ajuste o processamento | Falhas de integração: como isolar e resolver problemas com M |
| Agente não aciona fallback | Contingência não implementada ou mal configurada | Implemente e teste o fallback para fontes alternativas | Falhas de integração: como isolar e resolver problemas com M |
| O agente retorna resposta vazia ou genérica | Erro de autenticação ou endpoint incorreto | Verifique token, endpoint e headers da requisição | Falhas de integração: detectando e corrigindo problemas entr |
| Timeout ao consultar sistema externo | Sistema externo indisponível ou erro de rede | Teste a conectividade e aumente o timeout se necessário | Falhas de integração: detectando e corrigindo problemas entr |
| Dados retornados estão desatualizados | Cache não invalidado ou integração com endpoint antigo | Limpe o cache e atualize o endpoint | Falhas de integração: detectando e corrigindo problemas entr |
| Erro de schema (campo ausente ou renomeado) | Mudança na API do sistema externo | Atualize o código da ferramenta e os casos de teste | Falhas de integração: detectando e corrigindo problemas entr |
| Logs não mostram detalhes da falha | Nível de log insuficiente | Ajuste para DEBUG e ative tracing | Falhas de integração: detectando e corrigindo problemas entr |
| O agente não retorna resposta após integração | Timeout ou erro silencioso na chamada externa | Verifique logs e implemente timeout explícito com retry | Falhas de integração: diagnóstico e recuperação em sistemas |
| Mensagens de erro 401 Unauthorized | Chave de API inválida ou expirada | Atualize a variável de ambiente com a chave correta | Falhas de integração: diagnóstico e recuperação em sistemas |
| Falhas recorrentes em sistemas diferentes | Problema de rede ou DNS | Teste conectividade e revise configurações de rede | Falhas de integração: diagnóstico e recuperação em sistemas |
| Dados divergentes entre sistemas | Cache desatualizado ou resposta parcial | Limpe cache e force sincronização completa | Falhas de integração: diagnóstico e recuperação em sistemas |
| O agente retorna erro genérico ao consultar sistema externo | Schema de resposta MCP incompatível ou endpoint fora do ar | Ajustar schema ou restaurar endpoint, validando com caso de teste | Falhas de integração: MCP, voz e vídeo fora do ar, como isol |
| Áudio não é gerado e não há mensagem clara | Chave API ElevenLabs inválida ou voice_id inexistente | Corrigir chave ou voice_id e testar novamente | Falhas de integração: MCP, voz e vídeo fora do ar, como isol |
| Vídeo HeyGen fica indefinidamente em 'waiting' | Processamento travado ou erro não tratado | Consultar status via API, registrar erro e tentar recriar vídeo após análise | Falhas de integração: MCP, voz e vídeo fora do ar, como isol |
| Solicitação do colaborador some após falha | Falta de registro de contexto ou logs insuficientes | Implementar logging detalhado e fallback para humano | Falhas de integração: MCP, voz e vídeo fora do ar, como isol |
| O agente não executa a ferramenta e não há resposta | Timeout ou endpoint MCP indisponível | Verifique logs de tracing e conectividade da ferramenta. | Falhas de integração: quando a automação não conversa |
| Erro de autenticação ao chamar ferramenta externa | Chave de API ausente ou inválida | Confirme variáveis de ambiente e permissões. | Falhas de integração: quando a automação não conversa |
| Resposta da ferramenta não tem campo obrigatório | Contrato de integração desatualizado ou erro na ferramenta | Revise o contrato e atualize os testes. | Falhas de integração: quando a automação não conversa |
| O agente trava esperando resposta da API. | Timeout não definido ou muito alto. | Defina timeout explícito em todas as chamadas externas. | Falhas de integração: quando a ferramenta não responde ou re |
| O agente entra em loop de retries. | Limite de tentativas não configurado. | Implemente limite de retries e backoff exponencial. | Falhas de integração: quando a ferramenta não responde ou re |
| Erro de ferramenta não aparece nos logs. | Logging incompleto ou mal configurado. | Inclua stack trace e contexto completo nos logs de erro. | Falhas de integração: quando a ferramenta não responde ou re |
| Usuário recebe mensagem de erro técnico. | Erro não tratado ou fallback ausente. | Implemente fallback e mensagens amigáveis ao usuário. | Falhas de integração: quando a ferramenta não responde ou re |
| Erro 401 ao chamar ElevenLabs | Chave de API inválida ou expirada | Atualize a chave de API na variável de ambiente | Falhas em integração, voz e vídeo: diagnóstico rápido com lo |
| Erro 400 na criação de vídeo HeyGen | Campo obrigatório ausente no payload | Inclua avatar_id, script e voice_id | Falhas em integração, voz e vídeo: diagnóstico rápido com lo |
| Áudio gerado mas sem som | Texto vazio ou voice_id inexistente | Verifique o texto e o voice_id enviado | Falhas em integração, voz e vídeo: diagnóstico rápido com lo |
| Status do vídeo HeyGen não sai de 'waiting' | Processamento em fila ou payload inválido | Aguarde alguns minutos e revise o payload | Falhas em integração, voz e vídeo: diagnóstico rápido com lo |
| Log não registra erro, mas integração falha | Exceção não capturada ou log mal configurado | Reveja o nível e formato do logging | Falhas em integração, voz e vídeo: diagnóstico rápido com lo |
| O agente publica conteúdo incompleto ou corrompido | Não validou status de resposta da ferramenta externa | Adicione guardrail para só publicar com status 'completed'. | Falhas em integrações e ferramentas: diagnóstico e rollback |
| Erro 429 em integração com ElevenLabs | Limite de uso da API atingido | Implemente retry com backoff e alerta para revisão do fluxo. | Falhas em integrações e ferramentas: diagnóstico e rollback |
| Rollback não remove recurso criado | ID do recurso não foi registrado corretamente | Garanta que cada criação registre o ID retornado pela API. | Falhas em integrações e ferramentas: diagnóstico e rollback |
| Logs não mostram detalhes do erro | Nível de log insuficiente ou falta de contexto | Inclua payload, status, tempo e exceção nos logs. | Falhas em integrações e ferramentas: diagnóstico e rollback |
| Agente ignora variações relevantes | Prompt insuficiente ou ferramenta de comparação com erro | Revisar prompt e lógica de comparação de saldos | Fechamento mensal e explicação de variações: agentes e revis |
| Explicações automáticas incoerentes | Dados de entrada inconsistentes ou prompt genérico demais | Ajustar dados de teste e detalhar o prompt | Fechamento mensal e explicação de variações: agentes e revis |
| Aprovação humana não registrada | Workflow de revisão incompleto ou falta de logging | Implementar registro obrigatório de cada ação do contador | Fechamento mensal e explicação de variações: agentes e revis |
| A IA tenta chamar a função com argumentos errados | Contrato Pydantic ausente ou permissivo demais | Reforce validação nos modelos e adicione testes de borda | Ferramentas e contratos: como a IA chama funções externas |
| Função executa ação perigosa sem revisão | Faltam guardrails ou handoff obrigatório | Implemente lógica de permissão e revisão humana para ações críticas | Ferramentas e contratos: como a IA chama funções externas |
| Logs não mostram chamadas de função | Tracing não habilitado ou mal configurado | Ative tracing no SDK e revise configuração de logs | Ferramentas e contratos: como a IA chama funções externas |
| A IA tenta usar a ferramenta com parâmetros errados | Contrato mal definido ou descrição ambígua | Revise nome, descrição e tipos dos parâmetros; use exemplos claros | Ferramentas, skills e plugins: contratos e casos de uso |
| A função executa com dados inválidos | Falta de validação na entrada | Implemente checagem rigorosa antes de executar qualquer ação | Ferramentas, skills e plugins: contratos e casos de uso |
| A saída da ferramenta não aparece no agente | Formato de retorno incompatível com o contrato | Garanta que a função retorna exatamente o formato esperado | Ferramentas, skills e plugins: contratos e casos de uso |
| Fila cresce indefinidamente | Gargalo no processamento ou limite da API atingido | Reduza a entrada, aumente workers ou otimize o processamento; revise limites da API | Filas e paralelismo: até onde dá para acelerar sem perder co |
| Workers travam ou morrem | Exceções não tratadas ou falta de timeout | Implemente tratamento de erros e timeout em cada worker | Filas e paralelismo: até onde dá para acelerar sem perder co |
| Logs incompletos ou confusos | Tracing insuficiente ou IDs duplicados | Garanta IDs únicos e logging estruturado por tarefa | Filas e paralelismo: até onde dá para acelerar sem perder co |
| Agente aprova pagamento sem revisão | Trigger de revisão mal configurado ou prompt incorreto | Revisar lógica de triggers e instruções do agente | Financeiro, atendimento, RH: três exemplos de multiagentes e |
| Logs de tracing ausentes | Tracing não habilitado no SDK | Ativar tracing na configuração do agente | Financeiro, atendimento, RH: três exemplos de multiagentes e |
| Dados pessoais vazando em logs | Falta de anonimização ou filtragem | Implementar filtros e revisar contratos de ferramentas | Financeiro, atendimento, RH: três exemplos de multiagentes e |
| Nota fiscal não aparece no relatório | Arquivo corrompido ou nome incorreto no diretório de entrada | Verifique a integridade do arquivo e a padronização do nome. | Fluxo de dados no fiscal: da nota ao relatório |
| Alerta de campo obrigatório ausente | Estrutura do XML incompatível com o parser | Atualize o script de extração para refletir o leiaute vigente. | Fluxo de dados no fiscal: da nota ao relatório |
| Erro de cálculo de imposto | Regra de cálculo desatualizada ou valor fora do padrão EXEMPLO | Revise as fórmulas e os parâmetros do cálculo. | Fluxo de dados no fiscal: da nota ao relatório |
| O agente toma decisão sem aprovação humana | Falta de trigger ou bloqueio para revisão em decisões sensíveis | Configure pontos de controle obrigatórios antes de executar ações críticas. | Fluxo de dados no planejamento com IA: do input ao replaneja |
| Saídas não são rastreáveis | Ausência de versionamento ou logs automáticos | Implemente registro automático de todas as saídas e logs de execução. | Fluxo de dados no planejamento com IA: do input ao replaneja |
| Dados de entrada inconsistentes | Falta de padronização ou validação de schema | Padronize entradas em JSON e valide antes do processamento. | Fluxo de dados no planejamento com IA: do input ao replaneja |
| Currículo não aparece para triagem | Falha no upload ou no registro do arquivo | Verifique logs do endpoint e permissões de storage | Fluxo de dados no RH automatizado: do currículo ao plano de |
| Agente retorna erro de campo ausente | Dados extraídos incompletos ou mal formatados | Ajuste o script de extração e valide campos obrigatórios | Fluxo de dados no RH automatizado: do currículo ao plano de |
| Vídeo de treinamento não é gerado | Chave de API HeyGen inválida ou parâmetros incorretos | Confirme chave, parâmetros e formato do payload | Fluxo de dados no RH automatizado: do currículo ao plano de |
| Dados de entrada são aceitos mesmo com campos faltando | Modelo de validação incompleto ou sanitização ausente | Reforce o uso de Pydantic e valide todos os campos obrigatórios | Fluxo de dados, comandos e aprovações: do input ao registro |
| Logs não mostram decisões tomadas pelo agente | Tracing não habilitado ou diretório de logs incorreto | Ative o tracing e verifique permissões no diretório de logs | Fluxo de dados, comandos e aprovações: do input ao registro |
| Dados pessoais aparecem em logs ou prompts sem necessidade | Falta de anonimização ou minimização de dados | Implemente filtros para remover ou anonimizar dados sensíveis | Fluxo de dados, comandos e aprovações: do input ao registro |
| Respostas incoerentes ou fora do contexto | Pré-processamento inadequado ou contexto insuficiente recuperado do banco vetorial | Ajuste o tamanho dos chunks e revise a consulta vetorial. | Fluxo de dados: do prompt ao resultado em LangChain |
| Latência alta nas buscas | Índice vetorial mal configurado ou infraestrutura limitada | Otimize o índice e revise a infraestrutura do banco vetorial. | Fluxo de dados: do prompt ao resultado em LangChain |
| Dados sensíveis vazando na resposta | Falta de pós-processamento ou regras de filtragem insuficientes | Implemente filtros mais rigorosos no pós-processamento. | Fluxo de dados: do prompt ao resultado em LangChain |
| O agente rejeita todas as entradas | Schema de validação excessivamente restritivo ou campos obrigatórios ausentes | Revise o schema e garanta que os dados de entrada estejam completos e no formato esperado | Fluxo de decisão: do dado bruto à recomendação auditável |
| Recomendações fora dos limites de negócio | Guardrails de saída ausentes ou mal implementados | Adicione validações explícitas para cada campo crítico antes de liberar a recomendação | Fluxo de decisão: do dado bruto à recomendação auditável |
| Faltam registros de aprovação humana | Processo de aprovação não integrado ao fluxo de registro | Inclua etapa obrigatória de aprovação e registro antes de executar ações finais | Fluxo de decisão: do dado bruto à recomendação auditável |
| Lançamentos não aparecem no sistema | Erro na integração entre agente e ferramenta de registro | Reveja o contrato da ferramenta e valide o retorno. | Fluxo do lançamento ao fechamento: arquitetura do agente con |
| Logs ausentes ou incompletos | Tracing não habilitado ou diretório sem permissão | Ative o tracing e ajuste permissões do diretório de logs. | Fluxo do lançamento ao fechamento: arquitetura do agente con |
| Sugestões incoerentes de classificação | Prompt de sistema mal definido ou dados de entrada inconsistentes | Revisite o prompt e padronize os dados de entrada. | Fluxo do lançamento ao fechamento: arquitetura do agente con |
| Lead não recebe dados complementares | Fonte de dados externa indisponível ou chave de API inválida | Verifique conectividade e credenciais das integrações | Fluxo ideal do comercial com agentes: do lead ao resumo da r |
| Proposta gerada com produtos fora do catálogo | Prompt de sistema mal definido ou catálogo desatualizado | Revisar prompt e atualizar catálogo digital | Fluxo ideal do comercial com agentes: do lead ao resumo da r |
| Alertas de leads parados não são enviados | Lógica de monitoramento não está rodando ou variável de tempo mal calculada | Ajustar agendamento e validação de datas no código | Fluxo ideal do comercial com agentes: do lead ao resumo da r |
| O fluxo para antes da aprovação humana | Guardrail ou handoff não liberado | Verifique se a aprovação foi registrada corretamente e se o orquestrador está monitorando o ponto de pausa. | Fluxo multiagente do administrativo de ponta a ponta com orq |
| Dados sensíveis vazando entre agentes | Contexto passado sem filtragem | Ajuste o orquestrador para repassar apenas os campos necessários a cada agente. | Fluxo multiagente do administrativo de ponta a ponta com orq |
| Logs incompletos ou ausentes | Tracing não implementado em todas as etapas | Inclua chamadas de logging detalhado em cada agente e no orquestrador. | Fluxo multiagente do administrativo de ponta a ponta com orq |
| O fluxo trava na etapa de aprovação | Aguardando resposta humana que não chegou ou não foi processada | Verifique o canal de notificação e a função de aguardar resposta | Fluxo multiagente do apoio à decisão executiva de ponta a po |
| Logs incompletos ou ausentes | Tracing não implementado corretamente nos agentes | Habilite tracing nos SDKs e confira permissões de escrita | Fluxo multiagente do apoio à decisão executiva de ponta a po |
| Teste automatizado falha na validação do registro | Contrato de saída do agente de registro não corresponde ao esperado | Ajuste o contrato e revise o teste | Fluxo multiagente do apoio à decisão executiva de ponta a po |
| O fluxo para e não avança após uma etapa crítica | Aprovação humana não registrada ou sistema de fila travado | Verifique o status de aprovação e o funcionamento da fila ou banco de dados | Fluxo multiagente do comercial e vendas de ponta a ponta com |
| Agente não recebe contexto correto | Erro na passagem de payload entre agentes | Revise o formato do contexto e os contratos das ferramentas | Fluxo multiagente do comercial e vendas de ponta a ponta com |
| Logs incompletos ou faltando ações | Falha na implementação de registro | Garanta que cada etapa registre logs completos, com timestamps e responsáveis | Fluxo multiagente do comercial e vendas de ponta a ponta com |
| Checkpoints de aprovação não aparecem | Ferramenta de aprovação não foi registrada no agente ou chamada no fluxo | Inclua a ferramenta de aprovação na lista de tools do agente e chame explicitamente no fluxo | Fluxo multiagente do contabilidade de ponta a ponta com orqu |
| Dados pessoais vazando no prompt | Falta de anonimização ou minimização dos dados de entrada | Remova ou mascare dados pessoais antes de enviar para o agente | Fluxo multiagente do contabilidade de ponta a ponta com orqu |
| Falha na conciliação automática | Casos de teste divergentes ou lógica de comparação inconsistente | Revise os casos de teste e ajuste a lógica de conciliação | Fluxo multiagente do contabilidade de ponta a ponta com orqu |
| O fluxo para inesperadamente após um checkpoint | Aprovação não foi concedida ou houve exceção no código do checkpoint | Revise o código do checkpoint e garanta que o input está correto. | Fluxo multiagente do desenvolvimento de negócios de ponta a |
| Agente retorna erro de autenticação | Chave de API ausente ou inválida | Verifique as variáveis de ambiente e as permissões da chave. | Fluxo multiagente do desenvolvimento de negócios de ponta a |
| Dados sensíveis aparecem em logs | Logs não filtram informações pessoais | Implemente filtros e minimize o registro de dados pessoais. | Fluxo multiagente do desenvolvimento de negócios de ponta a |
| O agente trava aguardando aprovação | Checkpoint de aprovação humana sem input recebido | Confirme que o responsável foi notificado e o input está sendo lido corretamente. | Fluxo multiagente do estratégia de ponta a ponta com orquest |
| Saídas inesperadas ou fora do escopo | Prompt de sistema mal definido ou ferramenta sem contrato claro | Revise o prompt e os contratos das ferramentas. | Fluxo multiagente do estratégia de ponta a ponta com orquest |
| Logs incompletos ou ausentes | Orquestrador não está registrando outputs de cada etapa | Implemente logging detalhado em cada agente e checkpoint. | Fluxo multiagente do estratégia de ponta a ponta com orquest |
| O fluxo para antes da entrega | Aprovação humana não foi concedida | Confirme a aprovação pelo responsável técnico e reinicie o fluxo | Fluxo multiagente do fiscal de ponta a ponta com orquestrado |
| Dados extraídos incompletos | Prompt do Leitor de Notas mal definido ou arquivo corrompido | Revise o prompt e valide os arquivos de entrada | Fluxo multiagente do fiscal de ponta a ponta com orquestrado |
| Erro de validação fiscal | Regras de validação inconsistentes entre agentes | Padronize contratos e casos de teste entre agentes | Fluxo multiagente do fiscal de ponta a ponta com orquestrado |
| Logs ausentes ou incompletos | Tracing não implementado corretamente | Implemente registro detalhado em cada etapa | Fluxo multiagente do fiscal de ponta a ponta com orquestrado |
| O fluxo trava em um checkpoint | Aguardando aprovação humana ou integração de notificação falhou | Verifique se o canal de aprovação está operacional e se a função de pausa está implementada corretamente. | Fluxo multiagente do gestão de equipes e operações de ponta |
| Um agente retorna erro ou None | Prompt mal formatado ou falta de dados de entrada | Revise o prompt de sistema e garanta que os dados estejam completos e no formato esperado. | Fluxo multiagente do gestão de equipes e operações de ponta |
| Logs não aparecem ou estão incompletos | Tracing não ativado ou mal configurado nos SDKs | Habilite e configure o tracing conforme a documentação dos SDKs. | Fluxo multiagente do gestão de equipes e operações de ponta |
| Falha ao integrar com MCP | Endereço ou credencial incorreta | Confirme as variáveis de ambiente e o endpoint MCP usado no código. | Fluxo multiagente do gestão de equipes e operações de ponta |
| O fluxo para antes do esperado | Checkpoint de aprovação não foi confirmado | Verifique se a aprovação foi registrada corretamente e se o input está correto | Fluxo multiagente do jurídico de ponta a ponta com orquestra |
| Resultados inesperados em etapas automáticas | Casos de teste insuficientes ou prompt mal definido | Reforce os testes e revise o prompt de sistema | Fluxo multiagente do jurídico de ponta a ponta com orquestra |
| Logs incompletos ou ausentes | Tracing não ativado ou falha no registro | Habilite tracing e revise a rotina de logging | Fluxo multiagente do jurídico de ponta a ponta com orquestra |
| Agente retorna erro de autenticação | Chave de API ausente ou inválida | Verifique as variáveis de ambiente e gere nova chave se necessário | Fluxo multiagente do marketing de ponta a ponta com orquestr |
| Fluxo para sem mensagem clara | Teste automático falhou sem tratamento de exceção | Implemente try/except e mensagens de erro detalhadas | Fluxo multiagente do marketing de ponta a ponta com orquestr |
| Aprovação humana não registrada | Falta de persistência do log de decisões | Garanta que o orquestrador salve logs em arquivo ou sistema confiável | Fluxo multiagente do marketing de ponta a ponta com orquestr |
| Execução do comando não ocorre após aprovação | Checkpoint de aprovação não liberou o fluxo | Verifique se a função de aprovação retorna True e não há erro de lógica no orquestrador | Fluxo multiagente do NOC (centro de operações de rede) de po |
| Rollback não é acionado em falha | Agente de rollback não foi instanciado ou chamado corretamente | Implemente chamada explícita ao agente de rollback no bloco de exceção | Fluxo multiagente do NOC (centro de operações de rede) de po |
| Logs de ações não aparecem | Registro de logs não implementado em todos os agentes | Inclua logging em cada etapa do fluxo | Fluxo multiagente do NOC (centro de operações de rede) de po |
| O fluxo trava aguardando aprovação | Checkpoint de aprovação não foi confirmado | Pressione Enter no terminal para aprovar e seguir | Fluxo multiagente do planejamento de ponta a ponta com orque |
| Erro de autenticação ao rodar agentes | Chaves de API ausentes ou inválidas | Configure as variáveis de ambiente corretamente | Fluxo multiagente do planejamento de ponta a ponta com orque |
| Respostas dos agentes não fazem sentido | Prompt de sistema mal definido ou dados de entrada inconsistentes | Revise e ajuste os prompts e dados de teste | Fluxo multiagente do planejamento de ponta a ponta com orque |
| Processo trava aguardando aprovação | Notificação não enviada ou interface de aprovação inoperante | Verifique logs e integrações de notificação | Fluxo multiagente do RH (DP, folha e benefícios) de ponta a |
| Rollback não remove cadastro rejeitado | Função de reversão ausente ou falha | Implemente e teste função de desfazer cadastro | Fluxo multiagente do RH (DP, folha e benefícios) de ponta a |
| Agente retorna erro inesperado | Prompt ou parâmetros inconsistentes | Revise prompts e contratos de ferramenta | Fluxo multiagente do RH (DP, folha e benefícios) de ponta a |
| Logs incompletos | Orquestrador não registra todas as etapas | Inclua logging detalhado em cada passo | Fluxo multiagente do RH (DP, folha e benefícios) de ponta a |
| Checkpoint de aprovação não pausa o fluxo | Função de aprovação mal implementada | Revise o código do checkpoint para garantir bloqueio até aprovação explícita | Fluxo multiagente do RH (R&S, T&D e PDC) de ponta a ponta co |
| Logs ausentes ou incompletos | Tracing não habilitado ou falha de permissão | Ative o tracing nos SDKs e verifique permissões de escrita | Fluxo multiagente do RH (R&S, T&D e PDC) de ponta a ponta co |
| Teste automático não detecta erro | Casos de teste mal definidos | Reveja os casos de teste e alinhe critérios de aprovação | Fluxo multiagente do RH (R&S, T&D e PDC) de ponta a ponta co |
| O fluxo para antes do registro final | Falta de aprovação humana na etapa crítica | Certifique-se de que o responsável aprovou explicitamente antes de seguir | Fluxo multiagente do tributário de ponta a ponta com orquest |
| Dados incompletos nos registros | Algum agente não retornou todos os campos esperados | Revise os prompts e a integração das ferramentas dos agentes | Fluxo multiagente do tributário de ponta a ponta com orquest |
| Erros de autenticação nas APIs | Chaves de API ausentes ou inválidas em variáveis de ambiente | Configure as variáveis corretamente antes de rodar o fluxo | Fluxo multiagente do tributário de ponta a ponta com orquest |
| Erro 413 (Payload Too Large) | Input excede o limite da API (ex: 32 MB na Anthropic) | Valide e limite o tamanho do input antes de enviar | Fluxo ponta a ponta: do input humano ao output estruturado |
| Timeout na resposta da IA | Modelo escolhido é lento ou input é grande demais | Reduza o tamanho do input ou escolha modelo mais rápido | Fluxo ponta a ponta: do input humano ao output estruturado |
| Output fora do formato esperado | Mudança de versão do modelo ou erro no contrato | Atualize o contrato Pydantic e revise parsing | Fluxo ponta a ponta: do input humano ao output estruturado |
| O vídeo do HeyGen não sincroniza com o áudio | Incompatibilidade de formato ou duração do áudio | Garanta que o áudio esteja em um formato suportado e com duração compatível com o avatar escolhido. | Fluxo ponta a ponta: do texto ao vídeo com avatar e voz real |
| Erro 401 ao chamar ElevenLabs ou HeyGen | Chave de API inválida ou ausente | Revise as variáveis de ambiente e permissões das chaves. | Fluxo ponta a ponta: do texto ao vídeo com avatar e voz real |
| Latência excessiva na geração de vídeo | Fila de jobs no HeyGen ou áudio muito longo | Reduza o tamanho do áudio ou consulte o status da API para congestionamento. | Fluxo ponta a ponta: do texto ao vídeo com avatar e voz real |
| Respostas incorretas ou fora do contexto | Prompt mal definido ou dados de entrada inválidos | Revise o prompt de sistema e valide entradas com Pydantic | Fluxos de atendimento, treinamento e comunicação: do protóti |
| Latência alta nas respostas de vídeo | Canal assíncrono e sobrecarga na API do HeyGen | Implemente polling ou webhooks e ajuste a expectativa do usuário | Fluxos de atendimento, treinamento e comunicação: do protóti |
| Falha na integração com sistema legado | Contrato de API inconsistente ou segredo exposto | Valide contratos e use variáveis de ambiente para segredos | Fluxos de atendimento, treinamento e comunicação: do protóti |
| Respostas genéricas, sem contexto externo. | Busca vetorial falhou ou não encontrou documentos relevantes. | Verifique embeddings e a coleção no Qdrant. | Fluxos de dados e orquestração: do prompt ao resultado |
| Erro 413 ou truncamento de prompt. | Prompt excedeu o limite do modelo. | Implemente truncamento ou sumarização no pré-processamento. | Fluxos de dados e orquestração: do prompt ao resultado |
| Modelo não responde ou consome muita RAM. | Modelo escolhido é grande demais para o hardware. | Troque por modelo menor ou ajuste recursos da máquina. | Fluxos de dados e orquestração: do prompt ao resultado |
| Logs incompletos ou faltando etapas | Tracing não configurado corretamente no SDK | Revise a configuração do Tracer e garanta que todas as funções relevantes estejam instrumentadas | Fluxos de revisão e aprovação: trilha de responsabilidade no |
| Handoffs não chegam ao responsável | Agente não está atribuindo responsável ou não está enviando notificação | Implemente atribuição explícita e notificação por e-mail ou sistema interno | Fluxos de revisão e aprovação: trilha de responsabilidade no |
| Casos de teste não detectam falhas | Testes automatizados não cobrem exceções ou cenários críticos | Amplie o conjunto de testes com exemplos de exceção e risco | Fluxos de revisão e aprovação: trilha de responsabilidade no |
| E-mails não são lidos | Configuração IMAP incorreta ou falta de permissão | Verifique servidor, porta e credenciais; teste login manual. | Fluxos integrados: e-mail, planilhas e atendimento automatiz |
| Respostas da IA incoerentes | Prompt mal estruturado ou dados insuficientes | Reveja o prompt e forneça contexto suficiente. | Fluxos integrados: e-mail, planilhas e atendimento automatiz |
| Planilha não atualiza | Erro de tipo de dado ou permissão de arquivo | Valide tipos com pandas e confira permissões do arquivo. | Fluxos integrados: e-mail, planilhas e atendimento automatiz |
| Áudio não gera | voice_id incorreto ou chave de API inválida | Consulte a documentação para o voice_id correto e valide a chave. | Fluxos integrados: e-mail, planilhas e atendimento automatiz |
| Um agente recebe dados irrelevantes ou sensíveis. | Passagem de contexto mal filtrada. | Revise as funções de filtro e minimize o contexto compartilhado. | Fluxos multiagente: divisão de responsabilidades, sincroniza |
| Fallback humano não é acionado quando deveria. | Critérios de guardrails insuficientes ou mal definidos. | Ajuste as condições de fallback e teste com casos limítrofes. | Fluxos multiagente: divisão de responsabilidades, sincroniza |
| Logs de decisão estão incompletos ou ausentes. | Falha na rotina de registro. | Garanta que cada execução relevante chame a função de logging. | Fluxos multiagente: divisão de responsabilidades, sincroniza |
| Análise sem fonte registrada | Falta de implementação do padrão de citação no agente | Revisar o código para sempre anexar metadados de fonte | Fontes, citações e verificação: o que um agente do estratégi |
| Dados pessoais vazando em relatórios | Filtro de minimização ausente ou mal configurado | Implementar e testar função de remoção de campos sensíveis | Fontes, citações e verificação: o que um agente do estratégi |
| Ação crítica executada sem aprovação | Campo de aprovação não verificado antes da execução | Adicionar checagem obrigatória do campo 'aprovado_por' | Fontes, citações e verificação: o que um agente do estratégi |
| Agente executa ação proibida | Limite de automação mal configurado | Reveja a lista de tarefas permitidas e ajuste o código de orquestração | Fronteiras e desafios: o que ainda não é possível automatiza |
| Dados sensíveis aparecem em logs | Falta de anonimização ou filtragem | Implemente anonimização automática e revise o registro | Fronteiras e desafios: o que ainda não é possível automatiza |
| Respostas incoerentes ou enviesadas | Falta de guardrails ou dados de teste insuficientes | Inclua validações e amplie os casos de teste | Fronteiras e desafios: o que ainda não é possível automatiza |
| Erro de validação ao registrar a tool | Schema Pydantic incompatível com o esperado pelo SDK | Revise o uso de .schema() e consulte a documentação do SDK | Function calling: o modelo chama as ferramentas da sua empre |
| Função não é chamada pelo modelo | Prompt de sistema pouco claro ou tool mal registrada | Reforce o prompt e revise o registro da tool | Function calling: o modelo chama as ferramentas da sua empre |
| Retorno inesperado ou vazio | Contrato de saída divergente do esperado | Alinhe o modelo de retorno Pydantic com o schema registrado | Function calling: o modelo chama as ferramentas da sua empre |
| Testes falham para entradas inválidas | Validação insuficiente no contrato Pydantic | Inclua tipos e restrições explícitas nos modelos | Function calling: o modelo chama as ferramentas da sua empre |
| Áudio cortado ou incompleto | Texto excedeu o limite do modelo TTS | Divida o texto em partes menores conforme o limite do ElevenLabs. | Geração multimodal: texto, voz e vídeo na mesma API |
| Vídeo não gera ou falha no upload | Formato de áudio incompatível ou campos obrigatórios ausentes | Converta o áudio para MP3 44100Hz e revise os campos obrigatórios na documentação da HeyGen. | Geração multimodal: texto, voz e vídeo na mesma API |
| Saída do LLM muito longa | Prompt ou modelo com limite menor que o esperado | Ajuste o prompt ou troque de modelo para um com contexto maior; consulte a documentação. | Geração multimodal: texto, voz e vídeo na mesma API |
| Sessões desaparecem após reinício | Backend local ou não persistente | Use backend distribuído e persistente como Redis com RDB/AOF habilitado. | Gerenciamento de estado e memória em escala |
| Respostas incoerentes entre instâncias | Sincronização ausente ou falha | Implemente locks ou versionamento no backend. | Gerenciamento de estado e memória em escala |
| Uso de memória cresce sem parar | Falta de política de retenção | Configure TTL e limpezas periódicas. | Gerenciamento de estado e memória em escala |
| Respostas trocadas entre clientes | Sessões ou contexto compartilhados entre agentes | Garanta isolamento total de sessão e histórico para cada agente | Gerenciamento de múltiplos agentes e fluxos concorrentes |
| Logs incompletos ou misturados | Falta de identificação de sessão nos logs | Inclua sempre o ID da sessão em cada entrada de log | Gerenciamento de múltiplos agentes e fluxos concorrentes |
| Erros de concorrência ou dados corrompidos | Acesso simultâneo a recursos compartilhados sem lock | Implemente locks ou mecanismos de sincronização | Gerenciamento de múltiplos agentes e fluxos concorrentes |
| Dificuldade para rastrear falhas | Ausência de tracing distribuído | Integre ferramenta de tracing e registre eventos críticos | Gerenciamento de múltiplos agentes e fluxos concorrentes |
| O agente responde de forma inesperada após atualização | Prompt ou ferramenta não compatível com a nova versão | Reverta para a versão anterior via Git e revise o contrato da ferramenta | Gerenciamento de versões e migração: evoluindo sem parar a o |
| Rollout não alterna entre versões | Variável de ambiente não setada corretamente | Confirme o valor da variável e reinicie o serviço | Gerenciamento de versões e migração: evoluindo sem parar a o |
| Testes automatizados falham só na nova versão | Mudança não coberta por testes ou incompatibilidade não prevista | Amplie os testes e revise o prompt/ferramenta | Gerenciamento de versões e migração: evoluindo sem parar a o |
| Logs não mostram qual versão foi usada | Falta de registro de versão no tracing | Inclua a versão em cada log de requisição | Gerenciamento de versões e migração: evoluindo sem parar a o |
| A nova versão não recebe tráfego | Campo 'traffic' está zerado ou configuração incorreta no YAML | Verifique e ajuste o campo 'traffic' para a versão desejada | Gerenciamento de versões e rollout seguro de modelos |
| Erro ao aplicar YAML | Sintaxe inválida ou campo não suportado | Remova campos não oficiais como 'canary' ou 'canaryTrafficPercent' e siga o padrão da documentação | Gerenciamento de versões e rollout seguro de modelos |
| Métricas não aparecem no Prometheus | Serviço Prometheus não está instalado ou nome do serviço está incorreto | Confira o nome do serviço (ex: 'prometheus-k8s') e namespace correto | Gerenciamento de versões e rollout seguro de modelos |
| Fila crescendo sem parar | Workers insuficientes ou modelo lento demais | Aumente o número de workers ou use modelos mais rápidos para tarefas simples | Gerenciando múltiplos fluxos: filas, prioridades e balanceam |
| Tarefas urgentes atrasadas | Prioridade não implementada corretamente | Revise a lógica de prioridade na fila | Gerenciando múltiplos fluxos: filas, prioridades e balanceam |
| Logs incompletos ou execuções sem rastreio | Tracing desativado ou mal configurado | Ative e teste o tracing dos SDKs | Gerenciando múltiplos fluxos: filas, prioridades e balanceam |
| O agente responde de forma inesperada após atualização de prompt. | Prompt novo não compatível com ferramentas ou entradas existentes. | Rode testes automatizados, compare com a versão anterior e faça rollback se necessário. | Gerenciando versões de prompts e ferramentas sem caos |
| Erro de importação ao carregar ferramenta. | Nome do módulo ou arquivo de ferramenta não corresponde à versão. | Verifique nomes e caminhos dos arquivos. Corrija a chamada de importação. | Gerenciando versões de prompts e ferramentas sem caos |
| Rollback não reverteu o erro. | Mudanças em dados ou dependências externas não foram revertidas. | Garanta que rollback inclua todos os componentes afetados, não só o prompt ou ferramenta. | Gerenciando versões de prompts e ferramentas sem caos |
| Endpoints não desligam mesmo sem requisições. | Scale-to-zero não está ativado ou o período de graça está alto. | Verifique a configmap config-autoscaler e ajuste enable-scale-to-zero e scale-to-zero-grace-period. | Gestão de custos e eficiência operacional em serving de IA |
| Latência aumentou após reduzir requests. | Requests abaixo do necessário para o workload. | Aumente requests gradualmente e monitore o impacto na latência. | Gestão de custos e eficiência operacional em serving de IA |
| Métricas de uso não aparecem no Prometheus. | Prometheus não está coletando métricas do namespace kserve. | Revise as configurações de targets e relabeling no Prometheus. | Gestão de custos e eficiência operacional em serving de IA |
| Agentes param de responder durante pico de uso | Limite de chamadas ou tokens atingido | Revise cotas e implemente fallback manual | Gestão de custos e recursos em ambientes multiagente |
| Custos inesperados no fim do mês | Falta de monitoramento em tempo real | Ative tracing e revise limites de uso | Gestão de custos e recursos em ambientes multiagente |
| Logs não mostram consumo detalhado por agente | Tracing ou logging mal configurado | Ajuste hooks e revisite configuração de logs | Gestão de custos e recursos em ambientes multiagente |
| O agente gera respostas incoerentes após uma alteração | Prompt de sistema alterado sem revisão ou rollback | Reverta para a última versão aprovada do prompt e repita os testes. | Governança de agentes: papéis, responsabilidades e revisão p |
| Ferramenta retorna erro inesperado | Contrato da ferramenta mudou sem atualização nos testes | Atualize a documentação e os casos de teste para refletir a nova interface. | Governança de agentes: papéis, responsabilidades e revisão p |
| Usuário não foi avisado de mudança crítica | Falta de comunicação na gestão de mudanças | Implemente rotina de aviso obrigatório antes do go-live. | Governança de agentes: papéis, responsabilidades e revisão p |
| Execuções do agente não aparecem nos logs de auditoria. | Hooks de tracing não implementados ou falha de permissão no diretório de logs. | Verifique se o decorator @trace está aplicado e se o diretório de logs tem permissão de escrita. | Governança de agentes: versionamento, auditoria e atualizaçã |
| Rollback falha e o agente continua com comportamento inesperado. | Deploy não foi feito a partir da tag correta ou arquivos antigos não foram sobrescritos. | Garanta que o deploy sempre parte da tag desejada e limpe artefatos antigos antes de subir nova versão. | Governança de agentes: versionamento, auditoria e atualizaçã |
| Ferramenta do agente retorna erro após atualização. | Mudança de contrato (parâmetro ou retorno) sem atualizar todos os pontos de uso. | Versione contratos de ferramentas e revise dependências antes de atualizar em produção. | Governança de agentes: versionamento, auditoria e atualizaçã |
| O agente aceita inputs proibidos sem bloquear. | As funções de validação não estão associadas corretamente ao Guardrails. | Revise a configuração do objeto Guardrails e garanta que os validadores estão na lista correta. | Guardrails de entrada e saída no OpenAI Agents SDK: bloquear |
| Os logs de violação não aparecem no arquivo. | O logging não está configurado ou o caminho do arquivo está incorreto. | Verifique a chamada logging.basicConfig e permissões de escrita no diretório. | Guardrails de entrada e saída no OpenAI Agents SDK: bloquear |
| Exceções não interrompem o fluxo do agente. | Os validadores não estão lançando ValueError corretamente. | Confirme que cada violação realmente lança uma exceção e não apenas retorna um valor. | Guardrails de entrada e saída no OpenAI Agents SDK: bloquear |
| Entradas válidas estão sendo rejeitadas | Regras de validação muito restritivas ou erro de lógica | Revise as funções de validação e ajuste os critérios | Guardrails de entrada e saída: limites para não errar nem va |
| Saídas inadequadas estão passando | Cobertura insuficiente nas regras de saída | Inclua mais casos de teste e amplie as validações | Guardrails de entrada e saída: limites para não errar nem va |
| Logs de incidentes não aparecem | Tracing não habilitado ou erro de permissão no diretório de logs | Habilite o tracer e garanta permissão de escrita | Guardrails de entrada e saída: limites para não errar nem va |
| O agente aceita comandos perigosos | Função de bloqueio incompleta ou não associada ao agente | Reveja a implementação das listas de bloqueio e valide nos testes. | Guardrails de entrada e saída: limites que o agente não pode |
| Entradas válidas estão sendo bloqueadas | Expressão regular ou regra muito restritiva | Ajuste as regras para cobrir só o necessário. | Guardrails de entrada e saída: limites que o agente não pode |
| Saídas indevidas passam pelo guardrail | Falta de validação na resposta do agente | Implemente output_validator para filtrar as respostas. | Guardrails de entrada e saída: limites que o agente não pode |
| O agente executa comandos perigosos mesmo com guardrails | Hook ou guardrail não está sendo chamado corretamente | Revise a configuração dos hooks/guardrails e teste com logs detalhados | Guardrails de entrada e saída: limites técnicos, éticos e le |
| Bloqueios legítimos impedem ações normais | Regras muito restritivas ou mal definidas | Ajuste as condições das regras e valide com casos reais | Guardrails de entrada e saída: limites técnicos, éticos e le |
| Logs não mostram tentativas bloqueadas | Falta de registro no código de validação | Implemente logging explícito em cada bloqueio | Guardrails de entrada e saída: limites técnicos, éticos e le |
| O agente aceita nomes muito curtos ou campos vazios | Validação de entrada insuficiente ou desativada | Reforce a validação com pydantic ou guardrails do SDK | Guardrails de entrada e saída: validando o que entra e o que |
| Saídas do agente expõem dados sensíveis | Falta de validação de saída ou ausência de anonimização | Implemente guardrails de saída e revise os contratos de ferramenta | Guardrails de entrada e saída: validando o que entra e o que |
| Ação irreversível executada sem revisão | Guardrail não marcado como obrigatório para revisão | Ajuste o fluxo para exigir aprovação humana antes da execução | Guardrails de entrada e saída: validando o que entra e o que |
| Ação fiscal executada sem revisão humana | Handoff ou hook de aprovação não implementado corretamente | Revise a função de handoff e garanta que o campo de aprovação seja obrigatório | Guardrails e revisão: limites de atuação do agente fiscal |
| Agente aceita dados inválidos (ex: CNPJ com 13 dígitos) | Função de validação ausente ou não aplicada | Implemente e associe a função de validação ao parâmetro | Guardrails e revisão: limites de atuação do agente fiscal |
| Logs de tracing não aparecem no diretório configurado | Permissões de escrita insuficientes ou caminho incorreto | Ajuste permissões e verifique o caminho do log | Guardrails e revisão: limites de atuação do agente fiscal |
| Erro ao rodar validação automática | Exceção não tratada na função de validação | Adicione tratamento de exceções e mensagens claras | Guardrails e revisão: limites de atuação do agente fiscal |
| O agente aprova contratos automaticamente | Guardrail de saída ausente ou mal implementado | Reforce a validação de saída para bloquear decisões finais sem revisão | Guardrails e revisão: limites do agente e checagem de ações |
| Entradas inválidas não são rejeitadas | Schema de entrada incompleto ou desativado | Implemente validação rígida com Pydantic | Guardrails e revisão: limites do agente e checagem de ações |
| Ações não aparecem no log | Tracing não ativado ou sessão mal configurada | Garanta que todas as execuções estejam dentro de uma sessão de tracing | Guardrails e revisão: limites do agente e checagem de ações |
| Revisão humana não é solicitada | Workflow de aprovação não integrado | Inclua chamada explícita à função de revisão antes de executar ações críticas | Guardrails e revisão: limites do agente e checagem de ações |
| O agente aprova um orçamento acima do limite | Guardrail de entrada não está implementado ou está incorreto | Revise a função de validação e teste com valores extremos | Guardrails e revisão: limites para evitar falhas graves no a |
| Aprovação humana não é registrada | Falta de log na etapa de revisão | Adicione registro explícito da decisão do revisor | Guardrails e revisão: limites para evitar falhas graves no a |
| Ação crítica é executada sem revisão | Fluxo de aprovação não está integrado ao agente | Garanta que a execução dependa da aprovação explícita | Guardrails e revisão: limites para evitar falhas graves no a |
| Entradas inválidas passam para o agente | Validação não implementada ou não integrada ao fluxo | Reveja os hooks e pontos de validação; garanta que o modelo Pydantic ou guardrails está ativo | Guardrails e validação de entrada/saída: evitando erro gross |
| Bloqueios não aparecem nos logs | Registro de exceções ausente ou mal configurado | Inclua logging estruturado nos validadores e configure o destino dos logs | Guardrails e validação de entrada/saída: evitando erro gross |
| Erros de validação não são claros para o usuário | Mensagens genéricas ou não tratadas | Personalize as mensagens de erro nos validadores para facilitar o diagnóstico | Guardrails e validação de entrada/saída: evitando erro gross |
| O agente aceita dados absurdos (ex: receita negativa) | Validação de entrada ausente ou mal configurada | Revisar e reforçar as funções de validação | Guardrails e validação: limites de entrada e saída para evit |
| Respostas com campos faltando ou valores incoerentes | Falta de validação de saída | Adicionar checagem de saída antes de devolver a resposta | Guardrails e validação: limites de entrada e saída para evit |
| Violação não aparece no log | Registro de erro desabilitado ou mal implementado | Ajustar configuração de logging e garantir que exceções sejam capturadas | Guardrails e validação: limites de entrada e saída para evit |
| Usuário não entende o motivo do bloqueio | Mensagem de erro genérica ou ausente | Melhorar feedback ao usuário com explicação clara | Guardrails e validação: limites de entrada e saída para evit |
| O agente aceita entradas inválidas | Contrato de parâmetros mal definido ou regex incorreta | Revisar definição dos parâmetros e padrões de validação | Guardrails e validação: limites de entrada e saída para não |
| Respostas com dados pessoais vazam | Guardrail de saída ausente ou falho | Implementar e testar filtro de saída | Guardrails e validação: limites de entrada e saída para não |
| Tentativas de violação não aparecem nos logs | Registro de eventos não configurado | Adicionar tracing nas funções de bloqueio | Guardrails e validação: limites de entrada e saída para não |
| O agente bloqueia comandos legítimos | Guardrail excessivamente restritivo | Ajustar regras para cobrir só o necessário | Guardrails e validação: limites de entrada e saída para não |
| Agente aceita parâmetros fora do padrão | Guardrail ausente ou mal implementado | Revisar definição dos guardrails e hooks | Guardrails e validação: limites de entrada, saída e ação |
| Dados sensíveis aparecem no retorno | Validação de saída insuficiente | Adicionar inspeção de retorno e bloquear campos não previstos | Guardrails e validação: limites de entrada, saída e ação |
| Ação crítica executada sem aprovação | Fluxo de handoff não configurado | Implementar pausa para aprovação humana antes da execução | Guardrails e validação: limites de entrada, saída e ação |
| Testes automatizados não detectam falhas | Cobertura de teste insuficiente | Adicionar casos para entradas e saídas fora do contrato | Guardrails e validação: limites de entrada, saída e ação |
| Entradas inválidas estão passando para o agente | Função de validação ausente ou mal implementada | Revise e teste as funções de guardrail de entrada | Guardrails, rastreamento e revisão: garantindo segurança e r |
| Logs não aparecem ou estão incompletos | Tracing não ativado ou erro de permissão no diretório de logs | Ative o Tracer e ajuste permissões de escrita | Guardrails, rastreamento e revisão: garantindo segurança e r |
| Decisões críticas são executadas sem revisão | Handoff não implementado corretamente | Garanta que o fluxo realmente pausa e aguarda aprovação | Guardrails, rastreamento e revisão: garantindo segurança e r |
| O agente aceita dados incompletos | Função de validação de entrada ausente ou incorreta | Reveja e teste a função de validação | Guardrails, tracing e revisão: como evitar surpresas do agen |
| Não há registros no log | Tracing não ativado ou caminho de log incorreto | Verifique configuração do Tracer e permissões de escrita | Guardrails, tracing e revisão: como evitar surpresas do agen |
| A IA envia propostas sem revisão | Workflow de handoff não implementado | Inclua etapa de revisão humana antes do envio | Guardrails, tracing e revisão: como evitar surpresas do agen |
| A IA executou uma ação irreversível sem revisão | Falta de implementação de revisão humana ou bypass nos guardrails | Revise o código dos hooks e garanta que toda ação crítica exige aprovação manual | Guardrails: validando entrada, saída e ações irreversíveis |
| Entradas inválidas chegam ao modelo | Validação de entrada ausente ou mal configurada | Reforce contratos de dados e testes de borda | Guardrails: validando entrada, saída e ações irreversíveis |
| Logs de decisões críticas não aparecem | Configuração de logging incorreta ou permissão de escrita insuficiente | Ajuste o caminho do arquivo de log e permissões do sistema | Guardrails: validando entrada, saída e ações irreversíveis |
| Respostas da IA contêm dados sensíveis | Falta de checagem de conteúdo na saída | Implemente filtros pós-processamento para bloquear termos proibidos | Guardrails: validando entrada, saída e ações irreversíveis |
| O agente de destino não entende o contexto recebido | Serialização incompatível ou perda de dados no payload | Padronize o formato (JSON) e valide campos obrigatórios antes do handoff | Handoffs, sessões e filas: como agentes trocam tarefas sem p |
| Respostas fora de contexto após tarefas assíncronas | Sessão não persistida corretamente ou job_id não associado | Implemente persistência robusta e sempre recupere o contexto pelo ID | Handoffs, sessões e filas: como agentes trocam tarefas sem p |
| Dados sensíveis vazando entre agentes | Falta de minimização ou uso de prompt para segredos | Reveja o contrato de contexto e use variáveis de ambiente para segredos | Handoffs, sessões e filas: como agentes trocam tarefas sem p |
| Erro 404 ao acessar /query | Servidor não iniciado ou endpoint incorreto. | Verifique se o haystack-api está rodando e se o endpoint está correto. | Haystack REST API: expondo e consumindo pipelines |
| Resposta vazia em /query | Nenhum documento indexado ou pipeline mal configurado. | Adicione documentos via /documents e revise a configuração do pipeline. | Haystack REST API: expondo e consumindo pipelines |
| Erro 500 no endpoint | Exceção interna no pipeline ou falta de dependências. | Cheque logs do servidor e dependências do Python. | Haystack REST API: expondo e consumindo pipelines |
| Erros 429 (Too Many Requests) frequentes | Limite de concorrência do fornecedor excedido | Reduza o paralelismo ou aumente o número de shards/instâncias | Horizontal ou vertical? Estratégias reais para escalar IA |
| Fila cresce sem esvaziar | Capacidade de processamento insuficiente | Aumente workers ou otimize o código | Horizontal ou vertical? Estratégias reais para escalar IA |
| Um departamento para de responder, outros seguem | Sharding isolou corretamente, mas há sobrecarga local | Reveja limites e recursos do shard afetado | Horizontal ou vertical? Estratégias reais para escalar IA |
| Ferramenta não é chamada pelo agente | Nome ou parâmetros da ferramenta não coincidem com o esperado no prompt | Revise o registro da ferramenta e o prompt de sistema | Implementando agentes multi-ferramenta com Claude Agent SDK |
| Erro de importação do SDK | SDK não instalado ou ambiente virtual errado | Reinstale o SDK e ative o ambiente virtual correto | Implementando agentes multi-ferramenta com Claude Agent SDK |
| Resposta inesperada do agente | Contrato da ferramenta ambíguo ou sem validação de entrada | Defina parâmetros e tipos explicitamente e adicione testes automatizados | Implementando agentes multi-ferramenta com Claude Agent SDK |
| Pods do Istio não sobem | Falta de recursos ou conflito de versão do Kubernetes | Aumente recursos do cluster e confira a versão suportada na documentação | Instalação do KServe e dependências: Istio, Knative e MinIO |
| Knative Serving não inicializa | Istio não instalado corretamente ou CRDs ausentes | Reinstale o Istio e reaplique os manifests do Knative | Instalação do KServe e dependências: Istio, Knative e MinIO |
| Erro ao acessar MinIO | Port-forward não ativo ou service não criado | Refaça o port-forward e verifique o service do MinIO | Instalação do KServe e dependências: Istio, Knative e MinIO |
| Ollama não responde na porta 11434 | Serviço não iniciado ou firewall bloqueando | Verifique se o processo está rodando com 'ps aux | grep ollama' e revise regras de firewall | Instalando Ollama, Open WebUI e Qdrant: o caminho real no Li |
| Open WebUI não conecta ao Ollama | Variável OLLAMA_BASE_URL incorreta ou porta errada | Confirme IP/porta e reinicie o container com a variável correta | Instalando Ollama, Open WebUI e Qdrant: o caminho real no Li |
| Qdrant não persiste dados após reinício | Volume não montado corretamente | Revise o parâmetro '-v' e garanta permissão de escrita no diretório | Instalando Ollama, Open WebUI e Qdrant: o caminho real no Li |
| Tela de autenticação não aparece | Pop-ups bloqueados ou restrição de Apps pelo administrador | Permitir pop-ups ou pedir ao administrador para liberar o app Runway | Instalar e conectar a Runway pedindo ao ChatGPT: instala, va |
| Pedido de chave de API | Fluxo manual ativado por engano | Refazer o pedido ao ChatGPT, pedindo instalação automática | Instalar e conectar a Runway pedindo ao ChatGPT: instala, va |
| Conta errada conectada | Login feito com e-mail diferente | Desconectar e refazer o login com a conta correta | Instalar e conectar a Runway pedindo ao ChatGPT: instala, va |
| Erro de conexão após login | Token expirado ou bloqueio de rede | Atualizar a página, repetir o login ou testar em outra rede | Instalar e conectar a Runway pedindo ao ChatGPT: instala, va |
| Resultados só vêm de um dos Document Stores | Configuração errada dos retrievers ou do JoinDocuments | Revise os inputs dos nodes e o join_mode | Integração avançada: Elasticsearch, FAISS e múltiplos modelo |
| Pipeline retorna erro de conexão | Elasticsearch não está rodando ou FAISS não foi inicializado | Verifique os serviços e as credenciais | Integração avançada: Elasticsearch, FAISS e múltiplos modelo |
| Resultados irrelevantes ou repetidos | JoinDocuments mal configurado (concatenação sem merge) | Ajuste o join_mode para 'merge' e revise os scores | Integração avançada: Elasticsearch, FAISS e múltiplos modelo |
| Erro de dimensão do vetor ao inserir | Dimensão do campo embedding diferente do vetor gerado | Ajuste o campo vector(384) ou gere embeddings com a dimensão correta | Integração com bancos vetoriais: PostgreSQL e Milvus |
| Conexão recusada ao Milvus | Serviço Milvus não está rodando ou porta errada | Verifique se o container está ativo e as portas corretas | Integração com bancos vetoriais: PostgreSQL e Milvus |
| Operador <#> não reconhecido no PostgreSQL | Extensão pgvector não instalada | Instale e habilite a extensão com CREATE EXTENSION vector; | Integração com bancos vetoriais: PostgreSQL e Milvus |
| O áudio não é gerado ou está vazio | Chave de API inválida ou parâmetros incorretos no SDK ElevenLabs | Revise a chave, os parâmetros e consulte a documentação oficial | Integração com ElevenLabs e HeyGen: voz e vídeo como ferrame |
| O vídeo nunca fica pronto | Polling insuficiente ou webhook não configurado corretamente | Implemente polling periódico ou corrija o endpoint do webhook | Integração com ElevenLabs e HeyGen: voz e vídeo como ferrame |
| O agente trava esperando resposta | Fluxo assíncrono não implementado corretamente no laço do agente | Use hooks (Claude Agent SDK) ou handoffs/tracing (OpenAI Agents SDK) | Integração com ElevenLabs e HeyGen: voz e vídeo como ferrame |
| Métricas não aparecem no Prometheus | ServiceMonitor mal configurado ou serviço não expõe /metrics. | Verifique labels, portas e path do ServiceMonitor e do serviço. | Integração com Prometheus e Grafana para métricas de modelos |
| Painéis do Grafana vazios | Datasource Prometheus não configurado ou queries erradas. | Valide a conexão do datasource e revise as queries dos painéis. | Integração com Prometheus e Grafana para métricas de modelos |
| Alertas não disparam mesmo com falha | Regras de alerta com expressão ou labels incorretas. | Revise as expressões das regras e teste manualmente os cenários. | Integração com Prometheus e Grafana para métricas de modelos |
| Erro 'API key missing' ao rodar o script | Variável de ambiente não definida ou nome incorreto | Defina a variável de ambiente correta antes de executar | Integração com Python: scripts reais usando SDKs oficiais |
| Arquivo de áudio não é criado | Falha na chamada à API do ElevenLabs ou permissão de escrita | Verifique a chave, o saldo e permissões do diretório | Integração com Python: scripts reais usando SDKs oficiais |
| ID de vídeo não aparece no output | Erro na chamada à API do HeyGen ou parâmetros inválidos | Consulte a documentação dos campos obrigatórios e revise os logs | Integração com Python: scripts reais usando SDKs oficiais |
| O agente não recebe eventos do sistema | Webhook não configurado corretamente ou endpoint inacessível | Verifique o endpoint, firewall e logs do servidor. | Integração com sistemas legados e APIs empresariais |
| Erro 401 ao chamar API externa | Chave de API ausente ou inválida | Confirme variáveis de ambiente e permissões da chave. | Integração com sistemas legados e APIs empresariais |
| Dados inconsistentes entre agente e sistema legado | Contrato MCP implementado de forma incorreta | Revise a implementação e valide os dados de entrada e saída. | Integração com sistemas legados e APIs empresariais |
| Respostas vazias ou None | Formato de resposta da API mudou ou parsing incorreto | Atualize o adaptador para refletir o novo formato | Integração com sistemas legados e APIs externas |
| Timeout ao acessar sistema legado | Rede lenta ou endpoint indisponível | Implemente retries e monitore latência | Integração com sistemas legados e APIs externas |
| Erro de autenticação | Token expirado ou credencial inválida | Renove o token e valide variáveis de ambiente | Integração com sistemas legados e APIs externas |
| Documentos duplicados após importação | IDs não únicos ou falta de filtro incremental | Implemente verificação de unicidade antes do write_documents | Integração com sistemas legados: ETL e sincronização de dado |
| Dados incompletos no Haystack | Transformação inadequada ou erro de leitura no CSV/JSON | Valide os dados antes de importar e trate exceções | Integração com sistemas legados: ETL e sincronização de dado |
| Importação lenta | Reprocessamento total em vez de incremental | Implemente sincronização incremental usando timestamps ou IDs | Integração com sistemas legados: ETL e sincronização de dado |
| O vídeo gerado não fala o texto correto | Desalinhamento entre o script enviado ao HeyGen e o áudio gerado | Garanta que o texto e o áudio sejam idênticos e enviados juntos | Integração de voz e vídeo: ElevenAgents e HeyGen na jornada |
| O áudio está cortado ou distorcido no vídeo | Formato de áudio incompatível ou bitrate incorreto | Use MP3 44100 Hz 128 kbps e valide antes do envio | Integração de voz e vídeo: ElevenAgents e HeyGen na jornada |
| O agente de voz não responde ao cliente | Erro na configuração do prompt ou falha na integração ASR | Revise o prompt e teste o reconhecimento de fala isoladamente | Integração de voz e vídeo: ElevenAgents e HeyGen na jornada |
| O áudio gerado pelo ElevenAgents está em inglês. | voice_id ou modelo TTS não configurado para português. | Ajuste o voice_id e o campo 'locale' para 'pt-BR' na configuração. | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo co |
| O vídeo do HeyGen não sai do status 'waiting'. | Processamento em andamento ou erro de parâmetros. | Verifique se todos os campos obrigatórios estão corretos e aguarde o tempo de processamento. | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo co |
| O agente de voz retorna respostas incompletas. | Prompt de sistema mal definido ou limite de caracteres na configuração. | Reescreva o prompt para ser mais objetivo e revise os campos de entrada. | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo co |
| O agente não inicia a chamada de voz | Chave de API inválida ou configuração de telefonia ausente | Verifique a chave e a integração SIP/Twilio | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo fi |
| Vídeo não é gerado ou fica em status 'waiting' | Parâmetros obrigatórios faltando ou avatar/voz inválidos | Revise avatar_id, voice_id e campos obrigatórios | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo fi |
| A resposta do responsável não é registrada | Falha no reconhecimento de voz ou na captura do evento | Teste o ASR com frases simples e revise o fluxo de registro | Integração de voz e vídeo: ElevenAgents e HeyGen no fluxo fi |
| Áudio não é reproduzido ou está cortado | Limite de caracteres excedido ou erro de codificação | Reduza o texto ou troque o modelo TTS; confira encoding do arquivo. | Integração de voz e vídeo: ElevenLabs e HeyGen em agentes de |
| Vídeo HeyGen não é entregue | Status da geração não foi consultado ou erro de autenticação | Implemente polling do status e confira chave de API. | Integração de voz e vídeo: ElevenLabs e HeyGen em agentes de |
| Latência alta na resposta | Fila de processamento ou modelo inadequado | Troque para modelo mais rápido na ElevenLabs ou ajuste o fluxo para entregar áudio antes do vídeo. | Integração de voz e vídeo: ElevenLabs e HeyGen em agentes de |
| Erro de validação na entrada da ferramenta | Input não segue o JSON Schema definido | Revise o contrato e ajuste o payload enviado pelo agente | Integração MCP: Claude, OpenAI e ferramentas externas em um |
| Chamada não registrada no log | Rastreamento de sessão desativado ou mal configurado | Ative logs estruturados e garanta que cada chamada gere um evento | Integração MCP: Claude, OpenAI e ferramentas externas em um |
| Respostas inconsistentes entre agentes | Perda de contexto ou sessão não compartilhada | Garanta que o identificador de sessão MCP seja propagado em cada etapa | Integração MCP: Claude, OpenAI e ferramentas externas em um |
| Áudio sai em inglês, não em português | Configuração de 'language' ou 'locale' incorreta | Ajuste para 'pt-BR' nos campos correspondentes | Integrando voz e vídeo: ElevenAgents e HeyGen no onboarding |
| Vídeo não gera ou fica travado em 'waiting' | Avatar ou voice_id inválido, ou script muito longo | Revise IDs e limite o script a até 10.000 caracteres | Integrando voz e vídeo: ElevenAgents e HeyGen no onboarding |
| Colaborador não recebe o vídeo ou áudio | Erro na entrega (e-mail, portal ou telefonia) | Verifique logs de envio e permissões de acesso | Integrando voz e vídeo: ElevenAgents e HeyGen no onboarding |
| Usuário não consegue acessar o modelo mesmo com Role configurada | RoleBinding pode estar ausente ou com nome de usuário incorreto | Revise o RoleBinding e o nome do usuário no manifesto | Isolamento de workloads e RBAC em KServe |
| Modelo de IA consome todos os recursos do cluster | ResourceQuota não aplicada ou insuficiente | Ajuste ou crie ResourceQuota adequada no namespace | Isolamento de workloads e RBAC em KServe |
| Operações não aparecem nos logs de auditoria | Política de auditoria não cobre o recurso ou audit log não está habilitado | Revise audit-policy.yaml e parâmetros do kube-apiserver | Isolamento de workloads e RBAC em KServe |
| InferenceService fica em estado 'NotReady' | Problema de storage (URI inválida) ou imagem do runtime não encontrada | Revise o campo 'storageUri' e a disponibilidade do bucket | KServe, KFServing e Seldon: o que muda, o que fica |
| Erro 503 ao acessar o endpoint | Gateway Istio não configurado ou serviço não exposto | Ajuste o VirtualService e verifique as rotas do Istio | KServe, KFServing e Seldon: o que muda, o que fica |
| Métricas não aparecem no Prometheus | ServiceMonitor do KServe ausente ou mal configurado | Adicione ou corrija o ServiceMonitor no namespace do KServe | KServe, KFServing e Seldon: o que muda, o que fica |
| Classificação errada de lançamentos | Prompt de sistema pouco específico ou exemplos insuficientes | Detalhe as instruções e adicione exemplos positivos e negativos | Lançamentos e conciliação: agentes em operação e lições apre |
| Divergências não identificadas na conciliação | Ferramenta compara apenas valores, ignorando descrições ou datas | Inclua validação por múltiplos campos e ajuste os parâmetros | Lançamentos e conciliação: agentes em operação e lições apre |
| Logs incompletos ou ausentes | Tracing desativado ou mal configurado | Ative e teste o registro detalhado no SDK | Lançamentos e conciliação: agentes em operação e lições apre |
| KeyError ao rodar a SequentialChain | Output_key de uma chain não corresponde ao input esperado pela próxima. | Verifique e alinhe os nomes das variáveis entre as etapas. | LangChain Expression Language (LCEL) e chains customizadas |
| TypeError: string indices must be integers | Output de uma etapa é string, mas a próxima espera dict. | Use TransformChain para adaptar o formato. | LangChain Expression Language (LCEL) e chains customizadas |
| Latência alta na execução da chain | Múltiplas etapas síncronas ou prompts complexos. | Simplifique prompts ou paralelize etapas fora do LangChain. | LangChain Expression Language (LCEL) e chains customizadas |
| Respostas irrelevantes ou genéricas | Escopo de dados mal definido ou modelo inadequado | Reveja as fontes de dados e considere trocar o modelo | Levantando requisitos: do problema ao modelo certo |
| Tempo de resposta alto | Modelo grande demais para o hardware disponível | Escolha um modelo menor ou otimize o ambiente | Levantando requisitos: do problema ao modelo certo |
| Erros de licença ao baixar modelo | Modelo não possui licença aberta ou há restrição de uso | Selecione apenas modelos com licença compatível | Levantando requisitos: do problema ao modelo certo |
| Cobertura insuficiente de perguntas | Casos de uso mal definidos ou dados incompletos | Revisite a análise de casos de uso e amplie o escopo dos dados | Levantando requisitos: do problema ao modelo certo |
| O agente retorna erro de permissão ao tentar acessar dados. | Acesso restrito corretamente, mas a ferramenta não está autorizada ao agente. | Revise a configuração das ferramentas e parâmetros permitidos. | LGPD e minimização: como tratar dados pessoais no agente do |
| Dados pessoais aparecem em logs ou prompts sem necessidade. | Minimização ou anonimização não implementada corretamente. | Ajuste o pipeline para remover ou anonimizar campos antes do processamento. | LGPD e minimização: como tratar dados pessoais no agente do |
| Não há registro de consentimento para operações baseadas em consentimento. | Fluxo de consentimento não implementado ou não integrado ao agente. | Inclua checagem e registro de consentimento antes do processamento. | LGPD e minimização: como tratar dados pessoais no agente do |
| O agente solicita dados desnecessários | Prompt ou contrato de ferramenta mal definido | Revise os contratos e remova campos supérfluos | LGPD e minimização: dados pessoais e sensíveis no agente de |
| Dados sensíveis aparecem em logs | Tracing configurado sem anonimização ou filtro | Ajuste o tracing para registrar apenas identificadores | LGPD e minimização: dados pessoais e sensíveis no agente de |
| Consentimento não está sendo registrado | Fluxo de consentimento ausente ou mal implementado | Implemente registro persistente do consentimento | LGPD e minimização: dados pessoais e sensíveis no agente de |
| Decisões críticas são tomadas sem revisão humana | Falta de checagem de aprovação no fluxo do agente | Inclua etapa obrigatória de revisão humana | LGPD e minimização: dados pessoais e sensíveis no agente de |
| Logs contêm nomes ou CPFs completos | Falta de filtragem ou anonimização nos pontos de registro | Implemente funções de anonimização e revise os hooks de logging | LGPD e minimização: só trate o dado que precisa |
| Dados pessoais permanecem após a finalidade | Rotina de exclusão automática não está funcionando | Agende e teste scripts de limpeza regularmente | LGPD e minimização: só trate o dado que precisa |
| Erro ao acessar logs antigos | Exclusão automática pode estar apagando mais do que deveria | Revise os critérios de tempo e os testes de limpeza | LGPD e minimização: só trate o dado que precisa |
| Dados sensíveis aparecem em logs ou respostas de agentes | Falta de validação ou contratos de dados frouxos | Reforce os modelos de dados e implemente guardrails de saída | LGPD na prática: minimização de dados e base legal para agen |
| Agente solicita dados além do necessário | Prompt de sistema mal definido ou ferramenta genérica | Reescreva o prompt e limite os campos aceitos | LGPD na prática: minimização de dados e base legal para agen |
| Não há registro de base legal para um fluxo automatizado | Falta de documentação ou revisão | Crie e versiona um arquivo de justificativa para cada fluxo | LGPD na prática: minimização de dados e base legal para agen |
| Prompt com dado sensível passou para o modelo | Falta de teste automatizado ou padrão de validação incompleto | Reforce o teste com mais padrões e bloqueio obrigatório | LGPD na prática: minimização, base legal e segredo fora do p |
| Chave de API vazou em log | Segredo foi interpolado em string de log ou prompt | Garanta que segredos só existam em variáveis de ambiente e nunca sejam logados | LGPD na prática: minimização, base legal e segredo fora do p |
| Erro de acesso a variável de ambiente | Variável não definida no ambiente de execução | Configure corretamente o arquivo .env e carregue as variáveis no ambiente | LGPD na prática: minimização, base legal e segredo fora do p |
| Pipeline trava ao bloquear prompt | Exceção não tratada ao validar prompt | Implemente tratamento de exceção e logging seguro | LGPD na prática: minimização, base legal e segredo fora do p |
| Dados pessoais aparecem em logs mesmo após descarte | Logs não foram configurados para anonimização ou exclusão de campos sensíveis | Revise a configuração de logging e implemente filtros para remover ou mascarar dados pessoais | LGPD no agente jurídico: minimização, base legal e registro |
| Agente solicita mais dados do que o necessário | Prompt ou ferramenta mal desenhada, sem aplicação do princípio da minimização | Reduza os parâmetros e revise a documentação do fluxo | LGPD no agente jurídico: minimização, base legal e registro |
| Não há registro da base legal aplicada | Registro estruturado incompleto ou ausência de campo obrigatório | Inclua campo 'base_legal' em cada log de operação | LGPD no agente jurídico: minimização, base legal e registro |
| O agente aceita campos não permitidos | Validação de minimização ausente ou mal configurada | Revisar e reforçar guardrails de entrada | LGPD no agente tributário: minimização, base legal e registr |
| Consentimento não é registrado | Fluxo de registro de consentimento não implementado | Adicionar registro persistente após aceite | LGPD no agente tributário: minimização, base legal e registr |
| Dados pessoais permanecem em logs após exclusão | Rotina de anonimização incompleta | Expandir anonimização para logs, backups e caches | LGPD no agente tributário: minimização, base legal e registr |
| Dados pessoais aparecem em logs ou prompts | Falta de filtro ou anonimização antes do envio ou registro | Reforce as funções de anonimização e revise o pipeline | LGPD no fiscal: minimização e registro de dados pessoais |
| Não há registro de base legal nos logs | Log estruturado incompleto | Inclua campos de finalidade e base legal obrigatoriamente | LGPD no fiscal: minimização e registro de dados pessoais |
| Auditoria não consegue rastrear acessos | Hash ou identificador ausente | Implemente geração e registro de hash dos dados sensíveis | LGPD no fiscal: minimização e registro de dados pessoais |
| Usuário solicita exclusão de seus dados e não é possível localizar todos os registros | Falta de rastreabilidade ou logs incompletos | Implemente identificadores únicos por sessão e revise o fluxo de logging | LGPD, dados sensíveis e minimização: como proteger o usuário |
| Dados anonimizados ainda permitem reidentificação cruzando com outros bancos | Anonimização insuficiente ou uso de dados correlacionáveis | Aplique técnicas de desidentificação adicionais e minimize ainda mais os dados | LGPD, dados sensíveis e minimização: como proteger o usuário |
| Consentimento não está registrado de forma auditável | Registro manual ou logs dispersos | Centralize e automatize o registro de consentimento com logs estruturados | LGPD, dados sensíveis e minimização: como proteger o usuário |
| Dados pessoais aparecem no prompt do modelo | Anonimização insuficiente ou bypassada | Reforce e teste os filtros de anonimização; revise regex e casos de teste | LGPD, minimização e controle de acesso: segurança no agente |
| Agente acessa documentos fora do escopo | Permissões de ferramenta mal configuradas | Revise a lista de ferramentas e o controle de acesso no SDK | LGPD, minimização e controle de acesso: segurança no agente |
| Logs não registram ações sensíveis | Falta de chamada de logging ou configuração errada | Inclua chamadas explícitas de registro em cada ação relevante | LGPD, minimização e controle de acesso: segurança no agente |
| Dados pessoais aparecem nos logs | Tracing configurado para registrar prompts completos ou ausência de anonimização | Ajuste a configuração do tracer e implemente anonimização antes do registro | LGPD, minimização e rastreabilidade: protegendo dados sensív |
| Agente processa campos não permitidos | Validação de entrada insuficiente ou tipos de dados permissivos | Restringir os campos aceitos e usar validação estrita | LGPD, minimização e rastreabilidade: protegendo dados sensív |
| Exclusão não remove dados de backups | Processo de exclusão física incompleto | Inclua rotinas para apagar dados também em backups operacionais | LGPD, minimização e rastreabilidade: protegendo dados sensív |
| Dados pessoais aparecem nos logs | Anonimização insuficiente ou script mal configurado | Revise e amplie os padrões de anonimização; teste com mais exemplos | LGPD, minimização e uso responsável de dados |
| IA responde com dados sensíveis | Prompt incluiu informações desnecessárias | Refatore o prompt para remover dados pessoais antes do envio | LGPD, minimização e uso responsável de dados |
| Auditoria não encontra registros de requisições | Logs desativados ou mal configurados | Ative logs com identificadores internos e revise a configuração | LGPD, minimização e uso responsável de dados |
| Base legal não documentada | Falta de registro dos fluxos e finalidades | Implemente planilha ou sistema de registro para cada fluxo de dados | LGPD, minimização e uso responsável de dados |
| O agente retorna erro de ferramenta não encontrada | Ferramenta MCP não registrada ou nome divergente | Verifique se o nome da ferramenta está igual ao registrado no SDK e no contrato MCP | Ligando o agente aos sistemas do administrativo com MCP e fe |
| Resposta do sistema não bate com o esperado | Contrato MCP divergente ou handler com bug | Revise o contrato e teste o handler isoladamente | Ligando o agente aos sistemas do administrativo com MCP e fe |
| Falha de autenticação na chamada MCP | Chave de API ausente ou inválida na variável de ambiente | Confirme a variável de ambiente e o valor da chave | Ligando o agente aos sistemas do administrativo com MCP e fe |
| O agente retorna erro de schema inválido | A resposta da ferramenta não bate com o contrato JSON definido | Ajuste o endpoint para seguir exatamente o schema de saída | Ligando o agente aos sistemas do apoio à decisão executiva c |
| O agente não encontra a ferramenta | Endpoint URL incorreto ou serviço fora do ar | Verifique o endereço e se o serviço está rodando | Ligando o agente aos sistemas do apoio à decisão executiva c |
| Chamada registrada mas sem resposta | Timeout ou erro interno na ferramenta externa | Revise logs da ferramenta e aumente timeout se necessário | Ligando o agente aos sistemas do apoio à decisão executiva c |
| O agente retorna erro de autenticação ao acessar a API de leads. | Token de API ausente ou inválido na variável de ambiente. | Verifique e atualize a variável LEADS_API_TOKEN. | Ligando o agente aos sistemas do comercial e vendas com MCP |
| O agente recebe dados em formato inesperado. | Contrato de saída da ferramenta MCP não está alinhado com a resposta real da API. | Ajuste o output_schema e a função para garantir compatibilidade. | Ligando o agente aos sistemas do comercial e vendas com MCP |
| A chamada trava ou não retorna. | Erro não tratado na função de integração ou timeout na API externa. | Implemente tratamento de exceções e defina timeouts adequados. | Ligando o agente aos sistemas do comercial e vendas com MCP |
| O agente retorna erro de parâmetro ausente | Campo obrigatório não informado ou nome incorreto | Revise os nomes e obrigatoriedade dos parâmetros no contrato MCP | Ligando o agente aos sistemas do contabilidade com MCP e fer |
| A resposta não contém id_lancamento | A função não retornou o campo esperado ou houve erro interno | Verifique a implementação da função e o contrato de retorno | Ligando o agente aos sistemas do contabilidade com MCP e fer |
| Logs não mostram as chamadas do agente | Tracing não habilitado ou configuração incorreta do SDK | Ative o tracing no SDK e revise permissões de escrita | Ligando o agente aos sistemas do contabilidade com MCP e fer |
| O agente retorna erro de autenticação ao chamar a API. | Variável de ambiente API_TOKEN não configurada ou inválida. | Defina a variável API_TOKEN com um token válido antes de rodar o agente. | Ligando o agente aos sistemas do desenvolvimento de negócios |
| A resposta da ferramenta é diferente do esperado. | Contrato MCP desatualizado ou divergente da API real. | Atualize o contrato MCP para refletir o formato real da resposta da API. | Ligando o agente aos sistemas do desenvolvimento de negócios |
| O agente trava ou não responde após erro na API externa. | Fallback não implementado ou exceção não tratada. | Implemente tratamento de exceções e fallback para intervenção humana. | Ligando o agente aos sistemas do desenvolvimento de negócios |
| O agente não aciona a ferramenta MCP | URL incorreta ou endpoint fora do ar | Verifique o endereço e se o serviço HTTP está rodando | Ligando o agente aos sistemas do estratégia com MCP e ferram |
| Resposta inesperada do sistema externo | Contrato de resposta MCP não seguido | Ajuste o endpoint para retornar o formato MCP correto | Ligando o agente aos sistemas do estratégia com MCP e ferram |
| Dados sensíveis vazando no tracing | Falta de sanitização ou minimização de dados | Implemente filtros para remover dados pessoais antes do registro | Ligando o agente aos sistemas do estratégia com MCP e ferram |
| O agente retorna erro de parâmetro ao chamar a função MCP. | Contrato MCP com parâmetros divergentes entre definição e implementação. | Revise o nome e tipo dos parâmetros no contrato e na função Python. | Ligando o agente aos sistemas do fiscal com MCP e ferramenta |
| A função retorna dados incompletos ou vazios. | Retorno não segue o formato do contrato MCP. | Garanta que todos os campos obrigatórios estão presentes e tipados corretamente. | Ligando o agente aos sistemas do fiscal com MCP e ferramenta |
| A chamada não aparece no tracing do agente. | Tracing não ativado ou tool não registrada corretamente. | Verifique a configuração do SDK e o registro da tool MCP. | Ligando o agente aos sistemas do fiscal com MCP e ferramenta |
| O agente não encontra a ferramenta MCP | Contrato não registrado ou nome inconsistente | Verifique se o nome da ferramenta está igual no contrato e no registro do SDK | Ligando o agente aos sistemas do gestão de equipes e operaçõ |
| Resposta fora do formato esperado | Erro na implementação da função ou mudança no sistema externo | Ajuste a função para garantir o formato definido no contrato | Ligando o agente aos sistemas do gestão de equipes e operaçõ |
| Fallback manual não aciona | Handler de exceção ausente ou mal configurado | Implemente tratamento de exceções e notificação ao responsável | Ligando o agente aos sistemas do gestão de equipes e operaçõ |
| Testes automatizados falham após alteração | Mudança no contrato sem atualizar testes | Atualize os testes para refletir o novo contrato | Ligando o agente aos sistemas do gestão de equipes e operaçõ |
| O agente não encontra a ferramenta MCP | Ferramenta não registrada corretamente no agente | Verifique se a ferramenta está na lista tools do agente. | Ligando o agente aos sistemas do jurídico com MCP e ferramen |
| Chave de API não reconhecida | Variável de ambiente não configurada ou valor incorreto | Configure ANTHROPIC_API_KEY corretamente. | Ligando o agente aos sistemas do jurídico com MCP e ferramen |
| Acesso negado a dados sensíveis | Permissões da ferramenta MCP restritas | Revise o contrato da ferramenta e ajuste o input_schema/output_schema. | Ligando o agente aos sistemas do jurídico com MCP e ferramen |
| O agente não encontra a ferramenta MCP | Contrato não registrado ou nome divergente | Verifique se o arquivo está no diretório correto e o nome bate com o chamado pelo agente | Ligando o agente aos sistemas do marketing com MCP e ferrame |
| Erro de permissão ao executar integração | Permissões não declaradas no contrato MCP | Inclua o escopo correto em 'permissions' e revalide | Ligando o agente aos sistemas do marketing com MCP e ferrame |
| Retorno inesperado da API externa | Estrutura de resposta diferente do contrato MCP | Ajuste a função de integração para normalizar o retorno conforme o contrato | Ligando o agente aos sistemas do marketing com MCP e ferrame |
| Agente retorna erro 401 ao chamar ferramenta MCP | Token de autenticação ausente ou inválido no header Authorization | Verifique se o agente está enviando o header correto e se o app MCP valida conforme o padrão | Ligando o agente aos sistemas do NOC (centro de operações de |
| Chamada retorna status inesperado ou erro 500 | Parâmetros enviados não batem com o contrato MCP ou erro interno na função | Confirme se input_schema e output_schema estão alinhados entre agente e app MCP | Ligando o agente aos sistemas do NOC (centro de operações de |
| Logs não registram agente ou parâmetros | App MCP não implementou rastreamento completo | Adicione logging detalhado em cada endpoint, incluindo agente, parâmetros e resultado | Ligando o agente aos sistemas do NOC (centro de operações de |
| O agente retorna erro de ferramenta não encontrada | A ferramenta não foi registrada corretamente no agente | Verifique se o nome e o contrato da ferramenta estão idênticos no agente e no servidor MCP. | Ligando o agente aos sistemas do planejamento com MCP e ferr |
| Resposta do MCP vem vazia ou com erro de validação | Formato do retorno não segue o contrato definido | Ajuste o endpoint para sempre retornar os campos obrigatórios. | Ligando o agente aos sistemas do planejamento com MCP e ferr |
| Falha de autenticação ao chamar o MCP | Chave de API ausente ou inválida | Confirme se a variável de ambiente está definida e usada corretamente no agente e no servidor. | Ligando o agente aos sistemas do planejamento com MCP e ferr |
| O agente retorna erro de tipo ao chamar a ferramenta | Contrato de parâmetros ou retorno divergente do especificado | Revise tipos e nomes dos parâmetros e do retorno na função Python | Ligando o agente aos sistemas do RH (DP, folha e benefícios) |
| Timeout ao acessar o sistema externo | Sistema de RH fora do ar ou endpoint incorreto | Verifique URL, conectividade e disponibilidade do sistema alvo | Ligando o agente aos sistemas do RH (DP, folha e benefícios) |
| Retorno inesperado ou vazio | Erro de serialização ou resposta fora do padrão | Ajuste o tratamento de resposta na função e reforce os testes automatizados | Ligando o agente aos sistemas do RH (DP, folha e benefícios) |
| O agente não encontra as ferramentas do RH | Endpoint MCP não está acessível ou contrato mal formado | Verifique a URL do MCP e o formato JSON das ferramentas | Ligando o agente aos sistemas do RH (R&S, T&D e PDC) com MCP |
| Erro de autenticação ao chamar ferramenta | Chave de API ausente ou inválida | Confirme as variáveis de ambiente e permissões do agente | Ligando o agente aos sistemas do RH (R&S, T&D e PDC) com MCP |
| Retorno inesperado em teste | Contrato da ferramenta mudou sem atualizar o agente | Sincronize o contrato e reimplemente os testes | Ligando o agente aos sistemas do RH (R&S, T&D e PDC) com MCP |
| Logs de auditoria não aparecem | Tracing não habilitado no SDK | Ative o tracing conforme a documentação do SDK | Ligando o agente aos sistemas do RH (R&S, T&D e PDC) com MCP |
| A função retorna erro inesperado | Parâmetros fora do contrato ou resposta da API diferente do esperado | Revisar o contrato e validar entradas/saídas | Ligando o agente aos sistemas do tributário com MCP e ferram |
| O agente ignora erros da ferramenta | Faltam guardrails ou tratamento de exceções | Implemente validação e fallback explícito | Ligando o agente aos sistemas do tributário com MCP e ferram |
| Logs não aparecem | Configuração de logging ausente ou nível incorreto | Ajuste o logging para registrar todas as execuções | Ligando o agente aos sistemas do tributário com MCP e ferram |
| A IA aprova notas com erros graves | Falta de casos de teste ou guardrails para exceções | Inclua casos de teste específicos e implemente validações de entrada/saída | Limites da automação: o que a IA ainda não faz (e talvez nun |
| Decisões do agente não aparecem no log | Tracing não ativado ou mal configurado | Ative o tracing no SDK e verifique permissões de escrita | Limites da automação: o que a IA ainda não faz (e talvez nun |
| O agente tenta enviar obrigações automaticamente | Fluxo de aprovação humana não implementado | Inclua etapa obrigatória de revisão e aprovação manual | Limites da automação: o que a IA ainda não faz (e talvez nun |
| Respostas truncadas ou incompletas | Entrada ou histórico ultrapassou o limite de tokens do modelo | Implemente corte, sumarização e chunking antes de enviar ao modelo | Limites de contexto, tokens e arquivos: como não travar o ag |
| Erro de API indicando tamanho excedido | Arquivo ou texto enviado maior que o permitido pela API | Divida o arquivo em partes menores ou reduza o texto | Limites de contexto, tokens e arquivos: como não travar o ag |
| Agente trava sem mensagem de erro | Exceção não tratada ao estourar limite de tokens | Adicione tratamento de exceção e fallback automático | Limites de contexto, tokens e arquivos: como não travar o ag |
| Erro HTTP 413 (Payload Too Large) | Lote excedeu o limite de tamanho do endpoint. | Reduza o número de documentos por lote. | Limites dos modelos e estratégias para contornar gargalos |
| Requisições demorando ou falhando intermitentemente | Paralelismo acima do suportado pela API ou rede. | Diminua o número de threads/processos simultâneos. | Limites dos modelos e estratégias para contornar gargalos |
| Resultados incompletos ou truncados | Saída ultrapassou o limite de tokens do modelo. | Reduza o tamanho do prompt ou aumente o parâmetro max_tokens se possível. | Limites dos modelos e estratégias para contornar gargalos |
| Processamento parou após erro de modelo | Fallback não implementado ou falhou | Revise a lógica de fallback e teste com erro simulado | Limites dos modelos e fallback distribuído: como não travar |
| Tempo de resposta aumentou repentinamente | Saturação de um agente ou modelo | Aumente o número de agentes e ajuste o balanceamento | Limites dos modelos e fallback distribuído: como não travar |
| Logs não mostram fallback mesmo com erro | Tracing desativado ou mal configurado | Ative tracing no SDK e valide registros de execução | Limites dos modelos e fallback distribuído: como não travar |
| Usuário não recebe bloqueio mesmo após exceder a cota | Limite mal configurado ou lógica de checagem ausente | Revise a implementação do rate limit e teste com múltiplas requisições | Limites e alertas: IA sob controle, não no escuro |
| Alertas não são enviados | Integração de notificação ausente ou falha no gatilho | Teste o envio de alertas manualmente e revise as condições de disparo | Limites e alertas: IA sob controle, não no escuro |
| Logs incompletos ou ilegíveis | Formato do log não estruturado ou campos ausentes | Padronize logs em JSON e inclua todos os campos relevantes | Limites e alertas: IA sob controle, não no escuro |
| Fila de requisições cresce sem parar | Capacidade de processamento insuficiente ou deadlock em algum agente | Reduza a carga, aumente workers ou revise o código do agente | Limites operacionais: como planejar crescimento sem travar o |
| Respostas muito lentas em horários de pico | Saturação de CPU, memória ou limite da API externa | Otimize prompts, distribua a carga ou aumente recursos | Limites operacionais: como planejar crescimento sem travar o |
| Erros 429 (rate limit) frequentes | Excesso de requisições simultâneas para o mesmo endpoint | Implemente controle de concorrência e retry com backoff | Limites operacionais: como planejar crescimento sem travar o |
| Resposta truncada ou incompleta | Limite de contexto do modelo foi excedido | Divida o documento e envie em partes menores | Limites práticos: contexto, tokens e concorrência em agentes |
| Erro de fila cheia | Muitas requisições simultâneas sem controle de concorrência | Aumente o tamanho da fila ou distribua a carga | Limites práticos: contexto, tokens e concorrência em agentes |
| Rejeição por tokens excedidos | Prompt ou entrada muito grande | Otimize o prompt e remova dados desnecessários | Limites práticos: contexto, tokens e concorrência em agentes |
| API retorna erro 400 ou 413 (Payload Too Large) | Prompt ou arquivo excede o limite de tokens/caracteres. | Implemente validação local antes de enviar e corte entradas grandes. | Limites práticos: o que quebra primeiro e como monitorar |
| Fila de tarefas cresce sem baixar | Processamento mais lento que a chegada de tarefas ou gargalo em modelo/API. | Aumente workers, otimize prompts ou implemente rejeição controlada. | Limites práticos: o que quebra primeiro e como monitorar |
| Erros 429 (Too Many Requests) frequentes | Limite de chamadas simultâneas ou por minuto excedido. | Implemente retry exponencial e reduza paralelismo. | Limites práticos: o que quebra primeiro e como monitorar |
| A resposta do agente ignora dados recentes | RAG não está buscando ou passando contexto atualizado | Verifique indexação e passagem de contexto no prompt | LLM, TTS, ASR, RAG e MCP: o glossário essencial para IA mult |
| O áudio sintetizado soa robótico | Modelo TTS inadequado ou voz mal configurada | Ajuste modelo_id, voice_settings ou escolha outra voz | LLM, TTS, ASR, RAG e MCP: o glossário essencial para IA mult |
| Transcrição com muitos erros | Áudio ruidoso ou idioma não suportado | Melhore a qualidade do áudio ou revise o modelo ASR | LLM, TTS, ASR, RAG e MCP: o glossário essencial para IA mult |
| Integração entre agentes falha | Incompatibilidade de implementação MCP | Confirme versões e contratos de integração nos dois lados | LLM, TTS, ASR, RAG e MCP: o glossário essencial para IA mult |
| O modelo não inicia ou encerra imediatamente | Falta de RAM ou incompatibilidade de hardware | Verifique requisitos do modelo e ajuste swap ou troque de máquina | LLMs locais: por que rodar modelos abertos em vez de APIs ex |
| Latência muito alta nas respostas | CPU/GPU insuficiente ou modelo muito grande | Use um modelo menor ou otimize o hardware | LLMs locais: por que rodar modelos abertos em vez de APIs ex |
| Erro de permissão ao instalar Ollama | Usuário sem privilégios de root | Execute o comando de instalação com sudo | LLMs locais: por que rodar modelos abertos em vez de APIs ex |
| Logs ausentes ou incompletos | Tracing não ativado ou formato errado | Verifique a configuração do SDK e paths de log | Logs e tracing: encontrando o erro antes que ele vire crise |
| Alertas não são disparados | Script de monitoramento não roda ou padrão de erro não detectado | Teste o script manualmente e ajuste o padrão de busca | Logs e tracing: encontrando o erro antes que ele vire crise |
| Logs expõem dados pessoais | Anonimização não implementada | Inclua função de anonimização antes de registrar logs | Logs e tracing: encontrando o erro antes que ele vire crise |
| Logs não aparecem no Kibana | Logstash não está lendo o arquivo ou há erro de permissão. | Verifique permissões do arquivo de log e status do serviço Logstash. | Logs estruturados: rastreando falhas e auditoria em produção |
| Identificadores de usuário aparecem em texto claro | Hashing ou anonimização não implementados corretamente. | Revise o código de logging e aplique hashing antes de registrar. | Logs estruturados: rastreando falhas e auditoria em produção |
| Logs em formato ilegível ou truncado | Formato do log não está em JSON válido. | Ajuste o formatter para garantir saída JSON bem formada. | Logs estruturados: rastreando falhas e auditoria em produção |
| Webhook do HeyGen nunca chega | URL inacessível publicamente ou configuração incorreta no painel HeyGen | Verifique se a URL está exposta (ex: ngrok) e se está cadastrada corretamente na HeyGen | Logs, callbacks e webhooks: onde buscar a raiz do problema |
| Logs incompletos ou sem IDs de correlação | Falta de padronização nos logs ou ausência de correlation ID | Implemente logging estruturado e gere correlation ID por fluxo | Logs, callbacks e webhooks: onde buscar a raiz do problema |
| Impossível saber se o erro foi no áudio ou no vídeo | Falta de rastreabilidade entre etapas | Registre todos os IDs externos e relacione-os ao correlation ID interno | Logs, callbacks e webhooks: onde buscar a raiz do problema |
| Notas com erro não aparecem na fila de pendências | Falha na chamada do fallback ou erro de lógica no append | Verifique se o fallback é chamado dentro do except e se a fila está corretamente inicializada | Logs, exceptions e fallback: garantindo operação mesmo em er |
| Logs não registram stack trace das exceções | Parâmetro exc_info ausente no logging.error | Inclua exc_info=True na chamada de logging | Logs, exceptions e fallback: garantindo operação mesmo em er |
| Notificações não chegam ao responsável | Erro de configuração no envio de email ou sistema de tickets | Confirme as credenciais e o endereço de destino; teste o envio manualmente | Logs, exceptions e fallback: garantindo operação mesmo em er |
| Logs não aparecem no arquivo ou sistema | Falha de permissão ou caminho incorreto | Verifique permissões de escrita e paths de log na configuração. | Logs, métricas e alertas: do erro ao insight acionável |
| Métricas não atualizam no dashboard | Instrumentação ausente ou coleta mal configurada | Confirme se os contadores/histogramas estão sendo incrementados e se o endpoint está exposto. | Logs, métricas e alertas: do erro ao insight acionável |
| Alertas não disparam mesmo com erro | Regra de alerta mal calibrada ou serviço de alerta inativo | Revise as expressões das regras e o status do serviço de alertas. | Logs, métricas e alertas: do erro ao insight acionável |
| Logs não aparecem ou estão truncados | Container não está emitindo logs estruturados ou log collector mal configurado | Verifique a configuração do container e do agente de logs. | Logs, métricas e tracing: o tripé da observabilidade em KSer |
| Métricas não aparecem no Prometheus | Scrape_config incorreto ou pods sem endpoint /metrics acessível | Confirme labels e portas dos pods, revise scrape_config. | Logs, métricas e tracing: o tripé da observabilidade em KSer |
| Traces incompletos ou ausentes | Istio não está injetando sidecar ou backend de tracing não configurado | Verifique se o sidecar está presente e revise a configuração do IstioOperator. | Logs, métricas e tracing: o tripé da observabilidade em KSer |
| Log vazio ou incompleto | Nível de log inadequado ou diretório de logs não configurado | Ajuste o nível para DEBUG e verifique permissões de escrita | Logs, tracing e análise de falhas: como identificar o ponto |
| Trace não registra todas as etapas | Tracing não habilitado ou não integrado ao runner do agente | Ative o tracing e passe o objeto de trace ao executar o agente | Logs, tracing e análise de falhas: como identificar o ponto |
| Erros de integração sem detalhes | Respostas de erro do sistema externo não registradas | Grave sempre o payload completo de resposta, mesmo em erro | Logs, tracing e análise de falhas: como identificar o ponto |
| O agente ignora permissões e acessa arquivos proibidos. | Permissões mal definidas no payload de criação. | Revise o campo 'permissions' e restrinja explicitamente os caminhos permitidos. | Managed Agents e Agents API: quando deixar a nuvem do fornec |
| Não aparecem eventos no stream. | session_id incorreto ou erro de autenticação. | Confirme o session_id e a chave de API usada nos headers. | Managed Agents e Agents API: quando deixar a nuvem do fornec |
| O agente não executa nenhuma ação. | Ferramentas não cadastradas ou não associadas ao agente. | Garanta que o campo 'tools' foi preenchido corretamente na criação. | Managed Agents e Agents API: quando deixar a nuvem do fornec |
| O stream trava ou não retorna linhas. | Problema de conexão ou consumo do streaming sem tratamento de linhas vazias. | Implemente timeout e verifique se a linha não está vazia antes de processar. | Managed Agents e Agents API: quando deixar a nuvem do fornec |
| Ferramenta não aparece para o agente | Registro incorreto do contrato da ferramenta ou erro de tipagem | Revise a assinatura da função e o registro como skill/tool | Managed Agents, hosted tools e MCP: o futuro da automação es |
| Tracing não registra todas as etapas | Tracing não ativado ou configuração padrão sobrescrita | Garanta que o tracing esteja habilitado no SDK e revise permissões | Managed Agents, hosted tools e MCP: o futuro da automação es |
| Revisão humana não é acionada | Faltam hooks ou handoffs definidos para ações críticas | Implemente hooks/handoffs nos pontos de decisão irreversível | Managed Agents, hosted tools e MCP: o futuro da automação es |
| O agente não invoca a ferramenta registrada. | Contrato (schema) incompatível ou ferramenta não registrada corretamente. | Revise o schema Pydantic e o registro da ferramenta/skill. | Managed Agents, hosted tools e MCP: o futuro já está disponí |
| A integração MCP retorna erro 401. | Token de autenticação ausente ou inválido. | Revise a autenticação e permissões conforme a especificação MCP. | Managed Agents, hosted tools e MCP: o futuro já está disponí |
| Tracing não aparece nos logs. | Tracing não ativado no SDK ou configuração ausente. | Ative tracing explicitamente e confira a documentação do SDK. | Managed Agents, hosted tools e MCP: o futuro já está disponí |
| Chain parou de responder após atualização | Incompatibilidade de dependência ou alteração não testada | Reverta para versão anterior via Git e revise os testes | Manutenção e atualização segura de fluxos de IA |
| Agent retorna respostas incoerentes | Mudança de lógica não coberta por testes regressivos | Amplie cobertura dos testes e corrija a lógica | Manutenção e atualização segura de fluxos de IA |
| Erro de importação após atualizar LangChain | Mudança de API na nova versão | Consulte a documentação oficial e ajuste o código | Manutenção e atualização segura de fluxos de IA |
| Testes automatizados falham após alteração de prompt | Prompt mudou e não cobre mais o cenário de teste | Atualize o prompt ou o caso de teste para refletir o novo comportamento esperado | Manutenção preventiva: testes, logs e feedback do usuário |
| Logs não registram chamadas de ferramentas | Configuração de logging incompleta ou nível de log inadequado | Ajuste o nível para INFO ou DEBUG e revise pontos de logging no código | Manutenção preventiva: testes, logs e feedback do usuário |
| Feedback de usuário não é coletado | Rotina de coleta não implementada ou falha de permissão | Implemente coleta estruturada e garanta conformidade com a LGPD | Manutenção preventiva: testes, logs e feedback do usuário |
| Tarefas automatizadas gerando erros graves | Ponto crítico não identificado ou automação excessiva | Revisar o mapeamento, recuar automação para tarefas de menor risco | Mapa do administrativo em tarefas de agente: o que automatiz |
| Agente pedindo revisão para tudo | Critérios de risco mal definidos, excesso de cautela | Reclassificar tarefas de baixo risco para automação total | Mapa do administrativo em tarefas de agente: o que automatiz |
| Processos lentos, gargalos em validação humana | Muitas tarefas assistidas sem necessidade | Reavaliar pontos de controle, liberar mais tarefas para o agente | Mapa do administrativo em tarefas de agente: o que automatiz |
| A IA toma decisão sem revisão humana | Falta de ponto de revisão no mapa ou erro na implementação do guardrail | Inclua revisão obrigatória e teste o fluxo com dados críticos | Mapa do apoio à decisão executiva em tarefas de agente: o qu |
| Tarefas humanas não aparecem no registro | Documentação incompleta do mapa de decisão | Revise o documento e garanta que todas as tarefas estejam listadas | Mapa do apoio à decisão executiva em tarefas de agente: o qu |
| A IA bloqueia tarefas rotineiras sem motivo | Critérios de automação excessivamente restritivos | Ajuste os limites e valide com mais casos de teste | Mapa do apoio à decisão executiva em tarefas de agente: o qu |
| O agente tenta enviar proposta sem aprovação | Falta de workflow de aprovação ou erro de configuração | Inclua etapa obrigatória de revisão humana antes do envio | Mapa do comercial e vendas em tarefas de agente: o que autom |
| Dados pessoais aparecem em logs | Logs não filtrados ou guardrails ausentes | Implemente guardrails e sanitize logs para ocultar dados sensíveis | Mapa do comercial e vendas em tarefas de agente: o que autom |
| O agente toma decisão financeira sem registro | Falta de tracing ou bypass de aprovação | Ative registro obrigatório e revisão humana para decisões críticas | Mapa do comercial e vendas em tarefas de agente: o que autom |
| Lançamentos críticos não aparecem para revisão | Critérios de separação mal definidos ou lógica condicional ausente | Revise a regra de checkpoints e teste com casos de exceção | Mapa do contabilidade em tarefas de agente: o que automatiza |
| IA sugere classificações erradas para despesas incomuns | Falta de exemplos de exceção nos dados de teste | Inclua casos atípicos nos testes e ajuste o prompt do agente | Mapa do contabilidade em tarefas de agente: o que automatiza |
| Dados pessoais aparecem em logs de agentes | Falta de anonimização ou filtragem antes do registro | Implemente filtros para remover ou mascarar dados sensíveis | Mapa do contabilidade em tarefas de agente: o que automatiza |
| A IA executa ação crítica sem pedir aprovação | Guardrail ou handoff ausente ou mal configurado | Revise a configuração dos guardrails e pontos de parada no SDK | Mapa do desenvolvimento de negócios em tarefas de agente: o |
| Dados sensíveis aparecem no prompt de sistema | Falta de minimização e uso inadequado de variáveis de ambiente | Remova dados pessoais do prompt e use variáveis de ambiente para segredos | Mapa do desenvolvimento de negócios em tarefas de agente: o |
| Logs de execução incompletos | Tracing não habilitado ou mal implementado | Ative e teste o tracing dos SDKs para registrar todo o fluxo | Mapa do desenvolvimento de negócios em tarefas de agente: o |
| Agente executa ação crítica sem aprovação | Guardrail mal configurado ou ausente | Revisar implementação dos guardrails e testar com dados de exemplo | Mapa do estratégia em tarefas de agente: o que automatizar, |
| Tarefas assistidas não geram alertas para revisão | Critérios de alerta mal definidos | Ajustar condições de alerta e testar com desvios simulados | Mapa do estratégia em tarefas de agente: o que automatizar, |
| Dados pessoais vazam no prompt | Falta de minimização ou anonimização | Rever coleta de dados e aplicar minimização conforme LGPD | Mapa do estratégia em tarefas de agente: o que automatizar, |
| O agente executa ação crítica sem pedir aprovação | Prompt de sistema ou fluxo de aprovação mal implementado | Revise o prompt e implemente verificação obrigatória de aprovação antes da ação | Mapa do fiscal em tarefas de agente: o que automatizar, o qu |
| Alertas de pendência não são enviados | Calendário de obrigações desatualizado ou configuração de alertas incorreta | Atualize o calendário e teste o envio de alertas manualmente | Mapa do fiscal em tarefas de agente: o que automatizar, o qu |
| Agente falha ao ler XML de nota fiscal | Arquivo fora do padrão ou schema desatualizado | Valide o XML com o schema oficial e ajuste o agente para lidar com exceções | Mapa do fiscal em tarefas de agente: o que automatizar, o qu |
| Tarefa automatizada executando ações sem aprovação | Falta de ponto de controle ou revisão humana no fluxo | Adicione etapa obrigatória de revisão antes da ação irreversível | Mapa do gestão de equipes e operações em tarefas de agente: |
| Agente acessando dados além do necessário | Escopo de permissão mal definido | Restrinja acesso apenas aos campos essenciais e registre consentimento | Mapa do gestão de equipes e operações em tarefas de agente: |
| Erro não detectado no processo automatizado | Ausência de casos de teste ou critérios de aprovação | Implemente testes automatizados e revise critérios de aprovação | Mapa do gestão de equipes e operações em tarefas de agente: |
| A IA altera cláusulas contratuais sem revisão | Falta de guardrail ou configuração de permissão inadequada | Implemente validação obrigatória para ações críticas | Mapa do jurídico em tarefas de agente: o que automatizar, o |
| Dados pessoais aparecem em logs | Logs não filtrados ou anonimização ausente | Configure logs para mascarar ou omitir dados sensíveis | Mapa do jurídico em tarefas de agente: o que automatizar, o |
| Agente não reconhece exceções em contratos | Casos de teste insuficientes ou prompt mal definido | Amplie casos de teste e refine o prompt de sistema | Mapa do jurídico em tarefas de agente: o que automatizar, o |
| Tarefa automatizada gera resultados errados | Critérios de aprovação mal definidos ou ausência de casos de teste | Revisar e detalhar casos de teste, ajustar critérios de sucesso | Mapa do marketing em tarefas de agente: o que automatizar, o |
| IA publica conteúdo sensível sem revisão | Falta de ponto de controle obrigatório | Adicionar revisão humana antes de ações irreversíveis | Mapa do marketing em tarefas de agente: o que automatizar, o |
| Dados pessoais expostos em relatórios | Ausência de minimização e registro de tratamento | Aplicar regras de minimização e registrar base legal (LGPD) | Mapa do marketing em tarefas de agente: o que automatizar, o |
| Agente executa ação irreversível sem aprovação | Falta de guardrail ou critério de aprovação humana | Adicione validação obrigatória para ações críticas | Mapa do NOC (centro de operações de rede) em tarefas de agen |
| Alertas importantes não são triados corretamente | Prompt de sistema mal definido ou casos de teste insuficientes | Revise o prompt e aumente a cobertura dos testes | Mapa do NOC (centro de operações de rede) em tarefas de agen |
| Dados pessoais aparecem em logs | Falta de sanitização ou uso incorreto de variáveis de ambiente | Implemente filtros e revise o tratamento de dados sensíveis | Mapa do NOC (centro de operações de rede) em tarefas de agen |
| Agente toma decisão sem aprovação humana | Prompt ou ferramenta mal configurada, sem bloqueio em pontos críticos. | Reforce o prompt e implemente checagens explícitas para travar ações irreversíveis. | Mapa do planejamento em tarefas de agente: o que automatizar |
| Tarefas simples não são automatizadas | Classificação conservadora ou falta de ferramentas no agente. | Revise o mapeamento e amplie o escopo das ferramentas. | Mapa do planejamento em tarefas de agente: o que automatizar |
| Faltam registros de ações do agente | Tracing não implementado ou logs desativados. | Ative o tracing nos SDKs e garanta persistência dos registros. | Mapa do planejamento em tarefas de agente: o que automatizar |
| O agente aprova automaticamente sem revisão | Prompt de sistema mal definido ou ausência de guardrail | Reforce no prompt e implemente validação obrigatória de aprovação humana | Mapa do RH (DP, folha e benefícios) em tarefas de agente: o |
| Checklist de documentos incompleto | Lista de obrigatórios desatualizada | Atualize a lista conforme a função/cargo e revise periodicamente | Mapa do RH (DP, folha e benefícios) em tarefas de agente: o |
| Dados pessoais expostos em logs | Falta de anonimização ou minimização | Implemente filtros para mascarar dados sensíveis nos registros | Mapa do RH (DP, folha e benefícios) em tarefas de agente: o |
| O agente elimina candidatos automaticamente sem revisão. | Falta de bloqueio ou alerta em zona de revisão obrigatória. | Implemente validação para exigir aprovação humana antes da exclusão. | Mapa do RH (R&S, T&D e PDC) em tarefas de agente: o que auto |
| Dados pessoais aparecem em logs ou prompts. | Falta de anonimização ou uso inadequado de variáveis. | Implemente minimização e anonimização de dados; use variáveis de ambiente para segredos. | Mapa do RH (R&S, T&D e PDC) em tarefas de agente: o que auto |
| A IA sugere perguntas inadequadas na entrevista. | Critérios subjetivos mal definidos ou ausência de guardrails. | Refine os critérios e implemente validações de saída. | Mapa do RH (R&S, T&D e PDC) em tarefas de agente: o que auto |
| Decisão automatizada sem registro de revisão | Falta de integração entre agente e sistema de versionamento | Implemente hooks para registrar cada ação e revisão em repositório controlado | Mapa do tributário em tarefas de agente: o que automatizar, |
| Agente tomando decisão legal sem aprovação humana | Critérios de supervisão mal definidos | Reforce guardrails e obrigue aprovação explícita antes de ações irreversíveis | Mapa do tributário em tarefas de agente: o que automatizar, |
| Resultados divergentes entre simulações e realidade | Premissas ou regras desatualizadas no prompt | Versione e revise periodicamente os prompts e parâmetros de cálculo | Mapa do tributário em tarefas de agente: o que automatizar, |
| Arquivo ProRes veio pequeno ou sem canal alfa | Exportação feita em perfil errado ou sem transparência | Peça explicitamente ProRes 4444 com canal alfa, e confira se a IA confirma o perfil. | Master de verdade em uma frase: ProRes, sequência PNG e HDR |
| Sequência PNG veio incompleta ou sem áudio | Exportação não incluiu todos os quadros ou esqueceu o áudio separado | Peça novamente, especificando sequência completa e áudio WAV. | Master de verdade em uma frase: ProRes, sequência PNG e HDR |
| Arquivo HDR10 não é reconhecido como HDR | Conversão com Ruby não foi aplicada ou formato de saída não foi HDR10 | Peça a conversão SDR para HDR10 com Ruby, e peça para descrever o formato final. | Master de verdade em uma frase: ProRes, sequência PNG e HDR |
| Agente não responde ao orquestrador | Contrato MCP incompatível ou endpoint incorreto | Verifique o contrato e a URL do agente. | MCP e o futuro do RH: agentes plugáveis, interoperáveis e au |
| Dados sensíveis aparecem em logs | Falta de anonimização ou configuração inadequada de tracing | Configure logs para mascarar dados pessoais. | MCP e o futuro do RH: agentes plugáveis, interoperáveis e au |
| Falha ao trocar agente por outro fornecedor | Contrato MCP não seguido à risca | Garanta que entradas e saídas estejam padronizadas conforme MCP. | MCP e o futuro do RH: agentes plugáveis, interoperáveis e au |
| Vídeo não é gerado ou fica em status 'failed' | Parâmetros inválidos ou áudio/script incompatíveis | Revise os campos obrigatórios ('avatar_id', 'voice_id', 'script') e garanta que o áudio está no formato suportado. | MCP, agentes autônomos e orquestração avançada: o que já dá |
| Áudio não é criado pelo ElevenLabs | voice_id ou model_id incorretos | Confirme que está usando um voice_id válido e um model_id suportado ('eleven_multilingual_v2', por exemplo). | MCP, agentes autônomos e orquestração avançada: o que já dá |
| Agente não executa ferramenta MCP | Contrato da ferramenta não está conforme o padrão MCP | Garanta que os parâmetros e o retorno seguem o contrato definido pelo MCP e estão documentados. | MCP, agentes autônomos e orquestração avançada: o que já dá |
| O agente toma decisão sem registro | Falta de tracing ou log inadequado | Implemente tracing e logging detalhado no laço do agente | MCP, agentes autônomos e RH: tendências e riscos para os pró |
| Dados sensíveis vazam no prompt | Segredos não isolados em variáveis de ambiente | Armazene segredos apenas em variáveis de ambiente, nunca no prompt | MCP, agentes autônomos e RH: tendências e riscos para os pró |
| Critérios de triagem mudam sem controle | Prompts não versionados | Implemente versionamento obrigatório dos prompts de sistema | MCP, agentes autônomos e RH: tendências e riscos para os pró |
| O agente executa comandos não autorizados | Guardrails ausentes ou permissões mal configuradas | Reveja contratos e permissões das ferramentas | MCP, memória e laço de ferramentas: o que todo agente modern |
| Memória não persiste entre sessões | Configuração incorreta de armazenamento ou caminho de arquivos | Confirme diretórios e permissões de escrita | MCP, memória e laço de ferramentas: o que todo agente modern |
| Logs não aparecem ou estão incompletos | Tracing desativado ou mal configurado | Ative tracing e revise configuração de logs | MCP, memória e laço de ferramentas: o que todo agente modern |
| O agente não encontra o plugin | URL incorreta ou serviço fora do ar | Verifique o endpoint e se o serviço MCP está rodando | MCP, plugins e o futuro da integração de agentes: para onde |
| Erro de autenticação ao chamar o plugin | Cabeçalhos ou tokens ausentes | Inclua autenticação conforme o contrato MCP | MCP, plugins e o futuro da integração de agentes: para onde |
| Resposta inesperada do plugin | Contrato MCP divergente | Ajuste o plugin para seguir exatamente o contrato definido | MCP, plugins e o futuro da integração de agentes: para onde |
| Erro 401 ao chamar API | Chave de API ausente ou inválida | Verifique variáveis de ambiente e permissões da chave | MCP, SDKs e APIs: como Claude, OpenAI, ElevenLabs e HeyGen s |
| Áudio ou vídeo não gerado | Parâmetros obrigatórios ausentes (ex: voice_id, avatar_id) | Confirme todos os campos exigidos na chamada | MCP, SDKs e APIs: como Claude, OpenAI, ElevenLabs e HeyGen s |
| Agente retorna resposta vazia | Tool MCP não registrada ou erro de contrato | Revise o registro da ferramenta e os contratos de entrada/saída | MCP, SDKs e APIs: como Claude, OpenAI, ElevenLabs e HeyGen s |
| O agente não encontra a ferramenta MCP | URL ou contrato da ferramenta incorreto | Revise o endpoint e o schema de entrada/saída | MCP, SDKs e APIs: conectando Claude, OpenAI, ElevenLabs e He |
| Erro de autenticação nas APIs | Chave de API ausente ou inválida | Verifique as variáveis de ambiente e permissões | MCP, SDKs e APIs: conectando Claude, OpenAI, ElevenLabs e He |
| Áudio ou vídeo não gerado | Limite de caracteres ou formato incompatível | Ajuste o texto enviado e valide o output_format | MCP, SDKs e APIs: conectando Claude, OpenAI, ElevenLabs e He |
| O agente não reconhece a ferramenta MCP | Schema mal definido ou endpoint inacessível | Revise o schema JSON e teste o endpoint com curl ou requests | MCP: conectando agentes, ferramentas e fluxos externos |
| Respostas do MCP App não são aceitas pelo agente | Saída fora do padrão MCP | Valide a resposta com o schema e ajuste o output | MCP: conectando agentes, ferramentas e fluxos externos |
| Tracing não registra execuções | Logs não estruturados ou endpoint de tracing não configurado | Implemente logs em formato JSON e configure o tracing conforme a documentação | MCP: conectando agentes, ferramentas e fluxos externos |
| Consultas não aparecem no histórico | Persistência não implementada ou erro na gravação | Reveja o código de inserção e permissões do banco | Memória de consultas e simulações: guardando histórico e apr |
| Revisão não altera status da consulta | Erro na query de atualização ou falta de commit | Corrija a query e garanta commit após update | Memória de consultas e simulações: guardando histórico e apr |
| Dados pessoais não são anonimizados após o prazo | Rotina de limpeza não agendada ou falha de permissão | Implemente agendamento e revise permissões do banco | Memória de consultas e simulações: guardando histórico e apr |
| O agente esquece o contexto entre perguntas. | Sessão não foi mantida ou histórico foi limpo cedo demais. | Garanta que a mesma instância de sessão está sendo usada e ajuste a janela de histórico. | Memória, sessões e contexto: como o agente lembra e esquece |
| Respostas incoerentes ou repetitivas. | Histórico insuficiente ou excesso de limpeza. | Aumente o número de mensagens mantidas no histórico. | Memória, sessões e contexto: como o agente lembra e esquece |
| Vazamento de dados pessoais em logs. | Histórico salvo sem anonimização. | Implemente rotina de limpeza antes de salvar ou compartilhar históricos. | Memória, sessões e contexto: como o agente lembra e esquece |
| Arquivo de sessão não é criado | Permissão de escrita insuficiente ou diretório inexistente | Verifique permissões e crie os diretórios necessários | Memória, sessões e histórico: como persistir interações e ra |
| Histórico está incompleto | Nem todas as ações estão sendo registradas no código | Inclua registros explícitos após cada etapa relevante | Memória, sessões e histórico: como persistir interações e ra |
| Erro ao ler arquivo de sessão | Arquivo corrompido ou formato incompatível | Valide o JSON antes de salvar e implemente tratamento de exceções | Memória, sessões e histórico: como persistir interações e ra |
| O agente perde contexto entre etapas da mesma operação. | Sessão não foi mantida ou histórico não foi passado corretamente. | Garanta que a mesma instância de sessão é usada em todo o ciclo. | Memória, sessões e revisão: como garantir consistência e ras |
| Decisões sensíveis são tomadas sem revisão. | Falta de implementação do handoff ou bypass do ponto de revisão. | Revise o fluxo e insira o handoff obrigatório antes da ação. | Memória, sessões e revisão: como garantir consistência e ras |
| Logs de auditoria não aparecem ou estão incompletos. | Tracing não habilitado ou destino de log mal configurado. | Ative o tracing e direcione os logs para local seguro e acessível. | Memória, sessões e revisão: como garantir consistência e ras |
| Histórico da sessão está vazio após interação | Sessão não vinculada corretamente ao agente | Garanta que o objeto Session seja passado ao criar ou executar o agente | Memória, sessões e tracing: como o agente aprende e registra |
| Arquivo de tracing não é gerado | Tracing não ativado ou caminho inválido | Ative o tracing e confira permissões de escrita no diretório | Memória, sessões e tracing: como o agente aprende e registra |
| Ação crítica executada sem revisão humana | Handoff não implementado ou handler falhou | Implemente corretamente o handoff e teste o fluxo de aprovação | Memória, sessões e tracing: como o agente aprende e registra |
| Histórico não está sendo salvo | Diretório de memória não configurado ou permissões insuficientes | Verifique o caminho e permissões do diretório .claude/memoria_contabil | Memória, sessões e tracing: histórico e rastreabilidade no a |
| Tracing não registra execuções | Tracing não ativado ou diretório incorreto | Confirme se o objeto Tracing foi passado ao agente e o caminho existe | Memória, sessões e tracing: histórico e rastreabilidade no a |
| Sessões misturando contextos | Sessão não isolada por interação | Garanta que cada ciclo de uso crie uma nova sessão com identificador único | Memória, sessões e tracing: histórico e rastreabilidade no a |
| Logs com dados pessoais em excesso | Falta de anonimização ou minimização | Implemente filtros para remover ou anonimizar dados pessoais antes do registro | Memória, sessões e tracing: histórico e rastreabilidade no a |
| Decisões repetidas pelo agente | Memória não persistida corretamente | Verifique o caminho e permissões do arquivo de memória | Memória, tracing e revisão: garantindo histórico e correção |
| Faltam registros no tracing | Tracing não habilitado ou configuração incorreta | Confirme se o parâmetro tracing=True está ativo | Memória, tracing e revisão: garantindo histórico e correção |
| Ações irreversíveis executadas sem revisão | Handoff não implementado ou handler falhou | Teste o fluxo de handoff e revise o código de aprovação | Memória, tracing e revisão: garantindo histórico e correção |
| Métricas não aparecem no dashboard | Coleta ou envio de dados falhou | Verifique se o código de coleta está ativo e se o dashboard está recebendo os dados. | Métricas de agentes comerciais: o que monitorar para não ser |
| Alertas não disparam mesmo com erro alto | Condição de alerta mal configurada | Revise a lógica dos thresholds e teste com dados simulados. | Métricas de agentes comerciais: o que monitorar para não ser |
| Logs não mostram detalhes das execuções | Tracing não ativado ou nível de log insuficiente | Ative tracing nos SDKs e ajuste o nível de detalhamento dos logs. | Métricas de agentes comerciais: o que monitorar para não ser |
| Latência muito alta em todas as tarefas | Gargalo na chamada ao LLM ou ferramenta externa | Isolar etapas no tracing e otimizar a mais lenta | Métricas de operação: latência, acurácia e volume em agentes |
| Acurácia baixa em casos de teste | Prompt de sistema mal definido ou ferramenta com erro | Revisar prompt, regras de negócio e contratos das ferramentas | Métricas de operação: latência, acurácia e volume em agentes |
| Volume de operações anormalmente alto | Automação descontrolada ou uso indevido | Investigar logs por usuário e limitar requisições | Métricas de operação: latência, acurácia e volume em agentes |
| Métricas não aparecem no dashboard | Falha na coleta ou envio de dados | Verifique se os wrappers estão realmente sendo chamados e se o backend de métricas está acessível. | Métricas de uso, qualidade e engajamento em voz e vídeo |
| Taxa de sucesso muito baixa | Erros de autenticação ou limites de API | Revise as credenciais e monitore limites de uso nas plataformas. | Métricas de uso, qualidade e engajamento em voz e vídeo |
| Feedback negativo recorrente | Problemas de UX ou conteúdo, não capturados por métricas técnicas | Analise comentários e revise prompts e fluxos de interação. | Métricas de uso, qualidade e engajamento em voz e vídeo |
| Métricas não aparecem no dashboard | Endpoint de métricas não está acessível ou coleta não foi configurada. | Verifique se o start_http_server está rodando e se o Prometheus está configurado para coletar do endpoint correto. | Métricas e alertas: avaliando qualidade e performance no cic |
| Alertas não disparam mesmo com falhas | Thresholds mal configurados ou nomes de métricas inconsistentes. | Confirme os nomes das métricas e ajuste os thresholds nas regras de alerta. | Métricas e alertas: avaliando qualidade e performance no cic |
| Tempo de resposta irrealisticamente baixo | Medição feita antes da execução completa do agente. | Garanta que o timer englobe toda a execução, incluindo chamadas externas. | Métricas e alertas: avaliando qualidade e performance no cic |
| Alertas não estão sendo enviados | Configuração de SMTP ou webhook incorreta | Revise as credenciais e o endereço do servidor de envio | Métricas e alertas: monitorando agentes em produção no contá |
| Logs não aparecem no arquivo | Permissão de escrita no diretório ou erro no path do arquivo | Ajuste permissões e caminhos no logging.basicConfig | Métricas e alertas: monitorando agentes em produção no contá |
| Latência média muito alta | Gargalo na API do LLM ou dados de entrada muito grandes | Otimize os prompts e revise o tamanho dos dados processados | Métricas e alertas: monitorando agentes em produção no contá |
| Métricas não aparecem no dashboard | Erro de integração ou consulta SQL incorreta | Revise a conexão entre banco de métricas e dashboard; teste queries manualmente | Métricas essenciais do agente jurídico: uso, falhas e aprova |
| Falhas não registradas | Exceções não capturadas no código | Garanta que todos os pontos críticos estejam protegidos por try/except com log | Métricas essenciais do agente jurídico: uso, falhas e aprova |
| Alertas não disparam | Condições de alerta mal configuradas ou serviço de notificação inativo | Teste alertas manualmente com métricas simuladas | Métricas essenciais do agente jurídico: uso, falhas e aprova |
| Acurácia muito baixa nos testes | Prompt de sistema mal definido ou casos de teste fora do escopo do agente | Revisar prompt e alinhar casos de teste ao objetivo do agente | Métricas que importam: acurácia, latência e cobertura do age |
| Latência alta de forma intermitente | Gargalo em API externa ou processamento local | Identificar e otimizar chamadas lentas, escalonar recursos se necessário | Métricas que importam: acurácia, latência e cobertura do age |
| Cobertura menor que o esperado | Fontes não integradas ou falhas de coleta | Verificar integrações e implementar checagens de saúde para cada fonte | Métricas que importam: acurácia, latência e cobertura do age |
| Acurácia baixa mesmo com testes simples | Casos de teste mal definidos ou agente sem contexto suficiente | Revisar os prompts de sistema e os dados de teste | Métricas que importam: acurácia, latência, cobertura e revis |
| Latência alta em horários de pico | Sobrecarga do modelo ou infraestrutura de rede | Distribuir carga, otimizar prompts e revisar uso de ferramentas externas | Métricas que importam: acurácia, latência, cobertura e revis |
| Cobertura menor que o esperado | Cenários relevantes não foram mapeados | Revisar processos reais e ampliar a matriz de testes | Métricas que importam: acurácia, latência, cobertura e revis |
| Taxa de revisão humana abaixo do exigido | Falta de integração entre agente e workflow de aprovação | Automatizar handoffs e garantir registro obrigatório de revisão | Métricas que importam: acurácia, latência, cobertura e revis |
| Tempo de resposta alto | Gargalo em ferramenta externa ou modelo lento | Verifique logs de execução e isole o componente lento | Métricas que importam: o que medir em agentes do NOC |
| Taxa de sucesso baixa | Prompt mal definido ou casos de teste insuficientes | Revise o prompt e amplie os testes automatizados | Métricas que importam: o que medir em agentes do NOC |
| Alertas de anomalia não disparam | Lógica de detecção mal calibrada | Ajuste os limiares e teste com dados simulados | Métricas que importam: o que medir em agentes do NOC |
| A taxa de aprovação automática caiu repentinamente. | Mudança no prompt de sistema ou dados de entrada fora do padrão. | Revise o prompt e valide os dados de entrada. | Métricas que importam: o que medir para evoluir o agente |
| O tempo de resposta aumentou muito. | APIs externas lentas ou fila de processamento sobrecarregada. | Monitore tempos por etapa e otimize chamadas externas. | Métricas que importam: o que medir para evoluir o agente |
| O custo por tarefa está acima do esperado. | Consumo excessivo de tokens ou chamadas desnecessárias de APIs pagas. | Otimize prompts e revise uso de ferramentas externas. | Métricas que importam: o que medir para evoluir o agente |
| Dashboard não mostra dados atualizados | Falha na exportação ou coleta de métricas | Verifique se os hooks estão sendo executados e se o envio ao dashboard está correto | Métricas que importam: uso, erro, tempo de resposta e satisf |
| Alertas não são disparados mesmo com erro alto | Condição de alerta mal configurada ou script não rodando | Revise a lógica dos alertas e teste com dados simulados | Métricas que importam: uso, erro, tempo de resposta e satisf |
| Tempo de resposta não aparece nos logs | Falta de registro do timestamp inicial ou final | Garanta que o tempo está sendo capturado corretamente em cada chamada | Métricas que importam: uso, erro, tempo de resposta e satisf |
| Dados pessoais aparecem em logs | Função de filtragem ou anonimização não aplicada corretamente | Revise o pipeline de dados e garanta que a filtragem ocorre antes do logging | Minimização de dados e LGPD: o que pode e não pode ir para a |
| Agente retorna informações sensíveis | Prompt de sistema ou entrada contém dados pessoais | Ajuste o prompt e a filtragem de entrada para remover campos indevidos | Minimização de dados e LGPD: o que pode e não pode ir para a |
| Erro ao anonimizar dados | Campo esperado ausente ou formato inesperado | Adicione validação de presença dos campos antes de anonimizar | Minimização de dados e LGPD: o que pode e não pode ir para a |
| Modelo responde a comandos inesperados do usuário | Sanitização de input insuficiente ou prompt mal estruturado | Reforce filtros e revise o uso de PromptTemplate | Mitigando riscos em fluxos de IA: input sanitization e loggi |
| Dados sensíveis aparecem nos logs | Falta de mascaramento ou logging excessivo | Implemente funções de máscara e revise o nível de log | Mitigando riscos em fluxos de IA: input sanitization e loggi |
| Não é possível rastrear sessões no log | Ausência de IDs únicos por execução | Adicione geração e registro de session_id | Mitigando riscos em fluxos de IA: input sanitization e loggi |
| O agente não encontra a ferramenta MCP | Manifest.json inacessível ou URL errada | Verifique o endereço e permissões do manifest.json | Model Context Protocol 2026-07-28: interoperabilidade entre |
| Erro de schema ao invocar função | Input ou output não seguem o contrato do Manifest | Revise tipos e nomes de parâmetros no Manifest e na implementação | Model Context Protocol 2026-07-28: interoperabilidade entre |
| Resposta vazia ou incompleta | Função não retorna todos os campos definidos | Garanta que o output sempre preencha todos os campos do contrato | Model Context Protocol 2026-07-28: interoperabilidade entre |
| Erro de parsing JSON na integração | Schema MCP incompatível ou campo obrigatório ausente | Valide o JSON de entrada/saída com o schema oficial do MCP | Model Context Protocol e interoperabilidade: conectando IA, |
| Logs incompletos ou falha de auditoria | Faltam campos de contexto ou versionamento | Inclua session_id, user_id e versão do contrato em todas as mensagens | Model Context Protocol e interoperabilidade: conectando IA, |
| Handoff humano não retorna ao agente | Falta de endpoint ou timeout mal configurado | Implemente timeout e fallback para o agente retomar o fluxo | Model Context Protocol e interoperabilidade: conectando IA, |
| O agente retorna relatório incompleto | Prompt de sistema insuficiente ou ferramenta não registrada | Revise o prompt e garanta que todas as funções estejam expostas ao agente | Modelagem de negócio automatizada: do mapeamento ao relatóri |
| Erro de validação Pydantic | Tipos ou campos ausentes na saída do agente | Ajuste o contrato da ferramenta e reforce os exemplos no prompt | Modelagem de negócio automatizada: do mapeamento ao relatóri |
| Dados sensíveis aparecem no relatório | Prompt não restringe ou ferramenta expõe dados além do necessário | Inclua restrição explícita no prompt e revise o código das ferramentas | Modelagem de negócio automatizada: do mapeamento ao relatóri |
| Erro de falta de memória ao carregar modelo | Modelo escolhido exige mais VRAM do que disponível | Use modelo menor ou ative quantização se disponível | Modelos abertos de última geração: integração com Haystack |
| Latência muito alta nas respostas | Modelo grande rodando em CPU ou batch size inadequado | Habilite GPU e ajuste batch size conforme documentação | Modelos abertos de última geração: integração com Haystack |
| Modelo não encontrado ou erro de endpoint | Caminho do modelo incorreto ou servidor não iniciado | Verifique o caminho ou endpoint e reinicie o servidor de modelo | Modelos abertos de última geração: integração com Haystack |
| Erro 'model not found' ao rodar modelo | Nome do modelo incorreto ou modelo não baixado | Use 'ollama list' para ver modelos disponíveis e confirme o nome | Modelos abertos de última geração: o que já fazem e o que fa |
| Respostas incoerentes ou vazias | Prompt mal formulado ou modelo inadequado para a tarefa | Refine o prompt ou teste outro modelo | Modelos abertos de última geração: o que já fazem e o que fa |
| Uso excessivo de memória | Modelo grande para o hardware disponível | Escolha um modelo menor ou otimize a configuração do Ollama | Modelos abertos de última geração: o que já fazem e o que fa |
| Respostas genéricas ou vagas | Prompt ambíguo ou contexto insuficiente | Refine o prompt e forneça mais detalhes | Modelos de linguagem: como Claude, GPT e outros realmente fu |
| Erros factuais ou cálculos errados | Limite do modelo; LLM não executa lógica profunda | Valide com funções externas ou revise manualmente | Modelos de linguagem: como Claude, GPT e outros realmente fu |
| Saída truncada ou incompleta | Limite de tokens de saída atingido | Reduza o tamanho do prompt ou aumente o limite, se suportado | Modelos de linguagem: como Claude, GPT e outros realmente fu |
| Erro 400 ou mensagem de tokens excedidos | Prompt ou contexto maior que o limite do modelo | Reduza o tamanho do prompt ou troque para modelo com contexto maior | Modelos generativos e APIs: por que Claude e GPT mudam o jog |
| Resposta vazia ou incoerente | Prompt mal formulado ou fora do escopo do modelo | Reescreva o prompt e teste com exemplos menores | Modelos generativos e APIs: por que Claude e GPT mudam o jog |
| Erro de autenticação | Chave de API inválida ou ausente | Verifique a variável de ambiente e o cabeçalho Authorization | Modelos generativos e APIs: por que Claude e GPT mudam o jog |
| Pod do InferenceService fica em Pending | Não há GPU disponível ou device-plugin não está ativo | Verifique se há nós com GPU e se o device-plugin está rodando | Modelos serverless, GPU e inferência distribuída no KServe |
| Serviço não escala para zero | Knative não instalado ou annotation ausente | Confirme instalação do Knative e revise as annotations | Modelos serverless, GPU e inferência distribuída no KServe |
| Cold start muito alto | Modelo grande ou storage lento | Otimize o modelo e use storage rápido (ex: MinIO local) | Modelos serverless, GPU e inferência distribuída no KServe |
| O agente não executa a ferramenta | Contrato da ferramenta mal definido ou parâmetro ausente | Revise a assinatura da função e os parâmetros esperados | Modelos, SDKs e protocolos: Claude, OpenAI, ElevenAgents, He |
| Erro de autenticação ao chamar APIs | Chave de API ausente ou inválida | Configure variáveis de ambiente com as chaves corretas | Modelos, SDKs e protocolos: Claude, OpenAI, ElevenAgents, He |
| Vídeo não gera no HeyGen | Parâmetro obrigatório ausente ou avatar_id inválido | Confira o payload enviado e use IDs válidos | Modelos, SDKs e protocolos: Claude, OpenAI, ElevenAgents, He |
| Relatórios incompletos ou desatualizados | Falha na coleta ou fonte pública fora do ar | Verifique logs do agente e revise endpoints das fontes | Monitoramento de concorrentes: agente em produção em uma red |
| Erros de formatação nos dados | Normalização inadequada ou contratos de ferramenta inconsistentes | Ajuste o parser e reforce testes automatizados | Monitoramento de concorrentes: agente em produção em uma red |
| Alertas em excesso ou irrelevantes | Thresholds mal calibrados ou dados ruidosos | Ajuste critérios de alerta e refine filtros de análise | Monitoramento de concorrentes: agente em produção em uma red |
| Alertas não chegam ao canal configurado | Webhook ou endpoint incorreto, ou bloqueio de firewall | Verifique URL do webhook e permissões de rede | Monitoramento de sessões e ações: detectando desvios em temp |
| Métricas não aparecem no sistema de logs | Falha no envio dos logs ou formato incompatível | Confirme integração do logger e formato dos dados | Monitoramento de sessões e ações: detectando desvios em temp |
| Sessões com erro não são detectadas | Hooks ou callbacks não implementados para eventos de falha | Implemente handlers para eventos de erro e exceção | Monitoramento de sessões e ações: detectando desvios em temp |
| Métricas do Milvus não aparecem no Prometheus | Exporter não está rodando ou endpoint incorreto. | Confirme se o container do exporter está ativo e se o endereço no prometheus.yml está correto. | Monitorando bancos vetoriais e APIs integradas |
| Alertas não disparam mesmo com latência alta | Threshold ou configuração do alerta inadequados. | Revise a regra de alerta e o valor do threshold. | Monitorando bancos vetoriais e APIs integradas |
| Script de latência retorna erro de timeout | API está fora do ar ou bloqueando requisições. | Verifique a disponibilidade da API e ajuste o timeout se necessário. | Monitorando bancos vetoriais e APIs integradas |
| Latência alta em todas as requisições | Modelo pesado demais para o hardware ou sobrecarga de CPU | Reduza o tamanho do modelo, otimize hardware ou escale horizontalmente | Monitorando Ollama e modelos: métricas que importam |
| Uso de memória cresce continuamente | Possível vazamento de memória no Ollama ou modelo | Reinicie o serviço e monitore novamente; atualize para versão mais recente | Monitorando Ollama e modelos: métricas que importam |
| Jobs acumulando em fila | Throughput insuficiente para a carga | Aumente recursos ou distribua a carga entre instâncias | Monitorando Ollama e modelos: métricas que importam |
| Tenant não consegue criar novos pods | Quota de pods atingida no namespace. | Aumente a quota ou libere recursos existentes. | Multi-tenancy e isolamento em clusters de IA |
| Usuário de tenant-a acessa recursos de tenant-b | RBAC ou NetworkPolicy mal configurados. | Revise bindings e políticas de rede. | Multi-tenancy e isolamento em clusters de IA |
| Pods de um tenant consomem toda a CPU do node | Limits e quotas insuficientes ou ausentes. | Ajuste ResourceQuota e LimitRange. | Multi-tenancy e isolamento em clusters de IA |
| Áudio não é gerado ou está corrompido | Chave de API ElevenLabs inválida ou parâmetro incorreto | Verifique a variável de ambiente ELEVENLABS_API_KEY e os parâmetros de voz | Multiagente com voz, vídeo e integração MCP: o futuro do pla |
| Vídeo não aparece ou fica em processamento indefinido | Parâmetros obrigatórios ausentes ou formato do script incompatível | Confirme avatar_id, script e formato de entrada no POST do HeyGen | Multiagente com voz, vídeo e integração MCP: o futuro do pla |
| Agente não acessa sistema externo via MCP | Contrato MCP não implementado corretamente ou endpoint fora do ar | Revise o contrato MCP e teste o endpoint manualmente | Multiagente com voz, vídeo e integração MCP: o futuro do pla |
| Sessões misturadas entre planejamentos | ID de sessão não está único ou sharding mal implementado | Revise a geração de IDs e a função de sharding | Multiagente em larga escala: desafios e soluções para grande |
| Perda de contexto após reinício de instância | Sessões não persistidas em armazenamento externo | Implemente persistência em banco externo | Multiagente em larga escala: desafios e soluções para grande |
| Latência alta ou timeouts em picos de uso | Instâncias insuficientes ou balanceador mal configurado | Aumente o número de instâncias e ajuste o balanceamento | Multiagente em larga escala: desafios e soluções para grande |
| Agente executando tarefas fora do escopo | Prompt de sistema genérico ou permissivo demais | Restringir e versionar o prompt, limitando funções | Multiagentes e orquestração: dividindo para conquistar o NOC |
| Orquestrador travando em loops | Condições de fallback mal definidas | Revisar lógica de decisão e limites de repetição | Multiagentes e orquestração: dividindo para conquistar o NOC |
| Faltam registros de ações | Tracing não implementado ou logs fora do fluxo | Centralizar registros e auditar após cada execução | Multiagentes e orquestração: dividindo para conquistar o NOC |
| Agente não chama ferramenta MCP | Contrato MCP não registrado ou endpoint inacessível | Verifique se o contrato está correto e o serviço MCP está disponível | Multiagentes, workflows e MCP: o que já mudou e o que vem aí |
| Dados inconsistentes entre agentes | Formato de saída/entrada divergente | Padronize os contratos e valide com testes automatizados | Multiagentes, workflows e MCP: o que já mudou e o que vem aí |
| Logs incompletos ou ausentes | Tracing não habilitado ou mal configurado | Ative tracing nos SDKs e confira permissões de escrita | Multiagentes, workflows e MCP: o que já mudou e o que vem aí |
| Dados de uma empresa aparecem para outra | Compartilhamento de variáveis ou arquivos temporários | Isolar objetos e caminhos de arquivo por empresa | Multiempresa e multicliente: isolamento, dados e performance |
| Performance de todos os clientes cai quando um faz operação pesada | Recursos computacionais compartilhados | Separar processos ou containers e limitar uso de CPU/memória | Multiempresa e multicliente: isolamento, dados e performance |
| Logs misturam eventos de empresas diferentes | Configuração única de logging | Configurar logs segregados por empresa | Multiempresa e multicliente: isolamento, dados e performance |
| Falha de autenticação cruzada | Tokens ou chaves não exclusivos por empresa | Gerar e validar chaves únicas por cliente | Multiempresa e multicliente: isolamento, dados e performance |
| Resultados de simulações de empresas diferentes aparecem misturados | Sessões de agente não estão isoladas corretamente | Garanta que cada empresa use uma sessão e memória separadas | Multiempresa e multirregime: agentes tributários para cenári |
| Regime fiscal aplicado incorretamente em simulações | Ferramenta não parametriza regime explicitamente | Inclua o regime como parâmetro obrigatório em todas as funções | Multiempresa e multirregime: agentes tributários para cenári |
| Logs de auditoria incompletos ou ausentes | Tracing não configurado ou falha de permissão em diretório de logs | Habilite tracing e verifique permissões de escrita | Multiempresa e multirregime: agentes tributários para cenári |
| Dados de uma equipe aparecem em outra | Isolamento de contexto mal implementado | Revisar configuração de memória e session_id | Multiplicando agentes: como escalar para várias equipes e ro |
| Logs misturados entre agentes | Tracing não separado por instância | Ajustar sistema de logs para usar identificadores únicos | Multiplicando agentes: como escalar para várias equipes e ro |
| Provisionamento cria agentes com configurações erradas | Script não padroniza prompts ou diretórios | Padronizar template de configuração e validar antes de ativar | Multiplicando agentes: como escalar para várias equipes e ro |
| Sessões concorrentes travam ou perdem histórico | Identificadores de sessão não são únicos | Gerar session_id por equipe e rotina | Multiplicando agentes: como escalar para várias equipes e ro |
| Logs ausentes ou incompletos | Configuração de logging incorreta ou permissões insuficientes | Revise a configuração do logger e permissões do sistema de logs | Multiplicando agentes: como escalar RH sem perder rastreabil |
| Decisões inconsistentes entre agentes replicados | Prompts ou ferramentas divergentes entre instâncias | Garanta que todos os agentes usem o mesmo prompt versionado e ferramentas idênticas | Multiplicando agentes: como escalar RH sem perder rastreabil |
| Dados de uma sessão aparecendo em outra | Isolamento de sessão falho ou compartilhamento indevido de memória | Revise a criação de sessões e evite variáveis globais ou arquivos compartilhados | Multiplicando agentes: como escalar RH sem perder rastreabil |
| Respostas atrasadas ou fora de ordem | Concorrência excessiva ou falta de controle de threads/processos | Reduza o número de subagentes simultâneos e revise o controle de concorrência | Multiplicando agentes: divisão de tarefas, subagentes e cont |
| Erros de limite de API | Execução simultânea acima do permitido pela API | Implemente limites mais conservadores no ThreadPoolExecutor ou equivalente | Multiplicando agentes: divisão de tarefas, subagentes e cont |
| Logs incompletos ou ausentes | Tracing não ativado ou mal configurado nos SDKs | Ative tracing e revise a configuração dos SDKs | Multiplicando agentes: divisão de tarefas, subagentes e cont |
| Respostas de agentes misturando contextos | Sessões compartilhadas ou mal isoladas | Garanta que cada agente crie sua própria sessão; revise uso de variáveis globais. | Multiplicando agentes: isolamento, concorrência e balanceame |
| Sistema travando com muitos agentes | Falta de limitação de recursos ou concorrência mal implementada | Implemente limites e revise se está usando processos para cargas pesadas. | Multiplicando agentes: isolamento, concorrência e balanceame |
| Fila de requisições crescendo sem fim | Balanceamento de carga ineficiente ou poucos workers | Aumente o número de instâncias e ajuste o balanceador. | Multiplicando agentes: isolamento, concorrência e balanceame |
| Sessões misturadas entre filiais | Configuração incorreta de memória ou diretórios compartilhados | Ajuste o memory_path ou o identificador de sessão para separar ambientes | Multiplicando agentes: RH para vários departamentos e filiai |
| Agente travando em horários de pico | Falta de balanceamento de carga ou poucos workers | Aumente o número de instâncias ou distribua tarefas com filas | Multiplicando agentes: RH para vários departamentos e filiai |
| Histórico não registrado | Falha no código de persistência de sessões | Implemente salvamento obrigatório e logging de erros | Multiplicando agentes: RH para vários departamentos e filiai |
| Dados sensíveis vazando entre departamentos | Falta de isolamento lógico nos prompts ou ferramentas | Revise as instruções e ferramentas de cada agente para garantir isolamento | Multiplicando agentes: RH para vários departamentos e filiai |
| Dois agentes processam a mesma tarefa | Divisão de shards sobreposta ou IDs repetidos | Revise a lógica de sharding e garanta ranges exclusivos por agente | Multiplicando agentes: sharding, paralelismo e isolamento |
| Uso de memória dispara rapidamente | Processos acumulando histórico ou dados desnecessários | Limite o histórico por sessão e limpe variáveis ao final | Multiplicando agentes: sharding, paralelismo e isolamento |
| Logs mostram erros de contexto compartilhado | Objetos de sessão sendo reutilizados entre processos | Garanta inicialização limpa de cada agente e contexto isolado | Multiplicando agentes: sharding, paralelismo e isolamento |
| O agente executa o comando sem pedir aprovação | Hook de aprovação não configurado corretamente | Verifique se o hook está atribuído a agent.hooks["before_tool"] e se retorna True/False conforme esperado | NOC: o alerta vira runbook executado com aprovação e relatór |
| Relatório não é gerado após a execução | Função gerar_relatorio não chamada ou erro de permissão de escrita | Confirme chamada da função e permissões do diretório | NOC: o alerta vira runbook executado com aprovação e relatór |
| Aprovação não é registrada no relatório | Campo aprovador não passado para a função gerar_relatorio | Inclua o identificador do aprovador ao chamar gerar_relatorio | NOC: o alerta vira runbook executado com aprovação e relatór |
| O agente não reconhece o alerta recebido | Formato do JSON de alerta incompatível com o prompt ou ferramentas | Padronize o JSON de entrada conforme exemplo da lição | NOC: o alerta vira runbook executado com aprovação e relatór |
| Erro ao extrair campo do XML | Caminho XPath incorreto ou namespace não definido | Ajuste o namespace e revise o caminho conforme o layout oficial da NF-e | Nota fiscal eletrônica: leitura, validação e alerta automati |
| Validação de data falha para alguns XMLs | Formato de data diferente (ex: 'dEmi' vs 'dhEmi') | Implemente tratamento para ambos formatos e teste com amostras reais | Nota fiscal eletrônica: leitura, validação e alerta automati |
| Alerta não chega ao responsável | Integração de notificação não configurada ou erro de permissão | Verifique logs do agente e ajuste as credenciais de envio | Nota fiscal eletrônica: leitura, validação e alerta automati |
| O agente retorna erro ao chamar ferramenta MCP | Contrato de entrada/saída incompatível ou handler com exceção não tratada | Revise os parâmetros e trate exceções no handler | Novas capacidades: agents, MCP, voz e vídeo no jurídico avan |
| Áudio ou vídeo não é gerado | Chave de API inválida ou parâmetros obrigatórios ausentes | Verifique variáveis de ambiente e campos obrigatórios | Novas capacidades: agents, MCP, voz e vídeo no jurídico avan |
| Respostas do agente não passam nos testes automáticos | Prompt de sistema ambíguo ou ferramenta com retorno inconsistente | Ajuste o prompt e normalize a saída das ferramentas | Novas capacidades: agents, MCP, voz e vídeo no jurídico avan |
| O agente não registra logs de tracing | Tracing não ativado ou SDK desatualizado | Ative o tracing e atualize o SDK | Novidades dos SDKs e MCP: o que muda na prática |
| Erro ao chamar ferramenta MCP | Contrato da ferramenta incompatível ou endpoint incorreto | Revise o contrato MCP e o endpoint | Novidades dos SDKs e MCP: o que muda na prática |
| Falha nos testes após atualizar SDK | Mudança de formato de entrada/saída nos SDKs | Atualize os casos de teste e contratos conforme changelog | Novidades dos SDKs e MCP: o que muda na prática |
| O agente nunca finaliza a execução. | Prompt sem critério de encerramento ou falta de limite de iterações. | Adicione instrução de limite de tentativas e finalize explicitamente. | O agente entrou em loop: diagnóstico e correção em quatro pa |
| O agente repete a mesma ação várias vezes. | Ferramenta não retorna status claro ou memória não registra tentativas. | Garanta que a ferramenta sinalize erro ou sem progresso e registre tentativas. | O agente entrou em loop: diagnóstico e correção em quatro pa |
| Consumo de tokens ou unidades muito acima do esperado. | Loop não detectado ou guardrail ausente. | Implemente controle de iterações e revise o tracing. | O agente entrou em loop: diagnóstico e correção em quatro pa |
| Pipeline não retorna respostas | Documentos não indexados ou query fora do escopo | Reindexe os documentos e teste queries conhecidas | O ecossistema Haystack: componentes e casos de uso |
| Erro de conexão com Document Store | Configuração de host/porta incorreta | Verifique as credenciais e a disponibilidade do serviço | O ecossistema Haystack: componentes e casos de uso |
| Respostas irrelevantes ou repetidas | top_k muito alto ou modelo inadequado | Reduza top_k e teste outro modelo Transformer | O ecossistema Haystack: componentes e casos de uso |
| Agente publica conteúdo errado | Falta de casos de teste ou guardrails insuficientes | Reforce a avaliação automática e revise os prompts | O futuro dos agentes no marketing: tendências, riscos e opor |
| Erro de integração com API externa | Mudança na API ou credenciais inválidas | Atualize as configurações e teste a conexão | O futuro dos agentes no marketing: tendências, riscos e opor |
| Logs incompletos ou ausentes | Tracing não ativado ou configuração incorreta | Habilite tracing e revise o pipeline de logs | O futuro dos agentes no marketing: tendências, riscos e opor |
| O agente entra em loop infinito. | Critérios de parada mal definidos ou ausência de limite de iterações. | Implemente limites explícitos e registre o motivo de cada iteração. | O laço de agente: planejar, chamar ferramenta, observar, dec |
| Ferramenta retorna erro inesperado. | Contrato da ferramenta não seguido ou exceção não tratada. | Valide entradas e trate exceções em todas as ferramentas. | O laço de agente: planejar, chamar ferramenta, observar, dec |
| Decisões do agente não são rastreáveis. | Tracing ou logs desativados. | Ative e configure o tracing do SDK escolhido. | O laço de agente: planejar, chamar ferramenta, observar, dec |
| O vídeo não aparece | Falta de créditos ou erro de autenticação na conta Runway | Peça ao ChatGPT para verificar a conexão e informar se há créditos disponíveis. | O primeiro vídeo sai de uma frase: peça, receba, aprove |
| O vídeo não corresponde ao pedido | Descrição ambígua ou detalhamento insuficiente | Refaça o pedido, tornando a descrição mais clara ou ajustando apenas um elemento. | O primeiro vídeo sai de uma frase: peça, receba, aprove |
| Mensagem de erro sobre permissão | Conta de empresa com restrição de aplicativos | Peça ao administrador para adicionar o app Runway para sua conta. | O primeiro vídeo sai de uma frase: peça, receba, aprove |
| Erro de contexto excedido | Prompt ou entrada maior que o limite do modelo | Divida a entrada em partes menores ou resuma dados antes de enviar | O que já funciona e o que ainda falta: limites técnicos e de |
| Saída inesperada ou ambígua | Contrato de ferramenta mal definido ou falta de validação | Reforce tipos e validação de entrada/saída | O que já funciona e o que ainda falta: limites técnicos e de |
| Dados sensíveis vazando em logs | Falta de anonimização ou uso inadequado de variáveis | Implemente anonimização e use variáveis de ambiente para segredos | O que já funciona e o que ainda falta: limites técnicos e de |
| Taxa de sucesso despenca repentinamente | Mudança em dados de entrada ou integração externa fora do ar | Rever logs, testar APIs externas e ajustar parsing | O que monitorar: métricas vitais do agente de RH em produção |
| Tempo de resposta alto mesmo com fila pequena | Modelo LLM ou ferramenta externa lento | Testar cada etapa separadamente para isolar o gargalo | O que monitorar: métricas vitais do agente de RH em produção |
| Alertas não são disparados | Condições de alerta mal configuradas ou logs incompletos | Revisar código de alerta e garantir cobertura de logs | O que monitorar: métricas vitais do agente de RH em produção |
| O vídeo ficou parado ou sem ação | Faltou descrever o movimento no pedido | Inclua ação do sujeito e movimento de câmera | O que se vê e o que se move: a estrutura da Runway em portug |
| A luz ou o estilo não combinam com o pedido | Descrição vaga ou ambígua | Especifique luz, estilo e ritmo de forma objetiva | O que se vê e o que se move: a estrutura da Runway em portug |
| O vídeo trouxe elementos não desejados | Prompt deixou espaço para interpretação | Descreva só o que deve aparecer, em linguagem positiva | O que se vê e o que se move: a estrutura da Runway em portug |
| A duração não bate com o pedido | Prompt não especificou duração | Inclua a duração exata no pedido | O que se vê e o que se move: a estrutura da Runway em portug |
| O vídeo não aparece na conversa | A integração Runway não foi instalada ou autenticada | Peça novamente para instalar o app Runway e conecte à sua conta quando solicitado | O que você pede e o que a IA faz sozinha: o método deste cur |
| O vídeo veio em resolução errada | A IA selecionou um modelo incompatível com a resolução pedida | Peça explicitamente a resolução desejada e confirme que o modelo suporta | O que você pede e o que a IA faz sozinha: o método deste cur |
| A câmera se moveu mesmo pedindo fixa | O prompt não foi claro sobre movimento de câmera | Peça 'câmera perfeitamente parada' e repita a geração | O que você pede e o que a IA faz sozinha: o método deste cur |
| O vídeo consumiu mais créditos do que o esperado | A IA escolheu um modelo ou formato premium | Peça para usar o modelo Gen-4.5 em mp4 padrão e confirme o custo antes de gerar | O que você pede e o que a IA faz sozinha: o método deste cur |
| O agente não atende ligações. | Configuração incorreta do SIP trunk ou número Twilio. | Revise as configurações de telefonia na ElevenLabs e teste o canal. | O telefone da empresa atendido por voz, com consulta ao ERP |
| O agente não consulta o ERP. | URL da ferramenta MCP não registrada ou endpoint inacessível. | Verifique o registro da ferramenta e a disponibilidade do endpoint MCP. | O telefone da empresa atendido por voz, com consulta ao ERP |
| O agente responde com erro ao consultar saldo. | Contrato MCP divergente do esperado ou dados de teste inválidos. | Ajuste o contrato MCP e use dados de teste válidos. | O telefone da empresa atendido por voz, com consulta ao ERP |
| Dados sensíveis aparecem na resposta. | Prompt de sistema ou validação MCP insuficiente. | Reforce as instruções do prompt e bloqueie campos no MCP. | O telefone da empresa atendido por voz, com consulta ao ERP |
| Tokens reportados não batem com a fatura | Erro na contagem local ou uso de endpoint incorreto | Confirme que está usando os métodos oficiais e revise a documentação | Observabilidade de custos e batches: sem surpresas no fim do |
| Alertas não disparam mesmo após exceder o limite | Lógica de agregação ou comparação falha | Revise o código de agregação e teste com dados simulados | Observabilidade de custos e batches: sem surpresas no fim do |
| Batch não gera desconto esperado | Requisições não estão agrupadas corretamente | Verifique o payload enviado e consulte a documentação do endpoint de batches | Observabilidade de custos e batches: sem surpresas no fim do |
| Métricas não aparecem no Prometheus | Endpoint /metrics inacessível ou configuração errada | Verifique se o Qdrant está rodando e revise o job_name no Prometheus. | Observabilidade em Qdrant e RAG: logs, métricas e tracing |
| Logs não mostram detalhes suficientes | Nível de log padrão muito baixo | Ajuste RUST_LOG para debug ou trace. | Observabilidade em Qdrant e RAG: logs, métricas e tracing |
| Traces não chegam ao Jaeger | Collector OpenTelemetry não configurado ou endpoint errado | Revise variáveis de ambiente e conectividade entre Qdrant e collector. | Observabilidade em Qdrant e RAG: logs, métricas e tracing |
| Logs não aparecem em JSON | Formato do handler não configurado corretamente | Verifique se o handler do logger usa JsonFormatter | Observabilidade: logs, métricas e tracing em LangChain |
| Prometheus não coleta métricas | Endpoint HTTP não exposto ou firewall bloqueando porta | Confirme se start_http_server está ativo e porta liberada | Observabilidade: logs, métricas e tracing em LangChain |
| Traces não aparecem no Jaeger ou Grafana Tempo | Exporter não configurado ou spans não definidos | Ajuste configuração do OpenTelemetry e revise spans no código | Observabilidade: logs, métricas e tracing em LangChain |
| O agente não responde ou retorna erro de autenticação | Variável de ambiente OPENAI_API_KEY não definida ou inválida | Defina a variável corretamente e confira a chave | OpenAI Agents SDK na prática: mesmo caso, diferenças e decis |
| Função de ferramenta não é chamada | Erro no contrato de tipo ou na assinatura da função | Revise tipos de entrada/saída e anotações | OpenAI Agents SDK na prática: mesmo caso, diferenças e decis |
| Prompt não é respeitado pelo agente | Instructions mal formatadas ou conflitantes | Versione e revise o prompt, testando instruções claras | OpenAI Agents SDK na prática: mesmo caso, diferenças e decis |
| Histórico de sessão não é mantido | Memória não implementada | Implemente backend para persistência de histórico | OpenAI Agents SDK na prática: mesmo caso, diferenças e decis |
| O agente responde com erro após atualização | Prompt ou ferramenta incompatível com o novo SDK | Reverta para a versão anterior e ajuste o prompt ou ferramenta antes de atualizar novamente | Operação contínua: atualização, rollback e melhoria sem sust |
| Rollback não retorna ao comportamento esperado | Dados de teste ou artefatos não versionados corretamente | Inclua todos os arquivos relevantes no controle de versão e repita o rollback | Operação contínua: atualização, rollback e melhoria sem sust |
| Tracing não registra execuções | Tracing não ativado ou configuração incorreta | Ative o tracing conforme a documentação do SDK | Operação contínua: atualização, rollback e melhoria sem sust |
| O vídeo mistura acontecimentos ou inverte a ordem | Prompt pouco claro ou eventos descritos juntos | Separe cada etapa com 'primeiro', 'depois', 'por fim' ou marcas de tempo | Ordem dos acontecimentos e duração: sequências que fazem sen |
| O vídeo termina antes de mostrar tudo | Duração insuficiente para a quantidade de eventos | Peça mais segundos ou divida em clipes menores | Ordem dos acontecimentos e duração: sequências que fazem sen |
| Transições abruptas entre etapas | Faltou pedir transição suave | Inclua no pedido: 'mantenha a transição suave entre as etapas' | Ordem dos acontecimentos e duração: sequências que fazem sen |
| A última etapa não aparece | Prompt longo demais para a duração | Reduza o número de acontecimentos ou aumente a duração | Ordem dos acontecimentos e duração: sequências que fazem sen |
| Handoff não registrado no log | Função de handoff não implementa registro de contexto | Inclua logging explícito ao realizar handoff | Orquestração avançada: multiagentes, handoffs e workflows au |
| Checkpoint aprovado com erro | Critérios de avaliação automática mal definidos | Revise casos de teste e condições de aprovação | Orquestração avançada: multiagentes, handoffs e workflows au |
| Agente executando tarefa de outro | Prompt de sistema genérico ou compartilhado | Especialize prompts e restrinja ferramentas por agente | Orquestração avançada: multiagentes, handoffs e workflows au |
| O agente não chama a ferramenta registrada | Contrato da ferramenta mal definido ou não registrada corretamente | Revise o registro e a assinatura da função | Orquestração de agentes: Claude Agent SDK, OpenAI Agents SDK |
| Tracing não aparece nos logs | Tracing não ativado ou configuração incorreta | Ative tracing conforme a documentação do SDK | Orquestração de agentes: Claude Agent SDK, OpenAI Agents SDK |
| Agente executa ações inesperadas | Prompt de sistema ou contratos ambíguos | Reescreva o prompt e os contratos das ferramentas | Orquestração de agentes: Claude Agent SDK, OpenAI Agents SDK |
| Requisições retornam 502 Bad Gateway | Instância Haystack offline ou endpoint incorreto no proxy | Verifique se o Haystack está rodando e revise configuração do proxy | Orquestração de múltiplos pipelines e balanceamento de requi |
| Latência alta em todos os pipelines | Sobrecarregou CPU/GPU do host | Distribua pipelines em mais servidores ou otimize modelos | Orquestração de múltiplos pipelines e balanceamento de requi |
| Falha de failover, requisições não redirecionadas | Health check do proxy mal configurado | Ajuste max_fails, fail_timeout e endpoints de health check | Orquestração de múltiplos pipelines e balanceamento de requi |
| Respostas lentas ou timeouts frequentes | Latência alta do fornecedor principal ou falta de fallback | Reduza o timeout e teste o fallback para outro agente. | Orquestração distribuída: Agents, MCP e múltiplos fornecedor |
| Erros HTTP 429 ou 5xx | Limite de uso atingido ou instabilidade do fornecedor | Implemente retentativas e fallback imediato para outro backend. | Orquestração distribuída: Agents, MCP e múltiplos fornecedor |
| Respostas inconsistentes entre fornecedores | Contratos MCP divergentes ou prompts desatualizados | Versione contratos e revise prompts para garantir compatibilidade. | Orquestração distribuída: Agents, MCP e múltiplos fornecedor |
| Agente executa tarefa de outro domínio | Prompt ou guardrails mal definidos | Reforce instruções e valide ferramentas permitidas | Orquestrador, especialistas e ferramentas: a organização de |
| Fila processa tarefas fora de ordem | Configuração inadequada de filas ou workers compartilhados | Separe filas por agente e revise configuração Celery | Orquestrador, especialistas e ferramentas: a organização de |
| Canal de voz gera áudio no idioma errado | Parâmetro model_id incorreto no ElevenLabs | Confirme o model_id e idioma suportado | Orquestrador, especialistas e ferramentas: a organização de |
| Áudio não aparece no vídeo gerado | Formato de áudio incompatível ou URL inacessível | Converta o áudio para MP3 e hospede em URL pública acessível pelo HeyGen | Orquestrando voz e vídeo: ElevenAgents e HeyGen no fluxo jur |
| Voz do agente não corresponde ao idioma esperado | Configuração de voice_id ou model_id incorreta | Verifique se voice_id e model_id suportam português (exemplo: eleven_multilingual_v2) | Orquestrando voz e vídeo: ElevenAgents e HeyGen no fluxo jur |
| Vídeo não é gerado ou fica em status 'waiting' indefinidamente | Parâmetros obrigatórios ausentes ou limite de processamento atingido | Revise o payload enviado e aguarde o tempo de processamento típico | Orquestrando voz e vídeo: ElevenAgents e HeyGen no fluxo jur |
| Erro ao criar InferenceService: nome inválido | Nome com maiúsculas, underscores ou caracteres proibidos | Use apenas minúsculas, números e hífens | Padrões de naming, versionamento e documentação de modelos |
| Modelo sobrescreve versão anterior | Versionamento semântico não seguido | Implemente MAJOR.MINOR.PATCH no nome e storageUri | Padrões de naming, versionamento e documentação de modelos |
| Documentação não encontrada via annotation | Annotation docs-url ausente ou incorreta | Adicione ou corrija a annotation no YAML | Padrões de naming, versionamento e documentação de modelos |
| Automação de documentação falha no CI | Pipeline sem dependências ou comandos errados | Revise o script do pipeline e dependências | Padrões de naming, versionamento e documentação de modelos |
| Ferramenta não aparece para o agente | Contrato não registrado corretamente ou schema inválido | Revise o registro e valide o schema com Pydantic | Padrões de orquestração: Agents, MCP e ferramentas |
| Sessão não mantém contexto | Sessão não passada corretamente para o runner/agent | Garanta que o objeto Session é reutilizado entre chamadas | Padrões de orquestração: Agents, MCP e ferramentas |
| Tracing não gera logs | Tracing desabilitado ou mal configurado | Ative tracing conforme a documentação do SDK | Padrões de orquestração: Agents, MCP e ferramentas |
| Skill retorna erro de tipo | Parâmetros passados com tipos incorretos ou contrato não seguido | Revise o contrato da skill e ajuste os testes para usar os tipos corretos | Padronização e reuso: templates, skills e ferramentas para e |
| Prompt de sistema não produz o comportamento esperado | Instruções vagas ou conflito de regras | Refine o template do prompt e teste com exemplos reais | Padronização e reuso: templates, skills e ferramentas para e |
| Testes automatizados falham sem motivo aparente | Casos de teste desatualizados ou divergência entre contrato e implementação | Atualize os casos de teste e sincronize com a última versão da skill | Padronização e reuso: templates, skills e ferramentas para e |
| Jobs de vídeo ficam travados em 'pending' | Fila local não está processando jobs ou workers pararam | Reinicie os workers e monitore logs de erro | Paralelismo, filas e balanceamento para voz e vídeo em larga |
| Erros 429 (Too Many Requests) nas APIs | Concorrência excessiva ou limites da API atingidos | Reduza o número de workers ou implemente backoff exponencial | Paralelismo, filas e balanceamento para voz e vídeo em larga |
| Fila cresce sem baixar | Capacidade de processamento insuficiente para o volume de requisições | Aumente o número de instâncias ou otimize o código dos workers | Paralelismo, filas e balanceamento para voz e vídeo em larga |
| O agente usa dados reais em ambiente de teste | Variáveis de ambiente carregadas incorretamente | Verifique se o arquivo .env correto está sendo carregado e se não há sobrescrita manual. | Parametrização de agentes: adaptando prompts, ferramentas e |
| Prompt apresenta variáveis não preenchidas | Placeholder não foi substituído por valor seguro | Confirme que todas as variáveis do prompt estão definidas no ambiente. | Parametrização de agentes: adaptando prompts, ferramentas e |
| Ferramenta retorna erro 404 | Endpoint configurado incorretamente para o ambiente | Ajuste a variável de ambiente da URL da ferramenta. | Parametrização de agentes: adaptando prompts, ferramentas e |
| Timeouts frequentes | request_timeout muito baixo ou provider instável | Aumente o timeout ou teste a conectividade com o provider | Parâmetros críticos: configuração de LLMs, chains e agents |
| Respostas muito longas ou caras | max_tokens configurado alto demais | Reduza max_tokens para o mínimo necessário | Parâmetros críticos: configuração de LLMs, chains e agents |
| Logs expondo dados sensíveis | Falta de mascaramento ou nível de log inadequado | Implemente filtros e revise o nível de log | Parâmetros críticos: configuração de LLMs, chains e agents |
| Resposta cortada no meio | Output limit (max_tokens) baixo demais | Aumente o valor de max_tokens conforme o tamanho esperado da resposta | Parâmetros críticos: effort, context size e output limit na |
| Erro de contexto excedido | Prompt e anexos ultrapassaram o limite do modelo | Reduza o tamanho do contexto ou troque de modelo | Parâmetros críticos: effort, context size e output limit na |
| Resposta lenta demais | Effort ou contexto configurados acima do necessário | Reduza effort ou limite o contexto ao essencial | Parâmetros críticos: effort, context size e output limit na |
| A IA não aponta nenhum problema, mas o vídeo sai ruim | As imagens podem ter defeitos sutis que passaram despercebidos | Peça avaliação mais detalhada, destacando textura, nitidez e cor | Peça à IA que avalie suas referências antes de gerar: foto, |
| A IA indica risco de direito de uso em imagem própria | A imagem pode ter rosto, marca ou ambiente reconhecível | Confirme se há autorização e explique à IA que o direito é garantido | Peça à IA que avalie suas referências antes de gerar: foto, |
| A IA mistura análise de produto e estilo | As imagens não foram separadas por função | Organize e envie cada tipo em lote distinto | Peça à IA que avalie suas referências antes de gerar: foto, |
| A IA pede para consultar documentação | Pedido mal formulado ou IA sem contexto suficiente | Reforce que quer análise objetiva, sem referência externa | Peça à IA que avalie suas referências antes de gerar: foto, |
| O vídeo mostra o produto cortado ou deformado | Foto enviada com ângulo ruim ou fundo poluído | Envie fotos centralizadas, fundo limpo e ângulos claros | Peça um comercial: a Recipe Product Ad a partir da foto do p |
| Movimento da câmera exagerado ou estranho | Direção criativa ambígua ou ausência de instrução de movimento | Peça câmera fixa ou movimento mínimo explicitamente | Peça um comercial: a Recipe Product Ad a partir da foto do p |
| Luz artificial ou cor distorcida | Foto de referência com sombra dura ou cor dominante | Use fotos com luz neutra e uniforme | Peça um comercial: a Recipe Product Ad a partir da foto do p |
| Vídeo muito curto ou longo | Duração não especificada ou fora do intervalo permitido | Peça duração entre 4 e 15 segundos | Peça um comercial: a Recipe Product Ad a partir da foto do p |
| Arquivo não pode ser baixado | Problema temporário no serviço ou link expirado | Peça para gerar novamente | Peça um comercial: a Recipe Product Ad a partir da foto do p |
| O vídeo multi-shot não tem cortes claros | Pedido pouco detalhado ou cenas parecidas | Descreva cada plano com mais detalhes e peça cortes explícitos. | Peça uma peça com cortes e uma no estilo criador: Multi-Shot |
| O vídeo UGC não parece feito por influenciador | Referência de influenciador ruim ou tom do pedido genérico | Troque a imagem do influenciador e detalhe o estilo e o cenário. | Peça uma peça com cortes e uma no estilo criador: Multi-Shot |
| O produto aparece distorcido | Imagem de referência de baixa qualidade ou com fundo poluído | Envie imagens de alta resolução, centralizadas e com fundo limpo. | Peça uma peça com cortes e uma no estilo criador: Multi-Shot |
| O vídeo ficou curto ou longo demais | Duração não especificada ou fora dos limites da Recipe | Peça duração entre 5 e 15 segundos para Multi-Shot Video e 4 a 15 para Product UGC. | Peça uma peça com cortes e uma no estilo criador: Multi-Shot |
| Só uma versão foi gerada | O pedido não especificou o número de variações ou a IA entendeu como ajuste único. | Peça explicitamente o número de variações desejadas. | Pedir variações, comparar e escolher, sem refazer do zero |
| As versões são quase iguais | A mudança pedida foi muito sutil ou o prompt não diferenciou bastante as alternativas. | Peça mudanças mais claras entre as variações. | Pedir variações, comparar e escolher, sem refazer do zero |
| Exportação falhou ou não veio o link | O formato pedido não está disponível para o modelo ou houve erro de conexão com a Runway. | Peça exportação em mp4 padrão ou tente novamente após reconectar a Runway. | Pedir variações, comparar e escolher, sem refazer do zero |
| A IA exportou a versão errada | A escolha da melhor versão não foi clara na conversa. | Indique explicitamente o número ou nome da versão a ser exportada. | Pedir variações, comparar e escolher, sem refazer do zero |
| O agente acessa arquivos fora do diretório permitido | Permissões mal configuradas ou validação ausente na função/tool | Revise o arquivo de permissões ou implemente validação rigorosa | Permissões e isolamento: o que cada agente pode (ou não) faz |
| Logs não registram ações sensíveis | Hooks de logging não implementados ou erro de permissão no arquivo de log | Implemente ou corrija o hook de logging e verifique permissões do sistema | Permissões e isolamento: o que cada agente pode (ou não) faz |
| Sessões compartilham histórico entre usuários | Reuso indevido de objetos Session ou contexto global | Garanta que cada usuário/tarefa tenha sua própria sessão isolada | Permissões e isolamento: o que cada agente pode (ou não) faz |
| O agente consegue acessar arquivos fora da pasta permitida | Permissão mal configurada em permissions.yaml ou validação ausente na Tool | Revise o arquivo de permissões e adicione validação explícita nos parâmetros | Permissões e sandbox: o que o agente pode e não pode fazer |
| Tentativas de acesso negado não aparecem no log | Hook de logging não implementado ou caminho do log incorreto | Implemente o hook e verifique permissões de escrita no diretório de logs | Permissões e sandbox: o que o agente pode e não pode fazer |
| O agente trava ou é encerrado abruptamente | Limite de CPU, memória ou tempo muito restritivo no sandbox | Ajuste os limites no environment.yaml conforme a carga real do agente | Permissões e sandbox: o que o agente pode e não pode fazer |
| Logs não aparecem no sistema de auditoria | Formato incompatível ou falha de integração | Ajuste o formato para JSON e teste a conexão com o SIEM | Permissões, auditoria e revisão: IA sob controle |
| Ações críticas são executadas sem revisão | Guardrails ou hooks não aplicados corretamente | Revise a configuração dos guardrails/hooks e teste com casos de bloqueio | Permissões, auditoria e revisão: IA sob controle |
| Permissões não estão sendo respeitadas | Lista de ferramentas mal configurada | Reavalie o arquivo permissions.yaml ou a lista de tools do agente | Permissões, auditoria e revisão: IA sob controle |
| Logs contêm dados pessoais sem base legal | Falta de sanitização dos eventos | Implemente filtros para remover ou anonimizar dados pessoais | Permissões, auditoria e revisão: IA sob controle |
| Agente acessa arquivos fora da pasta autorizada | Permissões mal configuradas ou sandbox ausente | Revise o arquivo de permissões e o isolamento do ambiente | Permissões, sandbox e revisão: limites técnicos para evitar |
| Decisões críticas são executadas sem revisão | Falta de guardrails ou hooks de revisão | Implemente validação obrigatória antes da ação | Permissões, sandbox e revisão: limites técnicos para evitar |
| Erro ao rodar comandos permitidos | Sandbox excessivamente restrito | Ajuste o volume montado e permissões de execução | Permissões, sandbox e revisão: limites técnicos para evitar |
| Logs não mostram tentativas bloqueadas | Falta de tracing ou configuração de registro | Ative logging detalhado no SDK ou container | Permissões, sandbox e revisão: limites técnicos para evitar |
| O agente responde sem citar fonte completa | Prompt ou guardrail de saída insuficiente | Reforce o prompt e implemente validação obrigatória dos campos | Pesquisa de legislação e entendimentos: agente que traz a fo |
| Respostas com fontes inexistentes ou inventadas | Base de normas inconsistente ou IA sem restrição de fonte | Use apenas base confiável e bloqueie respostas sem correspondência real | Pesquisa de legislação e entendimentos: agente que traz a fo |
| Respostas não aparecem para revisão | Falha no registro ou workflow de anotação | Verifique o log e o fluxo de status das respostas | Pesquisa de legislação e entendimentos: agente que traz a fo |
| Respostas sem citação de fonte oficial | Prompt insuficiente ou ferramenta de busca não restrita | Reforce o prompt e limite as fontes no código da ferramenta | Pesquisa legislativa com citação: agentes em ação no jurídic |
| Texto legal desatualizado | Fonte não oficial ou scraping de página antiga | Restrinja buscas a domínios oficiais e atualize a rotina de busca | Pesquisa legislativa com citação: agentes em ação no jurídic |
| Respostas com opinião jurídica | Prompt de sistema vago | Inclua proibição explícita de opinião no prompt | Pesquisa legislativa com citação: agentes em ação no jurídic |
| Busca retorna resultados irrelevantes | Modelo de embeddings inadequado para o domínio técnico | Teste outro modelo aberto ou fine-tune em textos técnicos | Pesquisa semântica em base de conhecimento técnica |
| Latência alta nas buscas | Coleção muito grande sem tuning de índices | Ajuste o algoritmo de busca (ex: HNSW) e revise os parâmetros do Qdrant | Pesquisa semântica em base de conhecimento técnica |
| Artigos atualizados não refletem na busca | Embeddings antigos ainda indexados | Regenere e reindexe os embeddings após cada atualização | Pesquisa semântica em base de conhecimento técnica |
| O Reader retorna respostas vazias. | Documentos indexados não contêm contexto suficiente ou embeddings incompatíveis. | Revise os textos indexados e confirme se o modelo de embeddings bate com a dimensão configurada. | Pipeline básico Haystack: do zero ao primeiro resultado |
| Erro ao criar FAISS Document Store. | Dimensão de embedding incompatível com o modelo. | Ajuste o parâmetro embedding_dim para o valor correto do modelo de embeddings. | Pipeline básico Haystack: do zero ao primeiro resultado |
| Container Docker não sobe. | Porta 8000 já em uso ou falta de memória. | Libere a porta ou aumente a memória disponível. | Pipeline básico Haystack: do zero ao primeiro resultado |
| Endpoint retorna 404 após deploy | Manifest aponta para storageUri inexistente ou modelo não carregou. | Revise o path do modelo e logs do pod do KServe. | Pipelines de CI/CD para deploy automatizado de modelos |
| ArgoCD/Flux não aplica a mudança | Permissões insuficientes ou erro de sintaxe no manifest. | Cheque logs do operador e valide o manifest com 'kubectl apply --dry-run'. | Pipelines de CI/CD para deploy automatizado de modelos |
| Teste automatizado falha | Payload de teste incompatível com o modelo ou modelo corrompido. | Valide o payload e tente recarregar o modelo no storage. | Pipelines de CI/CD para deploy automatizado de modelos |
| Respostas irrelevantes ou vazias | Retriever mal configurado ou Document Store sem dados indexados | Reindexe os documentos e ajuste os parâmetros do Retriever. | Pipelines Haystack: como os componentes se conectam na práti |
| Pipeline lento | Backend subdimensionado ou Reader pesado | Reduza o número de documentos retornados pelo Retriever ou otimize o modelo do Reader. | Pipelines Haystack: como os componentes se conectam na práti |
| Erro de conexão com Document Store | Configuração incorreta de host/porta ou backend fora do ar | Verifique as credenciais e se o serviço está rodando. | Pipelines Haystack: como os componentes se conectam na práti |
| O agente propõe tarefas sem detalhamento suficiente. | Prompt de sistema pouco específico. | Refine o prompt para exigir tarefas SMART e detalhamento obrigatório. | Planejamento de metas e orçamento: caso EXEMPLO de desdobram |
| Orçamento calculado está incorreto. | Premissas EXEMPLO ou lógica da ferramenta erradas. | Revise os valores e a função de cálculo. | Planejamento de metas e orçamento: caso EXEMPLO de desdobram |
| Aprovação não é registrada corretamente. | Erro na implementação da ferramenta registrar_decisao. | Valide os parâmetros e o registro no log. | Planejamento de metas e orçamento: caso EXEMPLO de desdobram |
| Pod OOMKilled durante inferência | Limite de memória insuficiente para o modelo carregado | Aumente o valor de 'memory' em requests e limits | Planejamento de recursos: CPU, memória e storage para IA |
| Pods não escalam acima de certo número | Cotas de namespace ou falta de recursos no cluster | Revise ResourceQuota e a capacidade dos nodes | Planejamento de recursos: CPU, memória e storage para IA |
| Inferência lenta mesmo com CPU ociosa | Storage MinIO saturado ou rede lenta | Aumente réplicas do MinIO ou otimize a rede/storage | Planejamento de recursos: CPU, memória e storage para IA |
| Respostas inconsistentes do modelo | Base de conhecimento com versões conflitantes ou ingestão incompleta | Reindexe dados e valide integridade dos arquivos | Planejando a base de conhecimento: fontes, ingestão e atuali |
| Demora excessiva na atualização | Pipeline processando toda a base em vez de incremental | Implemente verificação de hash ou timestamp | Planejando a base de conhecimento: fontes, ingestão e atuali |
| Dados recentes não aparecem nas respostas | Ingestão incremental não detectou novos arquivos | Revise lógica de detecção de mudanças e permissões de leitura | Planejando a base de conhecimento: fontes, ingestão e atuali |
| Teste sempre falha mesmo com resposta correta | Critério de aprovação muito restritivo ou mal implementado. | Revise a função de validação para aceitar variações legítimas. | Planejando casos de teste e avaliação automática no jurídico |
| Respostas incoerentes em casos idênticos | Prompt de sistema inconsistente ou modelo instável. | Reforce instruções no prompt e avalie troca de modelo. | Planejando casos de teste e avaliação automática no jurídico |
| Testes de regressão passam a falhar após atualização | Mudança no prompt, modelo ou ferramenta afetou comportamento. | Compare versões e ajuste o prompt ou critérios conforme necessário. | Planejando casos de teste e avaliação automática no jurídico |
| Dados pessoais aparecem em logs ou prompts | Falta de masking ou uso de payloads brutos | Implemente funções de anonimização e revise o código de logging | Planejando dados e integrações: minimização, LGPD e performa |
| Chaves de API expostas no código-fonte | Segredos hardcoded | Mova todos os segredos para variáveis de ambiente | Planejando dados e integrações: minimização, LGPD e performa |
| Latência alta nas integrações | Excesso de chamadas individuais ou payloads grandes | Use endpoints de batch e minimize o tamanho dos dados enviados | Planejando dados e integrações: minimização, LGPD e performa |
| O agente processa currículos com dados pessoais sensíveis sem bloqueio. | Guardrails de entrada ausentes ou incorretos. | Reveja e corrija as funções de validação de entrada. | Pontos críticos: onde o agente pode errar e como prevenir fa |
| Decisões críticas são executadas automaticamente sem aprovação. | Falta de lógica de revisão humana. | Implemente etapa de aprovação obrigatória para ações críticas. | Pontos críticos: onde o agente pode errar e como prevenir fa |
| Logs de execução estão vazios ou incompletos. | Tracing não ativado ou mal configurado. | Ative o tracing e defina o diretório de saída corretamente. | Pontos críticos: onde o agente pode errar e como prevenir fa |
| Lead não avança para próxima etapa | Prompt ou ferramenta com critérios mal definidos | Revise o prompt e os contratos das ferramentas | Por que agentes de IA mudam o comercial: do lead ao fechamen |
| Proposta gerada com dados errados | Fonte de dados desatualizada ou erro de integração | Atualize a fonte e teste a ferramenta isoladamente | Por que agentes de IA mudam o comercial: do lead ao fechamen |
| Ação irreversível executada sem aprovação | Falta de guardrail ou revisão humana | Implemente checagem obrigatória antes de ações críticas | Por que agentes de IA mudam o comercial: do lead ao fechamen |
| O agente sugere regimes incompatíveis com os dados | Premissas de entrada erradas ou prompt mal definido | Revisar validação de entrada e clareza das instruções | Por que agentes de IA mudam o jogo no tributário: limites, p |
| Cita leis inexistentes ou desatualizadas | Fonte de dados desatualizada ou alucinação do modelo | Atualizar fontes e reforçar guardrails de citação | Por que agentes de IA mudam o jogo no tributário: limites, p |
| Não registra as fontes consultadas | Prompt ou ferramenta sem lógica de registro | Adicionar registro obrigatório nas ferramentas e no prompt | Por que agentes de IA mudam o jogo no tributário: limites, p |
| O agente não executa a ferramenta definida | Nome da ferramenta ou assinatura incompatível com o prompt ou SDK | Revisar nome, parâmetros e retorno da ferramenta no código | Por que agentes de IA mudam o planejamento: do fluxo manual |
| Resultados inconsistentes entre execuções | Dados de entrada variando ou falta de seed fixa em simulações | Padronizar dados de teste e inicialização | Por que agentes de IA mudam o planejamento: do fluxo manual |
| Logs incompletos ou ausentes | Tracing não configurado ou diretório de saída incorreto | Ativar tracing no SDK e revisar permissões de escrita | Por que agentes de IA mudam o planejamento: do fluxo manual |
| O agente gera recomendações sem citar premissas | Prompt de sistema incompleto ou mal especificado | Reforce no prompt que toda recomendação deve listar premissas e incertezas | Por que agentes e multiagentes mudam o apoio à decisão: sínt |
| Decisões irreversíveis são tomadas sem revisão | Falta de guardrails ou bypass de revisão humana | Implemente guardrails e exija aprovação manual para ações críticas | Por que agentes e multiagentes mudam o apoio à decisão: sínt |
| Dados confidenciais aparecem nos logs | Ausência de filtros ou validação de entrada/saída | Adicione validadores para bloquear termos sensíveis e minimize o registro de dados pessoais | Por que agentes e multiagentes mudam o apoio à decisão: sínt |
| O agente gera conteúdo fora do tom esperado | Prompt de sistema pouco específico ou ausência de exemplos claros | Refine o prompt e inclua exemplos de saída desejada | Por que agentes e multiagentes mudam o marketing: do conteúd |
| Decisões críticas são tomadas sem revisão humana | Falta de guardrails ou checagem de aprovação | Implemente verificação obrigatória antes de ações irreversíveis | Por que agentes e multiagentes mudam o marketing: do conteúd |
| Dados sensíveis aparecem em logs ou saídas | Falta de filtro de dados pessoais ou configuração inadequada de ferramentas | Adicione guardrails e revise permissões das ferramentas | Por que agentes e multiagentes mudam o marketing: do conteúd |
| O agente aprova documentos incompletos | Prompt de sistema mal definido ou ferramenta sem validação | Reforce o prompt e revise a função de validação | Por que agentes e multiagentes mudam o RH: limites, riscos e |
| Dados sensíveis aparecem em logs | Falta de controle de variáveis e logs excessivos | Reduza logs, use variáveis de ambiente para segredos | Por que agentes e multiagentes mudam o RH: limites, riscos e |
| O agente toma decisões sem revisão | Falta de guardrails ou bypass de aprovação | Implemente checagem obrigatória de aprovação humana antes de ações críticas | Por que agentes e multiagentes mudam o RH: limites, riscos e |
| Agente entregou obrigação sem revisão | Prompt de sistema permissivo ou ausência de guardrail | Reforce as instruções e implemente validação obrigatória | Por que agentes fiscais? Limites da IA e o papel do humano |
| Campos obrigatórios não validados | Falta de testes de exceção | Inclua casos de teste com campos ausentes ou inválidos | Por que agentes fiscais? Limites da IA e o papel do humano |
| Dados sensíveis vazaram em logs | Segredos não protegidos | Use variáveis de ambiente e restrinja acesso aos logs | Por que agentes fiscais? Limites da IA e o papel do humano |
| O agente não coleta dados corretamente | Fonte de dados mal configurada ou permissão insuficiente | Revise as credenciais e o endpoint de coleta | Por que agentes mudam a gestão: do dado manual ao fluxo auto |
| Alertas não são gerados mesmo com desvio | Lógica de análise com erro ou meta mal definida | Ajuste a função de análise e valide os parâmetros de meta | Por que agentes mudam a gestão: do dado manual ao fluxo auto |
| Ação é executada sem revisão humana | Falta de checagem condicional antes da ação | Inclua verificação obrigatória de aprovação humana nos fluxos críticos | Por que agentes mudam a gestão: do dado manual ao fluxo auto |
| O agente aprova pagamentos automaticamente | Prompt ou configuração de permissões incorreta | Revise o prompt e restrinja permissões do agente para apenas preparar, nunca aprovar. | Por que agentes no administrativo: limites, riscos e ganhos |
| Documentos são classificados incorretamente | Exemplos insuficientes ou prompt ambíguo | Ajuste o prompt e forneça mais exemplos claros para o agente. | Por que agentes no administrativo: limites, riscos e ganhos |
| Ações do agente não aparecem nos registros | Registro (tracing) desativado ou mal configurado | Ative o tracing e valide que cada ação é registrada para auditoria. | Por que agentes no administrativo: limites, riscos e ganhos |
| O agente classifica tudo como 'revisão necessária' | Prompt de sistema pouco claro ou plano de contas incompleto | Revise o prompt e detalhe o plano de contas. | Por que agentes no contábil: limites da automação tradiciona |
| Erros de autenticação ao rodar o agente | Variável de ambiente da chave de API não definida | Defina a variável CLAUDE_API_KEY ou OPENAI_API_KEY corretamente. | Por que agentes no contábil: limites da automação tradiciona |
| Decisões erradas em exceções | Falta de exemplos de exceções nos dados de teste | Inclua casos de exceção e revise os critérios de avaliação automática. | Por que agentes no contábil: limites da automação tradiciona |
| O agente retorna campos vazios ou incompletos. | Prompt de sistema ambíguo ou dados de entrada fora do padrão. | Reescreva o prompt de sistema e amplie os casos de teste. | Por que agentes: limites da automação tradicional no desenvo |
| O agente executa ações indevidas (ex: aprova sem validação). | Falta de guardrails ou critérios claros de aprovação. | Implemente validação automática e revisão humana obrigatória. | Por que agentes: limites da automação tradicional no desenvo |
| Resultados diferentes para entradas similares. | Prompt inconsistente ou falta de exemplos no treinamento. | Padronize o prompt e aumente a cobertura dos testes. | Por que agentes: limites da automação tradicional no desenvo |
| O agente classifica alertas errados | Prompt ou lógica de triagem inadequados | Revisar e ajustar o prompt e os casos de teste | Por que IA no NOC: limites do humano, oportunidades do agent |
| Ações não aparecem no registro (tracing) | Tracing desabilitado ou mal configurado | Ativar tracing no agente e validar logs | Por que IA no NOC: limites do humano, oportunidades do agent |
| Agente executa ações críticas sem aprovação | Guardrails ou limites de permissão ausentes | Implementar ou reforçar guardrails e revisão humana | Por que IA no NOC: limites do humano, oportunidades do agent |
| O LLM responde sem contexto dos dados internos | O conector do banco vetorial não foi configurado corretamente | Revise a configuração do vectorstore e da função de embedding | Por que LangChain? O elo entre modelos, dados e APIs |
| Erro ao acessar API externa | Endpoint ou autenticação incorretos | Verifique URL e credenciais da API | Por que LangChain? O elo entre modelos, dados e APIs |
| Pipeline não registra logs de cada etapa | Logging do LangChain não habilitado | Consulte a documentação para ativar logging detalhado | Por que LangChain? O elo entre modelos, dados e APIs |
| O orquestrador trava ao chamar um agente | Timeout ou erro de contrato de entrada/saída | Revise o contrato do agente e aumente o timeout se necessário | Por que multiagentes? De tarefas isoladas ao fluxo empresari |
| Dados sensíveis vazando entre agentes | Permissões excessivas ou prompts mal definidos | Reduza o escopo do prompt e restrinja permissões | Por que multiagentes? De tarefas isoladas ao fluxo empresari |
| Logs incompletos ou ausentes | Falta de configuração de tracing | Implemente logging detalhado em cada etapa | Por que multiagentes? De tarefas isoladas ao fluxo empresari |
| Agente executa ação crítica sem aprovação | Workflow sem etapa de revisão ou contrato de ferramenta mal definido | Inclua handoff obrigatório e revise contratos de ferramenta | Por que o jurídico precisa de agentes: limites, riscos e opo |
| Dados pessoais aparecem em logs | Falta de minimização ou de anonimização nos registros | Implemente filtros e revise o código de logging | Por que o jurídico precisa de agentes: limites, riscos e opo |
| Erro de autenticação ao chamar API | Variável de ambiente não definida ou chave de API inválida | Defina corretamente as variáveis de ambiente e valide as chaves | Por que o jurídico precisa de agentes: limites, riscos e opo |
| Decisões do agente não aparecem no log | Tracing não configurado corretamente ou permissões de escrita insuficientes. | Revise a configuração do tracer e garanta acesso de escrita ao diretório de logs. | Por que RH precisa de agentes: limites humanos, justiça e ra |
| Agente aprova candidatos inválidos | Critérios mal definidos ou casos de teste insuficientes. | Reforce os critérios e amplie os casos de teste para cobrir exceções. | Por que RH precisa de agentes: limites humanos, justiça e ra |
| Erro ao rodar agente com SDK | Dependências do SDK não instaladas ou versão incompatível. | Reinstale o SDK oficial e confira os requisitos de ambiente. | Por que RH precisa de agentes: limites humanos, justiça e ra |
| Modelo não sobe após rollback | Incompatibilidade de dependências ou storageUri incorreto | Verifique se o runtimeVersion e o storageUri correspondem à versão rollback | Por que serving de IA não é só um container exposto |
| Latência alta mesmo sem carga | Modelo pesado ou falta de recursos (CPU/GPU) | Ajuste requests/limits no deployment ou otimize o modelo | Por que serving de IA não é só um container exposto |
| Drift de acurácia detectado | Mudança no padrão dos dados de entrada | Re-treine o modelo com dados mais recentes | Por que serving de IA não é só um container exposto |
| Erro de limite excedido na API | Prompt ou contexto maior que o permitido pelo modelo | Reduza o tamanho do prompt ou divida a tarefa em partes menores | Previsão de uso e custos: como evitar surpresas na conta |
| Consumo de tokens maior que o esperado | Histórico ou contexto sendo enviado junto sem necessidade | Otimize o prompt e envie apenas o essencial | Previsão de uso e custos: como evitar surpresas na conta |
| Fatura inesperadamente alta após testes | Testes automatizados sem limitação de volume | Implemente limites e use mocks em ambientes de teste | Previsão de uso e custos: como evitar surpresas na conta |
| Erro 'Invalid API key' ou 'Unauthorized' | Chave de API incorreta ou variável de ambiente não definida. | Confirme a chave e defina corretamente a variável de ambiente. | Primeiro request: Anthropic e OpenAI lado a lado em Python |
| Campo 'completion' não encontrado na resposta da Anthropic | Uso de SDK desatualizado ou acesso ao campo errado. | Atualize o SDK e use 'response.completion'. | Primeiro request: Anthropic e OpenAI lado a lado em Python |
| Campo 'choices' não encontrado na resposta do OpenAI | Uso de endpoint ou método errado. | Confirme que está usando 'client.chat.completions.create'. | Primeiro request: Anthropic e OpenAI lado a lado em Python |
| O agente retorna erro de autenticação | Chave de API ausente ou mal configurada na variável de ambiente | Verifique e exporte a chave correta antes de rodar o agente | Princípios de operação segura e eficiente para agentes juríd |
| Mudança de prompt gera comportamento inesperado | Alteração sem versionamento ou teste | Implemente versionamento e rode testes automatizados a cada alteração | Princípios de operação segura e eficiente para agentes juríd |
| Ferramenta retorna dados inconsistentes | Contrato de parâmetros ou retorno mal documentado | Reveja a definição da ferramenta e ajuste documentação e testes | Princípios de operação segura e eficiente para agentes juríd |
| Logs não mostram ações do agente | Tracing desativado ou mal configurado | Ative o tracing no SDK e garanta persistência dos logs | Princípios de operação segura e eficiente para agentes juríd |
| Dados pessoais aparecem em logs ou registros. | Anonimização ou filtragem insuficiente. | Revise o código de logging e aplique hash ou mascaramento antes de registrar. | Privacidade e LGPD no comercial automatizado: o que não pode |
| Chaves de API vazam em prompts ou respostas. | Interpolação de variáveis insegura. | Garanta que segredos só sejam usados em variáveis de ambiente e nunca em strings processadas por agentes. | Privacidade e LGPD no comercial automatizado: o que não pode |
| Agente acessa dados além do necessário. | Prompt de sistema mal definido ou ferramentas com permissões excessivas. | Redefina o prompt e limite as ferramentas e parâmetros disponíveis ao agente. | Privacidade e LGPD no comercial automatizado: o que não pode |
| Dados pessoais completos aparecem em logs | Logging mal configurado ou prompts excessivos | Revise o código para filtrar dados sensíveis antes de registrar | Privacidade e LGPD no RH automatizado: minimização e control |
| Chaves de API vazam em mensagens de erro | Tratamento de exceção expõe variáveis | Oculte segredos em mensagens e logs; nunca retorne variáveis de ambiente ao usuário | Privacidade e LGPD no RH automatizado: minimização e control |
| Agente acessa mais dados do que deveria | Parâmetros de ferramenta mal definidos | Restrinja contratos de ferramentas e revise prompts de sistema | Privacidade e LGPD no RH automatizado: minimização e control |
| Resultado do agente não corresponde ao cenário informado | Premissas do prompt estão desatualizadas ou mal definidas | Revise e explicite todas as premissas no prompt, marcando EXEMPLO quando necessário | Prompt de sistema para o tributário: requisitos, versionamen |
| Não é possível saber qual versão do prompt gerou um resultado | Cabeçalho de versionamento ausente ou não registrado em log | Inclua sempre o identificador de versão no prompt e no registro de execução | Prompt de sistema para o tributário: requisitos, versionamen |
| Auditoria não encontra fonte para regra aplicada | Fonte não citada ou link não oficial | Sempre cite número, nome e link oficial da norma no prompt | Prompt de sistema para o tributário: requisitos, versionamen |
| O agente responde fora do formato JSON. | Prompt de sistema não especifica claramente o formato. | Reforce a instrução de formato obrigatório no prompt. | Prompt de sistema que não deixa o agente inventar: regras, f |
| O agente tenta responder a perguntas proibidas. | Falta de instrução explícita de recusa no prompt. | Inclua a mensagem de recusa padrão e teste com casos proibidos. | Prompt de sistema que não deixa o agente inventar: regras, f |
| A resposta contém dados inventados. | Prompt não proíbe invenção de informações. | Adicione a instrução: 'Não invente informações. Se não souber, diga 'Não sei'.' | Prompt de sistema que não deixa o agente inventar: regras, f |
| O agente gera atas com informações inconsistentes | Prompt sem exemplos claros ou contexto insuficiente | Inclua exemplos de entrada e saída no prompt e revise o objetivo. | Prompt de sistema versionado: como garantir contexto, rastre |
| Mudanças recentes no comportamento do agente não são rastreáveis | Prompt sem histórico de versões ou versionamento inadequado | Adicione cabeçalho de versão e registre mudanças em sistema de versionamento. | Prompt de sistema versionado: como garantir contexto, rastre |
| A IA toma decisões financeiras sem revisão | Critérios de revisão humana ausentes ou mal definidos | Inclua regras explícitas para revisão obrigatória no prompt. | Prompt de sistema versionado: como garantir contexto, rastre |
| O agente está usando instruções antigas | Arquivo de prompt desatualizado ou não referenciado corretamente | Confirme o caminho do arquivo e atualize o parâmetro de inicialização | Prompt de sistema versionado: garantia de contexto e rastrea |
| Dados sensíveis aparecem em logs | Segredos embutidos no prompt de sistema | Remova segredos do prompt e use variáveis de ambiente | Prompt de sistema versionado: garantia de contexto e rastrea |
| Não é possível auditar decisões antigas | Falta de versionamento ou logs de versão do prompt | Implemente versionamento e registre a versão em cada execução | Prompt de sistema versionado: garantia de contexto e rastrea |
| O agente começa a responder fora do escopo | Prompt de sistema insuficiente ou alterado sem teste | Rever o prompt, reforçar instruções e rodar testes automatizados | Prompt de sistema versionado: o coração do agente confiável |
| Dados sensíveis aparecem na resposta | Mistura de contexto dinâmico no prompt de sistema | Separar contexto do prompt e revisar fluxo de dados | Prompt de sistema versionado: o coração do agente confiável |
| Não é possível saber qual prompt gerou uma resposta | Falta de versionamento ou registro de versão | Implementar log de versão do prompt em cada sessão | Prompt de sistema versionado: o coração do agente confiável |
| O agente responde fora do escopo definido | Prompt de sistema vago ou instruções conflitantes | Revise o prompt para remover ambiguidades e alinhar as regras | Prompt de sistema versionado: papel, regras, formato e exemp |
| Mudanças no prompt não têm efeito | Arquivo de prompt não atualizado no ambiente de produção | Garanta que a versão correta do prompt está sendo usada e versionada | Prompt de sistema versionado: papel, regras, formato e exemp |
| Respostas inconsistentes entre sessões | Prompt de sistema não está sendo enviado corretamente em todas as requisições | Confirme no código ou console que o campo system está preenchido e separado do usuário | Prompt de sistema versionado: papel, regras, formato e exemp |
| O agente responde fora do formato esperado | Prompt não especifica claramente o formato de saída | Inclua instrução explícita de formato JSON no prompt. | Prompt de sistema versionado: preparando o agente para produ |
| Mudança no prompt causa erro em produção | Alteração não testada ou não versionada | Implemente testes automatizados e versionamento rigoroso. | Prompt de sistema versionado: preparando o agente para produ |
| Dados pessoais aparecem na resposta | Prompt ou entrada inclui campos sensíveis desnecessários | Revisar e remover campos não essenciais, conforme LGPD. | Prompt de sistema versionado: preparando o agente para produ |
| O agente responde de forma inconsistente após atualização | Prompt de sistema não versionado ou mudanças não rastreadas | Implemente versionamento e registre a versão usada em cada execução | Prompt de sistema, ferramentas e casos de teste: a base de u |
| Erros inesperados ao chamar ferramentas externas | Contrato de input/output mal definido ou não validado | Defina e valide contratos com Pydantic ou JSON Schema | Prompt de sistema, ferramentas e casos de teste: a base de u |
| Testes automatizados não detectam falhas | Cobertura de casos de teste insuficiente | Amplie os casos de teste para cobrir todos os fluxos críticos | Prompt de sistema, ferramentas e casos de teste: a base de u |
| O agente responde diferente para a mesma entrada após uma alteração | Prompt carregado de versão errada ou não versionado | Confirme o versionamento e carregamento correto do prompt | Prompt engineering avançado: versionamento, testes e adaptaç |
| Testes automatizados falham após atualizar o prompt | Mudança de instrução quebrou compatibilidade com casos de teste | Revise os casos de teste e ajuste o prompt ou os testes | Prompt engineering avançado: versionamento, testes e adaptaç |
| Respostas lentas ou custo elevado | Prompt caching não implementado ou ineficiente | Implemente ou otimize o cache de prompt e contexto | Prompt engineering avançado: versionamento, testes e adaptaç |
| O agente toma decisões financeiras sem aprovação. | Limite não está explícito ou não foi implementado no prompt. | Reescreva o prompt deixando claro que decisões financeiras exigem aprovação humana. | Prompt engineering para negócios: clareza, limites e manuten |
| O agente responde fora do escopo do negócio. | Faltam regras de negócio ou limites claros no prompt. | Inclua regras e exemplos específicos no prompt. | Prompt engineering para negócios: clareza, limites e manuten |
| Não é possível saber qual versão do prompt está em uso. | Cabeçalho de versionamento ausente. | Adicione versão, data e responsável técnico no início do prompt. | Prompt engineering para negócios: clareza, limites e manuten |
| O agente responde de forma inesperada após atualização de prompt. | Prompt novo não foi validado ou contém erro lógico. | Reverta para a versão anterior e revise o prompt. | Prompt versionado e contratos de ferramenta: configuração qu |
| Ferramenta retorna erro de parâmetro inválido. | Contrato da ferramenta não está claro ou não valida entradas. | Adicione validação de parâmetros e atualize a documentação. | Prompt versionado e contratos de ferramenta: configuração qu |
| Não é possível identificar qual prompt gerou uma resposta. | Falta de versionamento ou rastreio de prompts. | Implemente versionamento e registre a versão usada em cada execução. | Prompt versionado e contratos de ferramenta: configuração qu |
| O agente executa ações inesperadas após atualização do prompt. | Prompt não versionado ou alteração não registrada. | Implemente versionamento obrigatório e audite o histórico de commits. | Prompt versionado, ferramentas e avaliação: o método para op |
| Ferramenta lança exceção não documentada. | Contrato da ferramenta incompleto ou desatualizado. | Atualize docstrings e casos de teste para cobrir todas as exceções. | Prompt versionado, ferramentas e avaliação: o método para op |
| Dados sensíveis aparecem na saída do agente. | Guardrails de saída ausentes ou mal configurados. | Implemente validadores robustos para filtrar informações confidenciais. | Prompt versionado, ferramentas e avaliação: o método para op |
| O agente gera campanhas com dados irreais em produção | Dados de teste misturados com produção | Revisar diretórios e variáveis de ambiente para garantir separação. | Prompt, ferramenta e dados: padrões que evitam erro e retrab |
| Erro de validação ao chamar ferramenta | Contrato de entrada ou saída não seguido | Corrigir tipos e parâmetros para bater com o modelo Pydantic. | Prompt, ferramenta e dados: padrões que evitam erro e retrab |
| Prompt usado não corresponde ao resultado esperado | Prompt desatualizado ou sem versão registrada | Registrar e carregar sempre o prompt versionado correto. | Prompt, ferramenta e dados: padrões que evitam erro e retrab |
| O agente toma decisões inconsistentes após uma alteração de prompt. | Prompt não versionado ou alteração sem rastreio. | Implemente versionamento e registre cada mudança do prompt. | Prompt, ferramenta e teste: o tripé da confiabilidade no age |
| Função chamada com parâmetros errados ou tipos incompatíveis. | Contrato da ferramenta mal definido ou não seguido. | Documente e valide tipos e parâmetros em cada ferramenta. | Prompt, ferramenta e teste: o tripé da confiabilidade no age |
| Mudança em ferramenta ou prompt quebra o fluxo sem aviso. | Falta de testes automatizados cobrindo cenários críticos. | Implemente testes automatizados para cada cenário relevante. | Prompt, ferramenta e teste: o tripé da confiabilidade no age |
| O agente retorna erro ao acionar ferramenta. | Contrato de parâmetros incompatível ou não implementado. | Revise a definição da ferramenta e os tipos de dados esperados. | Prompt, ferramenta, guardrail e MCP: os quatro pilares do ag |
| Guardrail bloqueia toda entrada, mesmo válida. | Regra de validação excessivamente restritiva. | Ajuste a lógica do guardrail para aceitar casos permitidos. | Prompt, ferramenta, guardrail e MCP: os quatro pilares do ag |
| Não aparece registro de execução (trace). | Tracing não ativado ou não implementado no runner. | Implemente ou ative o tracing conforme a biblioteca do agente. | Prompt, ferramenta, guardrail e MCP: os quatro pilares do ag |
| Teste de regressão falha após alteração de prompt | Mudança quebrou um caso de uso já atendido | Reverta a alteração ou ajuste o prompt para restaurar o comportamento esperado | Prompts, skills e ferramentas versionados como código, com t |
| Rollback não funciona | Tag git não existe ou não foi criada | Crie tags de release sempre que fechar versões estáveis | Prompts, skills e ferramentas versionados como código, com t |
| Deploy foi feito mesmo com teste falhando | Pipeline CI/CD não está bloqueando merges em caso de falha | Ajuste o workflow para exigir testes verdes antes do deploy | Prompts, skills e ferramentas versionados como código, com t |
| Conexão recusada ao acessar Elasticsearch via HTTPS | TLS não habilitado ou certificado inválido. | Revise elasticsearch.yml e gere novos certificados. | Proteção de dados sensíveis em pipelines de QA |
| API Haystack responde apenas via HTTP | Proxy reverso não configurado ou escutando na porta errada. | Revise configuração do Nginx e portas. | Proteção de dados sensíveis em pipelines de QA |
| Dados sensíveis aparecem em logs | Anonimização não implementada ou logs não filtrados. | Ajuste scripts de anonimização e rotinas de logging. | Proteção de dados sensíveis em pipelines de QA |
| Chave de API aparece em logs | Código ou biblioteca imprime variáveis de ambiente ou exceções completas | Remova prints e configure logs para omitir variáveis sensíveis | Protegendo dados sensíveis e segredos em produção |
| Agente usa segredos de produção em ambiente de teste | Arquivo .env de produção copiado para teste | Separe arquivos .env e automatize a limpeza de dados | Protegendo dados sensíveis e segredos em produção |
| Logs de tracing não aparecem | Tracing não habilitado ou caminho de armazenamento incorreto | Revise inicialização do tracer e permissões de escrita | Protegendo dados sensíveis e segredos em produção |
| Dados sensíveis aparecem no output do agente | Minimização ou anonimização insuficiente | Revise o pipeline de dados e remova campos críticos antes do envio | Protegendo dados sensíveis: minimização, anonimização e cont |
| Usuário sem permissão acessa dados restritos | Falha na configuração de controle de acesso por papel | Reforce as checagens de papel e revise variáveis de ambiente | Protegendo dados sensíveis: minimização, anonimização e cont |
| Logs não mostram acessos a dados sensíveis | Tracing desativado ou mal configurado | Ative e teste o tracing nos SDKs e no sistema | Protegendo dados sensíveis: minimização, anonimização e cont |
| Erro 401 ao acessar endpoint protegido | Token JWT ausente ou inválido | Verifique se o token foi enviado corretamente e se o segredo bate com o usado para assinar | Protegendo dados: autenticação, autorização e criptografia |
| API responde via HTTP, não HTTPS | Proxy reverso mal configurado ou ausente | Revise a configuração do Nginx e dos certificados TLS | Protegendo dados: autenticação, autorização e criptografia |
| Segredos vazando em logs ou exceptions | Logging excessivo ou falta de sanitização | Nunca logue variáveis de ambiente ou payloads sensíveis | Protegendo dados: autenticação, autorização e criptografia |
| Erro 503 ao acessar endpoint | Gateway não está roteando corretamente para o serviço KServe. | Revise configuração de Gateway e VirtualService. | Protegendo endpoints: TLS, autenticação e Istio Policy |
| Erro 401 Unauthorized mesmo com token | Token JWT inválido ou configuração de issuer/jwksUri incorreta. | Verifique se o issuer e jwksUri correspondem ao provedor de identidade. | Protegendo endpoints: TLS, autenticação e Istio Policy |
| Falha ao criar segredo TLS | Arquivo de certificado ou chave inválido. | Confirme que os arquivos estão corretos e compatíveis com o domínio. | Protegendo endpoints: TLS, autenticação e Istio Policy |
| ImportError ao rodar scripts | Ambiente virtual não ativado ou dependências faltando | Ative o virtualenv e reinstale dependências | Provisionamento prático: ambientes de desenvolvimento e prod |
| Container não sobe | Erro no Dockerfile ou falta de variável obrigatória | Revise o Dockerfile e as variáveis de ambiente | Provisionamento prático: ambientes de desenvolvimento e prod |
| Secrets vazando em logs | Variáveis sensíveis expostas no código ou logs | Use variáveis de ambiente e filtre logs | Provisionamento prático: ambientes de desenvolvimento e prod |
| Latência alta no benchmark | Recursos insuficientes ou gargalo no banco vetorial | Aumente limites de CPU/memória e revise queries | Provisionamento prático: ambientes de desenvolvimento e prod |
| Erro de conexão recusada | Ollama não está rodando ou escutando em outra porta. | Inicie o Ollama e confirme a porta 11434. | Python e Ollama: integrando com API REST |
| Resposta vazia ou campo ausente no JSON | Campo de resposta mudou ou modelo não retornou texto. | Verifique a documentação e ajuste o parser para 'response', 'completion' ou 'text'. | Python e Ollama: integrando com API REST |
| Timeout ao enviar prompt | Modelo pesado ou hardware insuficiente. | Aumente o timeout ou use modelo mais leve. | Python e Ollama: integrando com API REST |
| Respostas vagas ou irrelevantes | Corpus mal indexado ou embeddings genéricos demais | Reindexe os dados e ajuste o modelo com fine-tuning em exemplos reais | QA corporativo em documentos técnicos de telecom |
| Comandos desatualizados nas respostas | Documentação antiga no corpus | Atualize o corpus e reingira os documentos mais recentes | QA corporativo em documentos técnicos de telecom |
| Erro de OCR em PDFs escaneados | OCR padrão falhou em tabelas ou comandos | Use um pipeline de OCR especializado e revise os resultados | QA corporativo em documentos técnicos de telecom |
| Busca retorna sempre os mesmos resultados, independentemente da consulta | Indexação corrompida ou embeddings duplicados | Reindexar a coleção e garantir unicidade dos embeddings | Qdrant e RAG: debugging de busca vetorial e contexto |
| Resultados irrelevantes para perguntas específicas | Embeddings de baixa qualidade ou parâmetros top_k muito altos | Ajustar modelo de embeddings e revisar top_k | Qdrant e RAG: debugging de busca vetorial e contexto |
| Coleção mostra menos pontos do que o esperado | Falha na ingestão ou erro na API de inserção | Reprocessar a carga de dados e monitorar logs | Qdrant e RAG: debugging de busca vetorial e contexto |
| Busca por payload está lenta | Campo não indexado | Crie índice para o campo usado no filtro | Qdrant na prática: coleções, payload e indexing |
| Erro ao inserir ponto | Dimensão do vetor incompatível com a coleção | Verifique o tamanho do vetor e ajuste conforme a configuração da coleção | Qdrant na prática: coleções, payload e indexing |
| Payload não aparece na busca | Payload ausente ou mal formatado | Garanta que o campo 'payload' está presente e em formato JSON válido | Qdrant na prática: coleções, payload e indexing |
| Recebo 502 Bad Gateway ao acessar o proxy | Nginx não consegue conectar ao Qdrant local | Verifique se o Qdrant está rodando em 127.0.0.1:6333 e se o proxy_pass está correto | Qdrant seguro: autenticação, criptografia e permissões |
| Navegador indica certificado inválido | Certificado TLS é self-signed ou não confiável | Use certificado de autoridade reconhecida ou aceite o risco em ambiente de testes | Qdrant seguro: autenticação, criptografia e permissões |
| Autenticação não é solicitada | Bloco auth_basic ausente ou mal configurado no Nginx | Revise a configuração do location e o caminho do .htpasswd | Qdrant seguro: autenticação, criptografia e permissões |
| Logs de acesso não aparecem | Access_log desabilitado ou caminho incorreto | Verifique diretiva access_log no nginx.conf | Qdrant seguro: autenticação, criptografia e permissões |
| O agente encaminha e-mails para o setor errado | Prompt ambíguo ou exemplos insuficientes | Reescrever o prompt e ampliar casos de teste | Quando o agente do administrativo erra: casos de teste, corr |
| Ferramenta retorna erro inesperado | Parâmetros inválidos ou não tratados | Adicionar validação de entrada e saída na ferramenta | Quando o agente do administrativo erra: casos de teste, corr |
| Teste de regressão falha após ajuste | Mudança quebrou lógica anterior | Revisar prompt e restaurar comportamento aprovado | Quando o agente do administrativo erra: casos de teste, corr |
| Agente processa dados pessoais sem autorização | Prompt não restringe casos sensíveis | Adicionar instrução explícita e teste para bloqueio | Quando o agente do administrativo erra: casos de teste, corr |
| Automação não detecta erro já conhecido | Caso de teste ausente ou mal definido | Adicionar o caso ao conjunto de testes | Quando o agente do administrativo erra: casos de teste, corr |
| O agente continua omitindo premissas nos cenários | Prompt de sistema ainda ambíguo ou ferramenta não exige premissas explicitamente | Reforce no prompt a obrigatoriedade e ajuste o contrato da ferramenta | Quando o agente do apoio à decisão executiva erra: casos de |
| Teste automatizado falha após ajuste no prompt | Critério de aprovação do teste não reflete o novo comportamento esperado | Atualize o teste para alinhar com o prompt revisado | Quando o agente do apoio à decisão executiva erra: casos de |
| Resposta do agente muda após atualização de SDK | Mudança no modelo subjacente ou no laço de agente | Revise o prompt e revalide todos os testes; ajuste se necessário | Quando o agente do apoio à decisão executiva erra: casos de |
| Propostas incoerentes ou fora do catálogo | Prompt de sistema incompleto ou ambíguo | Inclua lista explícita de produtos e exemplos negativos no prompt | Quando o agente do comercial e vendas erra: casos de teste, |
| Exceções de parâmetro em ferramenta | Contrato da função não seguido pelo agente | Revise parâmetros obrigatórios e ajuste instruções no prompt | Quando o agente do comercial e vendas erra: casos de teste, |
| Respostas vazias ou travamentos | Erro de integração ou timeout não tratado | Implemente tratamento de erro e instruções para o agente lidar com falhas externas | Quando o agente do comercial e vendas erra: casos de teste, |
| Teste de regressão falha após ajuste | Correção quebrou outro fluxo | Revise a abrangência do prompt e dos testes; ajuste para cobrir todos os casos | Quando o agente do comercial e vendas erra: casos de teste, |
| O agente volta a errar um lançamento já corrigido | Prompt não cobre o caso ou teste de regressão não foi atualizado | Inclua o caso no teste de regressão e ajuste o prompt | Quando o agente do contabilidade erra: casos de teste, corre |
| Testes passam localmente, mas falham em produção | Ambientes divergentes ou dados de teste desatualizados | Sincronize ambientes e atualize os dados de teste | Quando o agente do contabilidade erra: casos de teste, corre |
| Prompt ajustado gera erro em outros lançamentos | Regra específica demais ou ambígua | Generalize a regra e amplie os testes | Quando o agente do contabilidade erra: casos de teste, corre |
| O agente retorna setores errados mesmo após ajuste do prompt. | Prompt ainda ambíguo ou ferramenta sem filtro adequado. | Reforce a restrição no prompt e revise o contrato da ferramenta. | Quando o agente do desenvolvimento de negócios erra: casos d |
| Testes de regressão falham após ajuste. | Correção quebrou comportamento anterior. | Revise o ajuste, refine o prompt e revalide todos os casos. | Quando o agente do desenvolvimento de negócios erra: casos d |
| Tracing não mostra detalhes suficientes. | Tracing desativado ou configuração mínima. | Ative tracing detalhado no SDK e salve os logs para análise. | Quando o agente do desenvolvimento de negócios erra: casos d |
| O agente ignora uma exceção de mercado | Prompt de sistema não cobre o cenário | Revisar e ampliar o prompt, versionando a mudança | Quando o agente do estratégia erra: casos de teste, correção |
| Resposta do agente não bate com o esperado no teste | Contrato da ferramenta mudou sem atualizar o teste | Atualizar casos de teste e documentação da ferramenta | Quando o agente do estratégia erra: casos de teste, correção |
| Erro de execução ou resposta vazia | Falha na chamada de API ou parâmetro ausente | Verificar logs detalhados e corrigir parâmetros | Quando o agente do estratégia erra: casos de teste, correção |
| O agente retorna valores errados em campos fiscais | Prompt ambíguo ou ferramenta com contrato mal definido | Reescreva o prompt explicitando cada campo e revise a definição da ferramenta | Quando o agente do fiscal erra: casos de teste, correção do |
| Testes de regressão falham após ajuste | Correção introduziu novo bug ou quebrou funcionalidade antiga | Analise o diff dos testes e ajuste o prompt ou a ferramenta para cobrir todos os casos | Quando o agente do fiscal erra: casos de teste, correção do |
| Logs não mostram detalhes suficientes | Tracing não habilitado ou logs configurados em nível insuficiente | Ative tracing detalhado no SDK e aumente o nível de log | Quando o agente do fiscal erra: casos de teste, correção do |
| O agente ignora exceções fiscais em datas específicas | Prompt ou ferramenta não consideram regras de calendário | Inclua lógica de exceção no prompt e nos testes automatizados | Quando o agente do fiscal erra: casos de teste, correção do |
| Saída inesperada do agente | Prompt ambíguo ou contrato de ferramenta inconsistente | Reescreva o prompt e esclareça o contrato da ferramenta. | Quando o agente do gestão de equipes e operações erra: casos |
| Erro ao chamar ferramenta | Parâmetros inválidos ou tipo de retorno incorreto | Valide parâmetros e ajuste o tipo de retorno para o esperado. | Quando o agente do gestão de equipes e operações erra: casos |
| Regressão após correção | Caso de teste faltando ou não atualizado | Inclua novo caso de teste e reexecute toda a suíte. | Quando o agente do gestão de equipes e operações erra: casos |
| Logs incompletos | Tracing desativado ou configuração insuficiente | Ative tracing e aumente o nível de detalhamento dos logs. | Quando o agente do gestão de equipes e operações erra: casos |
| O agente omite cláusulas importantes em contratos conhecidos | Prompt de sistema vago ou ferramenta de extração mal definida | Reescrever o prompt com instruções mais específicas e revisar o contrato da ferramenta | Quando o agente do jurídico erra: casos de teste, correção d |
| Respostas inconsistentes para o mesmo caso de teste | Modelo LLM com temperatura alta ou prompt ambíguo | Reduzir aleatoriedade e explicitar exemplos de resposta no prompt | Quando o agente do jurídico erra: casos de teste, correção d |
| Testes de regressão que já passaram começam a falhar | Mudança recente de prompt, ferramenta ou modelo | Reverter alteração ou corrigir até todos os testes passarem | Quando o agente do jurídico erra: casos de teste, correção d |
| Logs incompletos ou ausentes | Tracing não implementado ou falha de configuração | Ativar tracing no SDK e garantir persistência dos registros | Quando o agente do jurídico erra: casos de teste, correção d |
| Texto gerado não segue o tom do briefing | Prompt de sistema ambíguo ou genérico | Reescreva o prompt especificando tom e exemplos claros | Quando o agente do marketing erra: casos de teste, correção |
| Respostas vazias ou genéricas | Falta de critérios de aprovação no prompt ou nos testes | Inclua critérios explícitos e exemplos no prompt e nos testes | Quando o agente do marketing erra: casos de teste, correção |
| Erro reaparece após ajuste | Regressão não executada em todos os casos de teste | Automatize a regressão e rode todos os testes a cada alteração | Quando o agente do marketing erra: casos de teste, correção |
| O agente classifica alertas graves como normais | Prompt ambíguo ou critérios de severidade mal definidos | Refinar o prompt e incluir exemplos claros de cada nível | Quando o agente do NOC (centro de operações de rede) erra: c |
| Erro ao executar runbook | Contrato da ferramenta mudou ou parâmetro ausente | Atualizar definição da ferramenta e revisar testes | Quando o agente do NOC (centro de operações de rede) erra: c |
| Testes de regressão falham após ajuste | Prompt novo quebrou casos antigos | Reverter prompt ou corrigir lógica | Quando o agente do NOC (centro de operações de rede) erra: c |
| O agente não pede detalhamento de metas vagas | Prompt de sistema insuficiente | Reforçar no prompt a exigência de detalhamento | Quando o agente do planejamento erra: casos de teste, correç |
| Datas em formato errado | Prompt ou ferramenta não especifica padrão | Incluir no prompt: datas sempre em AAAA-MM-DD | Quando o agente do planejamento erra: casos de teste, correç |
| Saldo de orçamento calculado errado | Falta de teste com premissas fictícias | Adicionar casos de teste com valores EXEMPLO e validar cálculo | Quando o agente do planejamento erra: casos de teste, correç |
| Resposta sem justificativa | Prompt não exige explicação | Ajustar prompt para exigir justificativa em cada resposta | Quando o agente do planejamento erra: casos de teste, correç |
| O agente retorna valor incorreto para férias | Prompt incompleto ou ferramenta sem parâmetro de desconto | Revisar e ajustar o prompt e a definição da ferramenta | Quando o agente do RH (DP, folha e benefícios) erra: casos d |
| Teste de regressão falha após ajuste | Correção criou efeito colateral em outro fluxo | Rever a lógica e ampliar cobertura dos testes | Quando o agente do RH (DP, folha e benefícios) erra: casos d |
| Resultado do agente não é rastreável | Falta de versionamento ou registro de mudanças | Implementar controle de versão e changelog detalhado | Quando o agente do RH (DP, folha e benefícios) erra: casos d |
| O agente aprova candidatos que não cumprem critérios | Prompt ambíguo ou critérios mal definidos | Reescreva o prompt para explicitar todos os requisitos obrigatórios | Quando o agente do RH (R&S, T&D e PDC) erra: casos de teste, |
| Mudança no prompt faz casos antigos falharem | Regressão não detectada | Automatize a execução de todos os testes após cada ajuste | Quando o agente do RH (R&S, T&D e PDC) erra: casos de teste, |
| Respostas inconsistentes entre execuções | Dados de entrada não controlados ou prompt com exemplos conflitantes | Padronize os dados de teste e revise os exemplos do prompt | Quando o agente do RH (R&S, T&D e PDC) erra: casos de teste, |
| Agente sugere regime fora dos disponíveis | Prompt não restringe a escolha ou guardrail ausente | Adicione instrução clara no prompt e valide saída | Quando o agente do tributário erra: casos de teste, correção |
| Justificativa sem fonte legal | Prompt não exige citação de legislação ou ferramenta não retorna fonte | Ajuste prompt e revise retorno da ferramenta | Quando o agente do tributário erra: casos de teste, correção |
| Respostas inconsistentes entre execuções | Prompt ambíguo ou parâmetros variáveis | Torne o prompt determinístico e fixe dados de entrada | Quando o agente do tributário erra: casos de teste, correção |
| Erro ao chamar ferramenta | Contrato da função mal definido ou parâmetros errados | Reescreva assinatura e instrução de uso no prompt | Quando o agente do tributário erra: casos de teste, correção |
| O agente repete a mesma ação indefinidamente | Critério de parada ausente ou mal definido no prompt | Adicione limite de iteração e critério de sucesso explícito | Quando o agente entra em loop, alucina ferramenta ou ignora |
| Erro de ferramenta não encontrada | Nome de ferramenta não registrado ou divergente entre prompt e código | Alinhe nomes e registre todas as ferramentas corretamente | Quando o agente entra em loop, alucina ferramenta ou ignora |
| Resposta fora do formato esperado | Falta de guardrails de saída ou prompt ambíguo | Implemente validação de saída e ajuste o prompt | Quando o agente entra em loop, alucina ferramenta ou ignora |
| Agente ignora restrição explícita | Regra mal especificada ou não reforçada por validação | Reforce a regra no prompt e adicione validação automática | Quando o agente entra em loop, alucina ferramenta ou ignora |
| Respostas truncadas ou incompletas | Excesso de tokens de entrada ou saída, ultrapassando o limite do modelo | Reduza o tamanho dos prompts ou divida em lotes menores | Quantos agentes, quais modelos: escolhendo Claude, OpenAI e |
| Fila de requisições crescendo | Modelo escolhido é lento para o volume de tarefas | Troque para modelo mais rápido ou distribua a carga entre múltiplos agentes | Quantos agentes, quais modelos: escolhendo Claude, OpenAI e |
| Erros de autenticação na API | Chave de API inválida ou mal configurada | Revise as variáveis de ambiente e permissões | Quantos agentes, quais modelos: escolhendo Claude, OpenAI e |
| E-mails acumulando sem resposta | Número de agentes insuficiente ou processamento lento | Aumente o número de instâncias e otimize o prompt ou ferramentas | Quantos agentes, quantas tarefas: dimensionando para o admin |
| Erros de contexto ou tokens excedidos | Documentos ou lotes maiores que o limite do modelo | Divida os documentos em partes menores antes de enviar | Quantos agentes, quantas tarefas: dimensionando para o admin |
| Agentes ociosos em horários de pico | Distribuição desigual de tarefas | Ajuste o balanceamento para dividir melhor os lotes | Quantos agentes, quantas tarefas: dimensionando para o admin |
| LLM responde sem contexto ou inventa dados | Prompt não está incluindo o contexto corretamente | Verifique a montagem do prompt e se os textos buscados estão sendo concatenados | RAG ponta a ponta: conectando Qdrant, embeddings e LLM |
| Qdrant não retorna resultados relevantes | Embeddings de baixa qualidade ou coleção com configuração errada | Confirme o modelo de embeddings e o parâmetro 'size' da coleção | RAG ponta a ponta: conectando Qdrant, embeddings e LLM |
| Erro de conexão com Qdrant | Serviço não iniciado ou porta errada | Cheque se o container está rodando e as portas estão corretas | RAG ponta a ponta: conectando Qdrant, embeddings e LLM |
| O agente gera textos genéricos, sem citar campanhas reais. | As ferramentas de consulta não estão registradas ou o prompt não exige uso do contexto. | Reveja o registro das ferramentas e o prompt de sistema. | RAG, base de conhecimento e segmentação: IA com contexto rea |
| O agente retorna dados pessoais sem autorização. | Falta de validação legal ou ausência de guardrails. | Implemente guardrails e revise o prompt para proibir uso indevido de dados. | RAG, base de conhecimento e segmentação: IA com contexto rea |
| Segmentação retorna lista vazia. | Critério de busca não existe na base ou erro de parâmetro. | Valide os parâmetros e revise os dados de teste. | RAG, base de conhecimento e segmentação: IA com contexto rea |
| Ação crítica não aparece no log | Configuração de logging ausente ou nível de log inadequado | Ajuste o nível para INFO ou DEBUG e revise o código de logging | Rastreabilidade e revisão: logs, auditoria e reversão de açõ |
| Reversão não restaura dados corretamente | Snapshot dos dados anterior ausente ou corrompido | Implemente backup obrigatório antes de qualquer alteração crítica | Rastreabilidade e revisão: logs, auditoria e reversão de açõ |
| Aprovação humana não é exigida em ações críticas | Hooks ou handoffs não configurados corretamente no SDK | Implemente validação obrigatória de aprovação antes da execução | Rastreabilidade e revisão: logs, auditoria e reversão de açõ |
| Não há registro do prompt usado durante o incidente | Tracing não ativado ou logs não persistidos | Ative o tracing e garanta persistência dos logs em disco | Rastreamento, rollback e auditoria: aprendendo com erros em |
| Rollback não reverte o comportamento do agente | Prompt ou código não estavam versionados corretamente | Implemente versionamento obrigatório de todos os artefatos | Rastreamento, rollback e auditoria: aprendendo com erros em |
| Erro reincidente após rollback | Causa raiz não identificada ou rollback parcial | Audite todo o fluxo, incluindo dependências externas e testes | Rastreamento, rollback e auditoria: aprendendo com erros em |
| Registro de decisão não aparece no sistema | Erro na integração da função de registro ou falta de permissão de escrita | Verifique logs da função e permissões do armazenamento | Recomendação com registro e revisão: agente que sugere, huma |
| Agente executa ação sem aprovação humana | Prompt de sistema mal definido ou lógica de fluxo incorreta | Reforce no prompt e revise o código para exigir decisão explícita | Recomendação com registro e revisão: agente que sugere, huma |
| Campos obrigatórios ausentes no registro | Validação insuficiente na função de registro | Implemente checagem de campos antes de gravar | Recomendação com registro e revisão: agente que sugere, huma |
| Fallback não aciona | Agente alternativo não está corretamente configurado ou não recebe o contexto necessário | Revise a configuração dos agentes e garanta que o contexto é repassado. | Recuperação e fallback: mantendo operação mesmo sob falhas |
| Retentativas infinitas | Falta de limite no loop de retentativa | Implemente contador de tentativas e backoff exponencial. | Recuperação e fallback: mantendo operação mesmo sob falhas |
| Notificação não chega | Hook de notificação não acionado ou erro de configuração no canal | Teste o canal isoladamente e revise o código do hook. | Recuperação e fallback: mantendo operação mesmo sob falhas |
| Logs incompletos | Tracing desativado ou mal configurado | Ative tracing no SDK e verifique permissões de gravação. | Recuperação e fallback: mantendo operação mesmo sob falhas |
| O agente sugere uma decisão fiscal sem pedir revisão | Prompt de sistema mal definido ou ausência de guardrail | Reforce o prompt e implemente validação obrigatória | Regimes fiscais, consultas e simulações: o que é automatizáv |
| Resultado divergente do esperado em simulação | Premissas inconsistentes ou dados de teste errados | Revise os casos de teste e ajuste as premissas | Regimes fiscais, consultas e simulações: o que é automatizáv |
| Faltam registros de fonte consultada | Prompt não exige citação de fonte | Inclua no prompt a obrigação de citar fonte oficial | Regimes fiscais, consultas e simulações: o que é automatizáv |
| Decisões não aparecem no log | Tracing não ativado ou sessão não registrada | Revisar configuração do tracer e garantir uso consistente do session_id | Registro, tracing e revisão: como garantir que a decisão é a |
| Fluxos multiagente com registros desconectados | Falta de identificador único de sessão | Gerar e propagar session_id em todas as chamadas | Registro, tracing e revisão: como garantir que a decisão é a |
| Revisão humana não registrada | Handoff não implementado ou bypassado | Forçar pausa e registro obrigatório antes de prosseguir | Registro, tracing e revisão: como garantir que a decisão é a |
| Logs não aparecem no arquivo esperado | Caminho de log incorreto ou permissões insuficientes | Verifique o parâmetro log_path e permissões de escrita no diretório | Registro, tracing e revisão: operando o agente sob supervisã |
| Eventos críticos não têm status de revisão | Fluxo de revisão não implementado ou bypassado | Garanta que todas as ações irreversíveis passem pelo status 'pending_review' antes da execução | Registro, tracing e revisão: operando o agente sob supervisã |
| Logs não são legíveis ou pesquisáveis | Formato não estruturado (texto livre) | Adote JSONL e defina campos obrigatórios para cada evento | Registro, tracing e revisão: operando o agente sob supervisã |
| Resposta 401 Unauthorized | Chave de API inválida ou ausente | Verifique se a variável de ambiente está correta e se a chave não expirou | Requests, respostas e contratos: a base de toda integração d |
| Resposta 400 ou erro de versão | Header anthropic-version ausente ou incorreto (Anthropic) | Adicione ou corrija o header anthropic-version para o valor suportado | Requests, respostas e contratos: a base de toda integração d |
| Erro de validação Pydantic ao receber resposta | Estrutura da resposta mudou ou contrato local está desatualizado | Atualize o modelo Pydantic conforme a resposta real da API | Requests, respostas e contratos: a base de toda integração d |
| Solicitação fica travada sem resposta | Timeout não configurado ou não tratado | Defina e trate timeouts em todas as chamadas de agente | Resiliência e fallback: o que fazer quando o agente não resp |
| Falha não registrada nos logs | Bloco try/except ausente ou log mal configurado | Adicione logging detalhado em todos os pontos de falha | Resiliência e fallback: o que fazer quando o agente não resp |
| Fallback não aciona humano | Lógica de fallback ausente ou erro no notificador | Implemente e teste o fluxo de notificação manual | Resiliência e fallback: o que fazer quando o agente não resp |
| Alertas não chegam aos responsáveis | Configuração de alerta incorreta | Revise integração com e-mail ou webhook | Resiliência e fallback: o que fazer quando o agente não resp |
| Erro 'Index not trained' no FAISS | Índice criado sem chamar train() | Chame index.train(vetores) antes de adicionar vetores | Resolução de erros em bancos vetoriais e modelos |
| index_not_found_exception no Elasticsearch | Índice não existe ou foi deletado | Crie o índice com o mapeamento correto antes de indexar | Resolução de erros em bancos vetoriais e modelos |
| Busca retorna resultados inconsistentes após atualização de modelo | Modelo novo incompatível ou mal treinado | Faça rollback para o modelo anterior e valide os dados | Resolução de erros em bancos vetoriais e modelos |
| O agente ignora comandos válidos | Função não foi exposta como ferramenta no LangChain | Adicione a função à lista de ferramentas do agente | Respostas automáticas e agentes: scripts que agem com LLM |
| Logs não aparecem | Função de logging não está sendo chamada ou arquivo sem permissão de escrita | Verifique permissões e chamadas de log_acao | Respostas automáticas e agentes: scripts que agem com LLM |
| Ollama não responde | Modelo não carregado ou serviço não iniciado | Execute 'ollama run modelo' e confira o status | Respostas automáticas e agentes: scripts que agem com LLM |
| Agente executa comandos perigosos | Funções inseguras expostas ao LLM | Restrinja as funções disponíveis e revise o código | Respostas automáticas e agentes: scripts que agem com LLM |
| O agente marca todas as cláusulas como críticas. | Prompt excessivamente restritivo ou genérico. | Ajuste o prompt para especificar critérios objetivos de risco. | Revisão automatizada de contratos: estudo de caso com agente |
| Ferramenta BuscarClausulaModelo retorna vazio. | Base de cláusulas modelo não configurada ou parâmetro incorreto. | Verifique a implementação da ferramenta e os dados de entrada. | Revisão automatizada de contratos: estudo de caso com agente |
| Logs de execução ausentes. | Tracing não habilitado no SDK ou falha de permissão no diretório de logs. | Habilite tracing e ajuste permissões do ambiente. | Revisão automatizada de contratos: estudo de caso com agente |
| Avaliação do revisor sempre aprova ou reprova tudo | Critérios de avaliação mal definidos ou prompt genérico demais | Refine e versiona os prompts, incluindo exemplos positivos e negativos | Revisão automatizada: agentes avaliando agentes |
| Logs de avaliação não aparecem no tracing | Falha na configuração do logger ou permissão de escrita | Verifique o caminho do log e permissões do sistema | Revisão automatizada: agentes avaliando agentes |
| Revisor não detecta erros óbvios | Casos de teste insuficientes ou input fora do escopo | Amplie os casos de teste e revise o prompt do revisor | Revisão automatizada: agentes avaliando agentes |
| Erros continuam aparecendo mesmo após ajustes no prompt. | Casos de teste insuficientes ou ajuste não cobre todas as variações. | Amplie os casos de teste e revise exemplos reais nos logs. | Revisão contínua: aprendendo com erros e evoluindo o agente |
| Logs de tracing não registram execuções. | Tracing não habilitado corretamente ou falta de permissão de escrita. | Verifique o comando de ativação e permissões do diretório de logs. | Revisão contínua: aprendendo com erros e evoluindo o agente |
| Mudanças no agente causam falhas em rotinas antes estáveis. | Ajuste no prompt ou ferramenta afetou outros fluxos. | Implemente casos de teste de regressão antes de liberar ajustes. | Revisão contínua: aprendendo com erros e evoluindo o agente |
| Testes de regressão sempre falham após atualização do prompt | Prompt incompatível com contratos das ferramentas | Revise o prompt para garantir aderência ao contrato e atualize os testes se necessário | Revisão contínua: como aprender com o agente em produção |
| Incidentes recorrentes não são detectados | Falta de registro estruturado ou análise periódica | Implemente rotina de documentação e revisão semanal dos incidentes | Revisão contínua: como aprender com o agente em produção |
| Métricas não refletem a realidade | Logs incompletos ou coleta inconsistente | Garanta logging detalhado e automatize extração de métricas | Revisão contínua: como aprender com o agente em produção |
| Usuários não reportam problemas | Canal de feedback pouco acessível ou ignorado | Facilite o acesso ao canal e incentive o reporte após cada interação | Revisão contínua: como aprender com o agente em produção |
| O agente voltou a errar no mesmo cenário | Correção incompleta ou teste automatizado insuficiente | Revise o caso de teste e amplie a cobertura. | Revisão contínua: como aprender com o erro e evoluir o agent |
| Mudança corrigiu um erro, mas quebrou outro fluxo | Regressão por falta de testes antigos | Inclua todos os casos antigos nos testes automatizados. | Revisão contínua: como aprender com o erro e evoluir o agent |
| Feedback humano não é incorporado | Falta de processo estruturado para coletar e priorizar feedback | Implemente formulário padrão e análise periódica dos dados. | Revisão contínua: como aprender com o erro e evoluir o agent |
| O agente começa a dar respostas genéricas ou evasivas | Prompt desatualizado ou ferramenta sem contrato claro | Revise o prompt, atualize contratos e exemplos de uso | Revisão contínua: como identificar e corrigir desvios do age |
| Erros recorrentes em campos fiscais específicos | Mudança no layout da nota ou regra fiscal não refletida no agente | Atualize o prompt e as ferramentas conforme a nova regra | Revisão contínua: como identificar e corrigir desvios do age |
| Testes automatizados que passavam começam a falhar | Ajuste recente introduziu regressão | Reverta para a versão anterior e aplique o ajuste de forma incremental | Revisão contínua: como identificar e corrigir desvios do age |
| A API aceita dados inesperados e retorna erro do modelo | Contrato Pydantic frouxo ou não validando corretamente | Reforce os tipos e limites no modelo Pydantic e revise os testes | Revisão de código, prompts e contratos: não confie só na IA |
| Prompt gera respostas fora do escopo | Prompt ambíguo ou não revisado | Reescreva o prompt, peça revisão cruzada e teste com casos adversos | Revisão de código, prompts e contratos: não confie só na IA |
| Mudança de prompt não foi rastreada | Falta de versionamento e documentação | Versione os arquivos de prompt e registre mudanças no CHANGELOG | Revisão de código, prompts e contratos: não confie só na IA |
| A IA executa lançamentos sem revisão humana. | Falta de checagem de aprovação antes da ação. | Implemente bloqueio obrigatório e revise o fluxo. | Revisão humana e aprendizado contínuo: o ciclo virtuoso do a |
| Feedbacks dos usuários não aparecem nos logs. | Registro de feedback mal implementado. | Ajuste o código para capturar e armazenar feedbacks. | Revisão humana e aprendizado contínuo: o ciclo virtuoso do a |
| Mudanças no prompt não melhoram o agente. | Prompt não está versionado ou testes não cobrem o caso. | Versione o prompt e amplie os casos de teste. | Revisão humana e aprendizado contínuo: o ciclo virtuoso do a |
| Incidentes recorrentes sem ajuste visível | Falta de revisão ou documentação dos ajustes | Implantar rotina obrigatória de revisão e atualização de changelog | Revisão humana e melhoria contínua: ciclo virtuoso no NOC au |
| Ajustes em prompt não refletem no comportamento do agente | Versão antiga do prompt ainda em uso | Verificar deploy e versionamento dos arquivos de prompt | Revisão humana e melhoria contínua: ciclo virtuoso no NOC au |
| Feedback humano não é registrado | Falta de interface ou processo definido para coleta de feedback | Implementar formulário ou integração com sistema de tickets | Revisão humana e melhoria contínua: ciclo virtuoso no NOC au |
| Ação crítica executada sem aprovação | Falta de bloqueio no workflow ou erro na verificação de aprovação | Revise o código do agente para exigir aprovação antes da execução | Revisão humana e registro: quando e como supervisionar o age |
| Registros incompletos ou ausentes | Hooks ou tracing não configurados corretamente | Implemente e teste hooks/tracing para todas as execuções | Revisão humana e registro: quando e como supervisionar o age |
| Dificuldade em auditar execuções passadas | Ausência de identificadores únicos ou logs imutáveis | Inclua IDs únicos e use logs versionados/impossíveis de editar | Revisão humana e registro: quando e como supervisionar o age |
| Casos críticos não aparecem na fila de revisão | Critérios de triagem automática mal configurados | Revise as regras e aumente a sensibilidade dos filtros | Revisão humana em escala: triagem, aprovação e feedback |
| Decisões de revisão não estão registradas | Falta de logging ou erro na gravação | Implemente logs obrigatórios e revise permissões de escrita | Revisão humana em escala: triagem, aprovação e feedback |
| Feedback não gera melhoria nos agentes | Ciclo de feedback não está integrado ao ajuste de prompts ou testes | Automatize a coleta e revisão periódica do feedback | Revisão humana em escala: triagem, aprovação e feedback |
| A IA executa ação crítica sem revisão | Falta de checagem de status ou má configuração do fluxo | Revise a lógica de sinalização e bloqueio de ações automáticas | Revisão humana: limites da IA e papel do operador |
| Revisões não aparecem no log | Erro na configuração do logger ou falta de chamada de logging | Confirme o caminho do arquivo e as permissões de escrita | Revisão humana: limites da IA e papel do operador |
| Operador não consegue editar respostas | Painel de revisão não implementa edição | Adicione interface para editar e reenviar respostas antes da execução | Revisão humana: limites da IA e papel do operador |
| O agente executa comandos não permitidos | Limites de comandos ou caminhos não configurados corretamente | Revise a configuração das ferramentas e restrinja permissões | Riscos operacionais: o que pode dar errado com agentes no NO |
| Dados pessoais aparecem em logs ou respostas | Prompt de sistema ou guardrails insuficientes | Ajuste o prompt e implemente validadores de saída | Riscos operacionais: o que pode dar errado com agentes no NO |
| Ações críticas são executadas sem aprovação | Fallback ou revisão humana não implementados | Inclua etapas de aprovação obrigatória para operações sensíveis | Riscos operacionais: o que pode dar errado com agentes no NO |
| Erro 'out of memory' ao rodar modelo | Modelo grande para a RAM disponível | Escolha modelo menor ou aumente swap | Rodando seu primeiro modelo: prompts, respostas e logs |
| Mensagem 'model not found' | Nome incorreto ou download incompleto | Verifique nome e repita 'ollama pull' | Rodando seu primeiro modelo: prompts, respostas e logs |
| WebUI não abre no navegador | Porta 3000 ocupada ou serviço não iniciado | Mude a porta ou inicie o serviço corretamente | Rodando seu primeiro modelo: prompts, respostas e logs |
| O agente gera respostas fora do padrão | Prompt de sistema mal definido ou falta de guardrails | Revisar o prompt e adicionar validações de saída | Rumo ao comercial autônomo: até onde dá para ir com IA hoje |
| Ações críticas são executadas sem revisão | Falta de bloqueio ou checagem no fluxo | Implementar revisão humana obrigatória antes da execução | Rumo ao comercial autônomo: até onde dá para ir com IA hoje |
| Dados pessoais aparecem sem justificativa | Ausência de filtros ou validação de base legal | Adicionar filtros de dados e checagem de consentimento | Rumo ao comercial autônomo: até onde dá para ir com IA hoje |
| InferenceService não sobe | Erro no storageUri ou permissão no bucket MinIO | Confirme o storageUri e as credenciais de acesso | Rumo ao MLOps completo: integração de KServe com pipelines d |
| Rollout canário não distribui tráfego | Campo canaryTrafficPercent ausente ou mal posicionado | Revise a estrutura do YAML conforme a documentação oficial | Rumo ao MLOps completo: integração de KServe com pipelines d |
| Métricas do modelo não aparecem no Prometheus | ServiceMonitor não configurado ou label incorreta | Ajuste o ServiceMonitor e labels conforme a documentação do Prometheus | Rumo ao MLOps completo: integração de KServe com pipelines d |
| Pods não escalam mesmo com alta carga | Métrica de scaling mal configurada ou provider de métricas indisponível | Verifique annotations, integração do Prometheus e logs do autoscaler | Scaling dinâmico com Knative e métricas customizadas |
| Latência alta mesmo com muitos pods | Cold start frequente ou limitação de storage/back-end | Aumente minScale ou otimize inicialização do modelo | Scaling dinâmico com Knative e métricas customizadas |
| Scaling excessivo e instabilidade | Target muito baixo ou maxScale alto demais | Ajuste target e maxScale conforme perfil de uso | Scaling dinâmico com Knative e métricas customizadas |
| Erro de autenticação ao rodar agente | Variável de ambiente da chave de API não configurada ou valor incorreto | Configure corretamente a variável de ambiente com a chave válida | SDKs em produção: configuração real de Claude, OpenAI, Eleve |
| Logs não são gerados | Diretório de logs não existe ou permissão insuficiente | Crie o diretório logs/ e ajuste permissões de escrita | SDKs em produção: configuração real de Claude, OpenAI, Eleve |
| Chave de API aparece em logs | Payload não mascarado antes do registro | Implemente função para remover ou substituir segredos nos logs | SDKs em produção: configuração real de Claude, OpenAI, Eleve |
| O agente retorna erro de autenticação ao chamar a API | Variável de ambiente com a chave de API não definida ou valor incorreto | Defina corretamente a variável de ambiente antes de iniciar o agente | SDKs em produção: variáveis, segredos e permissões para agen |
| O agente consegue acessar arquivos fora da pasta de dados | Permissões de sistema de arquivos mal configuradas ou ausência de sandbox | Restrinja o acesso do processo e use containers ou VMs | SDKs em produção: variáveis, segredos e permissões para agen |
| Logs mostram tentativas de acesso à internet não autorizadas | Configuração de rede do container ou VM permite saída não controlada | Use --network=none ou regras de firewall para bloquear | SDKs em produção: variáveis, segredos e permissões para agen |
| O script retorna erro de chave ausente | A variável de ambiente não foi definida ou está com nome errado | Defina a variável corretamente antes de rodar o script | Segredos, chaves e variáveis de ambiente: nunca exponha o qu |
| A chave aparece em logs ou prints | Código está imprimindo ou logando o valor do segredo | Remova qualquer print ou log do valor da chave | Segredos, chaves e variáveis de ambiente: nunca exponha o qu |
| Outro usuário acessa a variável de ambiente | Permissões do sistema operacional estão abertas demais | Restrinja permissões do arquivo ou do processo que define a variável | Segredos, chaves e variáveis de ambiente: nunca exponha o qu |
| Segredo aparece em log | Logger não está filtrando ou código imprime variáveis sensíveis | Adicione filtros de log e revise prints e exceptions | Segredos, logs e variáveis: como não vazar dados sensíveis n |
| Arquivo .env acessível a outros usuários | Permissões de arquivo incorretas | Ajuste com chmod 600 e revise o owner | Segredos, logs e variáveis: como não vazar dados sensíveis n |
| Chave antiga ainda válida após rotação | Chave não foi revogada na plataforma | Revogue manualmente e valide o ciclo de rotação | Segredos, logs e variáveis: como não vazar dados sensíveis n |
| O agente retorna erro de autenticação ao iniciar | Variável de ambiente da chave de API não está definida ou está incorreta | Defina a variável correta e reinicie o agente | Segredos, variáveis de ambiente e controle de acesso: operaç |
| Logs mostram chaves de API ou tokens | Código ou configuração permite vazamento de variáveis em logs | Ajuste o logger para mascarar ou omitir variáveis sensíveis | Segredos, variáveis de ambiente e controle de acesso: operaç |
| Outro usuário do sistema consegue ler arquivos do agente | Permissões do diretório estão abertas (755 ou 777) | Ajuste para 700 e revise o dono dos arquivos | Segredos, variáveis de ambiente e controle de acesso: operaç |
| Erro 'KeyError' ao acessar variável de ambiente | Variável não definida ou nome incorreto | Verifique o nome e se o arquivo .env foi carregado corretamente | Segredos, variáveis e permissões: preparando o ambiente do a |
| Logs não aparecem no arquivo esperado | Caminho do arquivo ou permissão incorreta | Ajuste o caminho e permissões do arquivo de log | Segredos, variáveis e permissões: preparando o ambiente do a |
| Agente acessa dados reais em ambiente de teste | Variáveis de ambiente trocadas ou ENV não definido | Garanta que ENV está correto e arquivos .env não estão misturados | Segredos, variáveis e permissões: preparando o ambiente do a |
| Outro usuário consegue ler arquivos de modelo | Permissões dos diretórios ou arquivos estão abertas demais | Ajuste com chmod 700 e chown para o usuário correto | Segurança em LLMs locais: riscos de dados e isolamento |
| Serviço do Ollama não inicia | Usuário dedicado não tem permissão de leitura nos arquivos necessários | Revise permissões e propriedade dos diretórios | Segurança em LLMs locais: riscos de dados e isolamento |
| Socket do Ollama acessível a todos | Permissão do socket está 666 ou 777 | Ajuste para 660 e limite ao grupo autorizado | Segurança em LLMs locais: riscos de dados e isolamento |
| Agente acessa dados não autorizados | Permissões mal configuradas no arquivo de controle ou tools excessivas registradas. | Revise e restrinja as permissões e tools do agente. | Segurança operacional: limites, isolamento e revisão em agen |
| Ação sensível executada sem revisão | Handoff não implementado ou trigger mal definido. | Implemente o handoff e teste os triggers de revisão. | Segurança operacional: limites, isolamento e revisão em agen |
| Logs de auditoria ausentes ou incompletos | Tracing não ativado ou diretório de logs inacessível. | Ative o tracing e verifique permissões do diretório de logs. | Segurança operacional: limites, isolamento e revisão em agen |
| Guardrails não bloqueiam ações inválidas | Validação insuficiente nos parâmetros ou ausência de guardrails. | Implemente validações rigorosas e teste casos de borda. | Segurança operacional: limites, isolamento e revisão em agen |
| Pods reiniciando em loop | Probes configuradas com delays muito curtos ou endpoints incorretos. | Ajuste os parâmetros de initialDelaySeconds e periodSeconds; verifique se os endpoints existem e respondem corretamente. | Self-healing e auto-remediação em serving de IA |
| Escalonamento não ocorre mesmo com alta latência | Métrica Prometheus não configurada corretamente ou query errada. | Revise a configuração do ScaledObject e as queries Prometheus. | Self-healing e auto-remediação em serving de IA |
| Pods não recebem tráfego após restart | Readiness probe nunca retorna sucesso. | Verifique logs do pod e endpoint da probe; corrija o path ou a lógica de readiness. | Self-healing e auto-remediação em serving de IA |
| Erro 401 ou 403 ao chamar a rota | Chave de API inválida ou não configurada | Verifique as variáveis de ambiente e permissões da chave | Serviço interno com FastAPI: uma API de IA para os outros de |
| 422 Unprocessable Entity | Payload fora do contrato Pydantic | Revise os campos obrigatórios e limites definidos em IARequest | Serviço interno com FastAPI: uma API de IA para os outros de |
| Timeout ou resposta vazia | Problema de rede ou modelo não disponível | Confirme conectividade e modelo informado; consulte a documentação do fornecedor | Serviço interno com FastAPI: uma API de IA para os outros de |
| Retorno 401 Unauthorized | Chave de API ausente ou incorreta | Verifique o header x-api-key e a variável de ambiente MCP_API_KEY | Servidor MCP da sua empresa: expondo ERP, CRM e planilhas co |
| Resposta 422 Unprocessable Entity | Parâmetros ausentes ou inválidos no corpo da requisição | Confirme o contrato MCP e envie todos os campos obrigatórios | Servidor MCP da sua empresa: expondo ERP, CRM e planilhas co |
| Dados não atualizam no sistema interno | Erro na integração com API do ERP/CRM/planilha | Revise o código do handler e teste a API interna isoladamente | Servidor MCP da sua empresa: expondo ERP, CRM e planilhas co |
| Logs ausentes ou incompletos | Logging não implementado ou mal configurado | Implemente logging estruturado em cada endpoint | Servidor MCP da sua empresa: expondo ERP, CRM e planilhas co |
| 401 Unauthorized ao chamar o endpoint | Token de autenticação ausente ou incorreto | Verifique se o cabeçalho Authorization está correto e o token bate com o da variável de ambiente | Servidor MCP em poucas linhas: o ERP vira ferramenta de qual |
| Resposta vazia ou erro 422 | Formato do JSON de entrada inválido | Confirme que o corpo da requisição segue o contrato pydantic | Servidor MCP em poucas linhas: o ERP vira ferramenta de qual |
| Agente Claude/OpenAI não reconhece a ferramenta | Contrato MCP ausente ou endpoint fora do padrão | Garanta que o endpoint e o contrato MCP estão publicados conforme a especificação | Servidor MCP em poucas linhas: o ERP vira ferramenta de qual |
| Não recebe eventos em tempo real | Falha na conexão com o endpoint de stream ou headers incorretos | Verifique headers, autenticação e mantenha a conexão aberta | Sessão gerenciada por horas com eventos em stream: fechament |
| Eventos de solicitação de revisão não aparecem | Prompt do agente não exige revisão ou lógica de contagem ausente | Reforce o guardrail no prompt e revise o consumidor de eventos | Sessão gerenciada por horas com eventos em stream: fechament |
| Sessão expira antes do fechamento | Inatividade ou erro de keep-alive | Garanta atividade periódica e monitore o status da sessão | Sessão gerenciada por horas com eventos em stream: fechament |
| Uma fila/shard fica cheia enquanto outras estão vazias | Distribuição desigual de tarefas ou hash mal calibrado | Revise o critério de sharding e balanceamento de carga | Sharding e particionamento: escalando agentes sem caos |
| Agentes processam tarefas duplicadas | Mais de um agente consumindo do mesmo shard sem controle | Garanta que cada agente consuma de um shard exclusivo | Sharding e particionamento: escalando agentes sem caos |
| Latência alta mesmo com muitos agentes | Gargalo de fila única ou saturação de recursos | Implemente particionamento e monitore uso de CPU/memória | Sharding e particionamento: escalando agentes sem caos |
| Processamento travando ou lento | Excesso de shards em paralelo ou fila mal dimensionada | Reduza o número de agentes concorrentes e ajuste o tamanho dos shards | Sharding, paralelismo e filas: escalando o fiscal com agente |
| Resultados inconsistentes entre shards | Estado compartilhado ou ferramentas sem isolamento | Garanta contexto independente para cada agente | Sharding, paralelismo e filas: escalando o fiscal com agente |
| Erros de autenticação nas APIs | Chaves de API não isoladas por agente | Use variáveis de ambiente separadas para cada agente | Sharding, paralelismo e filas: escalando o fiscal com agente |
| Logs incompletos ou ausentes | Falta de registro automático em cada shard | Implemente logging estruturado por shard e agente | Sharding, paralelismo e filas: escalando o fiscal com agente |
| O agente omite premissas no relatório | Prompt de sistema mal definido ou ferramenta não retorna metadados | Reforce a exigência no prompt e ajuste as ferramentas para sempre registrar contexto | Síntese de relatórios: agente que resume dados de múltiplas |
| Dados divergentes entre fontes não são sinalizados | Falta de lógica de detecção de conflito na síntese | Implemente checagem de consistência e obrigue o agente a declarar conflitos | Síntese de relatórios: agente que resume dados de múltiplas |
| Relatório sem seção de incertezas | Prompt não exige explicitamente ou caso de teste não cobre ausência de dados | Inclua teste para dados ausentes e ajuste o prompt para obrigar a seção | Síntese de relatórios: agente que resume dados de múltiplas |
| Propostas divergentes entre agentes | Algum agente está usando skill desatualizada ou alterada. | Atualize todos os agentes para a mesma versão da skill. | Skills: o jeito da empresa escrever propostas, reutilizado p |
| Proposta rejeitada pelo guardrail | Saída não segue o padrão definido no regex. | Revise o template da skill e ajuste os parâmetros de entrada. | Skills: o jeito da empresa escrever propostas, reutilizado p |
| Erro ao importar skill no agente | Nome da skill incorreto ou arquivo ausente. | Verifique o caminho e o nome do arquivo no repositório de skills. | Skills: o jeito da empresa escrever propostas, reutilizado p |
| Histórico de versões inconsistente | Commits manuais sem controle de versão. | Padronize o versionamento e use mensagens de commit claras. | Skills: o jeito da empresa escrever propostas, reutilizado p |
| O vídeo começa diferente da imagem enviada | A imagem de entrada estava com artefatos, baixa qualidade ou elementos conflitantes | Troque por uma imagem limpa, em alta resolução, sem ruídos ou objetos indesejados | Sua foto como primeiro quadro: imagem para vídeo com o movim |
| O movimento não segue o pedido | O prompt descreveu pouco ou contradisse pistas visuais da imagem | Reescreva o pedido focando só no movimento, sem repetir elementos visuais já presentes | Sua foto como primeiro quadro: imagem para vídeo com o movim |
| O vídeo apresenta cortes no meio | A combinação de imagem e prompt pede duração maior ou plano contínuo | Peça um plano contínuo, sem cortes, e aumente a duração se necessário | Sua foto como primeiro quadro: imagem para vídeo com o movim |
| O produto aparece borrado ou distorcido | A imagem de entrada já tinha borrado ou distorção | Use uma imagem original, nítida, sem compressão | Sua foto como primeiro quadro: imagem para vídeo com o movim |
| Uma resposta retorna 'Erro: ...' no dicionário resultados. | Exceção durante a execução do subagente, como timeout ou erro de rede. | Revise o input, aumente o timeout se necessário e verifique logs detalhados do Runner. | Subagentes em paralelo: pesquisa de mercado completa em minu |
| Respostas incompletas ou truncadas. | Limite de tamanho de entrada ou saída excedido. | Reduza o tamanho do prompt ou da resposta esperada e monitore o consumo de tokens. | Subagentes em paralelo: pesquisa de mercado completa em minu |
| Execução demora além do esperado. | Subagentes com tarefas muito longas ou ambiente sobrecarregado. | Ajuste o número de subagentes simultâneos e otimize os prompts para respostas mais objetivas. | Subagentes em paralelo: pesquisa de mercado completa em minu |
| Subagente retorna resultado errado ou incompleto | Prompt ou ferramentas mal configurados | Revise o prompt e as permissões do subagente | Subagentes, handoffs e fluxos paralelos: quando dividir para |
| Handoff não transfere histórico | Contexto não foi passado corretamente | Implemente passagem explícita de contexto e histórico | Subagentes, handoffs e fluxos paralelos: quando dividir para |
| Resultados de subagentes se sobrepõem ou conflitam | Falta de coordenação ou merge de resultados | Implemente lógica de priorização e merge no agente principal | Subagentes, handoffs e fluxos paralelos: quando dividir para |
| Ação crítica foi executada sem aprovação | Guardrail ou handoff não implementado corretamente | Revise o código do handler e os critérios de bloqueio | Supervisão e revisão: bloqueios para decisões legais, fiscai |
| Decisão não aparece no log | Registro não implementado ou falha de escrita | Garanta persistência e proteção do log | Supervisão e revisão: bloqueios para decisões legais, fiscai |
| Responsável não recebe notificação de aprovação | Integração de workflow incompleta | Verifique o canal de comunicação e o disparo do evento | Supervisão e revisão: bloqueios para decisões legais, fiscai |
| O agente ignora ferramentas e responde só com texto. | Prompt de sistema não instrui o uso de ferramentas ou elas não estão registradas corretamente. | Revise as instruções e confira a configuração das ferramentas no SDK. | Tendências e limites: para onde vão Claude, GPT, ElevenLabs |
| Custo de operação muito alto em tarefas longas. | Uso de modelos topo de linha para tarefas simples ou contexto maior que o necessário. | Avalie modelos menores ou reduza o tamanho do contexto enviado. | Tendências e limites: para onde vão Claude, GPT, ElevenLabs |
| Ações irreversíveis executadas sem revisão. | Falta de guardrails ou revisão humana no fluxo do agente. | Implemente obrigatoriedade de aprovação manual antes de ações críticas. | Tendências e limites: para onde vão Claude, GPT, ElevenLabs |
| Busca retorna poucos ou nenhum resultado relevante | Embeddings incompatíveis ou indexação incompleta | Verifique o modelo de embedding e reindexe os documentos | Tendências em bancos vetoriais e pipelines de QA abertos |
| Latência alta nas buscas | Configuração inadequada do índice vetorial ou hardware insuficiente | Ajuste parâmetros do índice (ex: nlist, m) e avalie uso de GPU | Tendências em bancos vetoriais e pipelines de QA abertos |
| Erro de integração entre Haystack e banco vetorial | Mudança de API ou versão incompatível | Consulte a documentação e atualize dependências | Tendências em bancos vetoriais e pipelines de QA abertos |
| Respostas irrelevantes ou genéricas | Indexação incorreta ou embeddings incompatíveis | Reindexe os documentos e valide a função de embedding | Tendências: RAG, integração com modelos open source e novas |
| Erro de conexão com Milvus | Porta ou host incorretos na configuração | Verifique os parâmetros de conexão e se o container está ativo | Tendências: RAG, integração com modelos open source e novas |
| Modelo Llama não carrega | Caminho do arquivo do modelo incorreto ou formato incompatível | Confirme o caminho e baixe o modelo no formato suportado pelo LlamaCpp | Tendências: RAG, integração com modelos open source e novas |
| Teste automatizado falha sem motivo aparente | Diferença sutil entre a saída do agente e a saída esperada (formatação, acento, espaço) | Padronize a comparação (ex: normalize acentos, ignore espaços extras) | Testando e avaliando agentes: casos de teste, métricas e rev |
| Tracing não registra execuções | Tracing não ativado ou mal configurado no SDK | Revise a chamada de enable_tracing() e dependências | Testando e avaliando agentes: casos de teste, métricas e rev |
| Ação irreversível executada sem revisão | Fluxo de aprovação não implementado corretamente | Adicione checkpoint de validação humana antes da execução | Testando e avaliando agentes: casos de teste, métricas e rev |
| Erros 429 (Too Many Requests) | Limite de requisições do modelo ou API atingido | Reduza a taxa de requisições ou implemente backoff exponencial | Testando escalabilidade: casos de carga e avaliação automati |
| Respostas lentas ou truncadas | Prompt grande demais ou ferramenta externa lenta | Reduza o contexto do prompt e otimize chamadas de ferramenta | Testando escalabilidade: casos de carga e avaliação automati |
| Logs incompletos ou ausentes | Falha no registro ou falta de hooks de tracing | Reveja a implementação dos logs e ative tracing nos SDKs | Testando escalabilidade: casos de carga e avaliação automati |
| Latência alta em voz/vídeo | Modelo de TTS/Avatar inadequado para carga | Troque para modelo mais rápido (ex: eleven_flash_v2_5) | Testando escalabilidade: casos de carga e avaliação automati |
| Erros 429 (Too Many Requests) na API | Limite de requisições simultâneas atingido | Reduza a concorrência ou implemente retry com backoff | Testando limites: como simular carga e detectar gargalos no |
| Latência explode acima de 30s em p95 | Gargalo de CPU, RAM ou dependência externa lenta | Otimize código, divida tarefas grandes, use filas assíncronas | Testando limites: como simular carga e detectar gargalos no |
| Consumo de tokens muito acima do esperado | Prompt ou entrada muito verboso, redundância de dados | Revise prompts, compacte entradas, use cache de prompt | Testando limites: como simular carga e detectar gargalos no |
| Latência explode ao aumentar número de agentes | Gargalo em API externa ou limite de concorrência do modelo | Reduza concorrência ou implemente filas e retries | Testando limites: simulação de múltiplos incidentes e agente |
| Erros de timeout frequentes | Limite de requisições simultâneas atingido | Ajuste número de workers ou negocie limites com o fornecedor | Testando limites: simulação de múltiplos incidentes e agente |
| Logs incompletos ou agentes sem resposta registrada | Falta de isolamento de sessão ou falha no registro de logs | Garanta contexto isolado e logging estruturado por agente | Testando limites: simulação de múltiplos incidentes e agente |
| Teste trava ou demora demais | Loop infinito ou chamada externa sem timeout | Implemente timeouts e revise a lógica do teste | Testando para não quebrar: casos de teste, simulação e crité |
| Falha intermitente em teste de API externa | Dependência de serviço instável ou não mockado | Use mocks para isolar o agente e garantir repetibilidade | Testando para não quebrar: casos de teste, simulação e crité |
| Resultado inesperado em casos de exceção | Critério de aprovação mal definido ou entrada mal formatada | Revise os critérios e valide o formato das entradas de teste | Testando para não quebrar: casos de teste, simulação e crité |
| Resultados não aparecem no relatório | Falha na integração de coleta de dados | Verifique se o agente está registrando cada evento corretamente. | Testes A/B e segmentação automatizada: agentes para experime |
| Segmentos desbalanceados | Erro na função de distribuição de variantes | Confirme que cada segmento recebe o mesmo número de cada variante. | Testes A/B e segmentação automatizada: agentes para experime |
| Ajuste automático não ocorre | Critério de aprovação não atingido ou guardrail bloqueando | Revise os thresholds e as condições dos guardrails. | Testes A/B e segmentação automatizada: agentes para experime |
| Teste falha mesmo com resposta correta | Critério de aceitação rígido demais (comparação exata de texto) | Ajuste o teste para aceitar variações ou use similaridade de texto | Testes automáticos de prompts e agentes: ciclo contínuo |
| Respostas inconsistentes entre execuções | Parâmetro de temperatura alto ou contexto não controlado | Reduza a temperatura ou fixe o contexto do prompt | Testes automáticos de prompts e agentes: ciclo contínuo |
| Erro de autenticação na API | Chave de API ausente ou variável de ambiente incorreta | Configure corretamente a variável de ambiente com a chave | Testes automáticos de prompts e agentes: ciclo contínuo |
| Teste falha com erro de contrato | O modelo retornou JSON fora do esperado | Ajuste o prompt ou o código para seguir o contrato Pydantic | Testes automáticos: casos, contratos e resultados esperados |
| Respostas variam entre execuções | O modelo de IA é estocástico | Use prompts mais determinísticos ou ajuste o critério de aceitação | Testes automáticos: casos, contratos e resultados esperados |
| Pipeline de CI não executa testes | Configuração do pipeline está incompleta | Revise o arquivo de configuração e paths dos testes | Testes automáticos: casos, contratos e resultados esperados |
| Erro de autenticação na API | Chave de API ausente ou errada | Configure variáveis de ambiente corretamente | Testes automáticos: casos, contratos e resultados esperados |
| Testes demoram demais | Limite de requisições ou lentidão da API | Reduza o número de casos ou paralelize execuções | Testes automáticos: casos, contratos e resultados esperados |
| Teste falha mesmo com entrada correta | Mudança não documentada no prompt ou lógica do agente | Revisar histórico de alterações e alinhar critérios de aprovação | Testes automatizados e regressão em fluxos multiagentes |
| Testes não cobrem casos recentes de erro | Casos críticos não foram atualizados após incidentes | Revisar matriz de casos e incluir novos testes | Testes automatizados e regressão em fluxos multiagentes |
| Saída do agente varia entre execuções | Prompt ou ferramenta sem determinismo suficiente | Fixar seeds ou ajustar critérios de validação para tolerar variações controladas | Testes automatizados e regressão em fluxos multiagentes |
| Teste automatizado falha sem motivo aparente | Dados de teste mudaram ou ambiente não está isolado | Garanta que os dados de teste são fixos e use mocks para dependências externas | Testes automatizados e regressão: garantindo que o fluxo não |
| Teste passa localmente mas falha no CI/CD | Diferença de ambiente ou variáveis de ambiente ausentes | Padronize o ambiente de teste e configure variáveis no pipeline | Testes automatizados e regressão: garantindo que o fluxo não |
| Teste nunca falha, mesmo com erro no agente | Critério de aprovação do teste é frouxo ou genérico | Refine os asserts para cobrir o comportamento esperado com precisão | Testes automatizados e regressão: garantindo que o fluxo não |
| Testes de integração falham apenas em CI/CD | Diferença de ambiente ou variáveis de configuração ausentes | Padronize variáveis de ambiente e use arquivos .env no CI | Testes automatizados e validação de resultados |
| Testes de regressão passam localmente mas falham no servidor | Versão diferente do modelo ou dos dados | Fixe versões de modelos e dados nos requirements e scripts de setup | Testes automatizados e validação de resultados |
| Validação automática acusa baixa acurácia após update | Mudança inesperada no comportamento do modelo | Revise o changelog do modelo e reavalie o golden set | Testes automatizados e validação de resultados |
| Teste falha por timeout na API | Instabilidade ou limitação da API externa | Use mocks para testes locais e só rode integração real em horários de menor uso | Testes automatizados para agentes de voz e vídeo: cobertura |
| Transcrição não bate com o texto original | Modelo ASR inadequado ou áudio de baixa qualidade | Ajuste o modelo ou parâmetros de entrada, e valide o áudio gerado | Testes automatizados para agentes de voz e vídeo: cobertura |
| Cobertura de testes baixa | Casos de borda ou fluxos alternativos não contemplados | Revise a matriz de casos e inclua cenários de erro e exceção | Testes automatizados para agentes de voz e vídeo: cobertura |
| Teste não detecta erro do agente | Cobertura insuficiente ou checagem de saída superficial | Aumente os casos de teste e valide conteúdo, não só status. | Testes automatizados para agentes: cobertura, regressão e ca |
| Falhas intermitentes em testes | Dependência de APIs externas instáveis ou respostas não determinísticas do modelo | Use mocks e fixe seeds/contextos nos testes. | Testes automatizados para agentes: cobertura, regressão e ca |
| Testes de caos travam o agente | Tratamento de exceção ausente ou incompleto | Implemente guardrails e mensagens padrão para falhas de ferramenta. | Testes automatizados para agentes: cobertura, regressão e ca |
| Testes travam ou demoram muito | Chamadas reais a LLMs ou bancos vetoriais | Implemente mocks para todas as dependências externas | Testes automatizados: chains, agents e integrações |
| Cobertura baixa em módulos críticos | Faltam testes para branches ou exceções | Adicione testes para fluxos de erro e casos limites | Testes automatizados: chains, agents e integrações |
| Testes de integração falham só no CI | Dependências externas não mockadas ou variáveis de ambiente ausentes | Garanta mocks e use dotenv para variáveis em testes | Testes automatizados: chains, agents e integrações |
| Testes demoram muito para rodar | Limite de requisições simultâneas ou modelo escolhido muito pesado | Reduza paralelismo ou troque para modelo mais rápido (ex: Claude Haiku 4.5 ou GPT-5.6 Luna) | Testes de carga e avaliação automática: como medir antes de |
| Muitos testes falham por erro de campo ausente | Prompt pouco claro ou ferramenta não configurada corretamente | Ajuste o prompt e revise contratos das ferramentas | Testes de carga e avaliação automática: como medir antes de |
| Resultados variam muito entre execuções | Prompt não determinístico ou dados de entrada inconsistentes | Inclua exemplos claros no prompt e normalize os dados de teste | Testes de carga e avaliação automática: como medir antes de |
| Respostas muito lentas ou timeouts frequentes | Modelo escolhido é pesado ou concorrência acima do limite da API | Troque para modelo mais rápido ou reduza número de threads/processos | Testes de carga e avaliação automática: como saber se o agen |
| Precisão abaixo do esperado | Dados de teste mal rotulados ou prompt do agente inconsistente | Revise dados de teste e ajuste o prompt de sistema | Testes de carga e avaliação automática: como saber se o agen |
| Logs incompletos ou inconsistentes | Falta de controle de ID/timestamp ou erro no script de registro | Implemente logging estruturado com campos obrigatórios | Testes de carga e avaliação automática: como saber se o agen |
| Respostas lentas ou timeouts | Sobrecarga de CPU ou latência de API | Reduza o número de threads, otimize o prompt ou aumente recursos | Testes de carga e avaliação automatizada: validando o dimens |
| Respostas inconsistentes entre execuções | Estado compartilhado ou falta de isolamento nos testes | Garanta que cada teste rode em ambiente limpo | Testes de carga e avaliação automatizada: validando o dimens |
| Erros de validação automática | Critérios de aprovação mal definidos ou saída do agente fora do padrão | Ajuste os critérios e normalize as saídas antes de comparar | Testes de carga e avaliação automatizada: validando o dimens |
| Latência alta mesmo com modelo rápido | Limite de sessões paralelas ou gargalo no host Python | Aumente o número de workers/processos ou distribua a carga em mais máquinas | Testes de carga e avaliação de throughput: do lançamento ao |
| Taxa de erro elevada (timeouts, falhas de API) | Excesso de requisições simultâneas ou limites da API atingidos | Reduza o paralelismo ou use batch API para agrupar operações | Testes de carga e avaliação de throughput: do lançamento ao |
| Throughput baixo mesmo com CPU/RAM ociosos | Modelo ou API limitando o processamento | Avalie trocar de modelo ou otimizar o uso de contexto/tokens | Testes de carga e avaliação de throughput: do lançamento ao |
| Respostas incompletas ou truncadas | Limite de tokens ou contexto excedido | Reduza o tamanho das entradas ou divida o fluxo em etapas menores | Testes de carga e casos de uso: dimensionando o agente para |
| Erros intermitentes sob carga | Concorrência excessiva ou race conditions | Limite o número de threads/processos ou implemente filas de requisição | Testes de carga e casos de uso: dimensionando o agente para |
| Saídas inconsistentes para a mesma entrada | Prompt de sistema mal definido ou falta de seed | Versione o prompt e padronize as entradas de teste | Testes de carga e casos de uso: dimensionando o agente para |
| Erros 429 (Too Many Requests) | Limite de requisições simultâneas da API atingido. | Reduza concorrência ou implemente backoff exponencial. | Testes de carga e limites práticos: simulando operações trib |
| Respostas lentas ou timeouts | Carga acima da capacidade do agente ou da API. | Reduza tamanho dos prompts ou divida operações em lotes menores. | Testes de carga e limites práticos: simulando operações trib |
| Erros 400 (payload too large) | Tamanho do payload excede limite da API. | Divida o conteúdo ou use endpoints de arquivos quando disponível. | Testes de carga e limites práticos: simulando operações trib |
| Erros HTTP 429 durante o teste | Limite de requisições por segundo da API excedido | Reduza a taxa de requisições simultâneas ou implemente backoff exponencial | Testes de carga e limites: como o agente responde sob pressã |
| Latência crescente até timeout | Gargalo local (CPU, I/O) ou fila no modelo | Reduza concorrência, otimize código ou aumente recursos do ambiente | Testes de carga e limites: como o agente responde sob pressã |
| Erros HTTP 413 | Payload acima do limite aceito pela API | Divida a entrada em partes menores | Testes de carga e limites: como o agente responde sob pressã |
| Logs sem tracing detalhado | Tracing não habilitado no SDK | Ative tracing conforme documentação do SDK usado | Testes de carga e limites: como o agente responde sob pressã |
| Tempo de resposta muito alto | CPU ou memória saturados, ou limite de API externo atingido | Reduza o número de agentes simultâneos ou otimize o código; revise limites da API | Testes de estresse e limites: como não ser pego de surpresa |
| Erros 429 (Too Many Requests) | Limite de requisições da API externa ultrapassado | Implemente backoff exponencial e limite de concorrência | Testes de estresse e limites: como não ser pego de surpresa |
| Processo travando ou encerrando | Consumo excessivo de memória ou deadlock em threads | Ajuste o número de threads/processos e revise uso de recursos | Testes de estresse e limites: como não ser pego de surpresa |
| Resultados inconsistentes entre execuções | Condições de corrida ou falta de isolamento entre agentes | Garanta que cada agente use dados e contexto isolados | Testes de estresse e limites: como não ser pego de surpresa |
| Transcrição incompleta ou com erros graves | Áudio de baixa qualidade ou formato incompatível | Garanta que o áudio esteja em formato suportado (ex: WAV, MP3) e com boa qualidade. | Thinking adaptativo, MCP e multimodalidade: o futuro dos age |
| Erro 401 ao chamar APIs | Chave de API ausente ou inválida | Verifique se as variáveis de ambiente estão corretas e se a chave está ativa. | Thinking adaptativo, MCP e multimodalidade: o futuro dos age |
| Vídeo não é gerado ou fica travado em 'waiting' | Payload incompleto ou avatar/voice_id inválidos | Confirme todos os campos obrigatórios e use IDs válidos conforme a documentação da HeyGen. | Thinking adaptativo, MCP e multimodalidade: o futuro dos age |
| A resposta nunca chega | Timeout não configurado ou valor muito alto | Defina timeout explícito de 10-30 segundos | Timeout, limite de tokens e erros de integração: ação rápida |
| Erro 422 ou mensagem de limite de contexto | Prompt excede o limite de tokens do modelo | Conte e reduza tokens antes de enviar | Timeout, limite de tokens e erros de integração: ação rápida |
| Erro 401 Unauthorized | Chave de API inválida ou ausente | Verifique variável de ambiente e cabeçalho | Timeout, limite de tokens e erros de integração: ação rápida |
| Erro 429 Too Many Requests | Limite de requisições atingido | Implemente retry com backoff exponencial | Timeout, limite de tokens e erros de integração: ação rápida |
| O agente toma decisão financeira sem aprovação. | Falta de guardrail ou erro no orquestrador. | Reforce a validação no orquestrador e exija revisão humana antes de ações críticas. | Tipos de agentes, multiagentes e orquestração: o que serve p |
| Protocolos duplicados aparecem no sistema. | Agente de protocolo sem verificação de unicidade. | Implemente verificação de duplicidade no agente ou orquestrador. | Tipos de agentes, multiagentes e orquestração: o que serve p |
| Logs incompletos ou ausentes. | Orquestrador não registra todas as etapas. | Inclua registro detalhado de cada ação no orquestrador. | Tipos de agentes, multiagentes e orquestração: o que serve p |
| Erro de contexto excedido ao processar um shard | Shard com notas demais ou notas muito grandes | Reduza o tamanho do shard ou pré-processe as notas para remover campos desnecessários | Tokens, arquivos e contexto: limites práticos dos modelos |
| Arquivo temporário ocupa muita memória e trava o agente | Leitura de arquivo inteiro em RAM | Processar em blocos menores ou usar leitura linha a linha | Tokens, arquivos e contexto: limites práticos dos modelos |
| Notas fiscais sumindo do resultado final | Estouro silencioso de contexto ou erro na agregação dos shards | Recalcule o tamanho dos shards e implemente logs de contagem em cada etapa | Tokens, arquivos e contexto: limites práticos dos modelos |
| Erro de limite de tokens | Prompt ou resposta maior que o contexto do modelo | Reduza o texto ou troque de modelo para um com contexto maior | Tokens, chamadas e latência: dimensionando para não travar |
| Latência alta em vídeo HeyGen | Muitos vídeos na fila ou limitação do serviço | Implemente fila e controle de concorrência; consulte status antes de exibir | Tokens, chamadas e latência: dimensionando para não travar |
| TTS não responde em tempo real | Modelo errado ou sobrecarga | Use eleven_flash_v2_5 ou eleven_v3_conversational e monitore uso simultâneo | Tokens, chamadas e latência: dimensionando para não travar |
| Erro de contexto excedido | Prompt, histórico ou anexos ultrapassaram o limite de tokens do modelo. | Reduza o tamanho do prompt ou histórico; meça tokens antes de enviar. | Tokens, contexto e batches: onde o custo e o erro nascem |
| Batch não processa todas as mensagens | O tamanho total do batch excede o limite permitido. | Divida o batch em partes menores e reenvie. | Tokens, contexto e batches: onde o custo e o erro nascem |
| Resposta truncada ou incompleta | Limite de saída do modelo foi atingido. | Solicite menos saída ou aumente o parâmetro de saída, se permitido. | Tokens, contexto e batches: onde o custo e o erro nascem |
| Resposta da IA cortada no meio | Limite de tokens de saída atingido | Reduza o tamanho do prompt ou peça respostas mais curtas | Tokens, contexto e custo: por que cada palavra tem preço e l |
| Erro de contexto excedido na API | Soma de tokens de entrada e saída ultrapassa o limite do modelo | Divida a tarefa em partes menores ou resuma o histórico | Tokens, contexto e custo: por que cada palavra tem preço e l |
| IA esquece instruções anteriores | Instruções foram removidas do contexto por truncamento | Garanta que instruções essenciais estejam sempre no início do prompt | Tokens, contexto e custo: por que cada palavra tem preço e l |
| Respostas truncadas ou incompletas | Contexto ou saída excedeu o limite de tokens do modelo | Implemente truncamento ou resuma o histórico antes de enviar | Tokens, contexto e limites: o que trava seu agente antes do |
| Erros de API com mensagem de limite | Prompt ou histórico muito grande | Reduza o tamanho do input e monitore com contagem de tokens | Tokens, contexto e limites: o que trava seu agente antes do |
| Agente esquece instruções anteriores | Histórico foi truncado de forma inadequada | Priorize instruções críticas e resuma o restante | Tokens, contexto e limites: o que trava seu agente antes do |
| Log de sessão ausente ou incompleto | Tracing não ativado ou erro no código de logging | Revisar inicialização do Tracer ou Runner.trace e garantir chamada dos métodos de log_event | Tracing avançado: rastreando execuções e decisões do agente |
| Dados sensíveis vazando para o log | Falta de minimização ou anonimização de dados | Ajustar o código para registrar apenas o necessário, mascarando dados pessoais | Tracing avançado: rastreando execuções e decisões do agente |
| Logs não são descartados após o prazo | Rotina de descarte não implementada ou falha de permissão | Automatizar a exclusão e revisar permissões dos diretórios de log | Tracing avançado: rastreando execuções e decisões do agente |
| Histórico de tracing vazio | Tracing não foi habilitado no agente. | Inicialize o agente com tracing=True. | Tracing e contagem de tokens: cada passo do agente visível, |
| Tokens retornando zero na Claude | Prompt enviado em formato incorreto. | Garanta que o body tenha 'model' e 'messages' corretos. | Tracing e contagem de tokens: cada passo do agente visível, |
| Custo calculado muito acima do esperado | Tokens de saída não foram limitados. | Ajuste o prompt ou limite de saída do modelo. | Tracing e contagem de tokens: cada passo do agente visível, |
| Logs não aparecem ou estão incompletos | Tracing não habilitado ou logs não configurados corretamente | Verifique se o tracing está ativo e o caminho do arquivo de log está correto | Tracing e depuração: seguindo o caminho do agente até o erro |
| Erros não são detectados nos logs | Guardrails ou validações ausentes | Implemente validações explícitas para cada regra crítica | Tracing e depuração: seguindo o caminho do agente até o erro |
| Dificuldade para entender logs | Logs não estruturados ou sem contexto suficiente | Padronize logs em JSON e inclua contexto detalhado | Tracing e depuração: seguindo o caminho do agente até o erro |
| Erros recorrentes sem solução | Prompt ou ferramenta com contrato ambíguo | Revise e explicite as regras no prompt e no contrato da ferramenta | Tracing e depuração: seguindo o caminho do agente até o erro |
| Logs não aparecem no arquivo | Caminho do arquivo incorreto ou permissões insuficientes | Verifique o caminho e permissões de escrita | Tracing e logs: como rastrear cada decisão do agente |
| Logs incompletos ou truncados | Buffer não foi descarregado | Use flush() ou feche o arquivo corretamente | Tracing e logs: como rastrear cada decisão do agente |
| Logs em formato ilegível | Formato de logging não definido como JSON | Ajuste o format do logging para JSON ou estruturado | Tracing e logs: como rastrear cada decisão do agente |
| Logs não aparecem no arquivo | Permissão de escrita insuficiente ou caminho do arquivo incorreto | Ajuste permissões e paths; garanta que o processo Python tem acesso ao diretório | Tracing e logs: monitoramento contínuo do agente de planejam |
| Erros não são registrados | Blocos try/except ausentes ou log_event não chamado em exceções | Inclua captura de exceções e registro explícito de erros | Tracing e logs: monitoramento contínuo do agente de planejam |
| Alertas não são enviados | Script de monitoramento não está rodando ou não lê o arquivo correto | Verifique agendamento do script e caminho do arquivo de log | Tracing e logs: monitoramento contínuo do agente de planejam |
| Logs não são gerados | Tracing não foi ativado ou caminho de log incorreto | Verifique se o parâmetro tracing=True está presente e se a variável AGENT_LOG_PATH aponta para um diretório válido | Tracing e logs: rastreando cada decisão do agente |
| Arquivo de log vazio | Permissões insuficientes no diretório de log | Ajuste as permissões do diretório para permitir escrita pelo processo do agente | Tracing e logs: rastreando cada decisão do agente |
| Dados sensíveis expostos nos logs | Falta de sanitização ou configuração inadequada | Implemente filtros para mascarar dados pessoais e revise o conteúdo dos logs regularmente | Tracing e logs: rastreando cada decisão do agente |
| Logs não aparecem no diretório | Permissões insuficientes ou caminho incorreto | Ajuste permissões e confirme o caminho do log | Tracing e logs: rastreando cada decisão do agente tributário |
| Alertas de exceção não são enviados | Função de envio de alerta não implementada ou erro de configuração | Implemente a função de envio e teste com exceção simulada | Tracing e logs: rastreando cada decisão do agente tributário |
| Entradas de log incompletas | Estrutura do evento mal definida ou serialização incorreta | Revise o formato do evento e use JSON válido | Tracing e logs: rastreando cada decisão do agente tributário |
| Logs não estão sendo gerados | Tracing não habilitado ou diretório inexistente | Confirme se o tracing está ativado e se o diretório ./logs existe e tem permissão de escrita | Tracing e logs: rastreando decisões e ações do agente |
| Justificativas ausentes nos logs | Prompt do agente não exige justificativa explícita | Inclua no prompt a instrução para justificar cada decisão | Tracing e logs: rastreando decisões e ações do agente |
| Integrações externas não aparecem nos logs | Registro manual das chamadas não implementado | Adicione logging explícito em cada ponto de integração | Tracing e logs: rastreando decisões e ações do agente |
| Métricas não aparecem no endpoint | Biblioteca prometheus_client não instalada ou start_http_server não chamado | Instale prometheus_client e chame start_http_server antes de processar tarefas | Tracing e métricas: monitorando o agente em tempo real |
| Logs de tracing não são gerados | Hooks de tracing não foram adicionados ao agente | Adicione o hook TracingHook ao criar o agente | Tracing e métricas: monitorando o agente em tempo real |
| Alertas não disparam mesmo com erro | Condição de alerta mal configurada ou contadores não atualizados | Revise a lógica de cálculo dos limites e incremente os contadores corretamente | Tracing e métricas: monitorando o agente em tempo real |
| Logs não aparecem no sistema de monitoramento | Formato incompatível ou falta de integração | Ajuste o formato para JSON e configure o agente de coleta corretamente | Tracing e métricas: o que e como medir em APIs de IA |
| Latência medida muito baixa ou zero | Timestamp calculado antes da chamada assíncrona terminar | Garanta que a medição ocorre após o recebimento da resposta | Tracing e métricas: o que e como medir em APIs de IA |
| Request_id ausente em logs de erro | Exceção lançada antes de gerar o identificador | Gere o request_id no início da requisição, antes de qualquer lógica | Tracing e métricas: o que e como medir em APIs de IA |
| Logs de tracing não aparecem | Tracing não foi habilitado ou diretório de saída incorreto. | Confirme que o parâmetro enable=True e o caminho do output_dir estão corretos. | Tracing em agentes: como registrar cada decisão e ação |
| Logs incompletos (faltam decisões ou ferramentas) | Versão do SDK desatualizada ou uso de funções fora do laço do agente. | Atualize o SDK e garanta que todas as ações passem pelo laço do agente. | Tracing em agentes: como registrar cada decisão e ação |
| Logs ilegíveis ou corrompidos | Escrita concorrente ou falta de permissão no diretório. | Garanta permissão de escrita e serialize as execuções para evitar concorrência. | Tracing em agentes: como registrar cada decisão e ação |
| Painel não mostra custos corretos | Tokens não extraídos corretamente do trace ou preço do modelo desatualizado | Revise o parsing do trace e consulte a documentação para preços atualizados | Tracing, custo por tarefa e taxa de acerto: o painel que a d |
| Taxa de acerto sempre 100% ou 0% | Casos de teste mal definidos ou avaliação automática falha | Ajuste os casos de teste e revise a lógica de comparação | Tracing, custo por tarefa e taxa de acerto: o painel que a d |
| Alertas não disparam | Condições de alerta mal configuradas ou integração com e-mail/webhook falha | Teste manualmente os limites e revise a configuração dos alertas | Tracing, custo por tarefa e taxa de acerto: o painel que a d |
| Logs não aparecem no arquivo | Handler ou nível de log não configurado corretamente | Revise configuração do logger e permissões de escrita. | Tracing, logs e auditoria: enxergando o que a IA faz |
| Eventos de tracing ausentes | Hooks não registrados ou trace=False | Confirme registro dos hooks (Claude) ou uso de trace=True (OpenAI). | Tracing, logs e auditoria: enxergando o que a IA faz |
| Logs duplicados | Múltiplos handlers ou loggers propagando eventos | Desative propagação ou revise handlers. | Tracing, logs e auditoria: enxergando o que a IA faz |
| Logs não aparecem após execução do agente | Hook de logging não configurado corretamente ou permissão de escrita insuficiente | Revise a configuração do logger e permissões do diretório de logs | Tracing, logs e auditoria: o que registrar e por quanto temp |
| Logs antigos não são removidos | Script de rotação/descarte não está agendado ou com caminho errado | Ajuste o script e agende execução periódica (cron ou equivalente) | Tracing, logs e auditoria: o que registrar e por quanto temp |
| Dados pessoais aparecem em texto aberto nos logs | Falta de hash ou anonimização no momento do registro | Implemente função de hash/mascaramento antes de gravar o log | Tracing, logs e auditoria: o que registrar e por quanto temp |
| Falha ao exportar logs para sistema externo | Endpoint incorreto ou falta de autenticação | Corrija a URL e as credenciais de exportação | Tracing, logs e auditoria: o que registrar e por quanto temp |
| Logs não aparecem no diretório esperado | Caminho incorreto ou permissões insuficientes | Verifique o caminho do log_dir e permissões de escrita. | Tracing, logs e métricas: monitoramento em tempo real dos ag |
| Métricas não atualizam no painel | Exportação ou coleta de métricas mal configurada | Revise o código de exportação e integração com o painel. | Tracing, logs e métricas: monitoramento em tempo real dos ag |
| Alertas não são disparados mesmo com erro | Regra de alerta mal definida ou função de notificação inativa | Ajuste as condições de alerta e teste o canal de notificação. | Tracing, logs e métricas: monitoramento em tempo real dos ag |
| Logs não aparecem no destino configurado | Permissão de escrita insuficiente ou caminho incorreto | Ajuste permissões do diretório e verifique o caminho do log | Tracing, métricas e alertas: monitorando o agente em tempo r |
| Alertas não são recebidos | Configuração incorreta de e-mail ou integração de alerta | Verifique credenciais e conectividade do serviço de alerta | Tracing, métricas e alertas: monitorando o agente em tempo r |
| Métricas de tempo não batem com a percepção do usuário | Coleta de tempo fora do escopo real da execução | Inclua toda a cadeia de processamento, não só a chamada ao agente | Tracing, métricas e alertas: monitorando o agente em tempo r |
| Logs não aparecem no arquivo | Caminho incorreto ou permissão insuficiente | Verifique permissões e o parâmetro log_path | Tracing: cada decisão, cada chamada, tudo registrado |
| Eventos ausentes nos logs | Nível de tracing insuficiente ou hooks não configurados | Ajuste o nível de detalhamento e revise configuração de hooks | Tracing: cada decisão, cada chamada, tudo registrado |
| Alertas não disparam | Query de alerta incorreta ou integração falha | Teste queries manualmente e revise integração com sistema de alertas | Tracing: cada decisão, cada chamada, tudo registrado |
| Transcrição retorna texto vazio ou incoerente | Áudio de baixa qualidade ou idioma não suportado | Verifique o formato do áudio e a qualidade da gravação; teste com outro arquivo | Transcrição e síntese: pipeline Python com ElevenLabs e Clau |
| Resposta da IA é vazia ou genérica | Prompt mal formulado ou contexto insuficiente | Ajuste o prompt para ser mais claro e inclua contexto relevante | Transcrição e síntese: pipeline Python com ElevenLabs e Clau |
| Arquivo de áudio de saída está corrompido ou mudo | Parâmetros inválidos na chamada de TTS ou voz/modelo incompatíveis | Confirme voice_id, model_id e formato de saída conforme a documentação | Transcrição e síntese: pipeline Python com ElevenLabs e Clau |
| Logs ausentes ou incompletos | Falha na configuração do logging ou permissões de escrita | Verifique permissões do arquivo de log e inicialização do logger | Transcrição e síntese: pipeline Python com ElevenLabs e Clau |
| O vídeo não é gerado após o envio do job | Erro de autenticação ou campos obrigatórios ausentes na requisição | Revise a chave de API e consulte a documentação dos campos obrigatórios | Treinamento corporativo com vídeos de avatar: do roteiro à e |
| O avatar ou voz não correspondem ao esperado | IDs de avatar ou voz incorretos no corpo da requisição | Confirme os IDs válidos usando os endpoints de listagem de avatars e voices | Treinamento corporativo com vídeos de avatar: do roteiro à e |
| O roteiro contém termos proibidos ou dados pessoais | Falta de validação automática ou revisão humana insuficiente | Ajuste o script de validação e reforce o processo de revisão | Treinamento corporativo com vídeos de avatar: do roteiro à e |
| Alerta não classificado corretamente | Prompt de sistema desatualizado ou dados insuficientes | Atualize o prompt e garanta que todos os campos necessários estejam presentes no alerta | Triagem automatizada: do alerta à resposta em minutos |
| Runbook falha em um passo | Ferramenta com contrato mal definido ou erro de integração | Reveja a definição da ferramenta e teste cada comando isoladamente | Triagem automatizada: do alerta à resposta em minutos |
| Ação crítica executada sem aprovação | Falta de checagem de aprovação no fluxo | Implemente guardrail obrigatório para bloqueio até resposta humana | Triagem automatizada: do alerta à resposta em minutos |
| O agente classifica muitos itens como 'Outros' | Prompt pouco específico ou exemplos insuficientes | Refine o prompt e aumente o conjunto de exemplos de teste | Triagem de e-mails e documentos: agente em produção |
| Dados pessoais aparecem em logs | Falta de sanitização nas funções de registro | Implemente filtros para ocultar ou remover dados sensíveis antes do registro | Triagem de e-mails e documentos: agente em produção |
| Itens críticos não são encaminhados para revisão | Erro na lógica de encaminhamento ou falha na definição da ferramenta | Revise a implementação da função enviar_para_revisao e os critérios de categoria | Triagem de e-mails e documentos: agente em produção |
| Relatório com notas diferentes para currículos idênticos | Viés ou erro no prompt/código | Revise o prompt e os testes de justiça | Triagem justa de currículos: do prompt ao relatório auditáve |
| Logs incompletos ou ausentes | Tracing não configurado corretamente | Ative o tracing nativo do SDK | Triagem justa de currículos: do prompt ao relatório auditáve |
| Dados pessoais sensíveis aparecendo no relatório | Prompt ou ferramenta não aplicou minimização | Ajuste o prompt e as funções para excluir dados irrelevantes | Triagem justa de currículos: do prompt ao relatório auditáve |
| Vídeo não é gerado ou fica em status 'waiting' indefinidamente | Parâmetros obrigatórios ausentes ou avatar_id/voice_id inválidos | Revise os campos enviados e use IDs válidos do painel HeyGen | Trilha de treinamento automatizada: vídeo, voz e avaliação e |
| Áudio gerado está em idioma errado ou com voz robótica | Uso de model_id ou voice_id incompatíveis com português | Confirme que model_id está como 'eleven_multilingual_v2' e voice_id suporta português | Trilha de treinamento automatizada: vídeo, voz e avaliação e |
| Avaliação automática retorna erro ou resultado inconsistente | Prompt de sistema mal formatado ou ausência de gabarito claro | Reescreva o prompt e garanta que o gabarito está explícito | Trilha de treinamento automatizada: vídeo, voz e avaliação e |
| Erro de autenticação ao rodar um modelo | Chave de API ausente ou inválida na variável de ambiente | Verifique se a variável de ambiente correta está definida (ANTHROPIC_API_KEY ou OPENAI_API_KEY) | Trocar de modelo sem reescrever nada: Haiku, Sonnet, Opus e |
| Resposta vazia ou None | Prompt mal formatado ou modelo não suporta o tipo de entrada | Revise o formato do prompt e o contrato de entrada/saída do wrapper | Trocar de modelo sem reescrever nada: Haiku, Sonnet, Opus e |
| Exceção ao instanciar wrapper | Provider não suportado ou parâmetro ausente | Confirme se o provider e os campos obrigatórios estão corretos na configuração | Trocar de modelo sem reescrever nada: Haiku, Sonnet, Opus e |
| Demora excessiva na resposta | Modelo escolhido é mais lento ou está sobrecarregado | Teste com outro modelo e monitore tempos de resposta | Trocar de modelo sem reescrever nada: Haiku, Sonnet, Opus e |
| Busca lenta em FAISS | nprobe alto demais ou hardware insuficiente | Reduza nprobe ou otimize hardware | Tuning de bancos vetoriais: FAISS e Elasticsearch em produçã |
| Shard indisponível no Elasticsearch | Nó do cluster falhou ou falta de recursos | Recupere o nó ou aumente recursos do cluster | Tuning de bancos vetoriais: FAISS e Elasticsearch em produçã |
| Resultados inconsistentes após migração | Índice corrompido ou incompleto | Reindexe e valide integridade dos dados | Tuning de bancos vetoriais: FAISS e Elasticsearch em produçã |
| O fluxo para em uma etapa sem resposta. | O agente correspondente não recebeu contexto suficiente ou houve erro na chamada. | Verifique se o contexto está sendo atualizado corretamente e se o agente foi instanciado. | Um orquestrador e cinco especialistas: a empresa em um arqui |
| O log não registra as etapas. | Configuração de logging ausente ou permissão de escrita insuficiente. | Confirme se logging.basicConfig foi chamado antes do fluxo e se o arquivo é gravável. | Um orquestrador e cinco especialistas: a empresa em um arqui |
| Respostas incoerentes dos agentes. | Instruções dos agentes vagas ou contexto mal formatado. | Refine as instructions e garanta que o contexto seja claro e objetivo. | Um orquestrador e cinco especialistas: a empresa em um arqui |
| O agente retorna resultados genéricos ou sem referências. | Prompt de sistema pouco específico ou ferramentas mal configuradas. | Reforce o prompt e revise os contratos das ferramentas. | Validação de novo produto: pesquisa, análise e apresentação |
| O áudio gerado está truncado ou incompleto. | Texto do roteiro muito longo ou erro no modelo TTS. | Divida o roteiro em partes menores e valide o texto antes de enviar. | Validação de novo produto: pesquisa, análise e apresentação |
| O vídeo não apresenta todos os tópicos do roteiro. | Script enviado para o HeyGen está incompleto ou mal segmentado. | Revise o script e garanta que todos os tópicos estão presentes. | Validação de novo produto: pesquisa, análise e apresentação |
| Erro de autenticação ao rodar o agente | Chave não definida ou variável de ambiente incorreta | Verifique se a variável está exportada e se a chave é válida | Variáveis de ambiente e segredos: nunca exponha no prompt |
| Chave de API aparece em logs | Logging sem filtro ou debug excessivo | Implemente filtros de redaction e revise níveis de log | Variáveis de ambiente e segredos: nunca exponha no prompt |
| Chave antiga ainda funciona após rotação | Não foi revogada no painel do provedor | Revogue manualmente a chave antiga | Variáveis de ambiente e segredos: nunca exponha no prompt |
| Erro de autenticação ao chamar a API | Variável de ambiente não definida ou nome incorreto | Confirme o nome e valor da variável e reinicie o serviço | Variáveis de ambiente e segredos: o que vai onde |
| Chave aparece em logs | Logger sem filtro de segredos | Implemente filtro para mascarar ou omitir segredos | Variáveis de ambiente e segredos: o que vai onde |
| Segredo exposto em repositório Git | Arquivo .env ou código com chave versionado | Remova o arquivo do controle de versão e troque a chave imediatamente | Variáveis de ambiente e segredos: o que vai onde |
| Erro de autenticação ao rodar o agente | Variável de ambiente não definida ou nome incorreto | Confirme o nome da variável e defina corretamente no ambiente | Variáveis de ambiente e segredos: protegendo credenciais e d |
| Chave de API aparece em logs ou exceptions | Código faz print ou log de variáveis sensíveis | Remova prints/logs de segredos e revise handlers de erro | Variáveis de ambiente e segredos: protegendo credenciais e d |
| .env aparece no repositório | .gitignore não inclui .env | Adicione .env ao .gitignore e remova do versionamento | Variáveis de ambiente e segredos: protegendo credenciais e d |
| Erro de autenticação ao chamar API | Chave ausente, inválida ou variável de ambiente não definida | Verifique se a variável está exportada e se a chave é válida no painel do serviço | Variáveis de ambiente, segredos e configuração segura de API |
| Chave de API aparece em logs ou exceptions | Código imprime variáveis de ambiente ou repassa segredos para logs | Remova prints e configure logs para nunca registrar variáveis sensíveis | Variáveis de ambiente, segredos e configuração segura de API |
| Ambiente de desenvolvimento acessa dados de produção | Chaves de produção usadas por engano em dev | Separe arquivos .env e valide o ambiente antes de rodar | Variáveis de ambiente, segredos e configuração segura de API |
| Variáveis de ambiente não são carregadas no agente | Arquivo .env não encontrado ou load_dotenv() não chamado | Confirme o caminho do .env e chame load_dotenv() antes de acessar os segredos | Variáveis de ambiente, segredos e logs: protegendo o que imp |
| Logs expõem dados sensíveis | Falta de mascaramento ou registro excessivo | Revise o código para mascarar ou omitir informações sensíveis nos logs | Variáveis de ambiente, segredos e logs: protegendo o que imp |
| Arquivo de log acessível a qualquer usuário | Permissões de arquivo mal configuradas | Use chmod 600 para restringir o acesso ao log | Variáveis de ambiente, segredos e logs: protegendo o que imp |
| O agente retorna erro de autenticação ao chamar a API | Variável de ambiente não definida ou valor incorreto | Verifique se a variável foi exportada corretamente e se o valor está atualizado | Variáveis, segredos e LGPD: configurando o agente sem expor |
| Chaves de API aparecem em arquivos do repositório | Arquivo .env não está no .gitignore | Adicione .env ao .gitignore e remova do versionamento | Variáveis, segredos e LGPD: configurando o agente sem expor |
| Dados pessoais aparecem em logs ou outputs | Falta de anonimização ou minimização | Implemente anonimização antes de registrar ou exibir dados sensíveis | Variáveis, segredos e LGPD: configurando o agente sem expor |
| O agente responde de forma inesperada após atualização. | Prompt ou ferramenta desatualizados, ou teste de regressão ausente. | Verifique a versão ativa e rode todos os testes automatizados. | Versionamento de prompt e ferramentas: como não perder o con |
| Rollback não restaura comportamento anterior. | Alterações não versionadas ou dependências externas não controladas. | Garanta que todos os arquivos relevantes estão sob controle de versão. | Versionamento de prompt e ferramentas: como não perder o con |
| Não é possível identificar qual prompt gerou uma resposta. | Falta de registro da versão do prompt em logs ou banco de dados. | Inclua sempre o identificador de versão no registro de cada execução. | Versionamento de prompt e ferramentas: como não perder o con |
| Teste automatizado falha após atualização do prompt | Prompt ou ferramenta mudou sem atualizar o teste ou a lógica de validação | Revise o caso de teste e ajuste para refletir a nova regra ou reverta a alteração | Versionamento de prompt, ferramentas e casos de teste |
| Rollback não restaura o agente corretamente | Mudanças não foram todas commitadas ou há arquivos não versionados | Garanta que tudo está sob controle de versão e use 'git status' antes de rollback | Versionamento de prompt, ferramentas e casos de teste |
| Não é possível auditar uma decisão antiga | Faltou registrar a versão do prompt/ferramenta usada na execução | Inclua sempre o identificador de versão nos registros de execução | Versionamento de prompt, ferramentas e casos de teste |
| O agente responde de forma inconsistente entre execuções | Prompt ou ferramenta foi alterado sem versionamento | Reverta para versão anterior e registre a alteração corretamente | Versionamento de prompt, ferramentas e testes: por que e com |
| Teste automatizado falha após atualização de ferramenta | Contrato da ferramenta mudou mas o teste não foi atualizado | Atualize o teste para refletir o novo contrato e registre a mudança | Versionamento de prompt, ferramentas e testes: por que e com |
| Não é possível rastrear quem fez determinada alteração | Falta de metadados nos arquivos ou log de mudanças | Inclua sempre autor e motivo em cada versão e mantenha o log atualizado | Versionamento de prompt, ferramentas e testes: por que e com |
| O agente retorna respostas incoerentes após alteração no prompt | Prompt de sistema alterado sem atualização dos testes | Atualize ou crie novos casos de teste para cobrir a nova versão do prompt | Versionamento de prompts e contratos de ferramenta: garantia |
| Erro ao chamar ferramenta externa | Contrato de ferramenta desatualizado ou parâmetros incompatíveis | Revise o contrato e sincronize versão entre agente e ferramenta | Versionamento de prompts e contratos de ferramenta: garantia |
| Histórico de execução não aparece | Tracing não habilitado no SDK | Ative o tracing ao rodar o agente, conforme exemplo | Versionamento de prompts e contratos de ferramenta: garantia |
| Prompt errado é usado pelo agente | Nome do arquivo ou caminho incorreto na configuração do agente | Verifique se o nome e o caminho do prompt na configuração batem com o arquivo versionado | Versionamento de prompts e ferramentas: como garantir rastre |
| Rollback não reverte o comportamento do agente | Commit incompleto ou arquivos não versionados no Git | Garanta que todos os arquivos relevantes estão sob controle de versão e revertidos juntos | Versionamento de prompts e ferramentas: como garantir rastre |
| Testes automatizados falham após alteração | Mudança no prompt ou ferramenta sem atualizar os testes | Atualize os testes para refletir os novos critérios e rode novamente | Versionamento de prompts e ferramentas: como garantir rastre |
| Teste automatizado falha após alteração de prompt | Mudança incompatível com o contrato da ferramenta ou saída esperada | Reverta o prompt e ajuste o contrato antes de prosseguir | Versionamento de prompts e ferramentas: controle de mudanças |
| Rollback não restaura o estado anterior | Arquivos não versionados ou commit incompleto | Garanta que todos os arquivos estejam sob controle do Git e faça commit antes de alterar | Versionamento de prompts e ferramentas: controle de mudanças |
| Resultado diferente para o mesmo caso de teste após alteração de ferramenta | Mudança de lógica não acompanhada de atualização do caso de teste | Atualize os casos de teste para refletir a nova lógica ou reverta a alteração | Versionamento de prompts e ferramentas: controle de mudanças |
| Agente responde de forma inesperada após alteração | Prompt ou função nova não compatível com entradas antigas | Rode testes regressivos e faça rollback para a versão anterior | Versionamento de prompts e ferramentas: evoluindo sem quebra |
| Não é possível identificar qual versão do prompt foi usada em uma execução | Falta de registro de versão no tracing | Inclua o identificador de versão no log de cada execução | Versionamento de prompts e ferramentas: evoluindo sem quebra |
| Rollback não restaura comportamento anterior | Mudanças não isoladas por versão de arquivo | Garanta que cada versão tenha arquivos próprios e não sobrescreva | Versionamento de prompts e ferramentas: evoluindo sem quebra |
| Não consigo voltar para uma versão anterior do prompt | Alterações não foram commitadas ou versionadas corretamente | Garanta que cada mudança seja commitada e identificada por tag ou mensagem clara. | Versionamento de prompts, ferramentas e casos de teste |
| Testes falham após atualizar ferramenta | Casos de teste não foram ajustados para o novo contrato da ferramenta | Atualize os testes para refletir os novos parâmetros ou lógica. | Versionamento de prompts, ferramentas e casos de teste |
| Não sei qual versão estava em produção quando ocorreu um erro | Falta de registro de versão na execução | Inclua log automático da versão do prompt, ferramenta e commit em cada execução do agente. | Versionamento de prompts, ferramentas e casos de teste |
| Rollback não restaura o modelo correto | Arquivo de modelo não versionado no DVC ou commit ausente | Adicione o arquivo ao DVC e garanta commits sincronizados | Versionamento e governança de modelos e pipelines |
| Metadados de versão ausentes nas respostas | Código do pipeline não inclui os campos de versão no output | Adicione a inclusão explícita dos metadados no código | Versionamento e governança de modelos e pipelines |
| Histórico de mudanças incompleto | Commits sem mensagens claras ou ausência de CHANGELOG | Padronize mensagens e mantenha o CHANGELOG atualizado | Versionamento e governança de modelos e pipelines |
| Execuções não aparecem nos logs | Falha na configuração do logging ou permissão de escrita | Revise o código de logging e permissões da pasta de logs | Versionamento e rastreabilidade: como garantir histórico e r |
| Não é possível saber qual versão do prompt foi usada | Falta de campo de versão nos registros | Inclua sempre o identificador de versão do prompt e ferramenta no log | Versionamento e rastreabilidade: como garantir histórico e r |
| Histórico de decisões incompleto | Logs sobrescritos ou não versionados | Use logs append-only e versionamento externo (git) para arquivos de configuração | Versionamento e rastreabilidade: como garantir histórico e r |
| Rollback não restaura o comportamento esperado do agente | Alterações não versionadas ou dependências externas não revertidas | Garanta que todos os arquivos relevantes estão sob controle de versão e que dependências são restauradas ao estado do release | Versionamento e rollback de prompts e ferramentas: controle |
| Prompt em produção não corresponde ao último commit | Deploy manual ou pipeline desatualizado | Automatize o deploy para sempre usar a versão tagueada e testada | Versionamento e rollback de prompts e ferramentas: controle |
| Ferramenta apresenta erro após rollback | Incompatibilidade entre versões de prompt e ferramenta | Sempre teste rollback em ambiente de homologação antes de liberar em produção | Versionamento e rollback de prompts e ferramentas: controle |
| O agente responde de forma inesperada após atualização de prompt. | Prompt novo não foi revisado ou testado. | Reverta para a versão anterior e refaça a revisão. | Versionamento, documentação e revisão: o tripé do agente con |
| Erro ao rodar ferramenta após deploy. | Mudança incompatível com dados ou contrato de entrada/saída. | Ajuste a ferramenta ou execute rollback. | Versionamento, documentação e revisão: o tripé do agente con |
| Não é possível identificar quem fez determinada alteração. | Falta de versionamento e registro de autoria. | Padronize uso de Git e exigência de commit assinado. | Versionamento, documentação e revisão: o tripé do agente con |
| Logs vazios ou incompletos | Tracing não ativado ou diretório sem permissão | Confirme enable_tracing e permissões do diretório de logs | Versionamento, rastreabilidade e memória curta: padrões para |
| Dados sensíveis aparecendo em logs | Prompt ou ferramenta registrando informações demais | Revise o prompt e ajuste para anonimizar ou omitir dados pessoais | Versionamento, rastreabilidade e memória curta: padrões para |
| Histórico não é limpo ao encerrar sessão | Função de limpeza não chamada | Implemente session.clear_history() ao final de cada ciclo | Versionamento, rastreabilidade e memória curta: padrões para |
| Rollback não aplica a versão correta | Variável de ambiente ou caminho de arquivo incorreto | Verifique o valor de PROMPT_VERSION e o caminho dos arquivos | Versionamento, rollback e documentação de prompts e agentes |
| Histórico de mudanças incompleto | Commits sem mensagem clara ou changelog desatualizado | Padronize mensagens e obrigue atualização do changelog a cada alteração | Versionamento, rollback e documentação de prompts e agentes |
| Prompt antigo sendo usado após rollback | Cache de aplicação ou deploy não atualizado | Limpe cache e redeploye a aplicação após rollback | Versionamento, rollback e documentação de prompts e agentes |
| Logs não aparecem ou estão incompletos | Configuração incorreta do logger ou falta de flush no arquivo | Revise a configuração do logging e garanta flush após cada evento | Versionamento, rollback e logs: prevenindo erros irreversíve |
| Rollback não reverte o comportamento do agente | Versão errada do prompt/configuração aplicada ou serviço não reiniciado | Cheque o hash/versão do arquivo ativo e reinicie o serviço corretamente | Versionamento, rollback e logs: prevenindo erros irreversíve |
| Ações sensíveis são executadas sem revisão | Falta de validação no código ou bypass do fluxo de aprovação | Implemente guardrails obrigatórios e revise testes automatizados | Versionamento, rollback e logs: prevenindo erros irreversíve |
| O agente se comporta de forma diferente após atualização | Prompt ou ferramenta foi alterado sem versionamento | Reverta para a versão anterior e implemente versionamento explícito | Versionamento, testes e revisão: arquitetura para agentes qu |
| Testes automatizados falham após uma alteração | Mudança quebrou compatibilidade ou lógica do agente | Corrija o código ou ajuste o prompt até todos os testes passarem | Versionamento, testes e revisão: arquitetura para agentes qu |
| Ação irreversível foi executada sem aprovação | Falta de ponto de handoff ou revisão humana | Implemente handoff obrigatório para decisões críticas | Versionamento, testes e revisão: arquitetura para agentes qu |
| Não há registro de execuções para auditoria | Tracing/log desativado ou mal configurado | Ative e valide o tracing no SDK utilizado | Versionamento, testes e revisão: arquitetura para agentes qu |
| Status do vídeo permanece em 'waiting' ou 'generating' por muito tempo | Fila alta ou parâmetros complexos demais para o modelo | Reduza a complexidade do prompt e referências; tente novamente em horário de menor demanda | Video Agent e cinematic_avatar: vídeo a partir de prompt e r |
| Status retorna 'failed' | Erro de configuração ou referência inválida | Revise o payload, URLs de referência e IDs de avatar; corrija e reenvie | Video Agent e cinematic_avatar: vídeo a partir de prompt e r |
| Vídeo gerado com erros de contexto ou fala | Prompt pouco claro ou referências ambíguas | Refine o prompt, especifique melhor as referências e repita o processo | Video Agent e cinematic_avatar: vídeo a partir de prompt e r |
| Vídeo fica travado no status 'generating' | Fila de processamento alta no HeyGen ou erro de configuração. | Aguarde alguns minutos e revise os parâmetros enviados. | Vídeo de treinamento a partir de um parágrafo e em três idio |
| Voz incompatível ou qualidade de áudio insatisfatória. | voice_id incompatível com o idioma de destino. | Liste as vozes disponíveis e escolha uma voz nativa para cada idioma. | Vídeo de treinamento a partir de um parágrafo e em três idio |
| Mensagem no vídeo está incompleta | Limite de caracteres ou erro no prompt. | Garanta que o texto original não ultrapasse o limite e revise a tradução. | Vídeo de treinamento a partir de um parágrafo e em três idio |
| Status 'failed' ao criar vídeo | Parâmetro obrigatório ausente ou valor inválido. | Confira se avatar_id, voice_id e idioma estão corretos. | Vídeo de treinamento a partir de um parágrafo e em três idio |
| O agente executa ações críticas sem pedir aprovação | Checkpoint ou handoff não implementado corretamente | Revise o contrato da ferramenta e a configuração de handoff no SDK | Visão de futuro: fluxos autônomos, supervisão e o papel do h |
| Logs de decisão estão incompletos | Registro automático não ativado ou campos ausentes | Habilite tracing e revise o schema de log | Visão de futuro: fluxos autônomos, supervisão e o papel do h |
| Dados sensíveis aparecem no prompt | Falta de sanitização ou uso incorreto de variáveis de ambiente | Implemente filtros e nunca insira segredos diretamente no prompt | Visão de futuro: fluxos autônomos, supervisão e o papel do h |
| Agente toma decisão sem pedir aprovação | Fluxo de revisão humana não implementado corretamente | Inclua etapa obrigatória de aprovação manual antes de ações irreversíveis | Visão do futuro: agentes autônomos e fiscalização assistida |
| Ferramenta retorna erro de tipo | Contrato de parâmetros ou retorno inconsistente | Revise definição de tipos e contratos das ferramentas | Visão do futuro: agentes autônomos e fiscalização assistida |
| Tracing não registra execuções | Tracing não ativado no SDK | Ative tracing ao instanciar o agente | Visão do futuro: agentes autônomos e fiscalização assistida |
| Relatório de validação incompleto | Casos de teste insuficientes ou prompt pouco claro | Amplie casos de teste e refine o prompt de sistema | Visão do futuro: agentes autônomos e fiscalização assistida |
| Erro 401 ao chamar APIs | Chave de API ausente ou inválida | Verifique as variáveis de ambiente e o valor das chaves | Visão, voz e vídeo: agentes que explicam, demonstram e regis |
| Áudio gerado está em idioma errado | Model_id ou voice_id incompatível com português | Use model_id e voice_id compatíveis com PT-BR | Visão, voz e vídeo: agentes que explicam, demonstram e regis |
| Vídeo não aparece após envio ao HeyGen | Processamento ainda em andamento ou erro de parâmetros | Aguarde o status 'completed' e revise os parâmetros enviados | Visão, voz e vídeo: agentes que explicam, demonstram e regis |
| O áudio não é gerado ou está cortado. | Texto acima do limite de caracteres do modelo TTS. | Divida o texto em partes menores, respeitando o limite do modelo. | Voz e vídeo no ciclo de planejamento: ElevenAgents e HeyGen |
| O vídeo não finaliza ('waiting' ou 'generating' indefinidamente). | Script longo, avatar inválido ou formato não suportado. | Reduza o script, valide avatar_id e use formatos suportados. | Voz e vídeo no ciclo de planejamento: ElevenAgents e HeyGen |
| Erro 401 ao chamar as APIs. | Chave de API ausente ou inválida. | Verifique as variáveis de ambiente e gere nova chave se necessário. | Voz e vídeo no ciclo de planejamento: ElevenAgents e HeyGen |
| Arquivo de áudio vazio ou corrompido | Chave de API inválida ou parâmetros ausentes | Verifique as variáveis de ambiente e os parâmetros enviados | Voz e vídeo no marketing: ElevenLabs, HeyGen e integração ao |
| Vídeo não finaliza o processamento | Script muito longo ou avatar/voz incompatíveis | Reduza o texto ou troque avatar/voz para opções suportadas | Voz e vídeo no marketing: ElevenLabs, HeyGen e integração ao |
| Erro 401 ao chamar API | Autenticação ausente ou incorreta | Confirme se a chave de API está correta e ativa | Voz e vídeo no marketing: ElevenLabs, HeyGen e integração ao |
| O áudio do agente está em inglês ou com pronúncia errada. | Configuração do idioma ou voice_id incompatível. | Verifique se 'language' e 'voice_id' estão para português (pt-BR) e se o modelo TTS suporta o idioma. | Voz e vídeo no NOC: ElevenAgents e HeyGen em fluxos de comun |
| O vídeo gerado não corresponde ao script enviado. | Erro no campo 'script' ou processamento incompleto. | Confirme o conteúdo do JSON enviado e aguarde o status 'completed' antes de baixar. | Voz e vídeo no NOC: ElevenAgents e HeyGen em fluxos de comun |
| Chave de API rejeitada. | Chave inválida ou variável de ambiente não definida. | Gere nova chave e exporte corretamente no ambiente. | Voz e vídeo no NOC: ElevenAgents e HeyGen em fluxos de comun |
| Áudio não é reproduzido | Formato de saída incompatível ou arquivo corrompido | Confirme que o output_format está em mp3_44100_128 ou outro suportado pelo player | Voz e vídeo: conectando ElevenLabs, ElevenAgents e HeyGen ao |
| Vídeo do HeyGen fica travado em 'waiting' | Processamento pendente ou parâmetros inválidos | Revise os campos obrigatórios e aguarde o tempo de processamento típico | Voz e vídeo: conectando ElevenLabs, ElevenAgents e HeyGen ao |
| Erro 401 ao chamar APIs | Chave de API ausente ou inválida | Verifique as variáveis de ambiente e o cabeçalho de autenticação | Voz e vídeo: conectando ElevenLabs, ElevenAgents e HeyGen ao |
| O áudio ou vídeo sai em inglês, mesmo com script em português. | Parâmetro de idioma (language ou locale) não definido corretamente. | Defina sempre 'pt-BR' nos campos de idioma e voz. | Voz e vídeo: ElevenAgents e HeyGen na comunicação estratégic |
| A voz está robótica ou monótona. | Falta de ajuste em 'voice_settings' ou escolha de modelo TTS inadequado. | Ajuste 'expressiveness' e teste diferentes modelos de voz. | Voz e vídeo: ElevenAgents e HeyGen na comunicação estratégic |
| O vídeo não finaliza (status não sai de 'waiting'). | Script muito longo ou erro de configuração. | Reduza o tamanho do script e revise os parâmetros obrigatórios. | Voz e vídeo: ElevenAgents e HeyGen na comunicação estratégic |
| O áudio gerado não está em português. | O model_id ou locale está incorreto. | Use model_id 'eleven_multilingual_v2' e locale 'pt-BR'. | Voz e vídeo: ElevenAgents, ElevenLabs e HeyGen no fluxo deci |
| A transcrição da aprovação por voz está incompleta. | Áudio de baixa qualidade ou formato incompatível. | Garanta áudio claro e formato suportado (WAV, MP3). | Voz e vídeo: ElevenAgents, ElevenLabs e HeyGen no fluxo deci |
| O vídeo do HeyGen não processa ou retorna erro 400. | Parâmetros obrigatórios ausentes ou inválidos. | Revise avatar_id, script e voice_id; preencha todos os campos obrigatórios. | Voz e vídeo: ElevenAgents, ElevenLabs e HeyGen no fluxo deci |
| O áudio gerado está incompleto ou corrompido. | Texto de entrada muito longo ou formato incompatível. | Divida o texto em partes menores e verifique o encoding do arquivo. | Voz e vídeo: integração do agente com ElevenLabs e HeyGen |
| O vídeo do HeyGen não finaliza ('status' parado em 'waiting'). | Parâmetros inválidos ou avatar_id/voice_id incorretos. | Revise os IDs enviados e teste com valores de EXEMPLO fornecidos pela plataforma. | Voz e vídeo: integração do agente com ElevenLabs e HeyGen |
| Erro 401 (não autorizado) ao chamar as APIs. | Chave de API ausente ou inválida. | Confirme as variáveis de ambiente e gere uma nova chave se necessário. | Voz e vídeo: integração do agente com ElevenLabs e HeyGen |
| O áudio não corresponde ao texto do resumo | Texto enviado ao TTS diferente do prompt ou erro de concatenação | Verifique o texto enviado e padronize o processo de geração | Voz e vídeo: integração do ElevenAgents e HeyGen no fluxo de |
| Vídeo gerado sem áudio ou com voz errada | voice_id incompatível ou ausência do campo no payload | Confirme voice_id e model_id suportados no HeyGen e ElevenLabs | Voz e vídeo: integração do ElevenAgents e HeyGen no fluxo de |
| Agente não acessa ferramentas externas | Endpoints REST não disponíveis ou contratos inconsistentes | Implemente contratos claros e teste com dados de exemplo | Voz e vídeo: integração do ElevenAgents e HeyGen no fluxo de |
| Logs incompletos ou ausência de tracing | Falta de instrumentação no código do agente | Implemente registro detalhado de cada ação | Voz e vídeo: integração do ElevenAgents e HeyGen no fluxo de |
| Áudio sai em inglês mesmo com texto em português | Parâmetro locale ou model_id incorreto | Use model_id 'eleven_multilingual_v2' e locale 'pt-BR' | Voz, vídeo e RH: conectando ElevenLabs, ElevenAgents e HeyGe |
| Vídeo demora para ficar pronto | Tempo de processamento depende da duração e resolução | Acompanhe status pelo video_id e ajuste resolução se necessário | Voz, vídeo e RH: conectando ElevenLabs, ElevenAgents e HeyGe |
| Erro 401 ao chamar API | Chave de API ausente ou inválida | Verifique variável de ambiente e permissões da chave | Voz, vídeo e RH: conectando ElevenLabs, ElevenAgents e HeyGe |
| Áudio não corresponde ao texto enviado | Texto enviado diferente do esperado ou erro de codificação | Confirme o texto de entrada e valide com transcrição automatizada | Voz, vídeo e RH: conectando ElevenLabs, ElevenAgents e HeyGe |
| O agente não responde por voz | Configuração incorreta de idioma ou voz no ElevenAgents | Verifique se 'language' está como 'pt-BR' e 'voice_id' válido | Voz, vídeo e workflow: ElevenAgents e HeyGen no atendimento |
| Vídeo não é gerado no HeyGen | Parâmetros obrigatórios ausentes ou avatar_id inválido | Confirme avatar_id, script e voice_id no payload | Voz, vídeo e workflow: ElevenAgents e HeyGen no atendimento |
| Respostas não aparecem no registro do caso | Workflow não está salvando arquivos multimodais | Implemente rotina de anexação e logging após cada resposta | Voz, vídeo e workflow: ElevenAgents e HeyGen no atendimento |
| O widget não responde ou retorna erro ao carregar | agent_id incorreto ou script JavaScript mal inserido | Verifique o agent_id e a posição do script no HTML | Widget de voz no site que responde pela base de conhecimento |
| Respostas erradas ou inventadas para perguntas fora da base | Prompt de sistema mal definido ou base de conhecimento abrangente demais | Ajuste o prompt para limitar o escopo e revise a base | Widget de voz no site que responde pela base de conhecimento |
| Base de conhecimento não aparece como opção no painel | Indexação incompleta ou erro no upload | Reenvie os arquivos e aguarde a indexação | Widget de voz no site que responde pela base de conhecimento |
| Widget responde em inglês | Idioma não configurado corretamente no agente ou widget | Defina 'pt-BR' no campo language da configuração | Widget de voz no site que responde pela base de conhecimento |
| Workflow para no meio sem erro claro | Estado não persistido corretamente ou exceção não tratada | Implemente persistência robusta e logging detalhado | Workflows automáticos: encadeando agentes e ferramentas |
| Agente recebe contexto incompleto | Contrato de entrada/saída mal definido entre agentes | Padronize schemas e valide entradas/saídas com MCP | Workflows automáticos: encadeando agentes e ferramentas |
| Resultado inesperado após retomada | Contexto salvo de forma inconsistente | Garanta atomicidade ao salvar estado e teste retomada em ambiente controlado | Workflows automáticos: encadeando agentes e ferramentas |
| Vídeo nunca fica pronto | Webhook não configurado ou polling insuficiente | Verifique configuração de webhook no painel HeyGen ou aumente frequência de polling | Workflows automáticos: geração, revisão e publicação de víde |
| Arquivo publicado está corrompido | Validação insuficiente ou bypassada | Reforce as checagens automáticas e bloqueie publicação sem validação | Workflows automáticos: geração, revisão e publicação de víde |
| Alertas não chegam à equipe | Token ou canal de notificação incorretos | Revise credenciais e canais nos scripts de alerta | Workflows automáticos: geração, revisão e publicação de víde |
