Phase 14 - Lesson 40

Handoff de Múltiples Sesiones

La sesión va a terminar. El trabajo no. El paquete de handoff es el artefacto que convierte "el agente trabajó durante una hora" en "la siguiente sesión es productiva en el primer minuto". Constrúyalo intencionalmente, no como una ocurrencia tardía.

Tipo: Construcción Lenguajes: Python (stdlib) Prerrequisitos: Phase 14 · 34 (Repo Memory), Phase 14 · 38 (Verification), Phase 14 · 39 (Reviewer) Tiempo: ~50 minutos

Objetivos de Aprendizaje

  • Identificar los siete campos que todo paquete de handoff necesita.
  • Generar un handoff a partir de los artefactos del banco de trabajo sin escribir prosa a mano.
  • Reducir logs de feedback grandes a un resumen del tamaño de un handoff.
  • Hacer que la primera acción de la siguiente sesión sea determinista.

O Problema

La sesión termina. El agente dice "excelente, progresamos". La siguiente sesión comienza. El siguiente agente pregunta "¿dónde nos quedamos?". La respuesta del primer agente ha desaparecido. El siguiente agente redescubre, vuelve a ejecutar los mismos comandos, vuelve a hacerle las mismas preguntas al humano y pierde treinta minutos recuperando los últimos treinta segundos de la sesión anterior.

El costo de un mal handoff se paga en cada sesión durante la vida útil de la tarea. La solución es un paquete generado automáticamente al final de la sesión: qué cambió, por qué, qué se intentó, qué falló, qué queda y qué hacer primero la próxima vez.

El Concepto

flowchart LR
  State[agent_state.json] --> Generator[generate_handoff.py]
  Verdict[verification_report.json] --> Generator
  Review[review_report.json] --> Generator
  Feedback[feedback_record.jsonl] --> Generator
  Generator --> Handoff[handoff.md + handoff.json]
  Handoff --> Next[Siguiente Sesión]

Siete campos que todo handoff incluye

Campo Pregunta que responde
summary Un párrafo de lo que se hizo
changed_files El diff de un vistazo
commands_run Lo que realmente se ejecutó
failed_attempts Lo que se intentó y por qué no funcionó
open_risks Lo que podría causar problemas la próxima sesión, con su nivel de gravedad
next_action El primer paso concreto que dará la siguiente sesión
verdict_pointer Ruta a los informes de verificación + revisión

El campo next_action es el principal soporte. Un handoff con todo excepto next_action es un informe de estado, no un handoff.

Los handoffs se generan, no se escriben

Un handoff escrito a mano es un handoff que se pasa por alto en un día difícil. El generador lee los artefactos del banco de trabajo y emite el paquete. El trabajo del agente es dejar el banco de trabajo en un estado que el generador pueda resumir, no escribir el resumen.

Dos formas: legible por humanos y legible por máquinas

handoff.md es lo que lee el humano. handoff.json es lo que carga el siguiente agente. Ambos provienen de los mismos artefactos de origen. Si divergen, gana el JSON.

Recorte del registro de feedback

El feedback_record.jsonl completo puede tener cientos de entradas. El handoff lleva solo las últimas K más cada entrada con una salida distinta de cero. La siguiente sesión carga el registro completo si es necesario, pero el paquete se mantiene pequeño.

Constrúyalo

code/main.py implementa:

  • Un cargador que reúne el estado, el veredicto, la revisión y el feedback en un solo WorkbenchSnapshot.
  • Una función generate_handoff(snapshot) -> (markdown, payload).
  • A filter that picks the last K feedback entries plus all non-zero exits.
  • Una ejecución de demostración que escribe handoff.md y handoff.json junto al script.

Ejecútelo:

python3 code/main.py

Salida: un cuerpo de handoff impresso, además de ambos archivos en el disco.

Patrones de producción en el mundo real

Codex CLI, Claude Code y OpenCode ofrecen cada uno una historia de compactación diferente; el paquete de handoff estructurado se sitúa por encima de los tres.

