Protocolos de comércio com agentes
A2A: as tarefas de um agente gravadas em jsonW, uma linha por mudança de estado
No A2A, cada pedido vira uma tarefa com estados e um resultado. O jsonW guarda essas tarefas em arquivos por dia, uma linha por mudança. Veja o formato do protocolo, o esquema que a Wortic declara e como o serviço relê a gravação ao subir.
· jsonW 1.3.11
O protocolo
O A2A troca mensagens entre agentes. Cada pedido vira uma tarefa, identificada por um id. A tarefa tem um estado, como em andamento ou concluída, e pode gerar artefatos, que são os resultados entregues. A especificação atual é a 1.0, e descreve as ligações em JSON-RPC, gRPC e HTTP com JSON.
O cartão do agente, o Agent Card, fica em /.well-known/agent-card.json. Ele declara as capacidades. A Wortic declara streaming como falso, o que quer dizer que as respostas não são transmitidas aos poucos.
"capabilities": {"streaming": false, "pushNotifications": false, "extendedAgentCard": false}
O que o jsonW guarda
As tarefas do A2A da Wortic ficam em jsonW. Cada mudança de estado vira uma linha. Os arquivos são de gravação viva, com um arquivo por dia, com o nome no formato tarefas seguido da data. O esquema é declarado à mão no próprio código, com quatro colunas:
// Esquema: id:texto,contexto:texto,estado:texto,tarefa:texto
A coluna id é o identificador da tarefa. A coluna contexto agrupa as mensagens de uma mesma conversa. A coluna estado diz em que ponto a tarefa está. A coluna tarefa traz o conteúdo da tarefa.
Como a regra de leitura funciona
Uma tarefa muda de estado várias vezes. Por isso, o arquivo tem várias linhas com o mesmo id. A regra é simples: a última linha de cada id vale. As linhas anteriores ficam como histórico.
Ao subir, o serviço relê os arquivos dos dias e monta um índice em memória. Assim, consultar uma tarefa não precisa abrir o disco. Cada linha é descarregada no fim da gravação, então o que já foi respondido está no disco mesmo se o serviço cair logo depois.
O que isso garante e o que não garante
A gravação em linha, com descarga no fim, dá ao sistema um registro de cada estado. Quem consulta a tarefa recebe o último estado, sem depender de uma leitura lenta. Essa é uma garantia sobre o registro, não sobre o resultado do negócio. Um pedido concluído diz que a resposta saiu, não que o cliente ficou satisfeito.
Por que um arquivo por dia
Um arquivo por dia separa o histórico de forma simples. Para achar uma tarefa antiga, basta olhar a data do arquivo.
O que o jsonW não guarda aqui
Este registro é o da tarefa do A2A. O carrinho, o pedido e o pagamento não ficam nesse arquivo. Eles são feitos pelas funções do banco de checkout, que o agente chama por outros caminhos. Essa separação evita que um dado de dinheiro esteja em dois lugares.
Quem deve olhar isso
Quem opera o sistema precisa saber que cada linha é um estado, e não um resumo. Para auditar um pedido, leia a sequência de linhas do mesmo id, na ordem em que foram gravadas.
A especificação oficial do protocolo está em a2a-protocol.org.