Databricks Certified Context Engineer Associate

O que é context engineering

Prompt engineering otimiza uma instrução. Context engineering decide tudo o que entra na janela a cada passo: instruções, histórico, documentos recuperados, resultados de ferramentas, memória. A janela é um orçamento de atenção — mais tokens nem sempre ajudam (o desempenho cai bem antes do limite).

Os quatro modos de falha

Falha	O que acontece	Exemplo
Poisoning	Uma informação errada (alucinação, dado incorreto) entra no contexto e passa a ser reutilizada	O agente "lembra" de um fato inventado e o cita em todos os passos
Distraction	O contexto fica tão longo que o modelo se apega ao histórico e para de usar o que aprendeu / de planejar	Repete ações antigas em vez de pensar no passo novo
Confusion	Conteúdo supérfluo/irrelevante (ferramentas demais, sessão antiga) é usado para gerar a resposta	Mistura cláusulas de um contrato de outra sessão
Clash	Partes do contexto se contradizem	Duas fontes com valores diferentes para a mesma regra

Estratégias proativas

• Conjunto mínimo de ferramentas por tarefa;
• Recuperação just-in-time (buscar quando precisar, não carregar tudo antes);
• Escopo do resultado das ferramentas (retornar só os campos necessários, paginar);
• isolar sessões e limpar histórico irrelevante.

Stack Databricks

Necessidade	Ferramenta
Governar dados, ferramentas (funções) e metadados	Unity Catalog
Memória/estado persistente, de baixa latência	Lakebase (Postgres gerenciado)
Conectar ferramentas e fontes de forma padronizada	MCP
Rastrear, avaliar e comparar configurações	MLflow 3 (tracing, evaluate)

Modo de raciocínio

Extended thinking para tarefas de várias etapas, ambíguas, com planejamento — custa tokens e ocupa janela. Reduzido/padrão para tarefas simples, de baixa latência ou alto volume.

Degradação por tamanho

Sinal: a partir de certo ponto (ex.: ~75% da janela) o agente cita errado e ignora restrições. Intervenção: compactação (resumo de alta fidelidade + itens recentes), não simplesmente truncar ou trocar por um modelo de janela maior.

Genie space pronto para produção

• Instruções gerais: vocabulário do domínio ("rates desk = product_type X e business_unit Y", "bps = pontos-base", "última fixing = data mais recente da tabela de taxas").
• Trusted assets: SQL validado para perguntas críticas/recorrentes.
• SQL expressions (medidas, filtros, dimensões) para métricas.
• Perguntas de exemplo orientam o usuário — não ensinam vocabulário ao modelo.

Few-shot com orçamento

Cada exemplo custa tokens. Mantenha os que trazem informação nova: um caminho de ferramenta ainda não coberto, o formato de saída exigido, um caso ambíguo. Corte exemplos redundantes (vários casos "fáceis" iguais).

Revisão pontual

Falhou num padrão específico? Adicione uma regra curta e explícita para aquele caso, em vez de reescrever o prompt inteiro ou anexar dezenas de exemplos.

Comparar prompts

No MLflow, compare a qualidade e o custo (tokens, latência) dos dois prompts no mesmo dataset. A versão longa se justifica se o ganho de qualidade vem de um elemento identificável (ex.: um bloco de regras) — às vezes dá para manter só esse elemento.

Metadados importam

Genie e agentes usam comentários de tabela/coluna, tags e descrições do UC. Coluna vl_liq sem comentário é um chute; com "valor líquido em BRL, após descontos" vira resposta certa. Prioridade: descrições das colunas mais consultadas, chaves de join e valores categóricos.

Curadoria do Genie

Poucas tabelas gold/certificadas e views do domínio, mais funções SQL e queries parametrizadas para lógicas críticas. Evite despejar o schema inteiro.

AI Search (Vector Search)

Problemas e causas comuns:

Sintoma	Causa provável	Correção
Texto desatualizado mesmo com a tabela atualizada	Índice TRIGGERED sem sync	Job chama sync após a carga (barato) ou CONTINUOUS (caro)
Trechos irrelevantes	Chunks grandes/heterogêneos, sem filtro	Rechunking, filtros de metadados, reranking
Termos exatos (códigos, siglas) não são achados	Só busca semântica	Hybrid search

Chunking

Documentos de tamanho e estrutura variados, perguntas amplas e específicas → splitter recursivo de ~512–1.024 tokens com 10–15% de overlap. Documento inteiro como chunk dilui o embedding; frase por chunk perde contexto.

Pré-inferência x just-in-time

• Pré-inferência: buscar documentos antes e colocar no prompt — bom para perguntas previsíveis sobre um corpus estável.
• Just-in-time: o agente chama ferramentas (busca, SQL em Delta) quando precisa — bom para dados dinâmicos, tarefas de várias etapas e para economizar contexto.

Fontes autoritativas

Restrinja o espaço de busca antes do deploy: permissões do agente (service principal) só nos catálogos/schemas autoritativos, índices construídos só de tabelas certificadas, tags (certificado = sim) como filtro, e excluir cópias derivadas/rascunhos.

Tipos de memória

Tipo	Vive onde	Exemplo
Sessão / curto prazo	Histórico da conversa (checkpoint do thread)	"o pedido que mencionei acima"
Longo prazo	Lakebase/Delta, entre sessões	Preferências do cliente, decisões anteriores
Estado de tarefa	Objeto persistido (Delta/Lakebase)	Passo 7 de 20, resultados parciais

