Runtime de AI Agents de Longa Duração: Sessões e Checkpoints

Viacheslav Dubrov

2026-05-26 · Atualizado 2026-09-06 · 49 min · Agentes de IA

Tradução automática Este artigo foi traduzido automaticamente a partir da versão original em inglês.

Atualização do artigo

Publicado originalmente em 26 de maio de 2026. Revisto e atualizado em 6 de setembro de 2026. A atualização abrange novas capacidades de runtime e opções de deployment, com comparações entre plataformas corrigidas, controlos orçamentais e links para as fontes.

Uma execução de um agent pode durar horas, mas o processo worker pode reiniciar a qualquer momento. O runtime mantém o estado da execução, executa as suas ferramentas e recupera se um tool call parar a meio. O modelo continua a escolher a próxima ação. A Parte 6 aborda o harness: o código que fornece contexto, verifica tool calls e decide se o trabalho está concluído.

Em resumo: para pausar e retomar, use um checkpoint store. Mantenha um event log durável do que aconteceu, um sandbox para a execução de ferramentas, um trace para debugging e um harness para executar o loop. Para a maioria das equipas, comece com uma queue, um worker e um checkpointer PostgreSQL. Se não consegue indicar quem é o responsável por cada job, o agent ainda é um protótipo.

O que é um AI agent runtime?

Um AI agent runtime é a infraestrutura que mantém um agent que usa ferramentas em execução depois de terminar uma chamada ao modelo. Armazena o estado da sessão, executa ferramentas, guarda checkpoints, gere secrets, escreve traces, impõe limites de custo e define como o serviço é deployed. O modelo escolhe a próxima ação. O runtime decide onde essa ação é executada, regista o resultado e restaura a execução após uma falha. O harness decide se uma ação é permitida. Não é um store, mas a tabela inclui-o porque o runtime tem de o executar em algum local.

Quatro das cinco primitivas armazenam estado ou limitam o que o código pode fazer: sessão, sandbox, checkpoint e trace. O harness toma as decisões sobre memória, contratos de ferramentas e permissões. Este artigo explica os serviços e stores de que precisa. A Parte 6 explica as suas verificações, retries e acceptance tests.

As execuções longas quebram as premissas de processos stateless

Um endpoint de chat stateless pode manter o estado do request num processo e descartá-lo depois da resposta. Uma execução longa de um agent atravessa reinícios de workers, deploys, resets de contexto e pausas para aprovações. O processo worker já não pode ser a fonte de verdade.

A equipa do OpenAI Codex descreve a duração que estas execuções podem atingir no seu texto sobre harness engineering:

“Vemos regularmente execuções individuais do Codex a trabalhar numa única tarefa durante mais de seis horas (muitas vezes enquanto os humanos estão a dormir).”

A equipa de engineering da Anthropic descreve o problema de estado correspondente em Effective harnesses for long-running agents:

“O desafio central dos agents de longa duração é terem de trabalhar em sessões discretas, começando cada nova sessão sem memória do que aconteceu anteriormente.”

Ambas as observações implicam o mesmo design de runtime: persistir o estado fora do worker e tornar os workers substituíveis.

A sessão tem de existir fora do processo worker. Um store durável regista chamadas ao modelo, intenções e resultados de ferramentas e aprovações, para que outro worker possa retomar no último ponto seguro após uma falha. Um efeito externo pendente precisa de reconciliação antes de essa retoma poder ser considerada segura. Os checkpoints também permitem ao runtime iniciar uma nova sessão do modelo quando a context window fica cheia, sem repetir todo o histórico. Nas palavras da Anthropic, as instâncias do harness tornam-se descartáveis e reiniciáveis; o estado durável vive noutro local.

Cinco primitivas a posicionar antes do deployment

O texto da Anthropic sobre Scaling Managed Agents fornece um vocabulário útil para cinco responsabilidades do runtime. O harness faz o agent avançar, enquanto a sessão regista o que ele fez e o sandbox executa comandos. O checkpoint fornece ao próximo worker um ponto de retoma; o trace preserva evidências para debugging posterior. Uma implementação pode combinar componentes, mas as responsabilidades e os limites de falha continuam a precisar de nomes.

Sessão. Um event log append-only, escrito separadamente, de chamadas ao modelo, tool calls solicitados e concluídos, erros e aprovações. Uma base de dados de checkpoints ajuda na recuperação, mas o histórico do estado do grafo não substitui este log.

O termo é ambíguo, por isso este artigo usa um esquema de nomes ao nível da aplicação para três spans. Um thread é a conversa de um utilizador ao longo de vários dias. É o span com maior duração e pode conter muitas execuções.

Uma sessão do modelo é a mais curta: um período contínuo de contexto do modelo. A compactação — o passo que resume a window para permitir a continuação do trabalho — prolonga uma sessão do modelo em vez de a terminar. Um restart ou um novo início deliberado termina-a. A Parte 6 usa “sessão do modelo” nesse sentido.

Neste artigo, “sessão” significa o log durável de uma execução. Várias sessões do modelo podem escrever num único log, e uma thread de conversa pode conter vários logs de execução. Para recuperar, acorde a execução, carregue a sua sessão, reconcilie qualquer efeito secundário pendente e retome depois do último evento: wake(sessionId) → getSession(id) → reconcile pending effects → resume from last event.

No LangGraph, thread_id é a chave de armazenamento e recuperação do checkpointer para o histórico do estado do grafo de uma thread (consulte LangGraph persistence); não define os limites de conversa, sessão do modelo ou event log deste artigo. Dê ao event log o seu próprio ID de execução ou sessão durável e escolha explicitamente como esses IDs são mapeados para threads do LangGraph. O OpenAI Agents SDK inclui dez session backends integrados, incluindo SQLiteSession, RedisSession, SQLAlchemySession, MongoDBSession e EncryptedSession (consulte a documentação de Sessions). Mantêm histórico mutável de conversas, incluindo remoção, limpeza e compactação; mapeie um SDK session ID para o run-event ID se for útil, mas não trate o histórico do SDK como log de recuperação ou auditoria append-only sem uma garantia equivalente de imutabilidade.

Harness. O loop de orchestration e a única primitiva aqui que toma decisões. Compõe o prompt a partir da memória, chama o modelo, verifica o tool call proposto contra as suas regras de permissões, dispatcha o que é permitido, escreve os resultados na sessão, aplica regras de retry e decide se a tarefa terminou. Auxiliares de planeamento e gestão de contexto codificam pressupostos sobre a capacidade do modelo. A autorização e o isolamento obrigatórios também implementam requisitos que continuam em vigor à medida que os modelos melhoram. A Anthropic afirma-o diretamente — a citação surge na secção sobre failure modes abaixo, que trata sobretudo do que acontece quando esses pressupostos ficam desatualizados.

A equipa do OpenAI Codex chama a isto harness engineering: escrever software continua a exigir engineering, mas uma parte crescente do esforço vai para o scaffolding e não para o código em si. O CompiledStateGraph do LangGraph, os Deep Agents do LangChain e o seu ponto de entrada create_deep_agent, bem como o próprio Claude Code, são harnesses neste sentido.

Sandbox. O ambiente de execução isolado onde os comandos são realmente executados. A página de sandbox concepts do OpenAI Agents SDK atribui aprovações, tracing, handoffs e o estado necessário para retomar execuções ao runtime exterior. Atribui comandos, alterações a ficheiros e isolamento do ambiente à sessão do sandbox.

“Runtime exterior” significa aí o harness juntamente com os seus state stores. No vocabulário desta série, aprovações e handoffs são decisões do harness (Parte 4 e Parte 6); tracing e controlo de retomas são as primitivas de sessão e checkpoint.

Os sandboxes diferem no tempo de vida e no que recordam entre execuções. A forma mais simples é fresh ephemeral: criar um para uma única tarefa, destruí-lo quando a tarefa termina e suportar o custo de cold start em cada execução.

