Protocolos de comércio com agentes
AG-UI: os eventos do agente e o estado da negociação, o que o jsonW já guarda
O AG-UI transmite para a tela os eventos de um agente em execução. Na Wortic, a negociação entre agentes já tem um estado guardado em jsonW, que é a base para esse fluxo. Veja o formato de evento, o que já existe no código e o que ainda não está no ar.
· jsonW 1.3.11
O protocolo
O AG-UI é um protocolo aberto para ligar um agente à aplicação que o usuário vê. Ele transmite eventos. Cada evento tem um tipo, como início de rodada, mudança de estado, mensagem em texto, fim ou erro. A aplicação lê os eventos e mostra o andamento.
[tipo do evento, identificador da rodada, dados do estado ou da mensagem]
O que já existe na casa
A negociação entre agentes guarda o seu estado em jsonW vivo. Existe uma função que lê esse estado para as partes da negociação, e só elas. Esse é o dado que o AG-UI vai transmitir para a tela.
Ou seja, a base de dados já existe. Falta a camada que transforma o estado em eventos e a rota que entrega esses eventos.
O que falta
A rota para o AG-UI não está no ar. O trabalho está parado e não tem publicação. O plano é ter uma rota de entrada que recebe o identificador da negociação e devolve os eventos em sequência.
Como o estado vira evento
A sequência prevista é simples. Primeiro, um evento de início. Depois, um evento com o estado atual da negociação. Em seguida, as mensagens em português. Por fim, um evento de fim, ou um evento de erro se algo der errado.
Por que o estado fica guardado
Como o estado fica gravado em jsonW, a tela pode ler a situação atual ao ser recarregada, quando a rota existir. A pessoa vê onde a negociação parou, e não só o último passo.
O que o jsonW não guarda aqui
O AG-UI não guarda nada por conta própria. Ele só transporta. O registro fica na negociação, e a regra de permissão fica no mandato. Confundir essas camadas é um erro comum.
Como conferir quando estiver no ar
Quando a rota existir, confira a sequência de eventos com uma negociação de teste. A ordem deve ser a mesma do estado gravado. Um erro deve aparecer como erro, e não como fim normal.
A documentação oficial está em docs.ag-ui.com, e o código, em github.com/ag-ui-protocol/ag-ui.
Ordem dos eventos
A ordem é o que faz a tela ficar certa. Um evento de estado só faz sentido depois do início da rodada. Uma mensagem em texto só aparece dentro da rodada aberta. A leitura deve seguir essa ordem, e um evento fora de ordem deve ser ignorado e registrado.
Estado e mensagem são coisas diferentes
O estado é a situação da negociação. A mensagem é o que foi dito. Quem volta à tela precisa ver o estado, e não a lista de mensagens inteira. Por isso, o registro guarda os dois, mas a tela mostra o estado primeiro.
Fim e erro
Uma rodada termina com um evento de fim ou de erro. O erro deve trazer um motivo legível. Sem fim ou erro, a tela fica presa, e o registro parece em andamento para sempre.