Glossário
60 termos de “Gerenciamento e persistência de estado: fazendo tarefas longas sobreviverem à interrupção”. Passe o cursor sobre a primeira ocorrência na lição para ver a definição.
| Termo | Definição | Fonte |
|---|---|---|
| memória | O contexto que você entrega ao modelo — responde à pergunta "o que o modelo já viu?". Pode já estar persistida em disco (como o NOTES.md) ou ainda viver apenas na memória do processo. | How we built our multi-agent research system — Anthropic Engineering |
| estado de execução | A cena em andamento que o processo do harness está segurando — o array messages, contadores como turns e tokensUsed, a chamada de ferramenta ainda não registrada. Por padrão vive apenas na memória do processo e se perde quando o processo termina. | How we built our multi-agent research system — Anthropic Engineering |
| messages | O array com o histórico completo da conversa que o harness segura em memória; é a única fonte para restaurar o contexto ao modelo e o maior campo do checkpoint. | How we built our multi-agent research system — Anthropic Engineering |
| turns | Contador de quantos turnos já rodaram, usado para julgar condições de parada como o teto de turnos; na retomada precisa continuar do valor do checkpoint, não recomeçar do zero. | How we built our multi-agent research system — Anthropic Engineering |
| tokensUsed | Contador cumulativo de uso de tokens; na retomada precisa ser carregado do checkpoint para sustentar as decisões de limiar de compactação de contexto. | How we built our multi-agent research system — Anthropic Engineering |
| pendingToolUse | Campo do checkpoint que marca uma chamada órfã (o modelo a nomeou, o resultado ainda não foi registrado); é null ou um objeto no formato {id, name, input}. | How we built our multi-agent research system — Anthropic Engineering |
| chamada órfã | Um bloco tool_use que o modelo nomeou mas cujo resultado não chegou a ser empurrado de volta em messages antes de o processo cair, ficando sem o tool_result correspondente. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint | Serializar o estado de execução (messages, turns, tokensUsed, pendingToolUse) em disco para que o processo consiga retomar depois de uma queda; uma das salvaguardas determinísticas emparelhadas com a adaptabilidade do modelo. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint.json | O arquivo de checkpoint que guarda version, task, turns, tokensUsed, messages e pendingToolUse — um instantâneo completo da cena de execução. | How we built our multi-agent research system — Anthropic Engineering |
| version | Número de versão do protocolo dentro do checkpoint.json; permite ao loadCheckpoint confirmar a compatibilidade de formato e recusar carregar versões que não batem. | How we built our multi-agent research system — Anthropic Engineering |
| task | A string da tarefa original do usuário guardada no checkpoint.json, para que o harness reiniciado saiba a que tarefa esta cena pertence e consiga relatar progresso. | How we built our multi-agent research system — Anthropic Engineering |
| saveCheckpoint | Função que escreve o estado atual em disco; a implementação correta grava primeiro um arquivo temporário e depois renomeia atomicamente, evitando a corrupção de uma gravação pela metade. | How we built our multi-agent research system — Anthropic Engineering |
| ponto de gravação A | Primeiro checkpoint dentro de um turno, salvo depois que o modelo nomeia uma ferramenta e antes de ela executar; registra em pendingToolUse o bloco tool_use daquele turno. | How we built our multi-agent research system — Anthropic Engineering |
| ponto de gravação B | Segundo checkpoint dentro de um turno, salvo depois que o resultado da ferramenta é empurrado para messages; devolve pendingToolUse a null. | How we built our multi-agent research system — Anthropic Engineering |
| arquivo temporário | Arquivo intermediário (por exemplo, checkpoint.json.tmp) gravado primeiro na escrita atômica do checkpoint; é escrito por inteiro antes de ser renomeado sobre o arquivo real. | How we built our multi-agent research system — Anthropic Engineering |
| fs.renameSync | Operação de renomeação atômica dentro do mesmo sistema de arquivos; a entrada de diretório ou aponta por inteiro para o arquivo novo ou continua apontando para o antigo, sem estado intermediário de meio-renomeado. | How we built our multi-agent research system — Anthropic Engineering |
| sobrescrever no lugar | Gravar direto por cima do arquivo de checkpoint com fs.writeFileSync; não é atômico e pode deixar um JSON truncado se o processo for morto no meio da gravação. | How we built our multi-agent research system — Anthropic Engineering |
| retomada | Reiniciar o loop a partir de um checkpoint depois de uma queda, lendo o estado de volta, reconstruindo messages e continuando de onde o erro aconteceu, em vez de recomeçar do turno 1. | How we built our multi-agent research system — Anthropic Engineering |
| loadCheckpoint | Função que lê e analisa o arquivo de checkpoint; deve validar o campo version e lançar erro em alto e bom som quando a versão não bate ou a análise falha, em vez de cair silenciosamente para um estado vazio. | How we built our multi-agent research system — Anthropic Engineering |
| reconcile | Função que trata um pendingToolUse órfão na retomada; decide pela natureza da ferramenta (somente leitura ou de alto impacto) e pelo estado do livro-razão se reexecuta, reusa ou devolve is_error. | Handle tool calls — Claude API |
| READ_ONLY_TOOLS | Conjunto de nomes de ferramentas (read_file, grep, list_dir, web_search) julgadas sem efeito colateral; na retomada, o reconcile reexecuta com segurança as ferramentas desse conjunto. | Handle tool calls — Claude API |
| ferramenta somente leitura | Ferramenta com efeito colateral zero (ler arquivos, buscar); é segura de reexecutar quantas vezes for, porque o mundo externo permanece inalterado. | Handle tool calls — Claude API |
| ferramenta de alto impacto | Ferramenta que muda estado externo (send_email, create_ticket, delete_file); precisa confirmar se já executou antes de reexecutar, para evitar efeitos colaterais duplicados. | Handle tool calls — Claude API |
| is_error | Campo opcional do tool_result definido como true para indicar que a execução da ferramenta falhou ou que o estado é desconhecido, deixando o modelo saber e se adaptar em vez de supor sucesso. | Handle tool calls — Claude API |
| tool_result | Bloco de conteúdo devolvido ao modelo para cada tool_use; o protocolo exige que todo tool_use tenha um tool_result correspondente, casado por tool_use_id, todos na mensagem user seguinte. | Handle tool calls — Claude API |
| tool_use | Bloco de conteúdo na resposta do modelo que nomeia uma ferramenta a chamar; contém os campos id, name e input. Um tool_use órfão fica sem tool_result correspondente quando o processo cai. | Handle tool calls — Claude API |
| idempotente | Operação que produz o mesmo efeito final quer você a rode uma vez, quer a rode muitas; o julgamento se apoia no efeito (o estado final no mundo externo), não no valor de retorno. | How we built our multi-agent research system — Anthropic Engineering |
| livro-razão de efeitos | Registro em disco separado, indexado por tool_use_id, que rastreia quais efeitos colaterais de fato aconteceram; escrito no instante em que a ferramenta tem sucesso, permitindo à retomada distinguir "rodou" de "não rodou". | How we built our multi-agent research system — Anthropic Engineering |
| effects.json | O arquivo do livro-razão de efeitos, indexado por tool_use_id, que registra o nome da ferramenta, o resultado e o carimbo de tempo; escrito assim que a ferramenta tem sucesso, antes do ponto de gravação B. | How we built our multi-agent research system — Anthropic Engineering |
| tool_use_id | Identificador único que o modelo atribui a cada bloco tool_use; não muda quando a mesma nomeação é repetida, o que o torna uma chave de idempotência natural para o livro-razão de efeitos. | Handle tool calls — Claude API |
| at-least-once | Semântica de execução inerente à retomada por checkpoint (pelo menos uma vez): uma ferramenta pode terminar sem que o resultado seja registrado antes da queda, tornando impossível distinguir "não rodou" de "rodou mas não foi registrado". | How we built our multi-agent research system — Anthropic Engineering |
| loadEffects | Função que lê o livro-razão de efeitos; devolve um objeto vazio quando o arquivo não existe ou não pode ser analisado, tratando isso como "ainda não há registros" em vez de bloquear a retomada. | How we built our multi-agent research system — Anthropic Engineering |
| saveEffect | Função que grava o livro-razão de efeitos de volta em disco usando a gravação atômica de arquivo temporário mais rename; só pode ser chamada depois que a ferramenta executa com sucesso e devolve um resultado real. | How we built our multi-agent research system — Anthropic Engineering |
| válvula de aprovação | Checagem pré-execução para ferramentas de alto impacto que exige confirmação humana; pergunta "isto deve ser feito?" (distinta do "isto já foi feito?" do livro-razão de efeitos). | How we built our multi-agent research system — Anthropic Engineering |
| ensureTicket | Exemplo de redesenhar "criar" como "garantir que existe": procura pelo título, devolve o existente se encontrar e só cria se faltar; idempotente por projeto. | How we built our multi-agent research system — Anthropic Engineering |
| acréscimo | Estilo de escrita cumulativo (array.push, append em arquivo de log); cada chamada de fato acrescenta mais uma coisa, fazendo o estado final variar com a contagem de chamadas — em geral não é idempotente. | How we built our multi-agent research system — Anthropic Engineering |
| sobrescrita | Estilo de escrita por substituição (definir uma linha com um valor fixo, um write_file de arquivo inteiro); chamar uma ou dez vezes deixa o mesmo estado final — em geral é idempotente. | How we built our multi-agent research system — Anthropic Engineering |
| runToolUses | Função que executa todos os blocos tool_use de um turno; depois de integrar o livro-razão de efeitos e a válvula de aprovação, a ordem passa a ser: consultar o livro-razão, depois a aprovação, depois executar, depois registrar no livro-razão. | How we built our multi-agent research system — Anthropic Engineering |
| rebobinagem | Reverter a cena da decisão para um turno anterior e tentar de novo quando a tarefa saiu do rumo (não uma queda); reverte o checkpoint, não os efeitos colaterais externos já consumados. | Checkpointing — Claude Code Docs |
| bifurcação | Copiar duas linhas do tempo independentes a partir do mesmo checkpoint para explorar rotas diferentes; cada linha ganha a própria sequência de checkpoints e o próprio livro-razão de efeitos em branco. | Checkpointing — Claude Code Docs |
| rewindTo | Função que pega o checkpoint de um turno específico dentro da sequência retida por turno; assume por padrão o último ponto de gravação escrito naquele turno. | Checkpointing — Claude Code Docs |
| forkFrom | Função que copia uma linha do tempo independente a partir do checkpoint de um turno específico; a nova linha traz a própria sequência de checkpoints e um livro-razão de efeitos em branco, isolada da linha principal. | Checkpointing — Claude Code Docs |
| turn-014-A.json | Exemplo de nomenclatura da sequência de checkpoints por turno, embutindo no nome do arquivo o número do turno e a letra do ponto de gravação para identificar turno e momento com precisão. | Checkpointing — Claude Code Docs |
| pickLatestPoint | Função que encontra o último ponto de gravação escrito dentro de um turno; apoia-se em a ordenação lexicográfica de A/B coincidir naturalmente com a ordem temporal "antes da ferramenta → depois do resultado". | Checkpointing — Claude Code Docs |
| cena da decisão | O que os checkpoints de fato rebobinam: messages, turns, pendingToolUse e os demais campos que você definiu no instantâneo — não as ações no mundo externo que já foram consumadas. | Checkpointing — Claude Code Docs |
| modo de dry-run | Modo, usado durante a bifurcação, em que ações externas não são executadas de fato, impedindo que as duas linhas do tempo acionem a mesma ferramenta de alto impacto e causem efeito colateral dobrado. | How we built our multi-agent research system — Anthropic Engineering |
| sequência de checkpoints | Série de arquivos de checkpoint retida por turno, em vez de sobrescrita para guardar só o mais recente; é o pré-requisito da rebobinagem e da bifurcação, e cada linha bifurcada carrega a própria cópia independente. | Checkpointing — Claude Code Docs |
| Git | Sistema de controle de versão que gerencia o histórico permanente e colaborativo do próprio código; distinto dos checkpoints (recuperação de sessão em escala de minutos) e do livro-razão de efeitos (registro de efeitos colaterais externos). | Checkpointing — Claude Code Docs |
| CRASH_AFTER | Variável de ambiente que controla o momento da queda simulada (por exemplo, CRASH_AFTER=after-effect-write:3 dispara a queda depois da 3ª gravação no livro-razão). | How we built our multi-agent research system — Anthropic Engineering |
| SimulatedCrash | Tipo de exceção dedicado a simular a morte do processo; main() captura apenas essa exceção, imprime um log e sai com o código 137, fazendo a demonstração se ler como uma morte real em vez de um stack trace. | How we built our multi-agent research system — Anthropic Engineering |
| crashPoint | Função de disparo de queda simulada controlada por variável de ambiente; compara o rótulo da operação corrente com CRASH_AFTER e lança SimulatedCrash quando eles casam. | How we built our multi-agent research system — Anthropic Engineering |
| --resume | Flag de linha de comando que indica que esta inicialização deve fazer loadCheckpoint e seguir o caminho de recuperação em vez de começar do zero; sem ela, main() limpa explicitamente os arquivos antigos de checkpoint e de livro-razão. | How we built our multi-agent research system — Anthropic Engineering |
| fila de respostas | Dublê de verificação que substitui o cliente de modelo real, devolvendo respostas pré-escritas em ordem fixa para tornar a execução da tarefa determinística e o momento da queda reproduzível. | How we built our multi-agent research system — Anthropic Engineering |
| makeStubClient | Função fábrica que constrói um cliente de modelo dublê a partir de uma fila de respostas, usada na verificação para substituir as chamadas reais a client.messages.create. | How we built our multi-agent research system — Anthropic Engineering |
| main() | Função de entrada do programa que faz um único julgamento: se --resume está presente, roteando daí para o caminho de recuperação ou o de início limpo, e capturando de forma unificada SimulatedCrash para imprimir e sair. | How we built our multi-agent research system — Anthropic Engineering |
| divisão em três vias | Os três ramos do reconcile para chamadas órfãs: acerto no livro-razão (reusar), falha no livro-razão com ferramenta somente leitura (reexecutar) e falha no livro-razão com efeitos colaterais (devolver is_error ao modelo). | Handle tool calls — Claude API |
| executar primeiro, registrar depois | Disciplina do livro-razão de efeitos: você tem de obter o resultado real da execução da ferramenta antes de escrevê-lo no livro-razão; inverter essa ordem registra "feito" para algo que nunca rodou. | How we built our multi-agent research system — Anthropic Engineering |
| 137 | Código de saída convencional para um processo morto por SIGKILL; as demonstrações de verificação o usam para fazer as quedas simuladas se lerem como mortes reais em vez de exceções. | How we built our multi-agent research system — Anthropic Engineering |
| aparato de verificação | Método de teste que usa uma fila fixa de respostas mais pontos de queda controlados para fixar os elementos não determinísticos (o que o modelo responde, quando o processo morre), permitindo afirmar o comportamento de recuperação linha por linha. | How we built our multi-agent research system — Anthropic Engineering |
| proporção | Princípio de que a maquinaria de checkpoint só deve ser acrescentada quando a complexidade comprovadamente melhora os resultados; nem toda tarefa curta precisa de checkpointing completo. | Building Effective AI Agents — Anthropic Engineering |