As ferramentas de Datagrid conectam o agente às tabelas customizadas (datasheets) criadas no workspace. O agente pode consultar, inserir e atualizar registros durante uma conversa, de forma autônoma, sem que o usuário precise sair do chat.
Inserir linha na tabela
A ação insert_row cria um novo registro na tabela com os campos fornecidos pelo agente. O agente monta os valores a partir do contexto da conversa — nome, e-mail, interesse, canal de origem — e grava o registro na tabela em tempo real.
- Colunas marcadas como obrigatórias no Datagrid são exigidas pelo agente antes de executar a inserção.
- Indicado para captura de leads, registro de pedidos, agendamentos e qualquer cenário em que o agente precisa persistir dados coletados na conversa.
Atualizar linha na tabela
A ação update_row modifica um registro existente identificado pelo row_id. O agente localiza o registro com uma busca prévia e, em seguida, aplica as alterações necessárias.
- Útil para atualizar status de pedidos, alterar disponibilidade de horários ou registrar o resultado de um atendimento.
- Requer que o agente tenha o
row_id do registro — normalmente obtido com uma busca semântica ou por similaridade antes de executar a atualização.
Busca semântica na tabela
A ação semantic_search localiza registros cujo conteúdo é semanticamente próximo da consulta, mesmo sem correspondência exata de palavras. A busca usa o modelo text-embedding-3-small (1.536 dimensões): a consulta do agente é convertida em embedding e comparada com os embeddings dos registros indexados.
- Ideal para catálogos de produtos, listas de imóveis e qualquer tabela onde o usuário descreve o que procura em linguagem natural.
- Retorna os registros com maior pontuação de similaridade, ordenados por relevância.
A busca semântica requer que os registros da tabela estejam indexados. Linhas inseridas diretamente pela API ou importadas em massa podem levar alguns minutos para serem indexadas e ficarem disponíveis para busca.
Busca por similaridade na tabela
A ação similarity_search localiza registros por correspondência aproximada de texto — útil para buscas por nome exato, código de produto, CPF ou qualquer campo de identificação curta onde a correspondência literal importa mais do que a semântica.
- Mais rápida que a busca semântica para campos de identificação.
- Retorna registros cuja coluna de texto tem maior sobreposição com a consulta fornecida.
A busca por similaridade não entende sinônimos ou intenção — ela compara texto com texto. Use busca semântica quando o usuário pode descrever o que procura com palavras diferentes das cadastradas na tabela.
Boas práticas
- Nomeie as colunas com clareza — o agente usa o nome da coluna para interpretar o dado e montar os argumentos da ferramenta.
- Marque colunas obrigatórias para evitar inserções incompletas.
- Habilite inserção e atualização apenas quando o caso de uso realmente exige — comece com leitura e valide antes de liberar escrita.
- Limite o número de resultados por busca — o padrão é 10, com máximo de 100; para a maioria dos casos 5 a 10 são suficientes.
