Ler e Gravar Anotações

O que é

Par de ferramentas nativas — Ler Anotações e Gravar Anotações — que dão ao agente uma memória estruturada por conversa. O agente escolhe chaves arbitrárias e armazena valores associados; pode ler e atualizar a qualquer momento dentro da mesma conversa.

O escopo depende do canal. Em canais externos (WhatsApp, Telegram, Instagram, API), as notas pertencem ao contato e persistem entre conversas e sessões — se a mesma pessoa voltar a falar depois, o agente reencontra tudo que anotou sobre ela. Em conversas internas do Hub (sem contato externo), as notas são por conversa.

Quando usar

• Coletar dados aos poucos ao longo da conversa (nome, e-mail, empresa, tamanho do time, etc.) sem perguntar tudo de uma vez.
• Lembrar preferências do usuário ao longo de várias respostas (“prefere ser tratado por X”, “já recebeu o orçamento”).
• Marcar etapas de um fluxo guiado (“etapa 1 concluída”, “aguardando confirmação”).
• Guardar fatos relevantes que vão reaparecer mais tarde sem precisar reler todo o histórico.
• Substituir o uso do prompt do sistema para informações que mudam durante a conversa.

Configuração

As duas ferramentas são independentes — você pode ativar só a leitura, só a escrita, ou ambas. O cenário normal é ativar as duas em conjunto.

1. Na aba Ferramentas do agente, clique em + Adicionar Ferramenta.
2. Em FERRAMENTAS NATIVAS, escolha Ler Anotações.
3. Repita para Gravar Anotações.

Nenhuma configuração adicional. As notas são armazenadas no banco junto do contato (em canais externos) ou da conversa (no Hub interno).

Como o agente invoca

O agente decide chamar essas ferramentas quando o prompt orienta o uso de memória estruturada ou quando o modelo identifica que vale a pena persistir algo:

• Gravar Anotações: chamado quando o agente quer salvar ou atualizar uma chave. Ele escolhe o nome da chave e o valor.
• Ler Anotações: chamado quando o agente quer recuperar o que já foi salvo antes de responder.

O agente geralmente lê no começo do turno e grava ao final, mas isso depende do prompt e do modelo.

Limitações e notas

• Escopo por canal. Em canais externos (WhatsApp, Telegram, Instagram, API) as notas são do contato e seguem com ele entre conversas e sessões — mesmo que a conversa anterior já tenha sido concluída. Em conversas internas do Hub, o escopo é a conversa atual.
• Estrutura livre. O agente escolhe os nomes das chaves. Para padronizar (ex.: sempre usar nome, email, empresa), descreva o esquema no prompt do agente.
• Sem versionamento. Uma escrita sobrescreve o valor anterior da chave; não há histórico de alterações.
• Ativação independente. Se você ativar só Gravar, o agente escreve mas não consegue ler depois — geralmente não é o que você quer.
• Uso eficiente. Ler notas adiciona conteúdo ao contexto do modelo a cada turno em que a ferramenta é chamada. Em conversas muito longas com muitas notas, isso pode aumentar o custo do prompt.