Notas prácticas: Creación de un agente de soporte LEPA con LangGraph
Guía paso a paso para utilizar las notas prácticas: Creación de un agente de soporte LEPA con LangGraph: contratos, verificaciones y espacios para código adicional para los equipos que implementan este patrón.
Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “Building LEPA Support Agent with LangGraph”: etapas claras, espacios de código ordenados y notas de recuperación que perduran tras el traspaso de tareas. La etapa de Resumen funciona mejor cuando se considera como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado.
Qué quería que hiciera el primer grafo
Para la etapa que usted desea, defina las entradas, el responsable de cada 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. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
User message
↓
Notice who is speaking (teacher / admin / unknown)
↓
Classify the topic (grades, login, …)
↓
Too vague? Ask a clarifying question
↓
Otherwise continue toward docs + an answer
Configuración del proyecto (mantenida intencionadamente aburrida)
Para la configuración del proyecto, se debe mantener intencionalmente una etapa definida, estableciendo las entradas, el responsable de cada 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. Se deben registrar los tiempos de ejecución 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. Se debe incluir la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión durante la compilación no equivale a una implementación completa desde el punto de vista empresarial.
PRJ-02/
├── app/
│ ├── state.py # SupportState
│ ├── graph.py # StateGraph wiring
│ ├── agents/ # intake, knowledge, support
│ ├── nodes/ # classify, ask_clarification
│ └── tools/ # search_knowledge (next article)
├── knowledge/ # LEPA support Markdown
├── api/ # FastAPI (later article)
└── tests/
Estado: el objeto que se desplaza a través del grafo
Para el estado del objeto de la etapa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en las acciones que implican gastos o modificaciones en los datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. Para el estado del objeto de la etapa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado.
e.messages # conversation turns (add_messages reducer)
user_role # teacher / admin / unknown
issue_category # grades, authentication, …
clarification_needed # should we ask for more detail?
clarification_question # what we ask
retrieved_documents # doc snippets (later step)
final_answer # what we return to the user
conversation_summary # reserved for later — unused in v1
messages: Annotated[list, add_messages]
{"user_role": "teacher"}
{"issue_category": "grades", "clarification_needed": False}
Nodos: una tarea cada uno
Al trabajar con los nodos, donde cada etapa tiene una tarea, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones en el código. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
(state) → partial update
Entrada
Al trabajar en la fase de entrada, 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 a los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Clasificar
Al trabajar en la etapa de Clasificar, anote primero el contrato: las entradas requeridas, 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. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior. Al trabajar en la etapa de Clasificar, anote primero el contrato: las entradas requeridas, 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 probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad en lugar de a un proceso complicado.
Solicitar aclaraciones
La etapa de aclaración de preguntas funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Conocimiento + soporte
La etapa de soporte basada en conocimientos funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. 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. Mantenga el estado del grafo en formato plano y con tipos definidos. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Aristas: cómo se transfiere el control
El funcionamiento óptimo de cómo los bordes controlan los movimientos en la etapa se logra al tratarlos como una superficie medible. Capture un registro exitoso, 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 datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso después de las interrupciones.
Bordes normales
La etapa de bordes normales funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
graph.add_edge(START, "intake")
graph.add_edge("intake", "classify")
graph.add_edge("knowledge", "support")
graph.add_edge("support", END)
When this node finishes, always go there next.
Bordes condicionales
La etapa de bordes condicionales funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
def route_after_classify(state: SupportState) -> Literal["clarify", "continue"]:
if state.get("clarification_needed"):
return "clarify"
return "continue"
graph.add_conditional_edges(
"classify",
route_after_classify,
{
"clarify": "ask_clarification",
"continue": "knowledge",
},
)
"help" → clarify → ask_clarification → END
"How do I enter grades?" → continue → knowledge → support → END
INICIO y FIN
Las etapas INICIO y FIN funcionan mejor cuando se tratan como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación posterior.
START = where the runtime begins
END = where this run stops
START → intake → classify → …
…
ask_clarification → END
support → END
La topología completa (tal como se construyó)
La topología completa, considerada como una etapa, funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. 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. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
START
→ intake
→ classify
→ conditional
├─ clarify → ask_clarification → END
└─ continue → knowledge → support → END
Cómo se procesa una solicitud a través del grafo
El funcionamiento de la etapa en la que se procesa una solicitud “How a request moves stage” es óptimo cuando se trata como un elemento medible. Capture una transcripción ejemplar, 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 datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan realizar auditorías sin tener que leer todo el grafo. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
Pregunta clara
La etapa de preguntas claras funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación juntos. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
User: "Why aren't grades showing?"
↓
intake → user_role = unknown (unless they said teacher/admin)
↓
classify → issue_category = grades, clarification_needed = False
↓
route → "continue"
↓
knowledge → search docs (next article)
↓
support → final_answer
↓
END
Pregunta vaga
User: "help"
↓
intake
↓
classify → unknown + clarification_needed = True
↓
route → "clarify"
↓
ask_clarification → asks which LEPA area
↓
END
compile() e invoke(): el momento en tiempo de ejecución
return graph.compile(checkpointer=checkpointer)
from langchain_core.messages import HumanMessage
from app.graph import app_graph
result = app_graph.invoke(
{"messages": [HumanMessage(content="How do I enter grades?")]}
)
print(result["final_answer"])