TUNC.AI / Guias do Tunc Orb

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.