Deep Research: un informe como grafo de estado

Un informe bien hecho no es una generación larga: es un proceso con etapas, con paralelismo y con un punto donde una persona decide. Deep Research convierte esa idea en un grafo de estado de dos niveles — uno exterior que planifica y compila, y un subgrafo que se ejecuta una vez por sección, en paralelo con sus hermanos. Entender esa forma vale más que el código, porque es reutilizable en cualquier tarea que se deje partir en piezas independientes.

01 — Los dos niveles

Quién decide el plan y quién escribe cada parte

Grafo exterior

Corre una vez por informe

Genera el plan de secciones a partir del tema.
Se detiene y espera aprobación humana.
Reparte las secciones que requieren investigación.
Redacta las que no la requieren —introducción, conclusión— usando las ya escritas.
Compila el informe final.

estado: tema, plan, secciones completadas, informe final

Subgrafo de sección

Corre una vez por sección, en paralelo

Genera queries de búsqueda para su sección.
Ejecuta las búsquedas web.
Redacta el contenido.
Lo somete a un evaluador: pasa o vuelve a empezar.

estado: su sección, sus queries, su contenido

Fíjate en el orden del grafo exterior: la introducción y la conclusión se escriben las últimas, usando como contexto las secciones ya investigadas. Es exactamente lo que hace una persona que escribe bien, y lo contrario de lo que hace un modelo al que le pides el informe de una sola vez.

02 — El paralelismo

Un detalle de tipos que lo hace posible

Varias secciones se investigan a la vez, y todas escriben en el mismo estado compartido. Eso normalmente es una receta para que la última sobrescriba a las demás. Lo que lo evita es una sola anotación:

class ReportState(TypedDict):
    topic: str
    sections: list[Section]
    completed_sections: Annotated[list, operator.add]   # ← acumulador
    final_report: str

Ese Annotated[list, operator.add] le dice al grafo que, cuando dos ramas devuelvan un valor para ese campo, no se elige uno: se suman. Es la diferencia entre un campo que se reemplaza y uno que se acumula, y es lo único que separa un grafo secuencial de uno que se abre en abanico sin conflictos.

Merece la pena retener el patrón más allá de este sistema: en cualquier grafo con ramas paralelas, la pregunta que hay que hacerse por cada campo del estado es ¿este se reemplaza o se acumula? Equivocarse no da error — da resultados que faltan.

// un campo que debía acumular y reemplaza pierde trabajo en silencio

03 — La parada

Por qué hay una persona en mitad del grafo

Entre el plan y la investigación hay un nodo que interrumpe la ejecución, enseña el plan propuesto y espera. El usuario aprueba —y el grafo continúa— o da retroalimentación —y el plan se regenera desde el principio.

No está ahí por prudencia genérica. Está ahí porque es el último punto barato: hasta entonces el sistema ha gastado una llamada de planificación; a partir de ahí gasta búsquedas y redacción por cada sección, en paralelo y con reintentos. Aprobar un plan malo cuesta minutos y dinero; corregirlo antes cuesta leer diez líneas.

Ese es el criterio general para colocar un humano dentro de un flujo automático: justo antes del punto donde el gasto se multiplica, no al final, donde ya solo sirve para lamentarse.

Auditoría Hay un problema serio con esta unidad, y conviene saberlo antes de sentarse a hacer el ejercicio: el material dice «trabajarás con el proyecto Deep Research ubicado en la carpeta deep_research/» y el script arranca con from graph.graph import builder — y esa carpeta no se entrega en ninguna parte. No hay repositorio, ni enlace, ni git clone, ni el código del grafo en ninguna página. Ese builder es el sistema entero: todos los nodos que describe el diagrama. El ejercicio, tal como está publicado, falla en su primera línea con un error de módulo no encontrado, y ninguna fila de su tabla de troubleshooting contempla ese caso. ¿Entrega la plataforma ese repositorio por otra vía que no viaja con el PDF? Merece la pena averiguarlo antes de intentarlo — y mientras tanto, la arquitectura de esta lección se puede dibujar y razonar sin ejecutar nada.

Para hacer

Dibujar el grafo de algo tuyo

Coge una tarea repetitiva que hagas con un LLM y que se deje partir en piezas —revisar varios documentos, redactar varias fichas, analizar varios casos— y dibújala como este grafo: qué nodo planifica, qué se puede abrir en paralelo, dónde va la persona y qué campo del estado acumula.

Después marca en el dibujo el punto donde el gasto se multiplica. Si tu humano no está justo antes de ese punto, muévelo. Ese único cambio suele valer más que cualquier ajuste de prompt.