Temario Lección 140 de 250 · Salidas estructuradas y llamadas a funciones y herramientas
Salidas estructuradas y llamadas a funciones y herramientas

De función a esquema de herramienta (introspección)

Las llamadas a herramientas (también llamadas llamadas a funciones) permiten que un modelo pida a tu programa que ejecute una función: anuncias un conjunto de herramientas, el modelo responde con el nombre de una herramienta y unos argumentos, y tú la ejecutas. Pero el modelo no puede ver tu Python -> solo ve un esquema: una descripción JSON del nombre y los parámetros de cada herramienta. Escribir esos esquemas a mano para cada función es tedioso y se desincroniza en cuanto cambias una firma. La solución es la introspección: generar el esquema directamente a partir de la función.

El módulo inspect de Python lee la firma de una función en tiempo de ejecución. El esquema que esperan las APIs de llamadas a herramientas se ve así:

{
  "name": "get_weather",
  "parameters": {
    "type": "object",
    "properties": {"city": {"type": "string"}, "days": {"type": "integer"}},
    "required": ["city"]
  }
}

Vas a construir tool_schema(func), que produzca exactamente eso. Dos ideas hacen todo el trabajo:

  • Traducir tipos de Python a tipos de JSON Schema. Lee la anotación de cada parámetro y tradúcela: int -> "integer", float -> "number", str -> "string", bool -> "boolean". Cualquier otra cosa, por defecto "string".
  • Deducir los obligatorios a partir de los valores por defecto. Un parámetro sin valor por defecto es obligatorio; un parámetro con valor por defecto es opcional. inspect.Parameter.empty es el centinela de "sin valor por defecto".
import inspect
sig = inspect.signature(func)
for name, param in sig.parameters.items():
    is_required = param.default is inspect.Parameter.empty
    json_type = ...   # from param.annotation

Usa func.__name__ como nombre de la herramienta. Constrúyela para que dos funciones con anotaciones distintas produzcan dos esquemas claramente distintos, un parámetro int aparezca como "integer" y uno str como "string", un parámetro con valor por defecto quede fuera de required y uno sin él esté dentro. Ese es el contrato del que depende toda integración con llamadas a herramientas.

Tu turno

Escribe tool_schema(func), que examine una función con inspect.signature y devuelva {"name": func.__name__, "parameters": {"type": "object", "properties": {param: {"type": json_type}}, "required": [...]}}. Traduce int->"integer", float->"number", str->"string", bool->"boolean" (por defecto "string"), y pon un parámetro en required solo cuando no tenga valor por defecto.

¿Has visto un problema en esta lección? Avísanos · Preguntar sobre esta lección

Este ejercicio se abre pronto

Termina la lección anterior y esta se desbloquea. Todo el curso es gratis, no hace falta cuenta, y puedes leer esta lección ahora mismo.