Ir al contenido principal
Español— Elegir un idioma
Menú

Llamada a funciones avanzada: esquemas y validación

Lección 7 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Llamada a funciones avanzada: esquemas y validación
  2. Esquemas JSON y modo estricto
  3. Validación personalizada con Pydantic
  4. Gestión de errores en las herramientas
  5. Salida estructurada para herramientas
  6. Patrón: herramientas con contexto compartido
  7. Puntos clave

Llamada a funciones avanzada: esquemas y validación

La llamada a funciones es el mecanismo central que permite a un agente decidir cuándo y cómo invocar tus herramientas. Declarar una herramienta es suficiente para un prototipo, pero pasar a producción exige restringir las llamadas, validar valores de negocio y gestionar los fallos sin que el agente se bloquee. Esto es lo que aborda esta lección.

Esquemas JSON y modo estricto

La API de Responses utiliza esquemas JSON para describir los parámetros de cada herramienta, y el modo estricto garantiza que el modelo se adhiera exactamente al esquema. En concreto, el uso de un Enum o un Literal cierra la puerta a valores inventados.

from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class CreateTicket(BaseModel):
    title: str = Field(description="Título breve del ticket (máx. 100 caracteres)")
    description: str = Field(description="Descripción detallada del problema")
    priority: Priority = Field(description="Nivel de prioridad del ticket")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Componente técnico afectado"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Etiquetas opcionales para categorizar el ticket"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Crea un nuevo ticket de soporte técnico."""
    # En producción: llamar a Jira, Linear, GitHub Issues, etc.
    return f"Ticket creado: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Con el modo estricto activado por defecto, el modelo nunca puede enviar una prioridad no válida ni un componente fuera de la lista permitida. No tendrás que escribir código defensivo en el backend para traducir «urgente» o «P1» a un valor que tu sistema de tickets reconozca.

Validación personalizada con Pydantic

La comprobación de tipos evita valores imposibles, pero no los absurdos. Un IBAN de quince caracteres es una cadena perfectamente válida; tu lógica de negocio lo rechazará. Pydantic te permite incrustar estas reglas directamente en el esquema.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="IBAN de la cuenta de origen")
    destination_account: str = Field(description="IBAN de la cuenta de destino")
    amount: float = Field(gt=0, le=50000, description="Importe en euros (máx. 50.000)")
    reason: str = Field(min_length=5, max_length=200, description="Motivo de la transferencia")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Solo se aceptan IBAN franceses")
        if len(v) != 27:
            raise ValueError("El IBAN debe tener 27 caracteres")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Ejecuta una transferencia bancaria entre dos cuentas."""
    return f"Transferencia de {transfer.amount} € iniciada desde {transfer.source_account[:8]}... hacia {transfer.destination_account[:8]}..."

Las restricciones gt=0 y le=50000 sobre el importe cumplen una función similar en otro nivel: hacen que una transferencia negativa o que supere el límite sea estructuralmente imposible, independientemente de cómo formule el usuario la solicitud.

Gestión de errores en las herramientas

¿Qué ocurre cuando una herramienta se ejecuta pero falla? La tentación es dejar que la excepción ascienda; eso es un error, porque interrumpe el bucle del agente. En su lugar, devuelve un mensaje de error claro que el modelo pueda leer e interpretar.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Consulta una API externa con los parámetros especificados."""
    try:
        # En producción: llamada HTTP real
        import httpx
        response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), ensure_ascii=False)
    except httpx.TimeoutException:
        return json.dumps({
            "error": True,
            "message": f"Tiempo de espera agotado al llamar a {endpoint}. Reinténtalo en unos momentos."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"Error HTTP {e.response.status_code} en {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Error inesperado: {str(e)}"
        })

Cada rama formatea el mensaje en un lenguaje que el modelo entiende. Ante un tiempo de espera agotado, el agente intentará otra llamada; ante un error HTTP 404, informará al usuario o cambiará de enfoque en lugar de persistir ciegamente.

Salida estructurada para herramientas

Esta restricción se aplica también a la salida final. Con output_type, final_output deja de ser texto para analizar y se convierte en un objeto tipado, directamente utilizable por el código que realiza la llamada.

from pydantic import BaseModel
from agents import Agent, Runner

class AnalysisResponse(BaseModel):
    summary: str
    key_points: list[str]
    recommendation: str
    confidence_score: float

agent = Agent(
    name="Analyst",
    instructions="Analiza los datos proporcionados y genera un informe estructurado.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analiza las tendencias de ventas del primer trimestre de 2026.")
# result.final_output es de tipo AnalysisResponse
print(f"Resumen: {result.final_output.summary}")
print(f"Puntuación: {result.final_output.confidence_score}")

Patrón: herramientas con contexto compartido

Un último problema recurrente: tus herramientas suelen necesitar estado compartido (sesión de usuario, conexión a base de datos, clave de API) que sería absurdo pasar a través del modelo. El contexto resuelve esto pasándolo junto con la conversación.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Tu conexión a la base de datos
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Recupera el perfil del usuario actual."""
    user_id = ctx.context.user_id
    # Usa ctx.context.db_connection para la consulta
    return f"Perfil de usuario {user_id}: Premium, activo desde 2024"

agent = Agent(
    name="Personalized Agent",
    instructions="Ayudas al usuario que ha iniciado sesión.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "¿Cuál es mi perfil?", context=context)

La herramienta no tiene parámetros de negocio: la identidad del usuario proviene del contexto, no del modelo. Esto es también una medida de seguridad, ya que el agente no puede ver el perfil de otra persona cambiando un argumento.

Puntos clave

  • Los esquemas de Pydantic con enums y Literals garantizan la validez de las llamadas
  • Los validadores de campo añaden validación de negocio sobre la comprobación de tipos
  • Devuelve mensajes de error en JSON en lugar de lanzar excepciones en las herramientas
  • output_type obliga al agente a estructurar su respuesta final
  • El contexto compartido (RunContextWrapper) permite a las herramientas acceder al estado de la aplicación