fx0 e libfx na prática: como montar um agente da Vercel que sobrevive a crashes

A estatística mais interessante dessa história não está no código. Segundo dados internos da Vercel citados pela Forkast, agentes de programação passaram de menos de 3% para mais de 50% dos deploys da plataforma em seis meses, e os deploys disparados por agentes cresceram 28 vezes. Quando metade do que vai para produção é empurrada por um loop de LLM, a pergunta deixa de ser se o modelo é bom. O que importa é saber o que acontece quando a função que roda esse loop morre no passo 37 de 50.

A resposta da Vercel é um stack de estado durável, com uma aplicação de referência aberta. Este guia explica o que foi publicado, como o mecanismo funciona, como colocar a referência no ar, como provar que ela de fato sobrevive a uma queda e onde estão as armadilhas.

O que foi aberto, exatamente

Vale começar pelos nomes, porque "harness durável" é uma descrição, não o nome de um pacote. As peças são duas:

• fx0 (abre em nova aba): um agente leve de design, publicado sob licença Apache-2.0 no GitHub da Vercel Labs. Na época da reportagem, tinha 228 estrelas. A Vercel o trata como implementação de referência.
• libfx (abre em nova aba): a biblioteca que o fx0 usa. Ela expõe as duas APIs centrais, createFxAgent() e createFxEngine().

Um detalhe que muita gente vai ignorar: o fx0 é um agente de design, não um agente de código. A durabilidade está na libfx, e é ela que interessa a quem quer blindar um agente de programação. O fx0 serve para ver a libfx funcionando de ponta a ponta.

A arquitetura, segundo a reportagem, separa três responsabilidades: a lógica do agente, o ambiente de execução e a camada de persistência. Na prática, cada uma fica numa peça da Vercel:

Como a durabilidade funciona

O mecanismo é menos mágico do que o marketing sugere, e isso é bom sinal. O próprio material da Vercel sobre agentes duráveis descreve o ciclo em quatro movimentos:

1. executar uma chamada de modelo ou uma operação de ferramenta;
2. salvar o resultado;
3. suspender quando a tarefa precisa de um evento externo;
4. retomar usando os resultados gravados.

O ponto-chave está no item 4. Numa retomada, o agente não refaz as chamadas que já completou: ele lê o que foi gravado. A Vercel insiste numa distinção que vale repetir. A escolha de ferramentas continua dinâmica, e o modelo pode decidir o que quiser. A durabilidade só determina que operações concluídas continuem disponíveis depois de uma interrupção.

Na libfx, isso aparece como três números que você precisa decorar:

Essa margem de 30 segundos é a parte que mais me agrada no desenho. Em vez de esperar a plataforma matar o processo e tentar se recuperar do caos, a biblioteca sai por conta própria, de forma limpa, e deixa um bilhete na fila dizendo onde parou. A queda inesperada continua coberta pelas Queues. A queda previsível, por tempo, vira uma operação rotineira.

O contador de 64 passos no Redis resolve outro problema, mais sutil. Um loop de agente, como lembra um levantamento da Developers Digest sobre cinco SDKs, não passa de um while que chama o modelo, executa ferramentas e repete até uma regra de parada disparar. Os limites padrão variam muito entre frameworks, e alguns não têm limite nenhum. Num sistema que retoma sozinho depois de cada queda, um limite que vive só na memória do processo não protege nada: a cada retomada, ele recomeça do zero. Por isso o contador precisa estar fora do processo. Sem isso, durabilidade vira uma forma elegante de queimar tokens para sempre.

Quando vale a pena, e quando não

A Vercel é honesta sobre isso no próprio texto. A execução durável compensa quando uma interrupção apagaria trabalho caro ou deixaria a próxima ação incerta. A empresa lista quatro casos:

• tarefas longas, que sobrevivem à requisição que as iniciou;
• aprovações humanas que chegam depois de a execução ter pausado;
• trabalho em várias etapas cujos resultados precisam sobreviver a uma falha;
• jobs externos que exigem retentativas ou uma resposta posterior.

O exemplo deles é bom: um agente de pesquisa passa a tarde juntando fontes e analisando dados, e o revisor só aprova a distribuição na manhã seguinte. Agentes de programação se encaixam quase sempre na terceira categoria, e frequentemente na segunda, com revisão de PR e aprovação de deploy.

O mesmo texto diz quando não vale. Para interações curtas, um loop convencional basta, desde que repetir a requisição custe pouco e não duplique uma ação externa. Se o seu agente responde perguntas sobre a documentação em dez segundos, adicionar World, Queues e Redis é complexidade sem retorno.

Para quem já usa o AI SDK (abre em nova aba), existe ainda uma alternativa dentro da própria casa: a Developers Digest descreve o AI SDK 7 com durabilidade via WorkflowAgent e suporte a aprovações. Para orquestração em sandbox fora desse ecossistema, a lista awesome-harness-engineering aponta o sandcastle, que trata o isolamento como primitiva (Docker, Podman ou microVMs Firecracker da Vercel). Um aviso de vocabulário: o Harness², que o Google abriu na mesma semana, usa "harness" em outro sentido, o de refinar o código ao redor de um modelo congelado. Não resolve o problema de crash.

Pré-requisitos

O último item não é burocracia. Em 14 de outubro, o Next.js publicou uma atualização urgente que corrige duas vulnerabilidades críticas de execução remota de código e uma de negação de serviço de alta severidade, como registrou a newsletter da Callstack. Um agente que faz deploys sozinho, rodando sobre um framework com RCE aberta, é exatamente o cenário que ninguém quer explicar num postmortem.

Passo a passo

1. Clone a referência e encontre as duas APIs

Comece lendo o código, não instalando. A forma mais rápida de entender a libfx é ver onde o fx0 a chama:

