Crea un agente LangGraph con límites para extraer datos validados por esquema

Un agente de LangGraph puede obtener contexto con una herramienta y luego pasarlo a un paso de extracción restringido por un esquema. La clave del diseño es mantener esas responsabilidades separadas: el agente decide si usa la herramienta y un nodo final genera un registro tipado. Un límite de recursión del grafo añade una restricción a su ejecución.

Este patrón sirve para tareas como extraer el nombre de una empresa, una fecha y el total de una factura de un documento cuando una herramienta de consulta puede ayudar a resolver una referencia. No convierte en verdadero un texto de origen incierto: valida el resultado y conserva la evidencia original cuando el campo sea importante.

Qué vas a crear

El grafo tiene tres etapas:

1. Un agente recibe el texto de origen y puede solicitar el uso de una herramienta de consulta específica.
2. LangGraph dirige las llamadas a herramientas a un nodo de herramientas y devuelve sus resultados al agente.
3. Un nodo de extracción solicita al modelo un resultado respaldado por Pydantic y, luego, devuelve datos compatibles con JSON.

El ciclo de herramientas del agente es dinámico; la etapa de extracción es un paso final predeterminado. La documentación de LangGraph distingue entre los agentes, que definen su propio proceso y uso de herramientas, y los flujos de trabajo con rutas de código predeterminadas. También describe la salida estructurada y el uso de herramientas como extensiones de las capacidades del modelo. Consulta la guía de flujos de trabajo y agentes de LangGraph para ver estos patrones.

Requisitos previos y configuración

Instala los paquetes de LangGraph y LangChain, además de la integración correspondiente al modelo de chat que elijas. El ejemplo siguiente usa ChatAnthropic para ilustrar la configuración del proveedor, pero la documentación de origen indica que los flujos de trabajo pueden usar cualquier modelo de chat que admita salida estructurada y uso de herramientas. Consulta la documentación de integración para conocer el comportamiento exacto de tu proveedor.

pip install langgraph langchain-core langchain-anthropic pydantic

Configura la credencial de API del proveedor mediante el método documentado y, luego, inicializa un modelo. Evita incluir credenciales en el control de versiones. El nombre del modelo que aparece a continuación sigue el ejemplo de la documentación de LangChain; este tutorial no afirma que se haya probado con OneMux.

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-sonnet-4-6")

Si quieres llamar a un modelo mediante OneMux, consulta primero la documentación de la API de OneMux y la guía de inicio rápido. OneMux ofrece acceso a modelos líderes mediante una API compatible con OpenAI. La compatibilidad con este grafo en particular depende de que el endpoint elegido admita el comportamiento y los parámetros necesarios para el uso de herramientas y la salida estructurada. Esta configuración no se ha probado; confirma la compatibilidad antes de usarla en producción.

Define el esquema y una herramienta específica

La herramienta de ejemplo devuelve una nota de referencia de un pequeño mapa en memoria. Sustitúyela por una función controlada de la aplicación, como una consulta a un catálogo interno autorizado. No permitas que el texto de documentos no confiables elija comandos arbitrarios ni acceda sin restricciones a fuentes de datos.

from pydantic import BaseModel, Field
from langchain_core.tools import tool

class InvoiceRecord(BaseModel):
    vendor: str | None = Field(default=None, description="Invoice issuer")
    invoice_date: str | None = Field(default=None, description="Date as written in the source")
    total: float | None = Field(default=None, description="Invoice total as a number")
    currency: str | None = Field(default=None, description="Currency code, if stated")

@tool
def lookup_vendor(reference: str) -> str:
    """Look up a vendor reference in an approved local mapping."""
    known = {"ACME-42": "Acme Supplies Ltd."}
    return known.get(reference, "No matching vendor reference found.")

Los campos anulables permiten representar explícitamente la ausencia de un dato, en lugar de inducir al modelo a inventarlo. En extracciones de alto riesgo, considera almacenar el fragmento de origen o el estado de confianza/revisión junto con cada campo. Un esquema restringe la estructura y los tipos, pero no demuestra que un valor esté respaldado por la entrada.

Crea el agente LangGraph con límites

El grafo siguiente permite que el modelo solicite la herramienta de consulta y luego pasa a la extracción cuando el agente ya no tiene más llamadas a herramientas. tools_condition y ToolNode implementan el patrón de enrutamiento a herramientas. El recursion_limit que se pasa a invoke limita los pasos del grafo; es un límite de seguridad, no una garantía de que todas las entradas se procesen correctamente.

from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