Sandboxes persistent paused mantêm o sistema de ficheiros e um snapshot de memória entre execuções. A próxima retoma pode evitar um boot completo. Snapshot or fork cria uma imagem copy-on-write a partir de um parent preparado, permitindo que muitas tarefas partilhem dependências instaladas e caches quentes sem partilharem o seu estado gravável.

Workspaces per-worktree dão às tarefas checkouts separados; Git worktrees partilham infraestrutura do repositório e não são sandboxes de sistema operativo. Restrinja a execução separadamente com um container, uma VM ou uma política de processos. Uma aplicação por tarefa pode também ter a sua própria stack de observability. Logs, métricas e traces separados permitem fazer debugging de uma execução sem que o seu estado contamine outra. A tabela de providers mais à frente compara os contratos de isolamento e persistência.

Checkpoint. O estado necessário para retomar: que nó do grafo foi executado, os seus valores mais recentes e o que deve ser executado a seguir. Um event log responde ao que aconteceu: as ações solicitadas e os seus resultados. Um checkpoint não pode reconstruir eventos que o harness nunca registou.

O PostgresSaver do LangGraph escreve um Checkpoint em cada fronteira de super-step. Um super-step é uma ronda do grafo, constituída por um único nó ou por um batch executado em paralelo. As escritas por tarefa vão para checkpoint_writes, para que os outputs de nós concluídos com sucesso não sejam recalculados quando um nó irmão falha.

Um checkpoint é um dict simples (v, id, ts, channel_values, channel_versions, versions_seen, updated_channels). O LangGraph serializa-o com o seu JsonPlusSerializer baseado em msgpack, e não com JSON. datetime, set, Decimal e dataclasses fazem round-trip. O formato está documentado na página do langgraph-checkpoint-postgres no PyPI e na referência de checkpoints do LangGraph.

StateSnapshot é a view separada e mais rica que graph.get_state() constrói sobre um checkpoint. Um debug bundle pode exportar o seu .values como o último estado conhecido do grafo; não pode reconstruir detalhes de eventos que o harness nunca registou.

Trace. A superfície de debugging e auditoria. Cada chamada ao modelo, tool call e passo de sub-agent deve emitir timing, estado, modelo e provider, IDs de correlação, contagens de tokens e custo. Prompts, completions, argumentos de ferramentas e resultados de ferramentas são conteúdo opt-in: a orientação GenAI do OpenTelemetry usa metadata por defeito, porque estes campos podem conter dados sensíveis. Capture-os apenas depois de decidir quais as regras de redaction ou filtering, controlos de acesso e retenção aplicáveis. Quando uma execução de seis horas falha, o trace é o que se consulta para perceber o que correu mal. Pode apoiar uma investigação, mas o event log e o estado do checkpoint, com tratamento de idempotency, são o que permite uma retoma ou replay seguros. Nessa altura, o output do terminal da execução já desapareceu há muito. As convenções semânticas GenAI do OpenTelemetry normalizam os nomes dos atributos (qual o modelo, qual o provider, quantos tokens, qual a conversa, qual o workflow). Para um destino compatível com OTLP que suporte estas convenções, a mesma instrumentação pode exportar o trace para sistemas como Tempo, Jaeger, Honeycomb ou LangSmith, embora possam continuar a ser necessários adapters do backend ou configuração específica do destino.

Policy e secrets atravessam as primitivas

Dois limites atravessam as cinco primitivas. São a versão de runtime do argumento de segurança da Parte 4. A decisão de permissão pertence ao harness; o que se segue explica onde está fisicamente a maquinaria que a impõe e alimenta.

Enforcement de permissões

A permission ladder da Parte 4 precisa de um local onde ser executada. A verificação ocorre antes de cada tool call e decide se este avança. Dois padrões são comuns em produção. O filesystem-permission middleware dos Deep Agents pode limitar as ferramentas de sistema de ficheiros integradas aos paths declarados. Não controla comandos shell do sandbox, ferramentas personalizadas ou chamadas MCP; imponha essas regras na policy do sandbox ou por trás do seu próprio tool proxy. Anthropic Managed Agents encaminha tool calls MCP personalizadas através de um proxy que detém as credenciais. A execução de comandos no sandbox e a autenticação Git usam caminhos separados; o proxy MCP não é um interceptor universal para todas as ações. Quando uma chamada sensível precisa de aprovação humana, interrupt() do LangGraph e o approval hook dos Deep Agents pausam o grafo até uma pessoa dizer sim.

Secret broker

O modelo não deve ver secrets de longa duração, e normalmente o sandbox também não. O padrão Managed Agents é o que deve copiar:

“Para Git, usamos o access token de cada repositório para clonar o repositório durante a inicialização do sandbox e ligamo-lo ao remote git local. Git push e pull funcionam dentro do sandbox sem que o agent alguma vez manipule o token. Para ferramentas personalizadas, suportamos MCP e guardamos tokens OAuth num vault seguro. O Claude chama ferramentas MCP através de um proxy dedicado; este proxy recebe um token associado à sessão. … O harness nunca toma conhecimento das credenciais.”

Na stack de referência market-analyst-agent — um pequeno agent LangGraph que obtém dados de mercado e escreve um relatório de analista, desenvolvido ao longo desta série — o worker chama localmente as suas ferramentas de dados de mercado. O servidor MCP opcional exporta uma superfície de ferramentas; não é um credential broker implementado entre esse worker e os seus providers. Ambos os containers podem ler o .env de desenvolvimento partilhado. Um broker de produção exigiria mover as credenciais dos providers para um store que o worker não consiga ler e encaminhar todas as chamadas relevantes através do broker.

Verificação de sanidade do posicionamento

Uma verificação de sanidade prática consiste em anotar cada componente e qual das cinco primitivas implementa. Postgres pode cobrir sessão e checkpoint. O container worker é o harness. Um serviço como Daytona, Modal ou E2B fornece o sandbox, enquanto Tempo ou LangSmith armazena o trace.

Depois, inspecione as falhas acopladas. Se duas primitivas viverem no mesmo processo, uma falha derruba ambas. Se partilharem uma credencial, uma fuga atravessa os dois limites. Exemplos comuns são um worker que também é responsável pela durabilidade dos traces ou um token de sidecar que também desbloqueia a base de dados de checkpoints.

Failure modes de um AI agent runtime em produção

O runtime gere retries, restaura trabalho anterior, isola workspaces e impõe budgets. À medida que as execuções atravessam workers e context windows, as falhas deslocam-se para problemas de estado, efeitos secundários duplicados, drift do sandbox e budgets excedidos.

As falhas dividem-se em quatro grupos:

• Falhas de qualidade do output: o agent declara vitória antes de o trabalho estar concluído, esquece o que fez durante um reset da context window ou confia na sua própria autoavaliação e entrega output com erros.
• Falhas de controlo de custos: o agent fica preso num retry loop ou consome um budget de tokens ou tool calls sem produzir nada de útil.
• Falhas de estado e crashes: os workspaces sofrem drift porque uma execução altera ficheiros que outra possui, os tool calls são executados mais do que uma vez porque os retries os repetem, ou o trabalho perde-se quando um worker morre entre eventos.
• Falhas de context window: o modelo faz um resumo e termina cedo porque pensa que está a ficar sem espaço, mesmo quando a window ainda tem margem.

A tabela associa cada falha a uma mitigação, à base da recomendação e ao runtime hook que a impõe. O comportamento específico do modelo pode mudar, por isso trate as observações dos vendors como motivos para voltar a testar o pressuposto, e não como regras permanentes.

Duas ideias estão por detrás da maioria dessas linhas. A Anthropic, sobre a obsolescência dos harnesses em Harness design for long-running application development:

