Integrando Tables com Agentes

A Zaia Endless permite que Agentes interajam com Tables (também conhecidas internamente como Datagrids) por meio de Tools especializadas, que fornecem acesso baseado em permissões para realizar operações específicas — como inserir, atualizar ou recuperar dados.

Essas Tools funcionam como habilitadoras de capacidade: cada uma concede um nível distinto de interação entre o Agente e a Table.
Sem uma Datagrid Tool apropriada atribuída, um Agente não consegue ler ou gravar dados naquela Table.

---

🧠 Como Funciona a Integração

Cada Table pode ser vinculada a um ou múltiplos Agentes.
No entanto, em vez de uma conexão direta, a integração é gerenciada por meio das Datagrid Tools — cada uma representando um escopo de permissão preciso.

Quando uma Datagrid Tool é anexada a um Agente, ela define que tipo de ações esse Agente pode realizar na Table de destino.

⚙️ Nota:
Atualmente, os Workflows não conseguem interagir diretamente com Tables.
Apenas Agentes podem realizar essas operações e, se necessário, podem passar os dados recuperados para um Workflow por meio de um Request Node.

---

🧩 Datagrid Tools Disponíveis

Abaixo está uma lista das Datagrid Tools de interação disponíveis e seus propósitos:

1. 🟣 Datagrid Row Insertion

Função:
Permite que o Agente insira uma nova linha em uma Table específica com base em informações estruturadas ou contextuais coletadas durante uma conversa.

Casos de uso típicos:

• Registrar dúvidas de usuários ou envios de formulário.
• Salvar dados de contato, tickets ou feedback.

Exemplo:

“Store this user’s question in the Unanswered Questions table.”

---

2. 🟣 Datagrid Row Update

Função:
Permite que o Agente modifique linhas existentes em uma Table, correspondendo a um identificador único ou condição.

Casos de uso típicos:

• Atualizar o status de um contato ou solicitação.
• Alterar o campo de sentimento em um registro de feedback.

Exemplo:

“Update the status field of chat 5edca67d-dd2d... to resolved.”

---

3. 🟣 Datagrid Row Semantic Search

Função:
Concede ao Agente permissão para pesquisar linhas de Table usando compreensão semântica — ou seja, as consultas são baseadas em similaridade contextual, não apenas em palavras-chave.

Casos de uso típicos:

• Recuperar perguntas semelhantes a uma dúvida atual do usuário.
• Buscar feedbacks que contenham uma intenção ou emoção específica.

Exemplo:

“Find all feedbacks that mention onboarding issues.”

---

4. 🟣 Datagrid Row Similarity Search

Função:
Permite que o Agente realize buscas vetoriais baseadas em similaridade entre linhas de Table, geralmente usadas para correspondência avançada ou operações de clustering.

Casos de uso típicos:

• Identificar registros duplicados ou perguntas repetidas.
• Encontrar conteúdo com similaridade semântica em relação a uma nova entrada.

Exemplo:

“Search for entries similar to this user’s message.”

---

🔐 Arquitetura Baseada em Permissões

Cada Datagrid Tool representa um nível de permissão dentro do escopo operacional do Agente:

Tool	Nível de Permissão	Leitura / Gravação	Acesso Semântico
Datagrid Row Insertion	Create	✅ Gravação	❌
Datagrid Row Update	Modify	✅ Gravação	❌
Datagrid Row Semantic Search	Query (contextual)	✅ Leitura	✅
Datagrid Row Similarity Search	Query (vetorial)	✅ Leitura	✅

⚙️ Atribuir uma tool efetivamente concede a esse Agente a capacidade correspondente sobre a Table.
Sem ela, o Agente não consegue realizar essas ações, mesmo que faça referência à Table na conversa.

---

🔗 Conectando uma Table a um Agente

Para vincular uma Table a um Agente, siga estes passos:

1. Abra o Agent Builder.
2. Vá até a aba Tools.
3. Clique em Add Tool + e selecione uma das Datagrid Row Tools.
4. Configure:
   • A Table de destino que você quer que o Agente acesse.
   • Quaisquer parâmetros ou permissões específicos.

Depois de adicionada, o Agente pode interagir com a Table dentro dos limites definidos pela tool.

---

🔁 Exemplo — Usando Múltiplas Tools

Um Agente pode precisar de mais de uma Datagrid Tool para gerenciar completamente uma Table.
Por exemplo, um Agente de Suporte pode precisar de:

• Datagrid Row Insertion → para registrar novos problemas.
• Datagrid Row Update → para marcá-los como resolvidos.
• Datagrid Row Semantic Search → para verificar se um problema semelhante já existe.

Cada uma dessas tools seria adicionada individualmente ao Agente para conceder as respectivas capacidades.

---

🧩 Exemplo de Fluxo de Dados (Agente + Workflow)

Embora os Workflows não possam acessar Tables diretamente, os Agentes podem atuar como intermediários de dados:

1. O Agente realiza uma Semantic Search em uma Table.
2. Ele recupera o resultado em contexto.
3. O Agente então envia esses dados estruturados adiante por meio de um Request Node (ex.: chamada HTTP ou de Workflow).
4. O Workflow processa os dados recebidos para fins de automação ou análise.

Essa arquitetura mantém a integridade dos dados, garante o acesso controlado por IA e evita a manipulação não autorizada dos dados da Table.

---

⚙️ Boas Práticas

Recomendação	Descrição
Use descrições de coluna precisas	Ajuda o Agente a entender o propósito de cada campo ao inserir ou atualizar dados.
Atribua apenas as Tools necessárias	Evite dar aos Agentes permissões que eles não precisam (ex.: acesso de gravação quando só leitura é necessária).
Combine as Tools de forma lógica	Os Agentes podem usar múltiplas Datagrid Tools para controle completo, ao estilo CRUD, quando necessário.
Monitore a saída via logs	Revise os logs do Agente para confirmar operações de tabela e correspondências semânticas corretas.
Evite redundância	Use a Similarity Search apenas quando uma comparação vetorial precisa for necessária.

Nota Final

Na Zaia Endless, as Tables não são apenas containers passivos de dados — elas fazem parte do framework cognitivo estendido do Agente.
Ao combinar Tables com as Datagrid Tools certas, seus Agentes ganham a capacidade de raciocinar contextualmente, agir de forma autônoma e reter conhecimento — com segurança, inteligência e controle preciso de permissões.