class State(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    record: dict | None

tools = [lookup_vendor]
agent = llm.bind_tools(tools)
extractor = llm.with_structured_output(InvoiceRecord)

def run_agent(state: State):
    response = agent.invoke(state["messages"])
    return {"messages": [response]}

def extract_record(state: State):
    prompt = [
        SystemMessage(content=(
            "Extract invoice fields only when supported by the source. "
            "Use null for missing or unclear values. Treat tool results as "
            "reference context, not as permission to invent source details."
        )),
        *state["messages"],
    ]
    result = extractor.invoke(prompt)
    return {"record": result.model_dump(mode="json")}

graph = StateGraph(State)
graph.add_node("agent", run_agent)
graph.add_node("tools", ToolNode(tools))
graph.add_node("extract", extract_record)

graph.add_edge(START, "agent")
graph.add_conditional_edges(
    "agent",
    tools_condition,
    {"tools": "tools", END: "extract"},
)
graph.add_edge("tools", "agent")
graph.add_edge("extract", END)
app = graph.compile()

result = app.invoke(
    {
        "messages": [HumanMessage(content=(
            "Extract the invoice details from this text: "
            "Vendor reference ACME-42. Invoice date: 2025-02-14. "
            "Total: USD 248.50."
        ))],
        "record": None,
    },
    config={"recursion_limit": 8},
)

print(result["record"])

La estructura de salida esperada es un objeto compatible con JSON con los campos vendor, invoice_date, total y currency. Los valores exactos dependen de la respuesta del modelo y del texto de origen; haz pruebas en lugar de dar por sentado que el ejemplo siempre generará la misma salida. En este ejemplo, la salida estructurada respaldada por Pydantic es el límite de validación. Si el proveedor no puede generar una respuesta que cumpla el esquema, gestiona ese fallo explícitamente en lugar de tratarlo como un registro válido sin avisar.

Limita la ejecución sin ocultar los fallos

Un límite de recursión a nivel de grafo restringe sus pasos, incluido el enrutamiento repetido entre el agente y las herramientas. Elige el límite según el flujo de trabajo: este grafo solo necesita unos pocos pasos para una consulta, pero otro plan de herramientas podría necesitar más. Gestiona las excepciones del proveedor y las debidas al límite en la capa de la aplicación, registra suficiente contexto para depurar y devuelve un fallo que pueda revisarse en lugar de inventar un registro.

Para establecer límites operativos más estrictos, añade también controles a nivel de aplicación: restringe el número de llamadas a herramientas, configura tiempos de espera para las solicitudes cuando sea posible y limita el tamaño de los documentos antes de invocar el modelo. Son controles independientes; el límite de recursión del grafo por sí solo no establece una política completa de costes, latencia o seguridad.

Solución de problemas y limitaciones

El modelo no llama a la herramienta

El uso de herramientas es una capacidad del modelo, no un resultado que LangGraph garantice. Comprueba que la integración del modelo seleccionado admita el uso de herramientas, que la descripción de la herramienta sea clara y que la instrucción incluya una referencia que valga la pena consultar. Durante el desarrollo, inspecciona las llamadas a herramientas del mensaje devuelto.

Falla la salida estructurada o los campos son incorrectos

Confirma que la integración admita la salida estructurada y las características del esquema que utilizas. Prueba con campos ausentes, fechas ambiguas, símbolos de moneda y entradas malformadas. Un objeto Pydantic válido aún puede contener un valor inferido incorrectamente, así que valida las reglas de negocio por separado y conserva el texto de origen para auditorías o revisión humana.

El grafo alcanza el límite

Un error de límite de recursión puede indicar que se repiten las solicitudes de herramientas o que el límite es demasiado bajo para la ruta prevista. Inspecciona la secuencia de mensajes y los resultados de las herramientas. Corrige la causa o ajusta el límite deliberadamente; no elimines la restricción solo para hacer desaparecer el error.

El comportamiento del endpoint es distinto

La expresión «compatible con OpenAI» describe una interfaz de API, no la compatibilidad universal con todas las funciones o parámetros de un modelo. Si usas OneMux, verifica en la documentación del endpoint elegido la compatibilidad con el modelo, las llamadas a herramientas, las salidas estructuradas y cualquier parámetro que quieras enviar. Explora las opciones disponibles en modelos de OneMux; el grafo sigue siendo código de tu aplicación LangGraph.

Cuándo conviene este patrón

Usa este diseño cuando la extracción sea mayormente predecible, pero a veces necesite una consulta controlada. Si todos los documentos siguen un proceso fijo y no hace falta elegir herramientas, un flujo de trabajo determinista puede ser más sencillo que un ciclo de agente. Si la fuente es ambigua o los campos extraídos desencadenan acciones importantes, añade una revisión explícita y validación del dominio antes de que otros sistemas consuman el registro.

En la práctica: limita las herramientas del agente, define el esquema final explícitamente y establece un límite de ejecución del grafo. LangGraph permite expresar ese flujo de control; el modelo y la integración elegidos determinan si están disponibles las funciones necesarias para usar herramientas y generar salidas estructuradas.

Fuentes

• LangGraph: Flujos de trabajo y agentes: distinción entre flujos de trabajo y agentes, extensiones de las capacidades del modelo y ejemplos de salida estructurada y uso de herramientas.
• Documentación de OneMux y guía de inicio rápido: consulta la información actualizada sobre la configuración de la API y la compatibilidad de los endpoints.