TUNC.AI / Guias do Tunc Orb

Guarda o estado do agente na nuvem, não num ficheiro 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 falhou, com novas tentativas que nunca se aplicam duas vezes.

Atualizado em

Os agentes que trabalham durante mais de uma sessão guardam estado: que itens estão concluídos, onde parou um trabalho longo, o que aconteceu em cada execução. Normalmente, isso é um state.json ao lado do agente. Perde-se com a máquina, os outros agentes não o conseguem ver, e duas execuções substituem-se uma à outra. O Tunc Orb guarda o mesmo estado na nuvem, com regras que tornam seguras as escritas simultâneas e repetidas.

Registos para o estado atual

Um registo guarda um valor: JSON, texto ou binário, até 16 MiB. Cria-o uma vez e depois altera-o com base na revisão que leste por último. Uma revisão desatualizada é recusada com revision_conflict, por isso dois agentes nunca se substituem um ao outro em silêncio: quem perde volta a ler 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 registo JSON, envia um JSON Patch (add, remove, replace, test). Se alguma 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-lhes os IDs e a ordem. Dá a uma entrada uma event_key, como o ID da mensagem de origem: voltar a enviar a mesma chave com conteúdo idêntico devolve a entrada original em vez de um duplicado, enquanto enviar conteúdo diferente com a mesma chave é recusado com event_key_conflict e arrasta consigo o resto desse 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

Cada alteração leva um mutation_id. Se um pedido expirar e não souberes se foi aplicado, envia-o de novo com o mesmo mutation_id, ou pede o resultado com data_read operação status. A alteração é aplicada uma única vez.

A partir do teu próprio código

Cria uma chave de API em https://tunchub.com/account/keys/new e envia-a como token Bearer para https://api.tuncorb.com (POST /v1/read, /v1/write, /v1/delete). Os agentes no claude.ai, ChatGPT, Claude Code, Cursor e VS Code usam o mesmo armazenamento através de https://mcp.tuncorb.com/mcp, por isso um script e um agente podem partilhar o mesmo checkpoint.

  • Por MCP remoto, um único valor tem no máximo 64 KiB; guarda os ficheiros maiores no Tunc Art e armazena o artifact_id deles num registo.
  • Por agente, a cada segundo: 50 leituras, 20 gravações, 5 pesquisas. Picos curtos não são problema.
  • Grátis: 1 GB de armazenamento partilhado pelo Tunc Hub, Tunc Art e Tunc Orb, com 50 000 operações do Tunc Orb por dia.