Sistemas, objetos e ações

A Niadra é a memória de todos os agentes da empresa: os que atendem o cliente e os que trabalham por dentro, no CRM, no ERP, no help desk, na cobrança e nos pedidos. Para isso, a memória recebe três coisas além das conversas: os eventos de sistema que os seus sistemas já emitem, os objetos de negócio a que eles se referem e as ações que os agentes fazem nesses sistemas. É assim que o agente de voz sabe às 14h07 o que o agente de cobrança fez às 14h06.

Eventos de sistema

Um evento de sistema é uma mudança de estado num sistema de registro: pedido criado, fatura contestada, ticket reaberto, pagamento recusado. Ele entra como kind: "system_event", com speaker igual a system e um canonical_type, como invoice.credited, além dos campos estruturados em fields. Há três portas de entrada:

Porta	Quando usar
Webhook genérico	O sistema já manda webhook. Você aponta para `POST /v1/ingest/webhook/{source_id}`, e um mapeamento versionado transforma o payload em evento
Importação de arquivo	O sistema não tem webhook e exporta arquivos: mande um JSONL de itens do lote para `POST /v1/ingest/files`, com até 512 MB, e acompanhe por `GET /v1/ingest/files/{import_id}`
API	O seu código já sabe do evento e manda pelo SDK ou por `POST /v1/batch`

from niadra import Niadra, system_id

niadra = Niadra()

niadra.track({
    "kind": "system_event",
    "channel": "erp",
    "canonical_type": "invoice.credited",
    "idempotency_key": "erp-inv-0823-credit-1",
    "handles": [system_id("crm", "48213")],
    "object_refs": [{"type": "invoice", "namespace": "erp", "id": "0823"}],
    "speaker": {"role": "system"},
    "fields": {"amount": 40.0, "currency": "USD"},
})

niadra.track({
  kind: "system_event",
  channel: "erp",
  canonical_type: "invoice.credited",
  idempotency_key: "erp-inv-0823-credit-1",
  handles: [handles.systemId("48213", "crm")],
  object_refs: ["invoice:erp:0823"],
  speaker: "system",
  fields: { amount: 40.0, currency: "USD" },
});

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/batch" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"type": "event", "kind": "system_event", "channel": "erp",
       "canonical_type": "invoice.credited", "idempotency_key": "erp-inv-0823-credit-1",
       "handles": [{"type": "system_id", "value": "48213", "scope": "crm"}],
       "object_refs": [{"type": "invoice", "namespace": "erp", "id": "0823"}],
       "speaker": {"role": "system"}, "fields": {"amount": 40.0, "currency": "USD"},
       "occurred_at": "2026-09-22T17:06:21Z"}]}'

Evento de sistema é dado estruturado e entra sem modelo de IA: o mapeamento extrai tipo, objeto, os ids do cliente, campos e horário. Só tipos mapeados entram na memória, o que protege a memória do volume de um ERP. O payload cru de um tipo não mapeado fica 7 dias guardado para você remapear, e não entra na memória. Texto livre de dentro de um sistema, como a descrição de um ticket, entra como message num canal próprio e passa pela extração normal. Eventos de sistema não entram na cobrança. A unidade continua sendo a conversa ou tarefa.

Objetos de negócio

Pedido, ticket, fatura, contrato, entrega e assinatura são objetos. Cada um é identificado pelo trio type, namespace e id, único no espaço, como invoice:erp:0823. Os SDKs aceitam essa forma curta. O objeto se prende ao cliente pelo id dele naquele sistema, o handle system_id, e guarda a linha do tempo de eventos e ações e um estado derivado, sempre com as_of, a fonte e a referência ao registro de origem. O valor oficial continua no seu sistema. A memória guarda o bastante para o agente lembrar e agir, e aponta para a origem. Uma separação de perfis leva os pedidos e as faturas para o dono certo sozinha, porque o objeto está preso ao handle de origem. Leia um objeto por GET /v1/objects/{object_type}/{namespace}/{external_id} e os eventos e ações dele por /timeline, as duas com o escopo context e comprovante. Os ids podem ter barra e dois-pontos. Nos SDKs, object_state() e object_timeline() em Python, objectState() e objectTimeline() em TypeScript:

invoice = niadra.object_state("invoice:erp:0823")
if invoice:
    print(invoice.state, invoice.as_of, invoice.open_items)

const { data: invoice } = await niadra.objectState("invoice:erp:0823");
if (invoice) console.log(invoice.state, invoice.as_of, invoice.open_items);

curl "https://acme-prod.us-east-1.api.niadra.com/v1/objects/invoice/erp/0823" \
  -H "Authorization: Bearer $NIADRA_API_KEY"

O seu time de governança vê todos os objetos de um cliente, com as ações sobre eles, por GET /v1/profiles/{profile_id}/objects.

Ações de agente

Uma ação é o registro do que um agente, interno ou de atendimento, ou um atendente humano fez num sistema: a operação canônica (credit, reschedule), o objeto, o resultado, a finalidade e, opcionalmente, closes, a pendência que a ação cumpre.