Las estrategias de compactación varían; el esquema del paquete no. El POST /v1/responses/compact de Codex CLI es un blob AES opaco del lado del servidor (ruta rápida para modelos de OpenAI); la alternativa es un "resumen de handoff" local que se añade como un mensaje de rol de usuario _summary. Claude Code ejecuta una compactación progresiva de cinco etapas al 95% del contexto. OpenCode realiza la ocultación de mensajes basada en marcas de tiempo más un resumen de LLM de 5 encabezados. Tres mecanismos diferentes, la misma necesidad: serializar lo que sobrevive a la compresión en un artefacto portátil. El paquete es ese artefacto.

El handoff de nueva sesión no es compactación. La compactación extiende una sesión; el handoff cierra una limpiamente e inicia la siguiente. El planteamiento de Hermes Issue #20372 (abril de 2026) es correcto: cuando la compresión in-place comienza a degradarse, el agente debe escribir un handoff compacto, finalizar la sesión y reanudar en un contexto nuevo. El paquete es lo que hace que esa transición sea económica. El error es seguir comprimiendo hasta que la calidad colapse; la solución es presupuestar un handoff temprano y limpio.

Un handoff activo por branch y tema. La coordinación multiagente falla más por handoffs desactualizados que por un mal output del modelo. Incluya siempre branch, last_known_good_commit y un status de active | superseded | archived. Los handoffs desactualizados se archivan; solo el activo guía la siguiente sesión. Esta es la diferencia entre handoff-como-notas y handoff-como-estado.

Termine antes del 50-75% del contexto, no al límite. El playbook del patrón escrito a mano (CLAUDE.md + HANDOVER.md) reporta mejores resultados cuando la sesión termina al 50-75% del presupuesto de contexto en lugar del 95%. El generador del paquete se ejecuta limpiamente antes de que los artefactos de compresión contaminen el estado de origen. Es económico escribirlo mientras el contexto está intacto; es costoso cuando el modelo ya está perdiendo su lugar.

Úselo

Patrones de producción:

  • Hook de fin de sesión. El runtime activa el generador cuando el usuario cierra el chat. El paquete va a outputs/handoff/<session_id>/.
  • Plantilla de PR. El markdown del generador también es el cuerpo de un PR. Los revisores lo leen sin abrir otros cinco archivos.
  • Handoff entre agentes. Construya con un producto (Claude Code), continúe con otro (Codex). El paquete es la lengua franca.

El paquete es pequeño, regular y económico de producir. El ahorro de costos se acumula con cada sesión.

Envíelo

outputs/skill-handoff-generator.md produce un generador adaptado a las rutas de artefactos del proyecto, un hook de fin de sesión que lo ejecuta y un esquema handoff.json que el siguiente agente lee al iniciar.

Ejercicios

  1. Agregue un campo assumptions_to_validate que muestre cada suposición que el constructor registró pero que el revisor no calificó por encima de 1.
  2. Recorte el resumen de feedback de manera diferente para las ejecuciones fallidas en comparación con las exitosas. Defienda la asimetria.
  3. Incluya una lista de "preguntas para el humano". ¿Cuál es el umbral para que una pregunta entre en el paquete en lugar de enviarse en un mensaje de chat?
  4. Haga que el generador sea idempotente: ejecutarlo dos veces produce el mismo paquete. ¿Qué debe ser estable para que esto se cumpla?
  5. Agregue una sección de "prerrequisitos de la próxima sesión" que enumere exactamente los artefactos que la próxima sesión debe cargar antes de actuar.

Términos Clave

Término Lo que dice la gente Lo que realmente significa
Paquete de handoff "Resumen de la sesión" Artefacto generado que contiene los siete campos, tanto en markdown como en JSON
Siguiente acción "Qué hacer primero" El único paso concreto que inicia la siguiente sesión
Recorte de feedback "Resumen de registro" Los últimos K registros más cada entrada con salida distinta de cero
Informe de estado "Qué hicimos" Un documento sin next_action; útil, pero no un handoff
Puntero del veredicto "Recibo" Ruta a los informes de verificación + revisión para trazabilidad

Lecturas Adicionales

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).