Como organizar o conhecimento dos seus Agentes

📋Tables

Quando usar

Tables são bancos de dados estruturados e vivos. Cada linha é um registro. Cada coluna é um campo tipado. O agente lê, cria, atualiza e exclui via Table Actions.

Use Tables quando:

Os dados mudam com frequência e precisam ser escritos pelo agente em tempo real
Os dados têm uma estrutura fixa e previsível — colunas definidas com tipos
Você precisa persistir informações entre conversas
O caso de uso envolve operações CRUD

Exemplos:

Leads: nome, e-mail, telefone, status, data de contato
Estoque: SKU, nome, preço, quantidade em estoque
Agenda: cliente, data, horário, tipo de serviço
Tickets: ID, descrição, status, responsável

Regra de ouro: se o agente vai escrever nesses dados, é uma Table.

Colunas de URL e Imagem

Tables funcionam com colunas tipadas. Além dos tipos básicos (texto, número, booleano, data), existem dois tipos especializados para referências externas.

Coluna URL

Armazena endereços web como o valor principal da célula. O sistema reconhece esse campo como um link — não como texto genérico.

Quando usar:

Cada registro tem um link associado que o agente precisa retornar
Catálogos com link para uma página de compra
Artigos com link de acesso externo
Registros com links para formulários, vídeos ou landing pages

Exemplo:

Table: Catálogo de Cursos

nome (texto): “Marketing Digital Avançado”
categoria (texto): “Marketing”
preço (número): 497
link_matricula (URL): https://site.com/courses/marketing
ativo (booleano): true

Coluna Imagem

Armazena URLs que apontam para arquivos de imagem. A diferença em relação ao tipo URL é a semântica visual — o sistema sabe que o conteúdo é uma imagem.

Quando usar:

Catálogos de produtos com fotos
Cardápios digitais
Portfólios com miniaturas
Perfis com avatares

Exemplo:

Table: Cardápio

nome (texto): “Frango Grelhado”
preço (número): 18,90
foto (imagem): https://cdn.restaurant.com/chicken.jpg
disponível (booleano): true

Aspecto	URL	Imagem
Conteúdo	Qualquer link	Link para um arquivo de imagem
Renderização	Link clicável	Imagem exibida (quando suportado)
Uso típico	Página, formulário, vídeo	Foto de produto, miniatura

Busca semântica e itens não pesquisáveis

A busca semântica em Tables é fundamentalmente diferente de uma query SQL.

Correspondência exata:

SELECT * FROM products WHERE name = 'nike sneaker'
-- Only finds if the field is exactly "nike sneaker"

Busca semântica:

Query: “calçado esportivo para corrida”
→ Encontra: “Tênis Nike Air Max”, “Tênis de Corrida Adidas”
→ Mesmo sem palavras em comum com a query

Colunas pesquisáveis vs. não pesquisáveis

Nem todas as colunas devem ser incluídas no índice semântico.

Incluir no embedding:

Campos descritivos: nome, descrição, categoria, tags
Campos que o usuário vai referenciar em linguagem natural

Excluir do embedding:

IDs internos (PRD-00847)
Datas e timestamps
Booleanos (true/false)
Valores numéricos exatos (97.50, 12)
URLs e imagens
Campos de controle interno

Incluir campos não semânticos polui o índice. O modelo não consegue criar embeddings significativos a partir de "true" ou "PRD-00847". Isso reduz a precisão da busca sem nenhum benefício.

Como lidar com itens não pesquisáveis

📌 Estratégia 1 — Separar busca de filtragem

O agente primeiro executa a busca semântica nas colunas descritivas, depois aplica filtros exatos nas colunas numéricas/booleanas.

Usuário: “Quero tênis de corrida por menos de R$100 que estejam em estoque”

Busca semântica: “tênis de corrida” → colunas nome, descrição, categoria
Filtro: preço <= 100 E disponível = true
Retorna os itens que passaram em ambos

📌 Estratégia 2 — Campos de texto derivados

Para facilitar consultas sobre dados normalmente não pesquisáveis, crie uma coluna auxiliar que os descreva:

faixa_preco (texto): “econômico” / “intermediário” / “premium”
-- Em vez de deixar a busca tentar interpretar “89.90”

📌 Estratégia 3 — Instrução explícita no prompt

“Ao buscar produtos na Table, use busca semântica nos campos
‘description’ e ‘category’. Depois filtre por ‘available = true’.
Para faixa de preço, use o campo ‘price_range’, não o campo numérico.”

