Como migrar Agents SDK v0.33.0 para Pi 1.5

Este é um roteiro de migração baseado na changelog e na documentação oficial consultadas em 4 de novembro de 2026. Não executamos o upgrade nem os exemplos nesta revisão.

Agents SDK v0.33.0 atualiza o PiHarness para Pi 1.5

PiHarness conecta o agente Pi Durable ao Agents SDK da Cloudflare e usa o armazenamento SQLite do Durable Object para preservar o estado de uma sessão. A versão v0.33.0 atualiza essa integração para Pi 1.5.

A Cloudflare relata menos escritas no armazenamento durante a transmissão de respostas e menor uso de memória em chamadas grandes de ferramentas. Em seus testes, informa 27 vezes menos transações para respostas longas e 5,7 vezes menos em turnos com chamadas paralelas de ferramentas.

Em uma carga com 2.048 sessões, a equipe reporta throughput de 88 para 459 execuções por segundo. Esses números descrevem o teste da Cloudflare. Eles não garantem o mesmo ganho em qualquer aplicação, conta, hardware ou padrão de uso.

A mudança também acrescenta um caminho para continuar uma conversa sem anexar uma nova mensagem do usuário. Isso ajuda quando uma execução termina sem resposta, por exemplo depois de um erro do modelo, mas exige que a sessão esteja ociosa.

Prepare a migração para Pi 1.5 antes de atualizar

Comece identificando qual versão do Agents SDK e do Pi Durable o projeto usa hoje. Registre também como a aplicação armazena transcripts e como o cliente acompanha a resposta enquanto ela é gerada.

Faça uma cópia de teste dos dados e execute a migração em um ambiente separado antes de alterar uma instalação usada por clientes. Essa é uma precaução de engenharia para reduzir o impacto de mudanças incompatíveis, não uma garantia publicada pela Cloudflare.

Depois, siga as instruções oficiais do changelog do Agents SDK v0.33.0. A documentação recomenda trocar chamadas a session.events() por session.watch() e remover dependências de retry() e do status parked.

session.watch() entrega a visão atual da sessão, incluindo entradas recentes do transcript e estado ao vivo, como resposta em transmissão, ferramentas em execução e motivo de uma execução que terminou sem resposta. A documentação mostra o início e a atualização do monitor assim:

const watch = await this.harness.session().watch();
render(watch.value);

watch.start(async (call) => {
  if (call.kind === "value") render(call.value);
});

O código ilustra o formato documentado, não foi executado nesta revisão. A aplicação também precisa encerrar o monitor quando o cliente se desconectar e tratar com cuidado uma reconexão depois que o objeto reiniciar.

Remova os estados antigos de retry e parked

O fluxo anterior podia estacionar uma tarefa que falhava repetidamente e expor o estado parked. Pi 1.5 remove retry() e esse status. Uma tarefa que atinge o limite de reinícios termina em vez de permanecer estacionada.

Antes de atualizar, procure os usos desses nomes no código e nos testes. Substitua a lógica antiga pelo tratamento de resultado que a versão nova oferece, em vez de remover a condição sem definir o que a interface deve mostrar ao usuário.

Para uma execução existente, a documentação da Cloudflare mostra a verificação do resultado e a continuação após model_error usando outro operationId:

const result = await session.wait(operationId);
if (result.status === "unanswered" && result.reason === "model_error") {
  const receipt = await session.continue({
    operationId: `${operationId}:continue`,
  });
  const continued = await session.wait(receipt.operationId);
  console.log(continued.status, continued.text);
}

continue() inicia uma nova execução sem acrescentar uma mensagem do usuário. A sessão precisa estar ociosa. Se o transcript já termina com uma resposta, a operação retorna unanswered com motivo nothing_to_answer.

Planeje um roll-forward porque Pi 1.4 não lê conversas de Pi 1.5

A ressalva mais importante da atualização é a compatibilidade do armazenamento. Depois que uma conversa é executada em Pi 1.5, Pi 1.4 não consegue lê-la.

Por isso, a Cloudflare orienta corrigir problemas avançando a versão, não voltando para Pi 1.4. Antes do deploy, defina como desativar a nova versão sem reabrir transcripts incompatíveis e como manter uma implantação de teste isolada.

Um plano de validação deve cobrir, no mínimo, uma resposta curta, uma chamada de ferramenta, uma falha do modelo e a reconexão do cliente durante uma sessão. Registre o estado salvo e o resultado visível em cada cenário.

O roteiro se conecta a práticas já descritas no blog, como automatizar tarefas de repositório com GitHub Agentic Workflows e organizar sessões de agentes no VS Code 1.145. Em ambos os casos, a revisão do fluxo e dos efeitos é parte do trabalho, não um detalhe opcional.

Meça o seu fluxo sem prometer os números da Cloudflare

Os dados da Cloudflare explicam por que a equipe atualizou a persistência e o uso de memória. Não substituem uma medição no seu workload, porque duração das respostas, número de ferramentas e concorrência podem ser diferentes.

Antes e depois da migração, compare o mesmo conjunto de tarefas e registre tempo até a primeira resposta, tempo total, falhas, uso de memória e leituras ou escritas persistidas. Separe os resultados por tipo de sessão para evitar que uma carga pequena esconda regressões em chamadas longas.

A documentação atual do PiHarness para Cloudflare Agents descreve session.watch() e o novo caminho de continuação. Confira-a junto do changelog antes de adaptar a assinatura exata ao seu código.