Como a Integração Funciona
Quando uma tabela é conectada a um agente, o agente recebe ferramentas para interagir com os dados em tempo real. Cada mensagem do usuário pode acionar uma ou mais ações na tabela — busca para formular uma resposta, inserção para registrar informações coletadas ou atualização para modificar um registro existente. O agente decide qual ação executar com base nas instruções do prompt de sistema e no contexto da conversa. As ações são executadas pela funçãodatagrid-tool-exec, que valida permissões, tipos de dado e limites antes de modificar qualquer registro.
Ferramentas de Datagrid Disponíveis
Inserção de Linha (insert_row)
A açãoinsert_row cria um novo registro na tabela com os valores coletados pelo agente durante a conversa. O agente só executa a inserção após coletar os campos obrigatórios — definidos na configuração de cada coluna. Se um campo obrigatório não foi informado pelo usuário, o agente solicita antes de prosseguir.
Caso de uso típico: o agente coleta nome, e-mail e interesse de um lead durante a conversa e insere os dados na tabela “Leads” ao final, sem intervenção humana.
Atualização de Linha (update_row)
A açãoupdate_row modifica os valores de um registro existente. Para atualizar, o agente primeiro localiza a linha via busca (semântica ou por similaridade), obtém o row_id e então executa a atualização com os novos valores.
Caso de uso típico: o usuário informa que quer atualizar seu e-mail de contato. O agente busca o registro pelo nome, solicita o novo e-mail e executa o update_row com o campo atualizado.
Busca Semântica de Linha (semantic_search)
A açãosemantic_search converte a consulta do agente em embedding e executa busca por similaridade coseno nas colunas com indexação semântica ativa. Retorna linhas ordenadas por relevância semântica, com score de similaridade.
Caso de uso típico: o usuário pergunta sobre produtos para cabelo seco e o agente executa semantic_search na tabela de catálogo, encontrando linhas com “hidratação”, “nutrição capilar” e “tratamento para fios ressecados” mesmo sem correspondência exata de palavras.
Busca por Similaridade de Linha (similarity_search)
A açãosimilarity_search executa busca por similaridade de texto sem vetorização — mais rápida e sem custo de API de embeddings, porém menos capaz para variações de linguagem. Ideal para identificadores, SKUs e termos técnicos onde a correspondência aproximada é mais útil que a semântica.
Caso de uso típico: o usuário informa o código do produto “NK-AIR-42” e o agente executa similarity_search para localizar exatamente aquele registro no catálogo.
Nota Final
As quatro ações podem ser combinadas num mesmo agente. Um agente de atendimento pode usarsemantic_search para consultar o catálogo, insert_row para registrar leads e update_row para modificar status de pedidos — tudo configurado a partir do prompt de sistema.
Arquitetura de Permissões
Cada ação é ativada individualmente ao conectar a tabela ao agente. Não é necessário conceder todas as ações — ative apenas o que o caso de uso requer.| Ferramenta | Nível de Permissão | Leitura/Escrita | Acesso Semântico |
|---|---|---|---|
semantic_search | Consulta | Somente leitura | Sim — requer colunas com busca semântica ativa |
similarity_search | Consulta | Somente leitura | Não — busca textual sem vetorização |
insert_row | Escrita | Escrita (criação) | Não aplicável |
update_row | Escrita | Escrita (modificação) | Não — localiza a linha por row_id obtido previamente por busca |
Conectando uma Tabela ao Agente
Abra a aba de Ferramentas
Dentro da configuração do agente, acesse a aba Ferramentas (ou Tabelas). A lista de tabelas disponíveis no workspace é exibida.
Adicione a tabela
Clique em + Adicionar tabela e selecione a tabela desejada. Apenas tabelas do mesmo workspace estão disponíveis.
Configure as ações e instrua no prompt
Selecione quais ações o agente pode executar (consulta, inserção, atualização). Em seguida, no prompt de sistema do agente, adicione instruções específicas sobre quando e como usar a tabela: qual ação usar, quais campos coletar e qual comportamento adotar quando a busca não retornar resultados.
Exemplo — Usando Múltiplas Ferramentas
Um agente de atendimento para uma clínica tem acesso à tabela “Agenda de Profissionais”. Quando o usuário pergunta “tem horário disponível com a Dra. Ana amanhã?”, o agente executasemantic_searchcom a query “Dra. Ana disponível amanhã” e recupera os horários cadastrados. Ao confirmar o agendamento, o agente executaupdate_rowpara decrementar as vagas disponíveis no horário escolhido einsert_rowna tabela “Agendamentos” para registrar os dados do paciente.
Fluxo de Dados — Agente + Tabela
Quando o agente recebe uma mensagem do usuário, o fluxo de dados segue a sequência:- O LLM processa a mensagem e identifica a intenção (consulta, coleta de dados, atualização).
- Com base nas instruções do prompt, o agente decide qual ferramenta de datagrid acionar.
- A função
datagrid-tool-execrecebe a requisição, valida permissões e tipos de dado e executa a ação no banco de dados. - O resultado (linhas encontradas, confirmação de inserção ou atualização) é retornado ao LLM.
- O LLM formula a resposta final ao usuário com base nos dados retornados pela tabela.
Boas Práticas
| Recomendação | Descrição |
|---|---|
| Seja específico no prompt | O agente tem acesso a várias ferramentas simultaneamente. Instruções vagas podem fazer o agente não usar a tabela quando deveria, ou usar quando não deveria. Indique explicitamente quando cada ação deve ser acionada. |
| Limite as ações ao mínimo necessário | Se a tabela é um catálogo somente leitura, não ative inserção nem atualização. Reduz o risco de dados incorretos e simplifica o comportamento esperado do agente. |
| Use campos obrigatórios com critério | Campos obrigatórios garantem que o agente colete informações críticas antes de inserir. Em excesso, tornam a conversa longa e podem frustrar o usuário. |
| Teste com casos extremos | Simule usuários que pulam perguntas, dão respostas vagas ou fornecem dados no formato errado. Verifique como o agente lida com cada situação antes de ativar em produção. |