git clone https://github.com/vercel-labs/fx0.git
cd fx0
grep -rn "createFxAgent\|createFxEngine" --include=*.ts --include=*.tsx .

Anote três coisas nesses arquivos: onde o agente é definido (lógica), onde o engine é criado (execução) e de onde vêm as conexões de persistência. Você vai replicar essa separação no seu projeto.

2. Instale as dependências com o gerenciador do repositório

Veja qual lockfile está no repositório e use o gerenciador correspondente. Se for package-lock.json:

npm install

Se houver um lockfile de outro gerenciador, use o respectivo. Misturar gerenciadores é a maneira mais rápida de rodar uma versão da libfx diferente da que a referência testou.

3. Vincule ao projeto Vercel e puxe as variáveis

vercel link
vercel env pull

O README do fx0 é a fonte das variáveis necessárias: credenciais do Redis, do AI Gateway e o que mais a referência exigir. Não tente adivinhar nomes de variáveis. Se o README e o código divergirem, o código manda.

4. Faça o deploy de preview

vercel deploy

Use um deploy de preview, não um ambiente local, para testar a durabilidade. O mecanismo depende de Queues e World, que são serviços da plataforma. Se o README não documentar como emulá-los localmente, um teste local de crash só prova que o seu processo morreu.

5. Leve o padrão para o seu agente

Com a referência funcionando, instale a biblioteca no seu projeto:

npm install libfx

A migração não se resume a trocar o loop. Ela exige reorganizar o agente nas três camadas que o fx0 separa. O trabalho mais importante, e que nenhuma biblioteca faz por você, é inventariar as ferramentas do agente e marcar quais têm efeito colateral externo: abrir PR, fazer deploy, mandar mensagem, escrever em banco.

O esqueleto abaixo não é a API da libfx. É só uma ilustração do raciocínio que você precisa aplicar em cada ferramenta com efeito externo: gravar antes de repetir.

// Ilustração do padrão, não da API da libfx
async function executarUmaVez(chave: string, efeito: () => Promise<string>) {
  const gravado = await lerResultado(chave); // persistência externa
  if (gravado !== null) return gravado;       // retomada: reutiliza
  const resultado = await efeito();
  await gravarResultado(chave, resultado);
  return resultado;
}

A chave precisa ser determinística em relação ao passo, por exemplo identificador da sessão mais número do passo. Uma chave aleatória a cada execução derruba toda a proteção.

Como verificar

Durabilidade só existe depois de testada. Faça estes quatro testes no deploy de preview, nesta ordem:

Crash no meio do turno. Dispare uma tarefa longa e, no meio dela, force a morte da função: lance um erro proposital numa ferramenta, atrás de uma flag de teste. O comportamento esperado, segundo a descrição do stack, é que o turno continue via Queues. Confira nos logs se os passos já concluídos aparecem uma única vez.

Turno que estoura o tempo. Monte uma tarefa que passe dos 800 segundos. Você deve ver a invocação terminar por volta dos 770 segundos, quando a libfx para com 30 segundos de folga, seguida de uma nova invocação que retoma de onde parou. Se a função for morta pela plataforma no segundo 800, a margem não está funcionando.

Orçamento de passos. Force um agente a entrar em loop, com uma ferramenta que sempre devolve "tente de novo". O turno precisa parar no passo 64. Consulte o contador no Redis durante o teste e confirme que ele não volta a zero depois de um crash forçado. Essa é a prova de que o limite vive fora do processo.

Efeito colateral duplicado. O teste mais importante e o mais esquecido. Escolha uma ferramenta com efeito externo inofensivo, como gravar uma linha numa tabela de testes, e derrube a função logo depois da chamada. Conte as linhas. Se aparecerem duas, você encontrou o bug antes do seu usuário.

Erros comuns

Confundir timeout maior com durabilidade. A Vercel dedica uma seção inteira a isso: um timeout mais longo dá mais tempo a uma invocação, mas a recuperação continua exigindo progresso salvo. Subir o limite só adia o momento em que você perde tudo.

Achar que a biblioteca protege efeitos colaterais. A durabilidade garante que resultados gravados sejam reutilizados. Se a função morrer entre o efeito externo e a gravação do resultado, a retomada pode repetir o efeito. Para um agente de programação, isso pode significar dois PRs ou dois deploys. Torne essas ferramentas idempotentes.

Testar crash localmente e declarar vitória. Sem as Queues e o World de verdade, o teste não exercita o mecanismo. Teste em preview.

Ignorar o orçamento de 64 passos no desenho do agente. Se a sua tarefa legítima precisa de mais de 64 passos num turno, o problema provavelmente é de decomposição, não de limite. Divida em turnos menores com checkpoints claros, o mesmo princípio de pequenas etapas, testes e revisões humanas que a Shopify descreveu na migração de volta ao nativo.

Deixar limites implícitos em outras partes do sistema. Se o agente durável chama sub-agentes construídos com outro SDK, cada um traz um limite padrão diferente. A recomendação da Developers Digest vale aqui: defina o limite explicitamente em todo SDK que você usa.

Tratar 228 estrelas como maturidade. O fx0 é uma referência recém-aberta, mantida na Vercel Labs. Fixe versões, leia o diff antes de atualizar a libfx e não espere a estabilidade de API de um framework 1.0.

O que a Vercel publicou é menos um produto pronto do que uma tese executável: num mundo em que metade dos deploys vem de agentes, o estado do agente precisa morar fora do processo que o executa. Você pode discordar do preço do acoplamento à plataforma, mas vale ler o código do fx0 de qualquer forma, porque a separação entre lógica, execução e persistência continua válida mesmo que você nunca rode uma linha dele na Vercel.