“Cada componente de um harness codifica um pressuposto sobre aquilo que o modelo não consegue fazer sozinho, e vale a pena testar esses pressupostos sob stress, tanto porque podem estar errados como porque podem rapidamente ficar desatualizados à medida que os modelos melhoram.”

A Vercel, sobre o problema relacionado de demasiadas ferramentas codificarem demasiados pressupostos, em We removed 80% of our agent’s tools:

“Apagámos a maior parte e reduzimos o agent a uma única ferramenta: executar comandos bash arbitrários. Chamamos-lhe um file system agent.”

A citação descreve o núcleo bash; o agent que a Vercel lançou manteve duas ferramentas, ExecuteCommand e ExecuteSQL, substituindo um exemplo de código antigo que nomeava dezassete ferramentas. A Parte 3 cobre o antes e o depois completos. O resultado reportado nas cinco queries representativas foi: o sucesso passou de 4/5 para 5/5, e o pior caso passou de 724 s / 100 passos / 145,463 tokens (falhado) para 141 s / 19 passos / 67,483 tokens (bem-sucedido). Essa linha do pior caso é a mais impressionante; em média nas cinco queries, a poupança de tokens foi de 37%. A lição não é “apague as suas ferramentas”. A assistência opcional pode tornar-se redundante à medida que o comportamento do modelo muda. Volte a testar o pressuposto quando o modelo mudar.

A Cognition observou o mesmo alvo móvel relativamente à duração das sessões com o Sonnet 4.5. Em Rebuilding Devin for Claude Sonnet 4.5 descreve um modelo que escreve proativamente SUMMARY.md / CHANGELOG.md quando sente que o contexto se está a esgotar, mas subestima quantos tokens ainda lhe restam. A solução foi ativar o contexto de 1M tokens e limitar a utilização a 200k, para que o modelo continuasse a acreditar que tinha margem. Na altura, isto era uma beta flag.

A documentação sobre context windows da Anthropic, consultada em 6 de setembro de 2026, lista Sonnet 5 e Opus 5 com 1M tokens por defeito; Sonnet 4.5 mantém-se nos 200k. Os modelos Sonnet atuais recebem automaticamente atualizações sobre o contexto restante, e a compactação server-side está disponível em beta para os modelos Claude 4.6 e posteriores. Antes de copiar o limite histórico da Cognition, teste o modelo selecionado com os controlos de contexto suportados. Uma window maior ou um contador de budget não estabelecem recall fiável, e nenhum deles substitui progresso durável fora do modelo.

A equipa de harness da OpenAI tem a versão de uma linha: “Os humanos orientam. Os agents executam.” Quando algo falha, a pergunta útil é que capacidade está em falta e como tornar essa capacidade simultaneamente legível e aplicável para o agent.

O ciclo de vida de uma execução saudável

Uma execução bem comportada é aborrecida. É uma cadeia de pequenos passos recuperáveis, e cada passo concluído escreve estado durável antes de o seguinte começar.

Escrever cada resultado antes de iniciar o passo seguinte limita os danos de um crash. Um efeito externo em curso é a exceção: um worker pode falhar depois de o provider fazer commit e antes de o harness registar o resultado. O worker seguinte tem de reconciliar esse efeito pendente antes de retomar a partir do último passo concluído.

1. Faça boot a partir de uma sessão nova ou retomada. Na retoma, monte o workspace a partir do seu último estado conhecido, leia os progress files deixados pela tentativa anterior (PROGRESS.md, feature-list.json), carregue o último checkpoint e inspecione o event log à procura de tool intents pendentes. Reconcilie qualquer efeito externo pendente antes de fazer outra chamada ao modelo ou ferramenta.
2. Planeie antes de executar qualquer tool call. Registe o que significa “done”, quanto a execução pode gastar, que ferramentas o agent pode invocar e o que deve interromper a execução mais cedo. Estes valores do plano tornam-se runtime checks; sem eles, a execução não tem nada que a limite.
3. Serialize ou coordene explicitamente os tool calls que produzem efeitos secundários. A verificação de permissões do harness decide se cada um é permitido. Antes do dispatch, acrescente uma intenção pending com a sua idempotency key; depois de o provider responder, acrescente o resultado. Chamadas independentes de leitura ou idempotentes podem correr em paralelo quando cada uma tem o seu próprio registo durável de intenção/resultado e os resultados são agregados de forma determinística. Se o worker morrer entre um efeito secundário e a escrita do resultado, retome consultando ou repetindo a chamada ao provider com a mesma key e acrescente o resultado recuperado ou needs_human. Por exemplo, o Stripe devolve o primeiro resultado guardado para uma idempotency key repetida; outro provider precisa de um contrato equivalente de lookup ou retry.
4. Faça checkpoint nas fronteiras de super-step ou, num harness mais simples, depois de cada evento. Persista o estado do grafo, o diff do workspace e referências para quaisquer artefactos produzidos. É este checkpoint que o passo 1 lê na próxima retoma. Se o checkpoint faltar ou estiver desatualizado, a recuperação pode precisar do event log para reconstruir o estado, o que é muito mais lento.
5. Avalie os artefactos quando o agent considerar que terminou: testes, um evaluator em contexto novo, validação de schema, verificações no browser. Se a verificação passar, a execução termina com sucesso. Se falhar, a execução retoma a partir do último checkpoint limpo, com a mensagem de falha adicionada ao contexto, e tenta novamente.

Nenhum passo da lista exige que o agent se recorde de alguma coisa entre execuções. O estado vive na sessão e no checkpoint, e o agent lê-o novamente em cada retoma.

Persista um operation ID pertencente à aplicação antes do dispatch e associe-o aos argumentos aprovados. Reutilize-o para recuperar a mesma intenção de negócio, mesmo que o replanning produza um novo model tool-call ID. Registe esses IDs do modelo separadamente para correlação. Atualizações naturalmente idempotentes podem precisar, em alternativa, de uma precondição de versão. A orientação da AWS sobre retries explica por que razão a identidade do request representa a intenção. Defina quando uma ação é realmente nova e durante quanto tempo dura a deduplicação: o Stripe permite eliminar keys após pelo menos 24 horas. Reconcilie payloads alterados e keys expiradas antes de tentar novamente.

Escolha um writer ativo ou um lease por thread. Para input que chega durante uma execução, rejeite, coloque em queue, interrompa ou faça rollback explicitamente; a descrição do runtime dos Deep Agents aborda estas opções. O cancelamento tem de impedir novos dispatches, registar o pedido e reconciliar efeitos em curso; matar o worker não desfaz uma chamada ao provider.

O enforcement do budget pertence ao lado do dispatch. Chamadas concorrentes não podem gastar a mesma allowance restante. O Prometheus é um sistema de monitoring, não um ledger autoritativo de gasto por request. Reserve de forma conservadora e reconcilie a utilização real; accounting atrasado do provider e cancelamento podem ainda causar overshoot.

Os novos controlos do modelo ajudam a regular o ritmo da execução, mas não são responsáveis pelo seu limite de gasto. O beta task budgets da Anthropic fornece aos modelos suportados da Messages API um budget indicativo ao longo de um loop agentic. Pode ser excedido; max_tokens limita uma resposta, não a execução completa. O suporte é específico do modelo: Opus 5 suporta task budgets, enquanto Sonnet 5 não suporta. Mantenha o dispatch ledger e o caminho de cancelamento mesmo quando o modelo recebe uma indicação de budget.

As paragens de segurança do provider precisam do seu próprio caminho terminal. Para misalignment_policy_violation da OpenAI, pare o dispatch, preserve os registos correlacionados e peça revisão de um operador em vez de fazer retry. Trate erros de stream depois de output parcial e reconcilie efeitos anteriores; a Parte 4 explica o limite de monitoring.

