Melhores práticas para engenharia de contexto

A contextualização eficaz garante que seu agente tenha acesso ao conhecimento certo, no momento certo, para a tarefa atual. Quando implementada corretamente, aumenta a precisão, melhora o desempenho e reduz os custos com tokens.

Esta seção descreve como configurar e manter suas fontes de contexto usando contextualização, incluindo melhores práticas para configuração de índice, projeto de esquemas e avaliação contínua.

Para obter detalhes sobre o serviço de contextualização, consulte a documentação dedicada: Sobre a contextualização.

Entenda o que é contextualização

Os agentes se conectam ao conhecimento da empresa, como documentos, perguntas frequentes, e-mails e SOPs, por meio da contextualização.Você cria índices no Orchestrator e os anexa a agentes no Studio Web para habilitar essa conexão.

A contextualização ajuda os agentes a:

• Raciocinar sobre dados específicos de negócios.
• Evitar alucinações ou fabricações.
• Responder com conhecimento atualizado e governado.
• Citar fontes quando configuradas com restrições de esquema.

Melhores práticas para configurar a contextualização

Para criar agentes confiáveis e responsivos, siga estas práticas fundamentais ao projetar e ajustar seu contexto:

Use nomes de índice descritivos e versionados

Nomeie seus índices usando um padrão claro e consistente. Exemplo: HR-Policies-2025-Q3.

Isso facilita o seguinte:

• Voltar para as versões de índice anteriores.
• Executar testes A/B com diferentes bases de conhecimento.
• Acompanhar as atualizações ao longo do tempo.

Crie um novo índice no Orchestrator quando o conteúdo mudar significativamente e atualize devidamente a definição do agente.

Escolha o modo de ingestão certo

Ao criar um índice, selecione o modo de ingestão que se ajusta ao seu conteúdo:

• Modo básico: ideal para documentos com texto simples predominante.
• Modo avançado: use para arquivos que combinam texto e imagens (por exemplo, PDFs digitalizados ou infográficos).

Isso afeta a cobertura e os custos relacionados ao OCR. Escolha com base no tipo de documentos e na importância do conteúdo visual para a recuperação.

Mantenha uma cadência regular de sincronização

Manter os índices atualizados garante que os agentes façam referência a informações atualizadas.Use a ação Sincronizar no Orchestrator ou a atividade Atualizarc ontextualização no Studio para atualizar o conteúdo do índice. Você pode agendar sincronizações periódicas com base na frequência de atualização do seu conteúdo de origem.

Calibre o número de resultados e a pontuação limite

• Número de resultados: ajuste essa configuração para controlar quantos pedaços de contexto são recuperados. Mais resultados aumentam a recuperação, mas também expandem o uso de tokens.
• Limite: filtra o contexto de baixa relevância. O valor padrão é 0. Você pode elevá-lo para melhorar a precisão se muitas passagens não relacionadas estiverem sendo retornadas. No entanto, observe que definir o valor limite acima de 0 (zero) significa que partes relevantes podem ser filtradas das respostas, o que pode levar a discrepâncias.

Balance esses parâmetros para garantir o contexto de alto sinal sem exceder os limites de token.

Use descrições de contexto claras no projeto de agentes

Ao adicionar um índice de contexto a um agente, forneça uma descrição breve e precisa do que o índice contém. Isso ajuda a orientar a recuperação e o uso do conhecimento por parte do agente durante a execução.

As descrições são particularmente úteis ao usar várias fontes de contexto.

Alinhe o esquema com as expectativas do agente.

Defina um esquema de resposta quando aplicável, especialmente para saída estruturada como JSON. Isso garante que o agente formate as respostas corretamente e inclua apenas informações do contexto.

Inclua exemplos do esquema em seus prompts do sistema para melhorar a confiabilidade.

Quando e como iterar

Revisitar a configuração de contexto quando:

• Os agentes não estão atingindo os resultados esperados.
• Conteúdo irrelevante aparece nos rastreamentos.
• Os agentes excedem os limites de tokens ou falham com erros de "tokens excedidos".
• Os esquemas de documentos mudam.
• Ocorre um novo caso de uso ou expansão de escopo.

