Pular para o conteúdo
jsonW Paper GitHub

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.

Especificação oficial do A2A (a2a-protocol.org) →