niadra.action(
    "credit",
    subject=system_id("crm", "48213"),
    object="invoice:erp:0823",
    result="$40 credit on the August bill",
    closes={"object": {"type": "invoice", "namespace": "erp", "id": "0823"}, "operation": "dispute"},
    channel="erp",
    task_id="billing-7741",
)

niadra.action({
  channel: "erp",
  task_id: "billing-7741",
  handles: [handles.systemId("48213", "crm")],
  object_refs: ["invoice:erp:0823"],
  operation: "credit",
  result: "$40 credit on the August bill",
  closes: { object: { type: "invoice", namespace: "erp", id: "0823" }, operation: "dispute" },
});

closes aponta a pendência pelo item_id ou pelo par objeto e operação, nunca pelos dois. Registrar ação exige o escopo act da chave, para aquela operação e aquele tipo de objeto; track sozinho não basta. A ação é imutável: uma correção é uma ação nova com corrects_action_id.

Declarada, confirmada, divergente

Estado	Quando
`declared`	O agente registrou e o sistema de registro ainda não confirmou. O contexto diz isso: “declarado pela Cobrança às 14h06; o sistema ainda não confirmou”
`confirmed`	Chegou o evento do sistema que confirma, como `invoice.credited`. A ação e o evento viram um registro só, e o crédito nunca conta duas vezes
`divergent`	A janela venceu sem confirmação. Você pode ser avisado por gatilho

Ação declarada só fecha pendência quando a operação dela está nas trusted_action_ops da fonte; ação confirmada sempre fecha. Ações de uma sessão com trecho marcado como injeção de prompt ficam em quarentena: não fecham nada e não aparecem como feitas.

Fechamento retroativo

A ação pode chegar antes da pendência. Às 14h05 Marina contesta a fatura no app, e a pendência só nasce quando a sessão do app fecha e é extraída, às 14h35. O agente de cobrança age às 14h06. Ao criar a pendência, a Niadra procura ações já aplicadas sobre o mesmo objeto e operação dentro da janela, e a pendência nasce resolved, fechada pela ação das 14h06.

Contexto por tarefa

O agente interno lê o contexto centrado no objeto, com uma view de tarefa e o nível no_customer, porque não há cliente presente:

with niadra.task(
    "billing-7741",
    object="invoice:erp:0823",
    view="task:billing",
    verification="no_customer",
    channel="erp",
) as task:
    ctx = task.context()
    # o agente decide e lança o crédito no ERP, com as credenciais dele
    task.action("credit", result="$40 credit on the August bill")
# ao sair do bloco, o SDK envia task.ended

const task = niadra.task({
  task_id: "billing-7741",
  channel: "erp",
  object: "invoice:erp:0823",
  view: "task:billing",
  verification: "no_customer",
});
const ctx = await task.context();
// o agente decide e lança o crédito no ERP, com as credenciais dele
task.action({ operation: "credit", object_refs: ["invoice:erp:0823"], result: "$40 credit on the August bill" });
await task.end();

A view de tarefa prioriza os objetos do tipo da tarefa, as pendências ligadas a eles e o que foi dito sobre eles nas conversas. O que a finalidade da fonte não permite fica de fora: o agente de cobrança lê faturas e contestações, não lê pendência técnica.

O caminho das 14h06

14h05, app: a contestação entra e, em menos de 1 segundo, está legível e ligada a invoice:erp:0823.
14h06, agente de cobrança: lê o contexto da fatura, recebe a contestação pelo live, lança o crédito no ERP e registra a ação.
14h06, ERP: emite invoice.credited; a ação passa a confirmed.
Em segundos: o contexto de voz ganha “feito por outro agente: crédito de 40, confirmado pelo sistema”.
14h07, ligação: o agente de voz diz que o crédito já foi lançado.

Nenhum modelo de IA fica no caminho entre a ação e o contexto de voz. Ação e evento de sistema chegam ao contexto recompilado em menos de 10 segundos.

A Niadra nunca escreve num sistema de registro. Quem age é o agente, com as credenciais dele. Para devolver o desfecho ao CRM, consuma os webhooks action.recorded e open_item.closed.

Próximos passos

Agentes internos

o guia completo do agente de cobrança.

Webhooks dos seus sistemas

mapeamento e autenticação.

Ler um objeto

estado derivado e pendências abertas.

A base da memória

O que o agente recebe

Governança

Sistemas, objetos e ações

Eventos de sistema

Objetos de negócio

Ações de agente

Declarada, confirmada, divergente

Fechamento retroativo

Contexto por tarefa

O caminho das 14h06

Próximos passos

Agentes internos

Webhooks dos seus sistemas

Ler um objeto

​Eventos de sistema

​Objetos de negócio

​Ações de agente

​Declarada, confirmada, divergente

​Fechamento retroativo

​Contexto por tarefa

​O caminho das 14h06

​Próximos passos

Agentes internos

Webhooks dos seus sistemas

Ler um objeto

Eventos de sistema

Objetos de negócio

Ações de agente

Declarada, confirmada, divergente

Fechamento retroativo

Contexto por tarefa

O caminho das 14h06

Próximos passos