Pular para o conteúdo
niadra
Registro

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

exemplo

turno 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ê
Um turno gravado, do que leu ao que disse
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.

O próximo agente já pode chegar sabendo.

Conte o que você está construindo. Quem responde é quem escreve o código.