Skip to main content
Algumas empresas não podem deixar os argumentos das ferramentas, os resultados ou os documentos que um agente escreveu saírem da própria infraestrutura: o texto de um processo, uma cotação com dados de saúde, um contrato. O modo pointer atende a isso sem perder o que o registro dá: o SDK escreve cada valor no seu bucket, com as suas credenciais, e manda à Niadra só o ponteiro e o digest. A Niadra guarda o quadro do turno (o que foi lido, chamado, afirmado e decidido, com os pinos) e nunca um valor; o replay e a conferência de afirmações leem os valores de volta dentro da sua empresa, pelo digest.

Os três modos

O modo é configuração do espaço, no documento recording (papel integration): um modo padrão e, se quiser, um por fonte. Uma fonte pode sempre guardar menos do que o espaço permite, nunca mais: um turno enviado num modo que guarda mais é recusado com content_mode_refused, e o SDK o manda de novo só com digests. Mudar o modo para um que guarda mais pede também o papel security. Um registro bronze, vindo de OpenTelemetry, é hash_only por padrão.

Ligar o modo pointer no SDK

O SDK escolhe o modo nesta ordem: content_mode das opções de turno, quando você o fixa; pointer assim que um armazenamento é configurado; o modo que a gravação do espaço nomeia para a fonte; stored. O upload roda no envio, em segundo plano, nunca no caminho do agente.
Cada valor vai para <turn_id>/<blob>.json, como JSON canônico (RFC 8785), e o ponteiro devolvido entra no registro ao lado do digest. Um registro cujos blobs não puderam ser todos escritos sai como hash_only, partial, em vez de esperar. O digest é o SHA-256 do JSON canônico do valor, então o mesmo valor tem o mesmo digest em qualquer produtor; antes de calcular, o SDK pode aplicar os normalizadores que a gravação do espaço declara, para tirar um id de pedido ou um carimbo de tempo que muda a cada chamada, e assim o args_hash de uma chamada bate entre replays.

O que a Niadra ainda vê

O quadro: o turno, o agente, o tipo, os horários, a build e os pinos, o que foi lido pela versão, as chamadas com o nome, o args_hash, a latência e o estado, as observações de estado tipado com a proveniência (os valores dos campos observados fazem parte do quadro, porque são estado dos seus objetos, não conteúdo), as interações, os vereditos de afirmação, as decisões de coordenação e os efeitos, os ids dos eventos da conversa e as marcas. O que a Niadra não vê: os argumentos, os resultados, o texto das leituras, os documentos escritos. Um registro em pointer ou hash_only é aceito mesmo com o armazenamento da Niadra indisponível, porque o quadro é tudo o que ele tem; a deduplicação pelo turn_id acontece quando o armazenamento volta.

Replay dentro da sua empresa

No replay, o caso traz o registro com os ponteiros e os digests, e o executor lê cada ponteiro com o resolvedor de conteúdo do SDK, com as suas credenciais, e confere o digest antes de usar: um valor que não pode ser lido ou não bate é um erro de infraestrutura, nunca uma asserção falhando.
O contexto da época é o blob da leitura pack do registro, lido do mesmo jeito. O caso traz também o histórico da conversa mascarado, então o executor tem tudo o que precisa sem que nenhum valor gravado passe pela Niadra no caminho de volta.

Conteúdo de terceiros por ponteiro

O mesmo vale para os campos de conteúdo dos tipos declarados: com content.mode: pointer, o texto de um tribunal ou de um documento fica no seu armazenamento, e uma leitura de estado traz só o marcador content (mode, sha256, pointer, scan). niadra.content.fill(context) preenche a view de estado com os textos, conferindo cada digest, e o texto entra no prompt dentro do envelope <niadra-data>, como qualquer conteúdo de terceiro. Um conteúdo por ponteiro fica pending quando o tipo exige triagem (scan: required), porque a Niadra não consegue lê-lo: a triagem, nesse caso, é sua, ou o tipo usa scan: rules sobre o que chega em claro.

Contrafactual e âncoras

O contrafactual de ferramenta roda as chamadas gravadas ao vivo dentro da sua empresa e reporta só posições e sobreposições, então funciona igual em qualquer modo. A âncora de texto do contrato de afirmação compara a citação com o documento que o executor tem em mãos, recomposto pelo ponteiro.

O que fica com a Niadra em cada modo

Próximos passos

Registros de turno

os modos de conteúdo e a fila do SDK.

Replay no seu CI

o executor que lê os ponteiros de volta.

O worker de resolução

o resolvedor de conteúdo e o de estado.

Privacidade

onde cada cópia mora e por quanto tempo.