Llamada a funciones avanzada: esquemas y validación
En esta página
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_typeobliga al agente a estructurar su respuesta final- El contexto compartido (
RunContextWrapper) permite a las herramientas acceder al estado de la aplicación