Veja por que o agente fez o que fez, turno a turno, com o que ele leu, chamou e afirmou.
Quem roda um agente de IA precisa ver por que ele fez o que fez: o que leu da memória, que ferramentas chamou e o que elas devolveram, o que mostrou à pessoa, o que afirmou e o que decidiu. O registro de turno é essa conta, num formato só para qualquer framework de agente. Ele é capturado dentro do processo do agente e enviado depois, então nunca atrasa a resposta. Fixa a build em que o turno rodou, prompt por versão e modelo exato, e é por isso que dá para reproduzir uma conversa real com a memória da época, no seu CI, sem que o conteúdo saia da sua empresa. O conteúdo pode ficar no seu armazenamento: a Niadra guarda o ponteiro e o hash. É o comprovante de cada leitura estendido ao que o agente fez com ela.
Como funciona
Registro do turno
exemploturno 01J9K2 · agente de voz · fornecedor B · 14h07
- Entrada
- A fala da cliente, na ligação 5521.
- Leu
- O contexto na view de voz (versão e7a1), o bloco de estado (versão 0412) e o bloco de restrições (cv_9c3).
- Chamou
- remarcar_visita(5521, "23/09 manhã"): ok em 212 ms. Objeto mostrado: visita_tecnica 5521.
- Coordenação
- Despedida: pode agora. Efeito farewell:call-5521 reservado e declarado feito.
- Afirmou
- Três afirmações: duas conferem, uma sem origem, que deu lugar à ressalva do contrato.
- Disse
- Aponta para o evento da fala das 14h07. O texto não se repete aqui.
- Build
- prompts voz@v12 · modelo gpt-4.1-mini · a versão do compilador de contexto e o hash do pacote, preenchidos pelo SDK.
- Conteúdo
- Modo ponteiro: os valores ficam no bucket da sua empresa; aqui, o ponteiro e o sha256 de cada um.
- Marcas
- guard_acted: a conferência agiu, então o turno vai à camada guardada, por 30 dias.
- Replay
- Reproduzível: niadra replay --scenario … --runs 5, no seu CI, com as ferramentas respondendo do registro.
Capturado no processo do agente e enviado depois: o agente não esperou por nada.
- Capturado no processo do agente, por cópia, e enviado em segundo plano: um resultado de ferramenta de 25 KB custa 0,05 ms no percentil 95
- Três modos de conteúdo: guardado na Niadra, só ponteiro para o seu armazenamento, ou só hash. Uma fonte pode sempre mandar menos, nunca mais
- O registro não repete o texto da conversa: aponta para os eventos que já entraram na memória
- Os adaptadores abrem e fecham o turno por você: Google ADK, OpenAI Agents, LangGraph e LangChain em Python; LangChain, LangGraph, Mastra, Vercel AI SDK, OpenAI Agents JS, Google ADK e VoltAgent em TypeScript
- Um turno marcado (erro, conferência que agiu, transferência, asserção que falhou) fica mais tempo, e uma reclamação que chega dias depois promove a conversa inteira
- Replay no seu CI: cenários de até 50 turnos com asserções, as ferramentas respondem do registro, os valores nunca saem, e a Niadra dá o veredito estatístico
- O índice dos turnos guardados entra na sua cadeia de auditoria: uma raiz de Merkle por dia, ao lado da raiz dos comprovantes
- Na tela Turnos do Console, cada turno abre com o que leu, chamou, afirmou e disse, as marcas, os pinos e, quando não pode ser reproduzido, por quê
from niadra import Niadra, phone
def shown(product):
fields = {"price_sale": product["price_sale"]}
return [{"ref": f"product:store:{product['sku']}", "fields": fields}]
@Niadra.tool("search_products", provenance=shown)
def search_products(sku: str) -> dict:
return CATALOG[sku]
niadra = Niadra(channel="whatsapp")
customer = phone(customer_phone)
with niadra.conversation(
thread_id, subject=customer, agent_id="store"
) as conversation:
conversation.customer(text)
build = Niadra.build(prompts={"store": "v3"}, model="gpt-4.1-mini")
with conversation.turn(build=build):
context = conversation.context(include=["constraints"])
# recorded: arguments, result, latency, the objects it showed
product = search_products("PX-4471")
reply = model(prompt_with(context, product))
# the record points at this event; the text is never repeated
conversation.agent(reply)
# Later, in your CI: the recorded turns run again with the pinned build
# niadra replay --agent app.agent:build_agent --scenario <id> --runs 5- Python
- TypeScript
Trecho de examples/turn_records.py do SDK: a ferramenta registra o que mostrou, o turno fixa a build, e o que o agente disse entra como o evento que já vai para a memória.
Uma memória, treze produtos
Qualquer agente se liga à memória com três chamadas, em Python, TypeScript, HTTP ou MCP, com adaptador pronto para os frameworks de voz e de agentes mais usados.
Ver a documentação(abre docs.niadra.com)- ContextoO que cada agente precisa saber antes de começar.
- HistóricoTudo o que já aconteceu, para o agente consultar.
- AvisosUm webhook assinado para o seu sistema na hora em que algo acontece.
- AfirmaçãoO que o agente pode afirmar, e a conferência do que ele afirmou, sem modelo a mais.
- CoordenaçãoQuem está com o cliente agora e o que já foi feito, antes de um agente agir.
- MediçãoSe cada agente usou o contexto que recebeu.
- RegistroVocê está aquiPor que o agente fez o que fez, turno a turno, e o replay no seu CI.
- ConsoleQuem leu o quê, revisão, exportação e apagamento.