Crea un agente de atención al cliente con LangGraph, llamadas a herramientas, aprobación humana y límites de ejecución

La decisión de diseño: permitir que el agente busque un reembolso, pero no que lo complete

Un agente de atención al cliente debe poder recopilar datos de compra y encontrar registros coincidentes sin tener permiso para emitir un reembolso por su cuenta. En LangGraph, esta distinción puede expresarse en el flujo de trabajo: dirigir la solicitud, llamar a herramientas de consulta de solo lectura según sea necesario y hacer una pausa antes de la operación de reembolso para que una persona la apruebe o rechace.

Este tutorial desarrolla ese patrón para clasificar solicitudes de atención al cliente. Usa LangGraph para la orquestación, un modelo de chat compatible con llamadas a herramientas para las consultas, un punto de revisión humana antes del nodo que ejecuta una acción con consecuencias y un límite de recursión para acotar la ejecución del grafo. El código es un patrón que puedes adaptar, no una integración de OneMux probada.

El tutorial de LangSmith proporcionado para este artículo crea un bot de atención al cliente para una tienda de música digital con subgrafos separados de consulta y reembolso. Describe cómo extraer datos del cliente y de la compra, solicitar la información que falta y evaluar las respuestas finales, las trayectorias de herramientas y los pasos individuales. Su ejemplo de reembolso elimina registros de la base de datos y omite explícitamente la autenticación y otras medidas de seguridad para producción. No copies el comportamiento destructivo de esa demostración en un sistema de atención al cliente en funcionamiento. Consulta el tutorial de LangSmith sobre la evaluación de agentes complejos.

Requisitos y límites

Instala LangGraph y la integración de LangChain correspondiente al proveedor del modelo que elijas. El tutorial de origen usa langgraph y langchain[openai], pero el ejemplo siguiente deja intencionadamente la inicialización del modelo en manos del proveedor. También necesitas una base de datos o un servicio con una consulta de compras de solo lectura y una operación de reembolso que controle tu aplicación.

Antes de conectar un modelo, define qué puede hacer cada herramienta:

• Consulta: devolver únicamente los registros que el cliente autenticado está autorizado a ver.
• Preparación del reembolso: identificar la transacción y el importe exactos sin modificar registros.
• Ejecución del reembolso: realizar la acción aprobada en el código de la aplicación, con autorización y registro de auditoría.

Mantén la autenticación y autorización del cliente, la idempotencia y la política de reembolsos fuera de la discreción del modelo. Un nombre de cliente o un ID de factura generado por el modelo no demuestra la identidad de nadie.

Crea un grafo con un punto de revisión humana

El ejemplo usa un modelo compatible con llamadas a herramientas, una herramienta de consulta y un nodo de reembolso independiente. Sustituye las funciones de la aplicación marcadas por tus propias llamadas autorizadas a servicios. El endpoint que configures debe admitir el modelo y el esquema de herramientas; la compatibilidad depende de la compatibilidad documentada con el endpoint y sus parámetros. Este fragmento no demuestra que se haya probado un modelo o una configuración de OneMux concretos.

from typing import Annotated, Literal

from langchain.tools import tool
from langchain_core.messages import AnyMessage
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import interrupt
from typing_extensions import TypedDict

# Replace with your provider's documented LangChain model setup.
# Confirm that the chosen endpoint supports tool calling and the parameters used.
model = make_your_chat_model().bind_tools([])  # bind the tools below in your application

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    refund_request: dict | None
    approval: str | None

@tool
def find_purchases(customer_reference: str) -> list[dict]:
    """Find purchases for an already authenticated customer."""
    return authorized_purchase_lookup(customer_reference)

tools = [find_purchases]
model = make_your_chat_model().bind_tools(tools)

def assistant(state: State):
    return {"messages": [model.invoke(state["messages"])]}

def prepare_refund(state: State):
    # Build this from validated application data, not model-invented values.
    request = build_validated_refund_request(state["messages"])
    decision = interrupt({
        "type": "refund_approval",
        "request": request,
        "instruction": "Approve or reject this exact refund request.",
    })
    if decision != "approve":
        return {"approval": "rejected", "refund_request": request}
    return {"approval": "approved", "refund_request": request}

def execute_refund(state: State):
    if state.get("approval") != "approved":
        return {"messages": [{"role": "assistant", "content": "The refund was not approved."}]}
    result = issue_refund_safely(state["refund_request"])
    return {"messages": [{"role": "assistant", "content": format_refund_result(result)}]}

builder = StateGraph(State)
builder.add_node("assistant", assistant)
builder.add_node("tools", ToolNode(tools))
builder.add_node("prepare_refund", prepare_refund)
builder.add_node("execute_refund", execute_refund)
builder.add_edge(START, "assistant")
builder.add_conditional_edges("assistant", tools_condition)
builder.add_edge("tools", "assistant")
builder.add_edge("prepare_refund", "execute_refund")
builder.add_edge("execute_refund", END)

graph = builder.compile(checkpointer=MemorySaver())