A avaliação deve incluir evidências fora do contexto que produziu o output. Um evaluator em contexto novo reduz o enviesamento de contexto partilhado, enquanto testes, linters, verificações no browser e validação de schema fornecem evidência determinística. A verificação pode devolver pass, fail ou needs_human. Para code agents, o reviewer pode ser outra sessão do modelo com ferramentas apenas de leitura. Para agents de dados e relatórios, combine validação determinística com um reviewer model quando ainda for necessário julgamento.

Onze padrões de deployment de AI agents e o que decide entre eles

Depois de nomear as cinco primitivas, a questão é qual a forma de deployment que as executa. Por “forma” entendo uma disposição dessas primitivas: onde vive o harness, onde persiste o estado e que tipo de sandbox executa o trabalho. Uma forma é uma decisão de wiring, não uma escolha de vendor. O gráfico abaixo mostra em que ponto cada forma é mais adequada no eixo da duração da execução. O texto seguinte explica o que decide entre elas.

Se só ler uma das onze, leia a forma 2: queue + worker + checkpoint DB. É o default que recomendo para a maioria das equipas, a forma usada pelo repositório de referência e o esqueleto que a maioria das outras formas varia: queue → worker → estado durável, trocando a origem do sandbox, o proprietário do harness ou o state engine. Ler primeiro a forma 2 torna o resto mais rápido de consultar.

O gráfico compara as formas pela duração da execução. A matriz abaixo compara-as pela propriedade: cada célula contornada identifica o componente que fornece essa primitiva.

1. SDK dentro de um app server (síncrono, limitado ao request)

A forma original. O agent SDK corre dentro de um request handler. É adequado para tarefas inferiores a 30 segundos, demos e ferramentas internas. É inadequado para tudo aquilo de que um cliente HTTP se possa desligar. O timeout HTTP do Cloud Run chega no máximo a 60 minutos, e qualquer panic no web tier mata a execução. O SDK é o harness. A execução de ferramentas não confiáveis precisa de um sandbox separado, e o estado normalmente vive na memória do processo, a menos que seja explicitamente enviado para outro local. Não use esta forma para trabalho de várias horas.

2. Queue + worker + checkpoint DB

O default que recomendo para a maioria das equipas e a implementação demo com forma de produção em market-analyst-agent: um worker Python com um checkpointer PostgreSQL, Redis Streams (ou RabbitMQ) para a queue de entrada e um MCP sidecar para ferramentas. É adequado para execuções de 10 minutos a várias horas com passos idempotentes. O runner local pode contornar a queue para desenvolvimento síncrono, mas a queue faz parte da forma de produção assim que precisar de submissão assíncrona e backpressure.

No padrão de produção, a app aceita um request, cria uma linha de sessão, coloca um job na queue e devolve um run ID. O worker obtém o job, executa o harness, escreve eventos de sessão e checkpoints, faz stream do estado e guarda artefactos à medida que avança. O Postgres sobrevive, os workers são descartáveis e a profundidade da queue fornece backpressure. Computação Spot/Preemptible funciona desde que as escritas duráveis de eventos e checkpoints terminem antes de o worker reportar sucesso. O repositório associado demonstra a forma, mas não uma recuperação durável verificada. O seu consumer lê mensagens novas sem reclamar jobs pendentes, faz ACK de exceções e redelivera trabalho com um novo estado inicial, em vez de ter um contrato de retoma definido. Em produção são necessários comportamentos de claim/lease/reclaim/ACK e fault tests antes de se poder chamar recoverable a esta topologia.

Nesta forma, o worker é o harness. O seu container e o workspace por thread fornecem um limite de execução, mas código não confiável continua a precisar de um sandbox hardened ou de uma VM. O event store é responsável pelo histórico da sessão; PostgresSaver é responsável pelo estado do checkpoint. Podem partilhar uma base de dados apenas quando o harness escreve explicitamente ambos os schemas. Os traces passam pelo OpenTelemetry para a stack de observability que executar.

3. Durable workflow engine (ao estilo Temporal)

O código de orchestration do agent corre dentro de um Temporal Workflow; chamadas ao modelo e tool calls correm como Activities. O estado do workflow vive num event-history log suportado por Cassandra, MySQL ou Postgres, para que possa ser reproduzido entre falhas. Deployments de workflow-code que se sobreponham a uma execução precisam de Worker Versioning ou patches seguros para replay; substituir código sem essa disciplina pode quebrar o replay. A integração Temporal × OpenAI Agents SDK, geralmente disponível desde março de 2026, inclui um OpenAIAgentsPlugin e um helper activity_as_tool, e o texto sobre agentic sandboxes descreve o fork de um agent em execução para outro provider de sandbox a meio da conversa. Workflows inativos consomem zero computação. As limitações são reais: agents realtime não são suportados e o streaming continua marcado como experimental, enquanto LocalShellTool e ComputerTool estão desativados por não se adequarem a um modelo distribuído.

Use esta forma quando a execução tiver pontos de espera reais: aprovações humanas, callbacks externos, sleeps longos, retries com regras de negócio, janelas de deployment — e a equipa conseguir operar versioning de workflows seguro para replay. Uma aprovação humana torna-se um sleep durável que não consome computação, e não um polling loop.

O código do Workflow é o harness. O sandbox vive normalmente fora do Temporal e é chamado a partir de Activities. O estado da sessão e do checkpoint colapsa no event-history log do Temporal, enquanto a visibilidade do trace vem da Temporal UI e de spans OpenTelemetry em cada Activity.

4. Sandbox provider por sessão

Uma forma mais recente. Cada execução do agent recebe a sua própria microVM ou container de um provider de sandbox-as-a-service. O harness vive algures de forma durável; o sandbox é o ambiente de execução descartável.

Os valores de startup dos providers medem intervalos diferentes e não constituem um ranking de velocidade. Meça separadamente o tempo entre o request à API e o primeiro comando concluído com sucesso, e a latência até a aplicação estar pronta, incluindo estado da image/cache, região, concorrência e p95/p99. O boot de container de aproximadamente um segundo do Modal, por exemplo, exclui a inicialização da aplicação. Verifique os limites de concorrência da conta antes de fazer load testing.

O Daytona regista um parent-child link para cada fork independente, preservando a lineage dos sandboxes derivados. O harness do Codex da OpenAI usa a variante por worktree: “O Codex trabalha numa versão totalmente isolada dessa app, incluindo os seus logs e métricas, que são destruídos quando a tarefa termina.”

Escolha esta forma quando o agent executar código não confiável, automação de browsers, testes ou instalações de packages. O compromisso é um custo e um acoplamento ao provider superiores aos de workers partilhados.

O provider é responsável pelo sandbox e por mais nada. Harness, sessão, checkpoint e trace continuam do seu lado, normalmente ligados como a forma queue + worker do #2.

5. Anthropic Managed Agents (harness hosted)

A Anthropic lançou Managed Agents em public beta a 8 de abril de 2026, por detrás do beta header managed-agents-2026-04-01. O serviço fornece uma sessão hosted, harness, sandbox e MCP proxy suportado por vault. wake(sessionId) pode inicializar o harness num novo worker sem perder o estado de sessão durável.

A Anthropic cobra Managed Agents às tarifas normais de tokens mais $0.08 por session-hour. A faturação tem granularidade de milissegundos e aplica-se apenas enquanto o estado da sessão for “running”; o tempo idle é gratuito. Um retry loop descontrolado acrescenta, portanto, custo de session-hour ao custo dos tokens.

Leia as limitações. O desconto da Batch API não se aplica (“As Sessions são stateful e interativas. Não existe batch mode.”). Managed Agents não está disponível através de AWS Bedrock ou Google Vertex AI. Dentro da beta, túneis MCP e o “dreaming” do agent estão por detrás de uma research preview adicional para a qual é necessário pedir acesso; coordination multi-agent e self-evaluation classificada por rubrics são componentes documentados da beta. O lock-in é elevado: troca liberdade do harness por não executar o loop diretamente.

