Notas prácticas: Cómo crear agentes de IA mejores con LangGraph
Guía práctica paso a paso: Cómo crear agentes de IA más eficaces con LangGraph: contratos, verificaciones y espacios para código listo para usar destinados a los equipos que implementan este patrón.
Las notas siguientes reconstruyen un camino práctico para abordar “Cómo crear agentes de IA mejores con LangGraph”. Se da énfasis en los contratos, las verificaciones y los marcadores de posición para código, en lugar de en un enfoque motivacional. Al trabajar en la etapa de descripción general, 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 garantiza que los cambios posteriores en el código sean transparentes. 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 realizadas posteriormente.
1. Esquema de investigación: Dominio de los flujos de trabajo agentes
La etapa de dominio del Esquema de Investigación 1 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. 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. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
2. La solución: un agente de búsqueda autocorregible
La etapa 2, “La Solución A”, 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. Considere esta etapa como un contrato entre las entradas y las salidas validadas. 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.
Importaciones
La etapa de Importaciones 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 versión de demostración a entornos compartidos. Mantenga el estado del gráfico simple y con tipos definidos. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
import operator
from typing import Annotated, TypedDict, Union
from langgraph.graph import StateGraph, START, END
El Cerebro Compartido
La etapa del Cerebro Compartido 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. 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. 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 después de las interrupciones.
# 1. State: The agent's shared memory
class AgentState(TypedDict):
# 'operator.add' lets us append messages instead of overwriting
messages: Annotated[list[str], operator.add]
attempts: int
found_info: bool
Los nodos trabajadores
La etapa de los nodos trabajadores 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 del proceso.
# 2. Nodes: Individual 'steps' in the process
def search_node(state: AgentState):
print(f\n"--- Attempt {state['attempts'] + 1}: Searching ---")
# Simulating a logic check
success = state['attempts'] >= 1
msg = "Success: Found LangGraph info!" if success else "No results found."
return {"messages": [msg], "attempts": state['attempts'] + 1, "found_info": success}
def refine_query_node(state: AgentState):
print("\n--- Refining query for better results ---")
return {"messages": ["System: Query refined."]}
La lógica de enrutamiento
La etapa de Lógica de Enrutamiento 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. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única 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 should_continue(state: AgentState):
if state["found_info"] or state["attempts"] >= 3:
return "end"
return "refine"
Construyendo el grafo
La etapa de Construcción del Gráfico 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. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del gráfico plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
# 4. Build the Graph
workflow = StateGraph(AgentState)
workflow.add_node("search", search_node)
workflow.add_node("refine", refine_query_node)
workflow.add_edge(START, "search")
workflow.add_conditional_edges("search", should_continue, {"refine": "refine", "end": END})
workflow.add_edge("refine", "search")
Ejecutar el Agente
La etapa “Ejecutar el agente” 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 gráfico simple y con tipos definidos; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
# 5. Execute
app = workflow.compile()
for output in app.stream({"messages": [], "attempts": 0, "found_info": False}):
print(output)
--- Attempt 1: Searching ---
{'search': {'messages': ['No results found.'], 'attempts': 1, 'found_info': False}}
--- Refining query for better results ---
{'refine': {'messages': ['System: Query refined.']}}
--- Attempt 2: Searching ---
{'search': {'messages': ['Success: Found LangGraph info!'], 'attempts': 2, 'found_info': True}}
La etapa “Ejecutar el agente” 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. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
3. Cinco consejos para mejorar su uso de LangGraph
Para los 3 consejos clave, 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. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellas tareas que implican gastos o modificaciones en datos de producción. La configuración en tiempo de compilación no equivale a una solución completa para los negocios.
Consejo 1: Defina con precisión su esquema de estado
Para el Consejo 1: Domina tu etapa, define 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. Considera esta etapa como un contrato entre las entradas y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y rechaza las completaciones parciales silenciosas. Incluye la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Consejo 2: Domina los casos condicionales
En la fase Master Conditional de Tip 2, 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 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 flujo pasa de entornos de demostración a entornos compartidos. Incluya la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase Master Conditional de Tip 2, 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 intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente.
Consejo 3: No olvide la persistencia (puntos de control)
Al trabajar en el Consejo 3 “No realice etapas”, 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 verificables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga puntos de control después de los pasos costosos. La reanudación no debe volver a realizar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Consejo 4: Acepte la intervención humana
Al trabajar en el Consejo 4, “Acepta la etapa”, anota 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. Considera esta etapa como un contrato entre los datos de entrada y los resultados validados. Nombra los artefactos, define las comprobaciones de éxito y rechaza las completaciones parciales silenciosas. Haz 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.
Consejo 5: Mantén tus nodos pequeños
Al seguir el Consejo 5 “Mantén tu entorno estable”, anota primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registra 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. Haz 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. Al seguir el Consejo 5 “Mantén tu entorno estable”, anota primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documenta 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 adicionales realizadas posteriormente.
Aplicación en la vida real
La etapa de Aplicación en la vida real 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. 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. 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.
Referencias
La etapa de Referencias 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. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace completaciones parciales silenciosas.
Lista de verificación operativa
Lecturas relacionadas
- Notas prácticas: Construir un sistema de revisión de código multi-agente con LangGraph — Guía paso a paso de las Notas prácticas: Construir un sistema de revisión de código multi-agente con LangGraph: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.
- Notas prácticas: Construir un enrutador multi-agente con LangGraph en 30 minutos — Guía paso a paso de las Notas prácticas: Construir un enrutador multi-agente con LangGraph en 30 minutos: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.