Use logs de rastreamento de execuções de teste e produção para diagnosticar se o problema é com parâmetros de qualidade, quantidade ou indexação de contexto.

Erros comuns e como corrigi-los

Use esta tabela para identificar e resolver problemas comuns de contextualização. Cada linha destaca um sinal de detecção que você pode observar nos rastreamentos e as ações recomendadas para corrigi-lo.

Tabela 1. Solução de problemas de contextualização

Erro	Sinal de detecção	Correção recomendada
O agente não está respondendo conforme o esperado, mesmo que deva ter documentos relevantes no índice	Nenhum resultado foi encontrado	Confirme os dados mais recentes, adicione documentos relevantes e sincronize o índice Limiar inferior.
Respostas esperadas ausentes	O rastreamento mostra filtros de limites altos	Reduza o limite ou melhore a cobertura do documento
Estouro da janela de contexto	O agente falha com "tokens excedidos"	Reduza o número de resultados ou encurte a entrada do usuário
Informações obsoletas retornadas	O rastreamento mostra um carimbo de data/hora desatualizado	Sincronize ou recrie o índice; republique o agente

Avaliação da qualidade do contexto

Use execuções de avaliação no Agent Builder para testar como suas fontes de contexto apoiam os objetivos do agente.

As execuções de avaliação devem:

• Incluir prompts diversos e do mundo real.
• Revisar os rastreamentos para inspecionar quais partes foram recuperadas.
• Incluir testes de regressão ao atualizar ou substituir índices.

Você também pode simular execuções usando simulações de ferramentas com contexto simulado para prever o desempenho antes de confirmar uma atualização de índice completa.

Lista de verificação resumida

Use a lista de verificação a seguir para garantir que sua configuração de contextualização siga as melhores práticas:

• Os nomes dos índices são versionados e descritivos.
• O modo de ingestão corresponde ao tipo de documento.
• Os índices são sincronizados regularmente.
• O número de resultados e o limite estão ajustados.
• As descrições de contexto são informativas.
• O esquema é definido e aplicado no prompt.
• Os erros comuns são rastreados e resolvidos usando logs de rastreamento.

Exemplo de modelos de prompts

Use os seguintes modelos como ponto de partida para seu prompt do Sistema do Agente. Personalize-os para se adequar ao seu caso de uso específico.

Pesquisa de GQ/conhecimento

Você é um assistente de conhecimento empresarial.

Objetivo: responder a perguntas dos usuários usando APENAS documentos da empresa aprovados.

Restrições:

• Cite cada resposta com o título e a seção da origem.
• Se a confiança estiver baixa ou nenhum contexto relevante tiver sido recuperado, faça uma pergunta de esclarecimento em vez de suposições.
• Responda em Markdown, a menos que JSON seja solicitado.

Etapas do processamento

1. Interpretar a pergunta do usuário.
2. Revise o contexto recuperado abaixo.
3. Use apenas informações encontradas no contexto; não criar.
4. Forneça uma resposta concisa e registre as fontes.

Extração e validação estruturadas

Você é um agente de extração que mapeia o conteúdo de documentos em um esquema estruturado.

Objetivo: preencher todos os campos obrigatórios de fragmentos de documentos recuperados.

Restrições:

• Retorne JSON válido correspondente ao esquema.
• Use nulo se o campo não for encontrado; NÃO adivinhe.
• Forneça uma pontuação de confiança 0 — 1 para cada campo.
• Inclua os metadados de origem_span (doc_id, chunk_id).

Etapas

1. Leia as instruções do usuário para o tipo de documento de destino.
2. Revise o contexto recuperado.
3. Campos de extração.
4. Validar campos obrigatórios; solicite o escalonamento se houver valores críticos ausentes.

Raciocínio e seleção de ações

Você é um agente de triagem de operações.

Objetivo: decidir a próxima melhor ação com base nas políticas e nos detalhes do caso atual.

Restrições:

• Escolha apenas da lista de ações permitidas.
• Forneça uma breve justificativa.
• Saída como JSON: {"action":string,"reason":string,"evidence_sources":[...]}

Ações permitidas

{{ACTION_LIST}}