A configuração cloud por defeito coloca as cinco primitivas na Anthropic. Com self-hosted sandboxes, opera a execução, os sistemas de ficheiros e o egress de rede, enquanto a Anthropic executa a orchestration e o modelo. Inputs e resultados das ferramentas continuam a chegar ao seu control plane; skills e memória associadas são aí armazenadas e sincronizadas. Ser proprietário da execução não torna o sistema todo self-hosted.

Claude Platform on AWS também suporta Managed Agents e self-hosted sandboxes; é separado do Bedrock. Aí, uma sessão autónoma precisa de um evento de user role para se reautenticar após seis horas, e sessões self-hosted não podem associar memory stores. Managed Agents first-party não tem essas duas restrições. Verifique a plataforma, além do modelo, antes de copiar um design de sessão.

6. LangChain Deep Agents Deploy (harness aberto gerido)

deepagents deploy empacota um deepagents.toml num LangSmith Deployment com execução durável, memória, multi-tenancy, human-in-the-loop, observability, execução de código em sandbox e execuções agendadas. São suportados modos de deployment cloud, híbrido e self-hosted. Os sandbox providers (LangSmith Sandboxes, Daytona, Modal, Runloop ou personalizados) podem ser trocados através de um único valor de configuração. Os ficheiros e a memória do agent vivem num virtual filesystem com backends plugáveis; a persistência de checkpoints é separada, e a memória é limitada ao user, assistant ou ambos. O lock-in é inferior ao Managed Agents: o harness tem licença MIT, as instruções usam o standard aberto AGENTS.md e os agents são expostos via MCP, o protocolo A2A (Agent2Agent) e Agent Protocol. Consulte o texto da LangChain sobre o runtime por detrás dos Deep Agents em produção.

Por defeito, as cinco primitivas são hosted, mas cada uma pode ser trocada por configuração. O sandbox fica atrás de um único valor de configuração. O memory filesystem é separado da persistência de threads e checkpoints. O trace vai para o LangSmith.

7. Serviço ou job no Google Cloud Run

O Cloud Run tem dois modos de runtime diferentes, e o mais adequado depende da forma como o agent é invocado. Services estão ligados a HTTP e escalam para zero entre requests; o harness corre como request handler e retorna quando a execução termina. Jobs correm até à conclusão sem um HTTP entrypoint; o harness corre como um worker one-shot que sai quando a tarefa termina. Ambos podem alojar o harness, mas nenhum mantém estado entre execuções. Sessões e checkpoints têm de viver em Postgres, Spanner ou outro store externo semelhante.

Os limites rígidos são muito diferentes entre os dois. Timeout de requests dos Cloud Run services: 300 s por defeito, máximo de 3.600 s (60 min). WebSockets têm o mesmo timeout. Cloud Run jobs: 10 min por tarefa por defeito, máximo de 168 h (7 dias); para tarefas que usem GPUs, máximo de 1 hora. A faturação baseada em instâncias (CPU sempre alocada) continua a permitir scale-to-zero; o número mínimo de instâncias é uma configuração separada; jobs não têm HTTP e não fazem autoscale.

Use um service para execuções síncronas até 60 minutos. Use um job para trabalho one-shot ou assíncrono mais longo. Os Cloud Run Jobs podem manter uma tarefa viva durante dias, mas não fornecem replay durável entre deploys, alterações de versão ou substituição de workers. Um workflow mais longo pode atravessar várias execuções quando um orchestrator externo é responsável pelo progresso durável.

O Cloud Run aloja o harness. O estado de sessão e checkpoint vive em Postgres, Spanner ou outro store externo, e os traces podem passar pelo Cloud Logging e OpenTelemetry. O container do service é um ambiente de execução; acrescente um sandbox separado quando o agent executar código não confiável.

8. AWS Lambda: invocações limitadas e workflows duráveis

O timeout máximo de uma função Lambda é 900 s (15 minutos), sem exceção. Se a API Gateway estiver à frente da função, o limite da integração depende do tipo de API. HTTP APIs permitem 30 segundos; as integrações REST têm um default de 29 segundos, enquanto Regional e private REST APIs podem configurar um timeout superior. Lambda durable functions, lançadas em dezembro de 2025, acrescentam checkpoints, steps e waits geridos entre execuções com duração até um ano. A invocação ativa continua limitada, enquanto o workflow durável pode sobreviver a ela. Compare runtimes suportados, regiões, regras de replay e idempotency de activities com os seus requisitos.

O Lambda pode manter um harness limitado dentro do seu limite de 15 minutos. O estado de sessão e checkpoint continua a precisar de localizações externas explícitas; acrescente um sandbox distinto para código não confiável e exporte traces para telemetria externa. Um workflow Lambda durável pode orquestrar trabalho de várias horas através de invocações limitadas.

9. AWS ECS / Fargate task por execução

O Fargate não documenta um limite rígido para a duração das tasks, ao contrário de uma invocação Lambda normal. O Fargate não suporta tasks com GPU; workloads ECS com GPU precisam de instâncias EC2 adequadas ou de um serviço externo de GPU. O Fargate fornece isolamento de tasks baseado em virtualização, embora as credenciais e o acesso de rede permitido continuem a precisar de um threat model. As quotas de throttling do Fargate permitem um burst de lançamento de 100 e reposição a 20 por segundo, com budgets on-demand e spot separados. As quotas de services ECS limitam services que usem discovery AWS Cloud Map a 1.000 tasks por service e clusters baseados em EC2 a 5.000 instâncias de containers.

O Fargate requer o modo awsvpc, pelo que cada task recebe uma interface de rede e um IP privado. Esta forma é adequada ao acesso a dados internos da VPC. O Fargate Spot acrescenta risco de interrupção, e a durabilidade continua a ser da sua responsabilidade, porque a plataforma não tem replay ao estilo Temporal.

O Fargate aloja o harness e dá a cada execução a sua própria task. Isto separa workspaces e credenciais por task, mas não é, por si só, um sandbox completo para código hostil. Sessão, checkpoint e trace vão para serviços externos como RDS ou DynamoDB, além de CloudWatch/X-Ray.

Compare também Amazon Bedrock AgentCore Runtime antes de construir de raiz a camada de sessões na AWS. Aloja o seu código de agent com lifecycle de sessões gerido e escolha de computação. A AWS documenta até 8 horas em serverless microVMs ou 14 dias no seu tipo de computação Instances, que também suporta workloads com GPU. Instances usa recursos EC2 geridos pela AWS na sua conta, com um modelo de segurança diferente da opção serverless. Selecione e teste explicitamente esse contrato de computação; uma instância de maior duração não garante que um efeito externo seja executado exatamente uma vez.

10. Kubernetes Job ou namespace por sessão

É adequado quando já opera Kubernetes e quer sandbox-per-session com controlos a nível do cluster. É inadequado quando precisa de startup inferior a um segundo, porque descarregar a container image e inicializar o pod demora demasiado num cold start. O padrão consiste num Job por execução de agent, com activeDeadlineSeconds, um PersistentVolumeClaim para o workspace e um sidecar para o servidor MCP. A recuperação de crashes é da sua responsabilidade. Adotar Kubernetes apenas para alojar agents é caro em overhead de configuração e carga operacional. Só vale a pena se já executar K8s por outros motivos.

O Kubernetes aloja o harness e o ambiente de execução por execução, normalmente como um Job e, por vezes, com um namespace dedicado. Um isolamento forte continua a depender da runtime class, network policy, pod security e do limite de container ou VM subjacente. O estado da sessão e do checkpoint vive numa base de dados externa ou num PersistentVolumeClaim.

11. Local Docker Compose (apenas dev)

