Salida estructurada JSON en agentes

Salidas estructuradas con create_agent

Cuando trabajamos con agentes en LangChain, a menudo necesitamos que devuelvan datos en un formato específico y predecible. El parámetro response_format de create_agent permite configurar cómo el agente retorna información estructurada, capturando automáticamente los datos, validándolos y devolviéndolos en la clave structured_response del estado final.

A diferencia de usar with_structured_output directamente sobre un modelo de chat, los agentes requieren un enfoque basado en estrategias que determina cómo se genera y valida la salida estructurada durante el flujo de ejecución del agente.

Estrategias disponibles

LangChain ofrece tres formas de configurar el response_format:

• ProviderStrategy: Utiliza la funcionalidad nativa del proveedor del modelo para generar salidas estructuradas.

• ToolStrategy: Emplea llamadas a herramientas (tool calling) para conseguir el mismo resultado cuando el modelo no soporta salidas estructuradas nativas.

• Tipo de esquema directo: Al pasar directamente una clase Pydantic, LangChain selecciona automáticamente la mejor estrategia según las capacidades del modelo.

from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5",
    response_format=MiEsquema  # Selección automática de estrategia
)

ProviderStrategy

La estrategia ProviderStrategy aprovecha las capacidades nativas de modelos como OpenAI, Anthropic o Gemini para generar salidas estructuradas. Esta opción proporciona mayor fiabilidad porque el proveedor del modelo aplica el esquema directamente.

from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.agents.structured_output import ProviderStrategy

class ContactInfo(BaseModel):
    """Información de contacto de una persona."""
    name: str = Field(description="Nombre de la persona")
    email: str = Field(description="Dirección de correo electrónico")
    phone: str = Field(description="Número de teléfono")

agent = create_agent(
    model="gpt-5",
    response_format=ProviderStrategy(ContactInfo)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extrae los datos de: María López, maria@ejemplo.com, 612345678"}]
})

# Acceso a la respuesta estructurada
contact = result["structured_response"]
print(f"Nombre: {contact.name}")
print(f"Email: {contact.email}")

Cuando se pasa un esquema directamente sin especificar estrategia, LangChain detecta si el modelo soporta salidas estructuradas nativas y utiliza ProviderStrategy automáticamente. Si el modelo no lo soporta, recurre a ToolStrategy.

ToolStrategy

Para modelos que no disponen de soporte nativo para salidas estructuradas, ToolStrategy utiliza el mecanismo de llamadas a herramientas para conseguir resultados equivalentes. Esta estrategia funciona con la mayoría de modelos modernos que soportan tool calling.

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy

class ProductReview(BaseModel):
    """Análisis de una reseña de producto."""
    rating: int | None = Field(description="Puntuación del producto", ge=1, le=5)
    sentiment: Literal["positive", "negative"] = Field(description="Sentimiento de la reseña")
    key_points: list[str] = Field(description="Puntos clave de la reseña")

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analiza: Excelente producto, 5 estrellas. Envío rápido pero caro."}]
})

review = result["structured_response"]
# ProductReview(rating=5, sentiment='positive', key_points=['envío rápido', 'caro'])

La clase ToolStrategy acepta parámetros adicionales para personalizar su comportamiento:

• schema: El modelo Pydantic, dataclass, TypedDict o esquema JSON que define la estructura.

• tool_message_content: Mensaje personalizado que aparece en el historial cuando se genera la salida estructurada.

• handle_errors: Configura cómo gestionar errores de validación.

Personalización del mensaje de herramienta

El parámetro tool_message_content permite definir un mensaje personalizado que aparece en el historial de conversación cuando el agente genera la salida estructurada:

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy

class MeetingAction(BaseModel):
    """Acción extraída de una reunión."""
    task: str = Field(description="Tarea específica a completar")
    assignee: str = Field(description="Persona responsable")
    priority: Literal["low", "medium", "high"] = Field(description="Nivel de prioridad")

agent = create_agent(
    model="gpt-5",
    tools=[],
    response_format=ToolStrategy(
        schema=MeetingAction,
        tool_message_content="Acción registrada en las notas de la reunión."
    )
)

Sin este parámetro, el mensaje por defecto muestra los datos de la respuesta estructurada en formato JSON.

Manejo de errores

Los modelos pueden cometer errores al generar salidas estructuradas mediante tool calling. LangChain proporciona mecanismos de reintento automático cuando la validación falla.

El parámetro handle_errors de ToolStrategy acepta varias configuraciones:

• True (valor por defecto): Captura todos los errores y reintenta con un mensaje de error estándar.

• False: No gestiona errores, las excepciones se propagan directamente.

• str: Mensaje personalizado para todos los reintentos.

• Tipo de excepción: Solo reintenta para ese tipo específico de error.

• Callable: Función que recibe la excepción y devuelve el mensaje de error.

from langchain.agents.structured_output import ToolStrategy, StructuredOutputValidationError

def manejador_errores(error: Exception) -> str:
    if isinstance(error, StructuredOutputValidationError):
        return "El formato no es correcto. Revisa los campos e inténtalo de nuevo."
    return f"Error: {str(error)}"

agent = create_agent(
    model="gpt-5",
    tools=[],
    response_format=ToolStrategy(
        schema=ProductReview,
        handle_errors=manejador_errores
    )
)

Cuando el modelo genera datos que no cumplen las restricciones del esquema Pydantic, como un valor fuera de rango, el agente recibe un mensaje de error y tiene oportunidad de corregir su respuesta automáticamente.

Tipos de unión para múltiples esquemas

ToolStrategy soporta tipos Union que permiten al modelo elegir entre varios esquemas según el contexto de la conversación:

from typing import Union
from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy

class ContactInfo(BaseModel):
    name: str = Field(description="Nombre de la persona")
    email: str = Field(description="Correo electrónico")

class EventDetails(BaseModel):
    event_name: str = Field(description="Nombre del evento")
    date: str = Field(description="Fecha del evento")

agent = create_agent(
    model="gpt-5",
    tools=[],
    response_format=ToolStrategy(Union[ContactInfo, EventDetails])
)

Cuando el modelo intenta devolver múltiples esquemas simultáneamente, el sistema de manejo de errores detecta esta situación y solicita al modelo que seleccione únicamente el más relevante para la consulta del usuario.