📚 Knowledge Base

Quando usar

Knowledge Bases são repositórios de conhecimento para consulta semântica. O agente não escreve nelas — ele apenas lê via Knowledge Base Search Tool.

Use uma Knowledge Base quando:

O conteúdo é textual, não estruturado ou semiestruturado
O conteúdo serve para responder perguntas, não para ser manipulado
O volume é grande demais para o Prompt (acima de ~5000 caracteres)
O conteúdo muda editorialmente — você o atualiza, não o agente
Você precisa de busca semântica baseada em similaridade

Exemplos:

- Manual de produto
- Política de trocas e devoluções
- FAQ com dezenas de perguntas
- Documentação técnica
- Catálogo descritivo com especificações narrativas
- Contratos e termos de serviço

Regra de ouro: se o agente vai apenas ler/consultar, é uma KB (se for longo) ou Prompt (se for curto e estático).

Consulta restrita por documento

Por padrão, a KB Search varre todos os documentos da base simultaneamente. Uma consulta restrita (scoped) limita a busca a um documento específico.

Quando usar

KB com documentos de contextos muito diferentes

KB contém: manual do produto A, manual do produto B, política de privacidade

Usuário: "Como eu reseto isso?"

A busca global pode retornar trechos dos documentos errados.
Busca com escopo em "product_a_manual.pdf" → só o contexto certo.

Agente multi-contexto com escopo dinâmico

1. Usuário informa que tem o Produto X
2. Agente armazena na Contextual Memory: product = "product_x"
3. KB Search com escopo em: document = "product_x_manual.pdf"
4. Todas as respostas vêm apenas daquele manual

Compliance e isolamento de informações

Usuário: "O que meu contrato diz sobre rescisão?"
→ Agente restringe o escopo ao contrato daquele cliente específico
→ Nunca retorna cláusulas de contratos de outros clientes

KBs muito grandes

Restringir o escopo reduz o espaço de busca e melhora tanto a precisão quanto a velocidade.

Como implementar no Prompt

"Quando o usuário fizer perguntas sobre o contrato dele, use o KB Search
com escopo no documento identificado pela variável {contract_id} da
Contextual Memory."

Quando não restringir o escopo

A pergunta é genuinamente entre documentos (cross-document)
Você não sabe de antemão qual documento é relevante
KB pequena com poucos documentos homogêneos

📄 PDF Reader Tool

Quando usar

Use quando o documento não existe previamente — ele é trazido pelo usuário no momento da interação.

Casos de uso:

- Usuário envia um currículo → agente analisa e pontua a candidatura
- Usuário envia um extrato bancário → agente categoriza as despesas
- Usuário envia uma proposta comercial → agente resume os pontos principais
- Usuário envia um laudo médico → agente explica em linguagem simples
- Usuário envia um contrato → agente sinaliza cláusulas problemáticas

O documento é diferente para cada usuário. Não faz sentido indexá-lo em uma KB, já que cada instância é única. O agente só precisa do conteúdo para aquela conversa.

PDF Reader vs. Knowledge Base

Dimensão	PDF Reader	Knowledge Base
Quando o documento existe	Em tempo real (usuário o envia)	Pré-carregado na configuração
Quem o fornece	O usuário, durante a conversa	O criador do agente
Tipo de leitura	Leitura direta do arquivo	Busca semântica em índice vetorial
Persistência	Temporária (dura a conversa)	Permanente
Volume	Um documento por vez	Múltiplos documentos indexados

Armadilha: usar a KB para processar documentos enviados pelo usuário. A KB não aceita uploads no momento da execução.

Armadilha: usar o PDF Reader para documentos que são sempre os mesmos. Ineficiente — processa o mesmo arquivo repetidamente, sem busca semântica.

Usando os dois juntos

Existem cenários em que ambos fazem sentido na mesma solução.

Agente de análise de contratos:

Knowledge Base:
→ Legislação vigente, jurisprudência, modelos padrão
→ Sempre disponível para qualquer consulta

PDF Reader:
→ O contrato específico que o usuário acabou de enviar
→ Agente lê o contrato e cruza com a legislação da KB

Agente de onboarding:

Knowledge Base:
→ Manual da empresa, código de conduta, benefícios, políticas

PDF Reader:
→ O contrato de trabalho específico do novo contratado
→ Agente explica as cláusulas daquele contrato específico