A referência para a secção seguinte. O objetivo desta forma é espelhar a topologia de produção um-para-um (as mesmas primitivas, a mesma forma de rede), executando-a numa única máquina. O que não espelha é o isolamento: um mount de workspace partilhado, um Postgres, nenhum sandbox hardened e nenhum failure domain separado entre o worker e o seu estado. Não faça deployment de nada com esta forma.

O Compose espelha a forma #2 num único host. Na stack de referência, o Postgres contém o estado do checkpoint e o container worker é o harness. Uma sessão com forma de produção precisa do seu próprio event store append-only; o histórico de PostgresSaver, por si só, não fornece um. O mount de workspace partilhado é conveniente para desenvolvimento, mas não isola execuções não confiáveis. A stack OpenTelemetry opcional regista traces.

Stack de referência: Docker Compose

A topologia de referência, usada em slavadubrov/market-analyst-agent, é composta por um worker LangGraph, um checkpointer Postgres, Qdrant para retrieval, um MCP sidecar, uma queue Redis para execuções assíncronas semelhantes às de produção e uma stack de observability opcional com Prometheus / Grafana / Loki / Tempo / OTel. No Compose local, o Redis é opcional apenas porque o runner síncrono pode chamar diretamente o worker. docker compose up levanta localmente a topologia central; o MCP sidecar e a stack de observability são perfis opt-in (--profile mcp, --profile observability).

O diagrama mostra o PostgresSaver da demo local. Uma sessão com forma de produção acrescenta um schema de eventos escrito separadamente para tool intents e outcomes; PostgresSaver continua a ser apenas o estado do checkpoint.

A única peça que vale a pena mostrar inline é a wiring canónica do LangGraph. É um excerto ilustrativo, não um exemplo executável a partir do repositório. Para o executar são necessários langgraph, langgraph-checkpoint-postgres e psycopg[binary,pool], uma base de dados PostgreSQL acessível com permissão para criar as tabelas do checkpointer, POSTGRES_PASSWORD e um StateGraph previamente construído em builder; consulte a configuração do checkpointer Postgres do LangGraph.

import os
from urllib.parse import quote

from langgraph.checkpoint.postgres import PostgresSaver

password = quote(os.environ["POSTGRES_PASSWORD"], safe="")
DB_URI = f"postgresql://agent:{password}@postgres:5432/agent"
# `builder` is your StateGraph, already built
session_id = "session-123"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.setup()  # creates tables on first run
    graph = builder.compile(checkpointer=checkpointer)
    result = graph.invoke(
        {"messages": [{"role": "user", "content": "Continue the task"}]},
        {"configurable": {"thread_id": session_id}},
    )

Observability que sobrevive à execução

É fácil fazer debugging de request handlers curtos: quando algo falha, lê-se a resposta e o log live. Os agents de longa duração não têm esse luxo. Quando uma execução de seis horas falha, o evento interessante aconteceu cinco horas antes, o output do terminal live desapareceu e o worker que o produziu foi substituído. Ninguém vai reconstruir a execução a partir da memória. Por isso, o debugging é feito a partir de artefactos duráveis escritos enquanto a execução ainda estava ativa.

As stacks de produção tendem a cobrir quatro tipos de artefacto, em dois grupos. Dois deles são lidos depois de a execução terminar, para postmortems e replay: um event log pesquisável de cada passo e traces OpenTelemetry de onde foram gastos tempo e tokens. Os outros dois são lidos durante a execução. Um é um live tail do que o agent está a produzir no workspace. O outro é uma stack de observability por worktree que o próprio agent pode consultar enquanto trabalha.

Event log estruturado (ler depois da execução)

Cada chamada ao modelo, tool call, resultado, erro e aprovação é escrito em armazenamento durável, indexado pelo session ID e timestamp. Quando a execução termina, consulta-se como uma tabela de base de dados normal. Addy Osmani define claramente o padrão em Long-running Agents: “Se não consegue reconstruir o que o agent fez nas últimas 24 horas a partir de armazenamento durável, aquilo que tem é um shell script de longa duração que por acaso chama um LLM, e não um agent de longa duração.”

Traces OpenTelemetry GenAI (ler depois da execução)

O mesmo tipo de dados passo a passo é emitido como spans usando os atributos standard das gen_ai.* semantic conventions: nome do modelo, provider, contagens de input e output tokens, conversation ID e workflow name. As convenções continuam com estabilidade Development.

Em 2026, saíram do repositório principal de semantic conventions do OpenTelemetry para o seu próprio repositório de semantic conventions GenAI. Os nomes dos atributos podem ser usados para instrumentação, mas fixe a revisão que validou em vez de um número de versão do main repo. Os campos específicos do provider vivem em subnamespaces (anthropic.*, openai.*) indexados por gen_ai.provider.name. A razão para usar o standard é a portabilidade: em destinos compatíveis com OTLP que suportem estas convenções, trocar de backend pode não exigir nova instrumentação, embora continuem a poder ser necessários adapters do backend ou configuração específica do destino.

Timeline de tool calls e diffs do workspace (ler durante a execução)

A forma mais rápida de saber o que um agent está a fazer neste momento é acompanhar o que produz no workspace, e não fazer grep através de um session log. O Harness Primitives for Long-Running Claude Agents da Anthropic inclui um watch loop em dois painéis para este efeito: watch -n 5 'git log --oneline -8' mostra os commits mais recentes feitos pelo agent e watch -n 5 'find screenshots -name "*.png" | tail -5' mostra os screenshots mais recentes que tirou. Dois painéis de terminal a atualizar a cada cinco segundos são suficientes para perceber se a execução está a fazer progresso real ou a girar em falso.

Stack efémera por worktree (lida pelo próprio agent durante a execução)

Segundo o post sobre o harness da OpenAI: “Logs, métricas e traces são expostos ao Codex através de uma stack local de observability que é efémera para um determinado worktree.” Cada worktree do agent recebe o seu próprio Loki + Prometheus + Tempo de curta duração, limitado apenas a essa execução. O agent consulta-o enquanto trabalha. É isso que permite que um prompt como “nenhum span nestas quatro user journeys excede dois segundos” se torne algo que o agent pode verificar diretamente, em vez de ter de adivinhar.

(O evaluator em contexto novo da tabela de failure modes lê estes artefactos para decidir “done”. Pertence à avaliação, não à observability; consulte § ciclo de vida de uma execução saudável. Depende de todas as superfícies acima.)

Uma stack de observability self-hosted mínima

Para algo como market-analyst-agent:

1. OpenTelemetry Collector com o GenAI Normalizer Processor (contrib, alpha) para atributos GenAI suportados. Use os processors genéricos Attributes ou Transform para filtrar ou reescrever campos gen_ai.*.
2. Tempo (ou Jaeger) para traces, indexados por gen_ai.conversation.id / thread_id.
3. Loki para entradas estruturadas do event log.
4. Prometheus para gen_ai.client.token.usage, gen_ai.client.operation.duration e gen_ai.client.operation.time_to_first_chunk — as métricas gen_ai.server.* vêm do model server, pelo que só as obtém se alojar os weights (consulte as convenções de métricas GenAI).
5. Grafana dashboards indexados por gen_ai.agent.name e gen_ai.request.model.

Alternativas hosted (escolha uma, não três):

• LangSmith: integração nativa com LangGraph; também é o deployment target para Deep Agents Deploy.
• Braintrust: melhor opção se a prioridade forem regression suites eval-first.
• Arize Phoenix: OSS, nativo de OTLP (o protocolo wire do OpenTelemetry), combina com instrumentação OpenInference.
• Dashboard de tracing da OpenAI: automático quando usa o OpenAI Agents SDK ou a sua integração Temporal.
• Tracing Claude da Anthropic: para sessões executadas dentro de Managed Agents.

Instrumentar o nó LangGraph

