Notas Internas

Notas internas — chamadas de Anotações no painel admin — são um espaço de memória estruturado por conversa, totalmente invisível para o usuário final. Servem para o agente lembrar de fatos coletados ao longo do atendimento e para a equipe humana enxergar contexto rápido sem precisar reler tudo.

O que são

Cada conversa carrega um objeto notes no formato chave-valor. As chaves são definidas pelo próprio agente (ou pelo admin que está intervindo), e os valores podem ser texto, número, booleano ou objetos JSON estruturados.

Exemplos comuns:

• nome_cliente: "Maria Silva"
• produto_em_duvida: "Plano Pro anual"
• humor: "frustrado"
• tentativas_reembolso: 2
• proximo_passo: "agendar callback na sexta"

As notas ficam visíveis no painel admin, no card Anotações abaixo de Informações (à direita do chat). O usuário final nunca vê. Quando a conversa não tem notas, aparece o texto “Nenhuma anotação ainda”.

Quem vê o que

Persona	Acessa as notas?
Usuário final (Hub, WhatsApp, chat público, widget, etc.)	Não
Admins da organização	Sim — painel ao lado do chat
O próprio agente (LLM)	Sim, se a ferramenta Ler Anotações estiver ativa

Em outras palavras: notas internas são um canal lateral entre o agente e a equipe. O usuário continua tendo uma conversa normal; em paralelo, o agente vai anotando o que considera importante e a equipe pode consultar a qualquer momento.

Como o agente lê e escreve notas

Existem duas ferramentas nativas dedicadas:

Ler Anotações (read_notes)

Permite que o agente leia todas as anotações já salvas na conversa atual. Não tem configuração — basta adicionar a ferramenta.

Use quando o agente precisar:

• Recuperar informações coletadas em mensagens anteriores.
• Evitar pedir de novo dados que o usuário já forneceu.
• Adaptar o tom de resposta com base em um sinal anterior (ex.: humor: frustrado).

Gravar Anotações (write_notes)

Permite que o agente crie ou atualize chaves no objeto de notas. Também não tem configuração.

Use quando o agente precisar:

• Registrar dados estruturados que apareceram na conversa (nome, telefone, produto).
• Marcar progresso de um fluxo de várias etapas.
• Deixar contexto para um humano que possa intervir depois.
• Gravar o resultado de uma decisão para não repetir trabalho na próxima mensagem.

Ativar as ferramentas no agente

1. Abra Agentes -> [agente] -> editar -> Ferramentas.
2. Adicione Ler Anotações e/ou Gravar Anotações.
3. Na instrução do agente, oriente quando usar cada uma. Por exemplo:

“Sempre que o usuário informar nome, telefone ou problema, salve em anotações com write_notes. No início de cada resposta, consulte as anotações com read_notes.”

Sem orientação no prompt, o modelo tende a usar anotações de forma esporádica. Vale ser explícito.

Casos de uso

• Atendimento longo: conversa que se estende por dias. O agente salva o que já foi resolvido e o que está pendente; quando o usuário volta, ele continua de onde parou.
• Atendimento multicanal: o usuário começa no WhatsApp e migra para o chat web; as anotações viajam com a conversa.
• Handoff humano: antes de chamar a ferramenta Intervenção Humana, o agente escreve um resumo em anotações (motivo_escalonamento, tentativas_feitas) — o admin que assume tem contexto imediato sem precisar reler o histórico inteiro.
• Qualificação de lead: o agente vai preenchendo campos do lead (interesse, orçamento, momento de compra) que o time comercial usa depois.

Boas práticas

• Use chaves curtas e consistentes entre conversas (nome_cliente, não nomeDoClienteQueAcabouDeChegar). Isso ajuda quando você for analisar várias conversas.
• Não duplique no prompt o que já está em anotações. O agente lê sob demanda — economiza tokens e mantém o contexto fresco.
• Não guarde segredos brutos em anotações. Elas não são criptografadas e ficam visíveis para qualquer admin da organização. Para dados sensíveis (senhas, tokens), use as integrações seguras de credenciais.
• Revise anotações em conversas-modelo antes de ajustar o prompt — elas mostram o que o agente realmente está capturando da realidade.