Agentes internos

Agentes internos trabalham dentro dos seus sistemas sem falar com o cliente: a cobrança analisa contestações e lança créditos, o de pedidos reagenda entregas no ERP, o de tickets classifica o help desk. Eles agem sobre os mesmos clientes com quem os agentes de atendimento conversam, e sem memória comum cada lado erra de um jeito. O agente interno age sem saber o que foi dito no atendimento; o agente de atendimento promete o que outro agente já fez. Este guia liga um agente de cobrança à Niadra com as mesmas chamadas de um agente de atendimento: ele lê o contexto da fatura em que trabalha, lança o crédito no ERP com as próprias credenciais e registra a ação. Um minuto depois, o agente de voz atende sabendo.

O fluxo das 14h05, 14h06 e 14h07

14h05, app. A Marina contesta a fatura de agosto no seu app. A mensagem fica ligada a invoice:erp:0823 pelo object_refs e entra na camada ao vivo em menos de um segundo.
14h06, agente de cobrança. Ele lê context(object="invoice:erp:0823", view="task:billing", verification="no_customer"), recebe a contestação pelo live, a visita técnica que falhou às 14h02 e o crédito de março no histórico. Lança o crédito de US$ 40 no ERP e registra action("credit", closes=...).
14h06, ERP. O ERP emite invoice.credited. A ação e o evento viram um registro só, e a ação passa de declared para confirmed.
14h07, ligação. O contexto de voz já diz: “Feito por outro agente: crédito de US$ 40 na fatura de agosto, Cobrança, 14h06, confirmado pelo sistema”.

Nenhum modelo de linguagem fica entre a ação registrada e o contexto de voz. Ações e eventos de sistema chegam à camada ao vivo em menos de um segundo e ao contexto recompilado em menos de dez.

A Niadra nunca executa ação em sistema de registro. Quem age é o seu agente, com as credenciais dele. A Niadra guarda o que ele precisa lembrar e o que ele fez.

Antes de começar: a fonte

Agente interno é uma fonte como qualquer outra, com chave própria, classe de audiência internal_agent e uma finalidade como billing. Acesso ao ERP não é acesso à memória: o agente de cobrança lê faturas e contestações, não pendência técnica nem dado de saúde. Duas configurações importam aqui:

Escopo act na chave, e trusted_action_ops na fonte (aqui ["credit"]): a lista fechada de operações que ela pode registrar, e as operações cujas ações declaradas fecham pendência antes de o sistema confirmar. O escopo track sozinho nunca registra ação.
Verificação no_customer, o nível das tarefas sem cliente presente. Fica fora da escala V0 a V4 e só é aceito de fontes internal_agent. Um contexto montado em no_customer nunca vai para o cliente.

As duas se configuram na fonte, pela API de controle ou pelo Console.

Passo a passo

1. Abra uma tarefa centrada na fatura

A tarefa faz, para o agente interno, o papel que a conversa faz para o de atendimento: fixa o contexto, delimita o cache do SDK, agrupa os eventos para a cobrança e fecha com task.ended. Sem ela, o servidor fecha a tarefa depois de 10 minutos de inatividade. A view task:billing é definida pelo seu espaço como template mais política. Ela prioriza os objetos do tipo da tarefa, as pendências ligadas a eles e o que foi dito sobre eles nas conversas, e deixa de fora o que a finalidade de cobrança não permite.

from niadra import Niadra, system_id

niadra = Niadra(channel="erp")

with niadra.task(
    "billing-7741",
    subject=system_id("crm", "48213"),
    object="invoice:erp:0823",
    view="task:billing",
    verification="no_customer",
    agent_id="billing-agent",
) as task:
    ctx = task.context()
    decision = billing_llm.review(instructions=BILLING_RULES, context=ctx.system_block, recent=ctx.turn_block)

import { Niadra } from "@niadra/sdk";

const niadra = new Niadra();

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();
const decision = await billingLlm.review({ instructions: BILLING_RULES, context: ctx.text, recent: ctx.suffix });

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/context" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object": { "type": "invoice", "namespace": "erp", "id": "0823" },
    "view": "task:billing",
    "verification": "no_customer",
    "task_id": "billing-7741"
  }'

O context(object=...) chega da fatura ao dono dela e devolve o contexto centrado nela: a linha do tempo do objeto mais o contexto do cliente que a tarefa pede. Valem as mesmas regras da conversa: pré-compilado, fixado por tarefa, com ETag e comprovante da leitura.

