Notas prácticas: De la recuperación al razonamiento: Creando agentes listos para su uso en producción

Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “De la recuperación al razonamiento: Creación de sistemas de IA agente listos para producción con grafos de conocimiento”: etapas claras, espacios ordenados para el código y notas de recuperación que perduran tras la transferencia de tareas. La etapa de Resumen funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.

from neo4j import GraphDatabase
import json

def get_grounded_context(user_query: str, entity_extractor, driver) -> str:
    # Step 1: Extract entities from the user query
    entities = entity_extractor(user_query)  # e.g., ["Product X", "Supplier Y"]

    # Step 2: Pull a relevant subgraph from Neo4j
    with driver.session() as session:
        result = session.run(
            """
            MATCH (e)-[r]-(connected)
            WHERE e.name IN $entities
            RETURN e.name AS entity,
                   type(r) AS relationship,
                   connected.name AS related_entity,
                   connected.attributes AS attributes
            LIMIT 50
            """,
            entities=entities
        )
        subgraph = [record.data() for record in result]

    # Step 3: Format subgraph as structured context
    context_str = json.dumps(subgraph, indent=2)

    grounded_prompt = f"""
    You are a reasoning agent. Use ONLY the following structured knowledge to answer.
    If the answer isn't derivable from this context, say so explicitly.

    KNOWLEDGE GRAPH CONTEXT:
    {context_str}

    USER QUERY: {user_query}
    """
    return grounded_prompt

def plan_with_graph(goal: str, graph_schema: dict, llm) -> list[dict]:
    schema_str = json.dumps(graph_schema, indent=2)

    planning_prompt = f"""
    You are a planning agent. Given the goal below, decompose it into steps.
    Each step must reference a valid entity type or relationship from the schema.
    Do not invent steps that require knowledge outside this schema.

    GRAPH SCHEMA:
    {schema_str}

    GOAL: {goal}

    Return a JSON list of steps. Each step must include:
    - "action": what to do
    - "graph_query": the Cypher query to retrieve required context
    - "depends_on": list of prior step indices this step requires
    """

    raw_plan = llm.complete(planning_prompt)
    plan = json.loads(raw_plan)
    return plan

def execute_with_validation(step: dict, intermediate_result: str, driver, llm) -> dict:
    # Extract claims from the intermediate result
    claim_extraction_prompt = f"""
    Extract all factual claims from this text as a list of (subject, predicate, object) triples.
    TEXT: {intermediate_result}
    Return as JSON array.
    """
    claims = json.loads(llm.complete(claim_extraction_prompt))

    validation_results = []
    with driver.session() as session:
        for claim in claims:
            result = session.run(
                """
                MATCH (s {name: $subject})-[r]-(o {name: $object})
                WHERE type(r) = $predicate OR $predicate IN r.aliases
                RETURN count(r) AS match_count
                """,
                subject=claim["subject"],
                predicate=claim["predicate"],
                object=claim["object"]
            )
            record = result.single()
            validation_results.append({
                "claim": claim,
                "validated": record["match_count"] > 0
            })

    unvalidated = [v for v in validation_results if not v["validated"]]

    return {
        "result": intermediate_result,
        "validated": len(unvalidated) == 0,
        "flagged_claims": unvalidated
    }

Lista de verificación operativa

Al trabajar en la etapa de la lista de verificación operativa, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista mantiene honestas las futuras modificaciones de código.

Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Ver la información sobre costos desde el principio evita facturas inesperadas cuando el camino pasa de entornos de demostración a entornos compartidos.

Almacene en caché las instrucciones del sistema y los esquemas de herramientas estables. Reenviar un preámbulo idéntico es una causa común de gastos innecesarios.

Separe la política de particionamiento del chunking de la política de recuperación. Cambiar una no debería obligar a reescribir la otra cuando cambian las métricas de calidad.

Deje que un humano apruebe aquellas operaciones que generan gastos o modifican datos de producción. La configuración en tiempo de compilación no equivale a una solución completa para el negocio.

Registre los costos y la latencia junto con la calidad. Una respuesta ligeramente peor que cuesta 10 veces menos podría ser la mejor opción para producción.

Antes de promocionar la solución, congele las versiones, capture una transcripción de referencia para el camino crítico y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.

Nota para el lote 7e5e1dbfc22b: mantenga las claves del proveedor fuera del repositorio, establezca un límite para los tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios posteriores en el modelo sigan siendo comparables.

La nota de fortalecimiento para la etapa 0 funciona mejor cuando se trata como una superficie medible. Capture una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables a scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado.

Detalle de reforzamiento 0/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Para la fase 1 de la nota de reforzamiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos.

Detalle de reforzamiento 1/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Al trabajar en la fase 2 de las notas de fortalecimiento, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código.

Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.

El detalle 2/956 de fortalecimiento: mida el tiempo de ejecución, la clase del error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de anécdotas.

La fase 3 de las notas de fortalecimiento funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta fase como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.

Detalle de fortalecimiento 3/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Para la fase 4 de la nota de fortalecimiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el sistema.

Detalle de fortalecimiento 4/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Al trabajar en la fase 5 de las notas de fortalecimiento, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado.

Detalle de fortalecimiento 5/956: mida el tiempo de ejecución, la clase del error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

La fase 6 de las notas de fortalecimiento funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos.

Detalle de fortalecimiento 6/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Para la fase 7 de la nota de fortalecimiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.

Detalle de fortalecimiento 7/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Al trabajar en la etapa 8 de las notas de fortalecimiento, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y rechace las completaciones parciales silenciosas.

Detalle de fortalecimiento 8/956: mida el tiempo de ejecución, la clase del error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

La etapa 9 de las notas de fortalecimiento funciona mejor cuando se trata como una superficie medible. Capture una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el sistema.

Detalle de fortalecimiento 9/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Para la etapa 10 de las notas de fortalecimiento, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado.

Detalle de fortalecimiento 10/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.

Al trabajar en la fase 11 de las notas de fortalecimiento, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos.

Detalle de fortalecimiento 11/956: mida el tiempo real empleado, la clase del error y el gasto en tokens para esta nota, y luego decida si mantener la modificación basándose en un conjunto fijo de preguntas en lugar de en observaciones anecdóticas.

La fase 12 de las notas de fortalecimiento funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son algo que se añade posteriormente.

Detalle de endurecimiento 12/956: mida el tiempo de ejecución, la clase de error y el consumo de tokens para esta nota, y luego decida si mantener el cambio basándose en un conjunto fijo de preguntas en lugar de en anécdotas.