Este é um excerto ilustrativo e é ignorado pelo example runner do repositório. Assume que o nó LangGraph já tem um span OpenTelemetry ativo, o thread_id atual e um objecto usage de resposta do provider com input_tokens e output_tokens; a configuração do tracer, a configuração de export e o mapeamento de usage específico do provider estão fora do snippet.

# In the LangGraph node, around the model call:
span.set_attribute("gen_ai.operation.name", "chat")
span.set_attribute("gen_ai.provider.name", "anthropic")
span.set_attribute("gen_ai.request.model", "<your-model-id>")
span.set_attribute("gen_ai.response.model", "<your-model-id>")
span.set_attribute("gen_ai.conversation.id", thread_id)
span.set_attribute("gen_ai.agent.name", "market-analyst")
span.set_attribute("gen_ai.workflow.name", "research_then_write")
span.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens)
span.set_attribute("gen_ai.usage.output_tokens", usage.output_tokens)

Nomes de atributos copiados literalmente do registo de semantic conventions GenAI do OpenTelemetry.

Três queries que vale a pena ter num dashboard

# Loki: output tokens per agent in the last hour (one completion event per call)
sum by (gen_ai_agent_name) (
    sum_over_time({service_name="market-analyst-agent"} | json | event = "model_call_completed" | unwrap gen_ai_usage_output_tokens | __error__="" [1h])
)

# PromQL: p95 model latency per model
histogram_quantile(0.95,
    sum by (le, gen_ai_request_model) (
        rate(gen_ai_client_operation_duration_bucket[5m])
    )
)

# TraceQL: long-running tool calls
{ span.gen_ai.operation.name = "execute_tool" && duration > 30s }

A agregação LogQL assume exatamente um evento de completion registado por chamada ao modelo. Deduplicate esses eventos antes da ingestão; rate reportaria tokens por segundo em vez deste total de uma hora. Valide o field mapping contra o stream Loki deployed.

O padrão do debug bundle

Quando uma execução falha, o worker deve deixar um /workspaces/${THREAD_ID}/_debug/ que contenha os artefactos pedidos num postmortem:

