Cómo migrar Agents SDK v0.33.0 a Pi 1.5

Esta es una guía de migración basada en el changelog y en la documentación oficial consultada el 4 de noviembre de 2026. No ejecutamos la actualización ni los ejemplos en esta revisión.

En este artículo verás:

• Qué cambios llegan con Agents SDK v0.33.0 y Pi 1.5.
• Cómo localizar llamadas y estados que necesitan migrarse.
• Cómo adaptar el seguimiento de sesión y la continuación de una ejecución.
• Por qué la compatibilidad del transcript exige planificar el rollback antes de la actualización.

Agents SDK v0.33.0 actualiza PiHarness a Pi 1.5

PiHarness conecta al agente Pi Durable al Agents SDK de Cloudflare y usa el almacenamiento SQLite del Durable Object para preservar el estado de una sesión. La versión v0.33.0 actualiza esta integración a Pi 1.5.

Cloudflare reporta menos escrituras en el almacenamiento durante la transmisión de respuestas y menor uso de memoria en llamadas grandes de herramientas. En sus pruebas, informa 27 veces menos transacciones para respuestas largas y 5,7 veces menos en turnos con llamadas paralelas de herramientas.

En una carga con 2.048 sesiones, el equipo reporta un throughput de 88 a 459 ejecuciones por segundo. Estos números describen la prueba de Cloudflare. No garantizan la misma mejora en cualquier aplicación, cuenta, hardware o patrón de uso.

El cambio también añade una ruta para continuar una conversación sin adjuntar un nuevo mensaje del usuario. Esto ayuda cuando una ejecución termina sin respuesta, por ejemplo después de un error del modelo, pero exige que la sesión esté ociosa.

Prepara la migración a Pi 1.5 antes de actualizar

Comienza identificando qué versión de Agents SDK y de Pi Durable usa el proyecto hoy. Registra también cómo la aplicación almacena transcripts y cómo el cliente hace seguimiento de la respuesta mientras se genera.

Haz una copia de prueba de los datos y ejecuta la migración en un entorno separado antes de modificar una instalación usada por clientes. Esta es una precaución de ingeniería para reducir el impacto de cambios incompatibles, no una garantía publicada por Cloudflare.

Después, sigue las instrucciones oficiales del changelog de Agents SDK v0.33.0. La documentación recomienda reemplazar llamadas a session.events() por session.watch() y eliminar dependencias de retry() y del estado parked.

session.watch() entrega la vista actual de la sesión, incluyendo entradas recientes del transcript y estado en vivo, como respuesta en transmisión, herramientas en ejecución y motivo de una ejecución que terminó sin respuesta. La documentación muestra el inicio y la actualización del monitor así:

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

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

El código ilustra el formato documentado, no se ejecutó en esta revisión. La aplicación también necesita cerrar el monitor cuando el cliente se desconecte y manejar con cuidado una reconexión después de que el objeto se reinicie.

Elimina los estados antiguos de retry y parked

El flujo anterior podía estacionar una tarea que fallaba repetidamente y exponer el estado parked. Pi 1.5 elimina retry() y ese estado. Una tarea que alcanza el límite de reinicios termina en lugar de permanecer estacionada.

Antes de actualizar, busca los usos de esos nombres en el código y en las pruebas. Reemplaza la lógica antigua por el manejo de resultado que ofrece la nueva versión, en lugar de quitar la condición sin definir qué debe mostrar la interfaz al usuario.

Para una ejecución existente, la documentación de Cloudflare muestra la verificación del resultado y la continuación tras model_error usando otro 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 una nueva ejecución sin añadir un mensaje del usuario. La sesión debe estar ociosa. Si el transcript ya termina con una respuesta, la operación devuelve unanswered con motivo nothing_to_answer.

Planifica un roll-forward porque Pi 1.4 no lee conversaciones de Pi 1.5

La advertencia más importante de la actualización es la compatibilidad del almacenamiento. Después de que una conversación se ejecuta en Pi 1.5, Pi 1.4 no puede leerla.

Por eso, Cloudflare recomienda corregir problemas avanzando la versión, no volviendo a Pi 1.4. Antes del deploy, define cómo desactivar la nueva versión sin reabrir transcripts incompatibles y cómo mantener un despliegue de prueba aislado.

Un plan de validación debe cubrir, como mínimo, una respuesta corta, una llamada a herramienta, una falla del modelo y la reconexión del cliente durante una sesión. Registra el estado guardado y el resultado visible en cada escenario.

El enfoque se conecta con prácticas ya descritas en el blog, como automatizar tareas de repositorio con GitHub Agentic Workflows y organizar sesiones de agentes en VS Code 1.145. En ambos los casos, la revisión del flujo y de los efectos es parte del trabajo, no un detalle opcional.

Mide tu flujo sin prometer los números de Cloudflare

Los datos de Cloudflare explican por qué el equipo actualizó la persistencia y el uso de memoria. No sustituyen una medición en tu workload, porque la duración de las respuestas, el número de herramientas y la concurrencia pueden ser diferentes.

Antes y después de la migración, compara el mismo conjunto de tareas y registra el tiempo hasta la primera respuesta, el tiempo total, fallas, uso de memoria y lecturas o escrituras persistidas. Separa los resultados por tipo de sesión para evitar que una carga pequeña oculte regresiones en llamadas largas.

La documentación actual de PiHarness para Cloudflare Agents describe session.watch() y el nuevo camino de continuación. Revísala junto con el changelog antes de adaptar la firma exacta a tu código.