Este es un ejemplo estructural, no un grafo de enrutamiento completo: tu aplicación debe dirigir una intención de reembolso verificada a prepare_refund y las preguntas habituales a la ruta del asistente y las consultas. La llamada a interrupt() pausa el grafo y devuelve los datos de aprobación al componente que lo invocó. Una interfaz de revisión humana debe mostrar el cliente, la transacción, el importe y el contexto de la política antes de enviar una decisión. Reanuda el mismo hilo mediante el mecanismo Command(resume=...) de LangGraph y el mismo identificador de hilo. Persiste los puntos de control de forma adecuada; los puntos de control en memoria son para desarrollo, no para flujos de trabajo duraderos en producción.

Un detalle fundamental del flujo de control: una interrupción es una pausa, no un sistema de permisos. Vuelve a verificar el valor de aprobación en el nodo de ejecución del reembolso y asegúrate de que el propio servicio de reembolsos compruebe la autorización, si la transacción cumple los requisitos y si existen solicitudes duplicadas.

Limita la ejecución y haz visibles los fallos

Pasa un límite de recursión al invocar el grafo. Este limita los superpasos del grafo; no limita los tokens del modelo, el tiempo de ejecución de las herramientas, el coste de las consultas a la base de datos ni el número de solicitudes de usuarios. Establece tiempos de espera y límites de recursos independientes para las llamadas al modelo y las herramientas.

from langgraph.errors import GraphRecursionError

config = {
    "configurable": {"thread_id": "support-case-123"},
    "recursion_limit": 12,
}

try:
    result = graph.invoke(
        {"messages": [{"role": "user", "content": "I need help with a purchase."}]},
        config=config,
    )
except GraphRecursionError:
    # Return a safe handoff or ask for clarification; log the trace for review.
    result = {"status": "needs_human_review"}

Elige un límite según el flujo de trabajo previsto y prueba tanto la finalización normal como las entradas propensas a generar bucles. Evita reintentar silenciosamente la ejecución de un grafo que ha alcanzado el límite: los reintentos pueden repetir llamadas a herramientas, a menos que estas sean idempotentes. Es más seguro reintentar herramientas de consulta de solo lectura que operaciones con efectos secundarios.

Evalúa la trayectoria, no solo la respuesta

El tutorial de LangSmith proporcionado identifica tres objetivos de evaluación útiles: respuesta final (¿fue adecuada la respuesta al cliente?), trayectoria (¿siguió el agente la secuencia esperada de llamadas a herramientas?) y paso individual (¿eligió la herramienta correcta para una decisión concreta?). Para la clasificación de solicitudes de reembolso, crea casos en los que falten datos de identidad, haya varias compras coincidentes, una consulta no arroje resultados, se rechace una aprobación y se apruebe un reembolso.

Comprueba que el agente solicite la información necesaria en lugar de inventarla, que una consulta no active un reembolso y que la ejecución no pueda producirse sin aprobación. Usa servicios simulados o de prueba para la evaluación, de modo que las pruebas no alteren registros reales de clientes. El tutorial de origen usa un modo simulado para sus operaciones de base de datos, pero describe su propia configuración de demostración, no una garantía de seguridad para producción.

Uso de OneMux para acceder a modelos

OneMux ofrece acceso a modelos de IA líderes mediante una única API compatible con OpenAI. Si quieres una única interfaz de API para acceder a modelos, consulta la guía de inicio rápido de OneMux, la documentación de la API y los modelos disponibles. La compatibilidad con este flujo de trabajo depende de la compatibilidad documentada del endpoint del modelo seleccionado con las llamadas a herramientas y de los parámetros que acepte. Confirma esos detalles antes del despliegue; este artículo no afirma que el ejemplo de LangGraph se haya probado con OneMux.

Limitaciones y solución de problemas

• El modelo no llama a una herramienta: comprueba que el endpoint seleccionado admita llamadas a herramientas y que el esquema de la herramienta se pase en el formato documentado.
• El grafo entra en un bucle: revisa las transiciones entre el asistente y las herramientas, limita los pasos del grafo y asegúrate de que el resultado completado de una herramienta cambie la siguiente decisión.
• La aprobación reanuda el caso equivocado: usa un identificador de hilo estable asociado al caso de atención al cliente y verifica el punto de control antes de reanudar.
• Un reembolso se ejecuta dos veces: añade idempotencia en el límite del servicio y registra la solicitud aprobada y su resultado.
• El agente expone registros de otro cliente: corrige la autorización en el servicio de consulta; una instrucción en el prompt no es un control de acceso.

Conclusión

LangGraph permite expresar la clasificación de solicitudes de atención al cliente como pasos explícitos de un flujo de trabajo, en lugar de confiar en una sola respuesta del modelo para decidir y actuar. Mantén las consultas en modo de solo lectura, haz una pausa antes de los reembolsos, valida la aprobación en el momento de la ejecución y limita los pasos del grafo. Después, evalúa tanto la respuesta como la trayectoria que siguió el agente. Estos controles facilitan la inspección del flujo de trabajo, pero la seguridad en producción y la aplicación de políticas siguen siendo responsabilidad de la aplicación.

Fuentes

• LangSmith: Evaluar un agente complejo — fuente del ejemplo de atención al cliente de la tienda de música, su estructura de consulta y reembolso, el modo simulado y los tres objetivos de evaluación.