Anotações

O que é

Anotações é uma única ferramenta nativa, identificada tecnicamente como manage_notes. Ela mantém um objeto de chaves e valores que o agente pode consultar e atualizar durante o atendimento. É adequada para fatos duráveis fornecidos pelo usuário, como nome, preferências, dados de qualificação e etapa de um processo.

Não confunda essa memória com uma Nota interna. A Nota interna é uma mensagem humana de texto livre na linha do tempo e não entra no contexto do agente. Anotações são dados estruturados compartilhados entre o agente e as telas administrativas.

Onde a memória fica

O agente não escolhe o registro de destino. A conversa em execução determina o escopo:

Contexto	Registro usado	Duração prática
Conversa com contato externo, inclusive WhatsApp, Telegram, Instagram e API	Contato	As Anotações acompanham o contato em conversas futuras
Conversa interna do Hub sem contato externo	Conversa	As Anotações ficam somente naquela conversa

Em canais externos, trate a memória como parte do cadastro do contato, não como um rascunho descartável da sessão. Consulte Contatos para entender onde a equipe vê esses dados.

Adicionar ao agente

Você precisa de um agente já salvo e de permissão agents.write.

1. Abra Agentes, selecione o agente e entre em Ferramentas.
2. Clique em Adicionar Ferramenta.
3. Em Ferramentas Nativas, escolha Anotações.
4. Confirme que a ferramenta aparece ativa na lista.

Não existe formulário de configuração. A entrada deixa de aparecer entre as ferramentas disponíveis enquanto estiver adicionada; para removê-la, use a ação de exclusão na própria lista.

Operações disponíveis

Todas as operações usam a mesma ferramenta:

Objetivo	Chamada esperada	Resultado
Ler todas as Anotações	action: "read", sem key	Objeto completo
Ler uma Anotação	action: "read" e key	Valor da chave ou null se ela não existir
Criar ou atualizar	action: "write", key e value	Objeto completo depois da alteração
Excluir	action: "write", key e value: null	Objeto completo sem a chave

Gravar na mesma chave substitui o valor anterior. Usar outra grafia cria uma segunda Anotação; não há junção automática nem histórico de versões.

Oriente o agente no prompt

O contrato da ferramenta recomenda ler as Anotações existentes antes de gravar. Isso evita chaves duplicadas e permite atualizar o fato correto.

Defina no prompt um esquema pequeno e estável, com chaves em inglês, minúsculas e em snake_case. Por exemplo:

Antes de gravar, leia as Anotações existentes e reutilize a chave correspondente.
Use apenas as chaves producer_name, preferred_channel e qualification_stage.
Grave somente dados fornecidos pelo usuário e úteis em atendimentos futuros.

Prefira producer_name a variantes como nome, Producer Name ou nome_produtor. Ao escrever, sempre envie key e value. O runtime atual interpreta um value omitido como null e exclui a chave; essa é uma limitação conhecida do produto.

Não persista segredo, credencial, dado de pagamento ou informação sensível sem uma finalidade e política de tratamento adequadas. A ferramenta aceita qualquer valor JSON, portanto o prompt é responsável por restringir o que deve ser guardado.

Visibilidade e manutenção

A equipe pode consultar e editar Anotações estruturadas em Conversas → Contexto → Contato e no perfil em Contatos. Em conversa interna sem contato, o painel de contexto mostra as Anotações da própria conversa.

Essas edições não têm histórico. Além disso, os controles embutidos em Conversas e as RPCs atuais ainda podem divergir das permissões granulares: um controle pode aparecer e a gravação falhar, ou uma função legada pode conservar acesso retirado da capability. Peça a um administrador para revisar a função quando isso ocorrer.

Limitações importantes

• Sem versionamento: atualizar uma chave perde o valor anterior.
• Sem busca entre contatos: a ferramenta acessa somente o contato ou a conversa que está em execução.
• Escopo externo durável: concluir uma conversa não apaga as Anotações do contato.
• Memória interna vulnerável a limpeza: no runtime atual, excluir qualquer mensagem da conversa limpa todas as Anotações guardadas no registro da conversa. Isso também pode ocorrer em limpezas técnicas de mensagens; não use esse escopo como armazenamento crítico.
• Custo de contexto: cada leitura devolve dados ao modelo. Evite objetos grandes e leia uma chave específica quando o fluxo permitir.

Se o agente criar duplicatas, ajuste o prompt para exigir leitura antes da gravação e normalize as chaves existentes. Se ele não usar a memória, confirme que Anotações está ativa e explicite no prompt em quais momentos deve ler ou gravar.