Guarde o estado do agente na nuvem, não em um arquivo JSON local
Checkpoints, listas de itens processados e logs de execução que sobrevivem a uma nova sessão, a um novo computador ou a um agente que travou, com novas tentativas que nunca se aplicam duas vezes.
Atualizado em
Agentes que trabalham por mais de uma sessão guardam estado: quais itens estão prontos, onde um trabalho longo parou, o que aconteceu em cada execução. Normalmente isso é um state.json ao lado do agente. Ele se perde junto com a máquina, outros agentes não conseguem vê-lo, e duas execuções sobrescrevem uma à outra. O Tunc Orb guarda o mesmo estado na nuvem, com regras que tornam seguras as gravações simultâneas e repetidas.
Registros para o estado atual
Um registro guarda um valor: JSON, texto ou binário, de até 16 MiB. Crie-o uma vez e depois altere-o com base na revisão que você leu por último. Uma revisão desatualizada é recusada com revision_conflict, então dois agentes nunca sobrescrevem um ao outro em silêncio: quem perde lê de novo e decide outra vez.
curl -s https://api.tuncorb.com/v1/write \
-H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
-d '{"operation":"create","name":"jobs/import/checkpoint",
"about":"Where the nightly import stopped",
"value":{"cursor":"2026-10-23T00:00:00Z","done":[]},
"mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'Para alterar parte de um registro JSON, envie um JSON Patch (add, remove, replace, test). Se qualquer operação falhar, nada muda:
curl -s https://api.tuncorb.com/v1/write \
-H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
-d '{"operation":"patch","name":"jobs/import/checkpoint","if_revision":"rev_…",
"patch":[{"op":"replace","path":"/cursor","value":"2026-10-24T00:00:00Z"},
{"op":"add","path":"/done/-","value":"batch-17"}],
"mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'Logs para o que aconteceu
Um log é só de acréscimo: cada append adiciona de 1 a 100 entradas (até 64 KiB) e o serviço atribui os IDs e a ordem delas. Dê a uma entrada uma event_key, como o ID da mensagem de origem: enviar a mesma chave de novo com conteúdo idêntico devolve a entrada original em vez de uma duplicata, enquanto enviar conteúdo diferente com a mesma chave é recusado com event_key_conflict e leva junto o resto daquele lote.
curl -s https://api.tuncorb.com/v1/write \
-H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
-d '{"operation":"append","name":"jobs/import/runs","about":"One entry per nightly import run",
"entries":[{"value":{"rows":1204,"status":"ok"},"event_key":"run-2026-10-24"}],
"mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'Novas tentativas nunca se aplicam duas vezes
Toda alteração leva um mutation_id. Se uma requisição expirar e você não souber se ela foi aplicada, envie-a de novo com o mesmo mutation_id, ou peça o resultado com data_read operação status. A alteração é aplicada uma única vez.
A partir do seu próprio código
Crie uma chave de API em https://tunchub.com/account/keys/new e envie-a como token Bearer para https://api.tuncorb.com (POST /v1/read, /v1/write, /v1/delete). Agentes no claude.ai, ChatGPT, Claude Code, Cursor e VS Code usam o mesmo armazenamento por https://mcp.tuncorb.com/mcp, então um script e um agente podem compartilhar um mesmo checkpoint.
- Pelo MCP remoto, um único valor tem no máximo 64 KiB; guarde arquivos maiores no Tunc Art e armazene o artifact_id deles em um registro.
- Por agente, a cada segundo: 50 leituras, 20 salvamentos, 5 buscas. Picos curtos não são problema.
- Grátis: 1 GB de armazenamento compartilhado pelo Tunc Hub, Tunc Art e Tunc Orb, com 50.000 operações do Tunc Orb por dia.