Erros típicos: buscar no longo prazo algo que está na sessão atual, ou depender do histórico da sessão para algo que exige persistência entre sessões.

Scratchpad x estado persistido

Tarefa curta e única → scratchpad no contexto. Tarefa longa, retomável, com vários agentes ou que precisa de auditoria → estado persistido (tabela), lido sob demanda.

Recuperação no Lakebase

• Pergunta semântica ("o que o cliente disse sobre entrega?") → busca vetorial (AI Search).
• Pergunta exata/estruturada ("último pedido do cliente 42", "preferências do usuário X") → SQL.

LangGraph + Lakebase

from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

async with AsyncPostgresSaver(pool) as checkpointer:   # pool async do Lakebase
    await checkpointer.setup()                          # cria as tabelas do checkpoint
    grafo = builder.compile(checkpointer=checkpointer)
    await grafo.ainvoke(entrada, config={"configurable": {"thread_id": "cliente-42"}})

Excesso x falta

Over-retrieval polui o contexto (confusion/distraction); under-retrieval perde fatos e gera respostas inconsistentes. Ajuste k, filtros e limiar de similaridade e meça no MLflow.

Resolver a intenção primeiro

Se as respostas são "corretas mas fora do contexto do usuário", reescreva/classifique a pergunta (intenção, entidades, período) antes de recuperar — senão a busca traz o assunto certo para a pergunta errada.

Comparar configurações

Escolha a configuração que vai bem em todas as métricas (ex.: no gráfico de coordenadas paralelas do MLflow), não a de maior média nem a de um pico isolado.

Progressive disclosure

Em vez de colocar os schemas de 60 ferramentas no prompt:

1. o agente vê um catálogo enxuto (nome + uma linha);
2. a etapa de descoberta escolhe as candidatas pela intenção e só então carrega o schema completo delas;
3. o resultado da execução entra resumido/escopado. Menos tokens fixos, menos confusão.

Ferramentas que se confundem

get_order_status × fetch_order_status × lookup_order_details com descrições quase iguais → seleção inconsistente. Solução: descrições distintas e específicas (o que retorna, quando usar, quando NÃO usar), e a descoberta mostrar só a melhor candidata — ou consolidar.

Limpeza de saídas antigas

Com a janela enchendo, as primeiras candidatas a sair são saídas brutas de ferramentas já consumidas (JSON enorme cujo resultado já foi resumido/usado). Mantenha decisões, restrições do usuário e resultados ainda necessários.

Escolha de ferramenta no UC

Compare função (faz o que a tarefa pede?), entrada/saída (parâmetros que você tem, retorno que precisa) e restrições (permissões, latência).

Agent Skills

Capacidades raras (ex.: "gerar relatório regulatório trimestral") saem do system prompt e viram skills carregadas sob demanda: só uma descrição curta fica no contexto base; as instruções completas entram quando a skill é acionada.

O que a compactação precisa preservar

Além dos fatos descobertos: decisões tomadas, restrições, exclusões e preferências do usuário, tarefas pendentes, identificadores (ids, nomes de arquivos). Se o agente passa a contradizer decisões anteriores depois de compactar, foi isso que se perdeu. Exemplo de revisão barata: "Resuma as descobertas e inclua uma lista deduplicada das restrições, exclusões e preferências declaradas pelo usuário."

Afinar o prompt

1. Recall primeiro: o resumo captura tudo o que os passos seguintes usam? (teste no trace)
2. Depois precisão: corte o que nunca é usado (saídas brutas, tentativas descartadas).

Heurística x compactação

Truncar as mensagens mais antigas funciona quando só o recente importa. Se informação antiga continua relevante (restrições do início, decisões), precisa de compactação com resumo.

Seguro remover

Saídas brutas já resumidas, chamadas que falharam e foram refeitas, raciocínio intermediário já concluído, conteúdo duplicado.

Agressiva x conservadora

	Agressiva	Conservadora
Tokens	Poucos	Muitos
Risco	Perder nuance	Custo e menos espaço livre
Bom para	Tarefas com dependências curtas	Tarefas longas com dependências distantes

Contexto compartilhado

Subagentes que recebem só "faça X" não sabem das decisões e restrições do coordenador → resultados conflitantes. Solução: anexar um resumo compacto do trace/decisões a cada despacho (não o trace inteiro).

Saídas dos subagentes

Para não saturar o orquestrador, subagentes devolvem resultados estruturados e resumidos (campos definidos, conclusões, referências), não o log completo do que fizeram.

Fronteiras

• Agentes demais, fatiados fino → muito handoff e perda na compressão a cada passagem.
• Agentes de menos → um agente acumula contexto até estourar. Corte por domínios coesos com interfaces claras.

Dados desatualizados ≠ falta de contexto

Se todos os subagentes estão consistentes entre si mas desatualizados, e leem de um índice, suspeite primeiro do índice sem sync — não da propagação de contexto.

Estratégias de longo horizonte

Estrutura da tarefa	Estratégia
Passos independentes	Paralelizar subagentes
Passos fortemente dependentes	Execução sequencial com estado persistido e compactação
Muito longa e retomável	Checkpoints + memória externa (Lakebase) + plano explícito atualizado