Melhores Práticas para Agentes de IA

Regras para construir sistemas e agentes RAG fundamentados, observáveis e controláveis.

Como Usar Esta Lista

• As Regras A-B cobrem a qualidade da recuperação e da geração.
• As Regras C-D governam a segurança do agente e o uso de ferramentas.
• As Regras E-F cobrem operações e avaliação.

A - Qualidade da Recuperação

• Divida em blocos com tamanho e sobreposição apropriados. 500-1000 caracteres para prosa; avalie recall@k.
• Armazene metadados com cada bloco. fonte, doc_id, página, seção para filtragem e citação.
• Use busca híbrida para produção. Combine BM25 e recuperação densa; reclassifique os principais candidatos.
• Fixe o modelo de embedding por índice. Nunca misture modelos ou dimensões em uma coleção.
• Retorne "Não sei" quando a recuperação estiver vazia. Não gere a partir de contexto irrelevante.

B - Qualidade da Geração

• Instrua o modelo a usar apenas o contexto. Prompt do sistema com regras explícitas de fundamentação.
• Cite fontes nas respostas. Inclua referências de blocos para verificação do usuário.
• Valide saídas estruturadas com Pydantic. Tente novamente em caso de falha na validação (máximo 3).
• Separe a avaliação de recuperação e geração. Recuperação ruim não pode ser resolvida apenas com engenharia de prompt.
• Temperatura=0 para QA factual. Temperatura mais alta apenas para tarefas criativas.

C - Segurança do Agente

• Valide argumentos de ferramentas antes da execução. Esquemas Pydantic em cada ferramenta.
• Limite as permissões das ferramentas ao mínimo necessário. Somente leitura por padrão; aprovação para escrita.
• Defina iterações máximas em loops de agente. 5-10 iterações evitam chamadas de ferramentas descontroladas.
• Execute ferramentas de execução de código em sandbox. Contêineres isolados com limites de recursos.
• Registre cada chamada de ferramenta. Nome, argumentos, resultado, latência para auditoria e depuração.

D - Observabilidade

• Trace o pipeline RAG completo. Consulta, blocos recuperados, prompt, resposta, latência.
• Monitore o recall da recuperação em produção. Amostre consultas com documentos relevantes conhecidos.
• Acompanhe o feedback do usuário. Botões de positivo/negativo vinculados à consulta e ao contexto recuperado.
• Alerta sobre falhas de fidelidade. LLM como juiz ou verificações heurísticas em CI.
• Versionamento conjunto de índice e prompts. Registre a versão do índice com cada resposta.

E - Arquitetura

• Comece simples: SDK bruto + banco de dados vetorial. Adicione LangChain/LlamaIndex quando a complexidade justificar.
• Use LangGraph para agentes multi-etapas. Não use loops while manuais em produção.
• Cache de consultas frequentes. Hash da consulta + versão do índice; retorne respostas em cache.
• Projete para atualizações de índice. upsert/delete por doc_id sem reindexação completa.
• Separe os caminhos de ingestão dos de consulta. Ingestão em lote offline; consulta em tempo real online.

F - Avaliação

• Construa o conjunto de avaliação antes do lançamento. Mínimo de 20+ pares de consulta-resposta rotulados.
• Execute a avaliação em CI a cada alteração. Alterações de prompt, modelo, chunking ou índice.
• Teste entradas adversárias. Injeção de prompt, consultas vazias, perguntas fora do tópico.
• Meça a latência de ponta a ponta. Orçamentos de p50/p99 de recuperação + geração.
• Revisão humana antes da produção. Verifique 50 respostas no conjunto de avaliação.

FAQs

Relacionados

• Noções Básicas de RAG
• Avaliação e Guardrails
• Uso de Ferramentas e Chamada de Funções
• Melhores Práticas de LLMs
• Monitoramento e Drift

Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.