2. Aja no ERP e depois registre a ação

Lance o crédito pela sua integração com o ERP. Depois registre a ação com closes, a pendência que ela cumpre. Informe pelo id, ou pelo objeto e por uma operação canônica, que é o que você costuma saber: a contestação da fatura 0823.

    erp.post_credit(invoice="0823", amount=40.00, currency="USD")  # sua integração, suas credenciais

    task.action(
        "credit",
        result="$40 credit on the August bill",
        purpose="billing",
        closes={"object": {"type": "invoice", "namespace": "erp", "id": "0823"}, "operation": "dispute"},
    )

await erp.postCredit({ invoice: "0823", amount: 40.0, currency: "USD" }); // sua integração, suas credenciais

task.action({
  object_refs: ["invoice:erp:0823"],
  operation: "credit",
  result: "$40 credit on the August bill",
  purpose: "billing",
  closes: { object: { type: "invoice", namespace: "erp", id: "0823" }, operation: "dispute" },
});
await task.end();

A ação é imutável, como todo evento. Uma correção é uma ação nova, com corrects_action_id apontando para a anterior.

3. Deixe o sistema de registro confirmar

A ação fica declared até um evento do sistema de registro confirmar. Mande os eventos do ERP pelo webhook genérico ou como eventos de sistema. Quando invoice.credited chega para o mesmo objeto e a mesma operação dentro da janela, os dois viram um registro só e a ação fica confirmed; assim o crédito nunca é contado duas vezes.

Estado	O que quer dizer	O que o contexto diz
`declared`	Registrada pelo agente, ainda sem confirmação do sistema	”Declarado pela Cobrança às 14h06; o sistema ainda não confirmou”
`confirmed`	O sistema de registro emitiu o evento correspondente	”Confirmado pelo sistema”
`divergent`	A janela passou sem o evento de confirmação	Marcada, e a condição de gatilho `fact.contradicted_by_system_event` pode avisar você
`quarantined`	Registrada numa sessão marcada por tentativa de injeção no prompt	Nunca aparece como feita e não fecha nada

Ação declared só fecha pendência se a operação dela estiver nas trusted_action_ops da fonte; ação confirmed sempre fecha.

4. Entenda o fechamento retroativo

A ação pode chegar antes de a pendência existir. A contestação escrita no app às 14h05 só vira pendência quando a sessão do app fecha e é extraída, digamos às 14h35, e o agente de cobrança agiu às 14h06. Ao criar a pendência, a Niadra procura ações e eventos já aplicados ao mesmo objeto e à mesma operação dentro da janela. Se houver, a pendência já nasce resolved, apontando para a ação que a fechou.

5. Deixe os outros agentes saberem

Todo agente que ler esta cliente em seguida vê a ação em “Feito por outro agente”, com a fonte e a hora. Se o seu CRM precisa mostrar o desfecho, assine os webhooks action.recorded e open_item.closed e grave lá pela sua integração. Veja Gatilhos e webhooks.

Delta para trabalho recorrente

Agentes internos voltam muito aos mesmos clientes. Peça com delta=True (delta: true) e a resposta traz só o que mudou desde a última leitura desta fonte: “o que mudou desde a última vez que VOCÊ olhou” custa dezenas de tokens.

Próximos passos

Sistemas, objetos e ações

objetos, estado derivado e ações em detalhe.

Webhooks dos seus sistemas

como o invoice.credited entra.

Agentes de voz

a ligação que já sabe do crédito.

Aproveitamento do contexto

como a ação conta como uso do contexto.

​O fluxo das 14h05, 14h06 e 14h07

​Antes de começar: a fonte

​Passo a passo

​1. Abra uma tarefa centrada na fatura

​2. Aja no ERP e depois registre a ação

​3. Deixe o sistema de registro confirmar

​4. Entenda o fechamento retroativo

​5. Deixe os outros agentes saberem

​Delta para trabalho recorrente

​Próximos passos

Sistemas, objetos e ações

Webhooks dos seus sistemas

Agentes de voz

Aproveitamento do contexto

O fluxo das 14h05, 14h06 e 14h07

Antes de começar: a fonte

Passo a passo

1. Abra uma tarefa centrada na fatura

2. Aja no ERP e depois registre a ação

3. Deixe o sistema de registro confirmar

4. Entenda o fechamento retroativo

5. Deixe os outros agentes saberem

Delta para trabalho recorrente

Próximos passos