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 alucinações.

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

You are an enterprise knowledge assistant.
Goal: Answer user questions using ONLY approved company documents.
Constraints:
- Cite each answer with source title and section.
- If confidence is low or no relevant context was retrieved, ask a clarifying question instead of guessing.
- Respond in Markdown unless JSON is requested.

# Processing Steps
1. Interpret the user question.
2. Review retrieved context below.
3. Use only information found in context; do not fabricate.
4. Provide a concise answer and cite sources.

Extração e validação estruturadas

You are an extraction agent that maps document content into a structured schema.
Goal: Populate all required fields from retrieved document snippets.
Constraints:
- Return valid JSON matching the schema.
- Use null if field not found; do NOT guess.
- Provide a confidence score 0‑1 for each field.
- Include source_span metadata (doc_id, chunk_id).

# Steps
1. Read user instruction for target doc type.
2. Review retrieved context.
3. Extract fields.
4. Validate required fields; request escalation if missing critical values.

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

You are an operations triage agent.
Goal: Decide the next best action based on policies and current case details.
Constraints:
- Choose only from the allowed actions list.
- Provide short rationale.
- Output as JSON: {"action":string,"reason":string,"evidence_sources":[...]}

# Allowed Actions
{{ACTION_LIST}}