• events.jsonl: export do event store append-only escrito separadamente pelo harness, incluindo tool intents, resultados, aprovações e erros.
• checkpoints.jsonl: histórico do estado do grafo de checkpointer.list({"configurable": {"thread_id": ...}}), identificado como checkpoints e não como event log.
• last_state.json: StateSnapshot.values do último super-step concluído com sucesso.
• trace.json: spans exportados via OTLP para a execução; metadata é a base, e qualquer conteúdo capturado segue a trace policy.
• tool_calls.csv: (ts, tool, input_hash, latency_ms, status, error).
• workspace.tar.zst: o diretório do workspace mais git diff contra o commit do initializer.
• screenshots/*.png: o que o agent viu.
• PROGRESS.md, feature-list.json e quaisquer outros progress files escritos pelo agent.
• env.txt: image tags, versão do modelo, harness commit SHA.

Em conjunto, estes artefactos podem fornecer a um humano ou reviewer agent evidência suficiente para reconstruir a falha, desde que o harness tenha escrito o event store enquanto a execução estava ativa. “O agent ficou bloqueado” é vago. Um relatório ilustrativo é concreto: a sessão s_123 gastou 71 por cento dos seus tokens a repetir três comandos depois de npm install falhar.

Escolher a forma certa: guia de decisão

A maior parte da comparação acima reduz-se a um conjunto limitado de decisões.

Começar pela duração da execução

Use a duração da execução como primeiro filtro:

• Menos de 30 segundos, idempotente: SDK limitado ao lifecycle do request num app server.
• 30 s a 60 min: queue + worker + checkpoint DB.
• 60 min a 24 h: a mesma queue + worker ou um Cloud Run Job para trabalho one-shot. Use um durable workflow engine se também precisar de versioning e replay.
• Mais de 24 h, com sobrevivência a deploys obrigatória: durable workflow engine (ao estilo Temporal). Cloud Run Jobs podem manter trabalho longo até ao limite da task, mas não fornecem semântica de replay.
• Loops de treino de reinforcement learning de vários dias: K8s Job + volume + Temporal.

Depois desse filtro geral, verifique efeitos secundários, recuperação, replay, isolamento, localização dos dados e a equipa que irá operar o sistema.

Adequação da plataforma por caso de uso

A matriz é densa, e nenhuma célula verde decide sozinha a arquitetura; as células condicionais, onde uma plataforma suporta algo apenas com uma limitação, são normalmente as que decidem. Uma cobertura ampla de workloads é útil, mas não mostra data residency, semântica de replay, dependência de provider, maturidade operacional ou o custo de mover o estado mais tarde.

As células condicionais usam a mesma regra em todas as plataformas. As opções AWS/VPC e GPU dos Deep Agents dependem de deployment híbrido ou de um sandbox provider; Managed Agents pode usar execução operada pelo cliente enquanto mantém orchestration hosted. A linha de escolha do sandbox inclui uma integração com um provider externo que se constrói num runtime próprio ou configura num harness gerido. Não promete um snapshot do estado em execução. Um Kubernetes Job também precisa de uma camada de API ou queue para um request interativo; concluir rapidamente não o transforma num HTTP service. Compare o acesso de rede, hardware, recuperação e caminho de export de estado do deployment escolhido antes de o selecionar. A linha sobre o código do harness diz respeito ao acesso à implementação do loop, não à portabilidade de um deployment gerido ou do seu estado. A execução de GPU em Kubernetes também requer GPU nodes, drivers e um device plugin.

Managed Agents requer Claude e orchestration operada pela Anthropic. O seu sandbox self-hosted opcional pode adequar-se a execução numa rede privada, mas um requisito para fazer self-host de inference ou do control plane continua a excluí-lo. Reveja que inputs de ferramentas, resultados, skills e memória podem atravessar esse limite. Trabalho interno de coding pode adequar-se quando esses fluxos de dados são aceitáveis e a equipa quer delegar a operação do harness.

Vale a pena modelar o pricing antes de se comprometer, e não depois. O custo de session-hour é $0.08/hora, além dos custos normais de tokens. Se uma sessão individual corresse continuamente, isso representaria cerca de $58/mês por sessão. Com 100 sessões a correr continuamente, seria cerca de $5,800/mês antes dos tokens. Multiplique $0.08 pelo número esperado de horas de sessões concorrentes, acrescente-o à fatura de tokens e compare com o custo de uma stack queue + worker na sua própria infraestrutura. Migrar mais tarde para fora de Managed Agents é um exercício de re-platforming, não uma alteração de configuração.

Harness hosted vs harness próprio

A distinção aqui é quem opera o harness, e não quem escreveu o seu código. Hosted significa que o vendor executa o loop do harness na sua infraestrutura e o cliente chama uma API. Próprio significa que executa o loop na sua própria infraestrutura, mesmo que o código do harness tenha vindo de um vendor.

A LangChain aparece dos dois lados desta linha, o que causa confusão. Fornece LangGraph, uma biblioteca com licença MIT que o cliente faz self-host (próprio), e Deep Agents Deploy, um produto gerido que executa um harness Deep Agents no LangSmith Deployment, no seu modo cloud por defeito (hosted). A mesma empresa, dois modelos operacionais diferentes. O que está a escolher é quem executa o loop, não o logótipo na biblioteca. (Deep Agents Deploy também tem um modo self-hosted para equipas que querem a ergonomia do harness sem o componente cloud; esse modo pertence à categoria própria.)

Escolha um harness hosted quando o seu suporte de modelos, limite de dados, comportamento de recuperação e extension points já forem adequados. Escolha um harness próprio quando essas restrições forem requisitos que espera alterar. A migração entre os dois altera estado, observability e limites de execução, por isso teste o exit path antes de os dados de produção dependerem dele.

Sandbox hosted vs ambiente de execução próprio

Escolha um sandbox hosted quando o isolamento, pause/resume ou semântica de fork do provider corresponderem ao threat model e ao budget de startup. Docker ou Fargate podem adequar-se a workloads internos confiáveis que precisem de acesso VPC ou de data residency estrita, mas um container normal não é um limite suficiente para código hostil. A Parte 4 apresenta o menu de isolamento para esse caso.

State stores: Git, DB e object storage lado a lado

Os agents de longa duração usam normalmente três state stores em simultâneo, porque cada store é responsável por um artefacto diferente.

O Git armazena o estado do workspace: o código, documentos e progress files que o agent altera. Cada commit fornece ao harness um ponto de recuperação estável e à sessão seguinte um histórico compacto.

A base de dados de checkpoints armazena o estado do grafo: o que foi decidido, que nós correram, que resultados regressaram e o que deve correr a seguir. O artifact store contém outputs finais grandes, como PDFs, ficheiros Parquet e screenshots. Esses artefactos não pertencem ao Git nem à base de dados de checkpoints.

Quando usar git como estado

Use git quando o workload tiver forma de código (edições em vários ficheiros, refactors, geração de apps) ou for suficientemente orientado a documentos para o histórico dos ficheiros ser relevante. O padrão é simples: crie uma run branch, faça um commit de initializer e depois faça commits em fronteiras significativas: depois da configuração, depois de cada feature, depois de os testes passarem e depois da limpeza final. Guarde o SHA do commit mais recente do workspace junto da linha do checkpoint. Na retoma, o worker seguinte faz checkout da branch, lê git log --oneline -8, inspeciona git status e o diff mais recente e lê PROGRESS.md ou o handoff file que a sessão anterior tenha escrito.

Isto torna o git uma superfície de recuperação para o artefacto em edição, e não um substituto da checkpoint DB. O Git pode responder a duas perguntas: o que mudou e qual a versão que passou os testes. Não pode dizer ao harness que nó do grafo deve ser executado a seguir, que tool call aguarda aprovação ou que retry já usou a sua idempotency key. O harness da Anthropic usa commits de initializer e commits por feature como fonte de verdade para a recuperação do workspace; o modelo lê git log --oneline -8 para recuperar o estado. Ignore o git quando o produto de trabalho for uma única resposta conversacional. O overhead não compensa.

Quando usar DB checkpointing

Use checkpointing ao estilo PostgresSaver quando o agent tiver uma estrutura de grafo com vários nós cujo estado intermédio seja relevante (planner → researcher → writer → verifier). O repositório de referência usa-o precisamente por essa razão. Não coloque artefactos de workspace à escala de terabytes no checkpoint; esses devem ir para object storage.

Quando usar um artifact store (S3 / GCS)

Use object storage quando:

• o output for maior do que aquilo que a base de dados de checkpoints deve transportar;
• os consumidores downstream precisarem de um artefacto endereçável por URL sem passar pelo agent; ou
• o deliverable e o estado da execução tiverem janelas de retenção diferentes.

Por exemplo, pode eliminar o log da sessão após 30 dias, mas manter o relatório final durante anos. Estruture o layout por (thread_id, checkpoint_id, artifact_name) para que a execução produtora continue a ser reconstruível.

Quando pedir aprovação humana

Defina requisitos de aprovação com base no risco da ação, na autoridade já concedida e na policy de deployment. Uma escrita reversível de draft numa base de dados é diferente de uma cobrança ao cliente ou de uma alteração destrutiva em produção. Quando for necessária aprovação, mostre a ação efetiva, os argumentos e o destino, persista essa decisão e volte a verificá-la se a chamada proposta mudar; não execute uma chamada rejeitada. interrupt() do LangGraph e o approval middleware dos Deep Agents podem pausar a execução para essa decisão. A Parte 4 explica por que isto é uma decisão de permissões, e não uma instrução de prompt.

Checklist prático de produção

Antes de fazer deployment de um agent de longa duração, responda a estas perguntas em termos concretos de infraestrutura.

1. Que store é responsável pelos eventos de sessão e pelos checkpoints?
2. O que acontece se o worker morrer a meio de um tool call?
3. Uma execução pode corromper o workspace de outra?
4. Que ações exigem aprovação?
5. O modelo ou o sandbox podem ler credenciais em bruto?
6. Que tool calls podem fazer retry em segurança?
7. Onde é imposto o limite de custo por execução?
8. Que evidência determinística decide a conclusão e que critérios restantes precisam de um reviewer?
9. Onde vivem os outputs finais depois de o sandbox desaparecer?
10. Conseguimos explicar uma execução falhada amanhã sem a executar novamente?

Se a resposta a alguma destas perguntas for “o prompt diz ao agent para ter cuidado”, o sistema ainda não está deployed. Continua a ser uma demo.

A camada seguinte é o loop do harness

Este runtime pode manter uma execução viva e recuperável, mas a durabilidade não prova que o trabalho esteja correto. A Parte 6, Harness Engineering for AI Agents, abre a primitiva harness da tabela acima: como um trace indica qual das várias falhas ocorreu, onde vivem as regras de retry e stop, o que um handoff tem de preservar e como uma verificação externa de aceitação decide que uma execução terminou. É também o último artigo da série.

Referências

Textos de engineering

• OpenAI, Harness engineering: leveraging Codex in an agent-first world.
• Anthropic Engineering, Effective harnesses for long-running agents.
• Anthropic Engineering, Harness design for long-running application development.
• Anthropic Engineering, Scaling Managed Agents: Decoupling the brain from the hands, 8 de abril de 2026.
• Cognition AI, Rebuilding Devin for Claude Sonnet 4.5: Lessons and Challenges.
• Vercel, We removed 80% of our agent’s tools.
• Addy Osmani, Long-running Agents.

LangGraph e Deep Agents

• Documentação do LangGraph, Persistence.
• Referência do LangGraph, Checkpoints.
• langgraph-checkpoint-postgres no PyPI.
• Documentação da LangChain, Deep Agents overview.
• Documentação da LangChain, Deep Agents permissions.
• Blog da LangChain, The runtime behind production Deep Agents.

OpenAI Agents SDK

• OpenAI Agents SDK, Sessions.
• OpenAI Agents SDK, Sandbox concepts.

Temporal

• Blog do Temporal, Introducing Temporal and agentic sandboxes: the OpenAI Agents SDK.
• Blog do Temporal, Production-ready agents with the OpenAI Agents SDK + Temporal.
• README do Temporal × OpenAI Agents SDK contrib (temporalio/sdk-python).

Plataforma Anthropic

• Anthropic, Claude platform pricing: tarifas de session-hour do Managed Agents.
• anthropics/cwc-long-running-agents: Code with Claude 2026 take-home com evaluator subagent e padrões de progress files.

Sandbox providers

• ZenML, E2B vs Daytona: sandbox comparison for platform engineers.
• Documentação do Daytona, Sandboxes.
• Changelog do Daytona, Sandbox fork and snapshot endpoints.
• Documentação do Modal, Sandboxes.
• Documentação do Modal, Cold start guide.
• Runloop on AWS Marketplace.
• Vercel Sandbox pricing and limits.

Timeouts e quotas de plataformas cloud

• Google Cloud, Configure request timeout for services.
• Google Cloud, Using WebSockets.
• Google Cloud, Set task timeout for jobs.
• AWS, Configure Lambda function timeout.
• AWS, Lambda quotas.
• AWS, Fargate throttling quotas.
• AWS, ECS service quotas and API throttling limits.

Observability

• OpenTelemetry, Semantic conventions for generative AI systems.
• OpenTelemetry, Gen AI attributes registry.
• OpenTelemetry, Semantic conventions for GenAI agent and framework spans.
• OpenTelemetry, Semantic conventions for generative AI metrics.

O código do Market Analyst Agent (worker LangGraph, checkpointer Postgres, memória Qdrant, MCP sidecar e a topologia Docker Compose descrita acima) está no GitHub.