# Lección 6 — Datasets para *function calling*: del ejemplo bonito a la evaluación ejecutable

**Duración objetivo:** 12–13 minutos  
**Formato:** guion de curso y podcast  
**Estado:** borrador en *scratch*; no publicar

## Objetivo de aprendizaje

Al terminar podrás diseñar un dataset de uso de herramientas y construir una evaluación que compruebe resultados, no sólo texto convincente. La meta es producir casos reproducibles donde podamos responder: ¿eligió la herramienta correcta?, ¿generó argumentos válidos?, ¿mantuvo la identidad de la llamada?, ¿respetó la política?, ¿dejó el estado esperado?

## Prerrequisitos

Necesitas lo visto en la lección 3: mensajes, esquemas JSON, `call_id`, respuesta de herramienta y bucle del orquestador. Aquí no conectaremos servicios reales ni afirmaremos que un resultado de BFCL o τ-bench mida automáticamente a Ornith. Cualquier variante concreta debe probarse con su plantilla, servidor y parser reales.

---

## Apertura del podcast

Imagina dos asistentes. El primero escribe: “Tu pedido ha sido cancelado correctamente”. El segundo llama `cancel_order`, recibe un resultado verificable y deja el pedido en estado `cancelled`. Sus frases pueden ser idénticas, pero sólo uno completó la tarea. Esa diferencia es el centro de la lección.

*Function calling* no es magia dentro del modelo. La aplicación presenta herramientas mediante contratos; el modelo propone nombre y argumentos; el orquestador valida, autoriza y ejecuta; después devuelve el resultado asociado a una llamada concreta. La documentación de OpenAI describe precisamente este flujo multietapa y el uso de esquemas JSON y `call_id`.[F1] Nuestro dataset debe representar esas fronteras sin esconderlas.

## 1. La unidad de datos es un contrato verificable

Un ejemplo útil no es sólo un par `pregunta → respuesta`. Debe contener, como mínimo:

1. **Entrada:** petición del usuario y contexto permitido.
2. **Catálogo de herramientas:** nombre, descripción y esquema de argumentos.
3. **Decisión esperada:** llamar, preguntar primero o abstenerse.
4. **Traza:** llamada propuesta, `call_id`, resultado simulado y respuesta final.
5. **Oráculo:** reglas que deciden si el caso pasó.
6. **Estado:** mundo inicial y estado final esperado cuando hay acciones.
7. **Metadatos:** versión del contrato, dominio, dificultad, semilla y procedencia.

El contrato tiene tres capas. La **sintáctica** pregunta si el JSON se puede parsear y respeta tipos, campos obligatorios y `additionalProperties`. La **semántica** pregunta si los valores significan lo correcto: “Mérida, Yucatán” no equivale a “Mérida, España”. La **operacional** pregunta si ejecutar la acción autorizada produce el efecto esperado. Un parser perfecto no detecta por sí solo una cancelación del pedido equivocado.

Hay que incluir negativos. Si el usuario pregunta por la política de devoluciones, quizá no haga falta una herramienta. Si falta el identificador del pedido, el comportamiento correcto puede ser pedirlo. Si solicita borrar datos sin confirmación, el agente debe detenerse. Un dataset compuesto sólo por llamadas exitosas enseña a llamar de más y no mide abstención.

## 2. Qué aportan BFCL y τ-bench

BFCL, el Berkeley Function Calling Leaderboard, evalúa llamadas simples, múltiples y paralelas, además de escenarios con abstención y estado. Su trabajo formal usa análisis de árbol sintáctico, o AST, para comparar estructura de llamadas a escala, y combina funciones curadas por expertos con contribuciones de usuarios.[F2] La página actual del proyecto deja claro que el benchmark ha evolucionado por versiones y publica un *commit* y paquete concretos para reproducir resultados.[F3]

La lección no es copiar un porcentaje del *leaderboard*. Es adoptar dos ideas. Primera: comparar estructura normalizada es mejor que comparar cadenas literales. `get_weather(city="Lima", unit="C")` y un JSON equivalente pueden ser válidos aunque cambie el orden de claves. Segunda: cuando sea seguro y determinista, la ejecución ofrece evidencia más fuerte que la forma. Aun así, AST y ejecución responden preguntas distintas: una llamada puede ser estructuralmente correcta y fallar por credenciales, red o estado externo.

τ-bench amplía la pregunta. Simula una conversación entre usuario, agente y herramientas de dominio sujetas a políticas. Su evaluación compara el estado final de una base de datos con un estado objetivo anotado y propone `pass^k`: el caso sólo cuenta como fiable si sale bien en las *k* repeticiones.[F4] Así distinguimos “funcionó una vez” de “funciona consistentemente”. El usuario simulado añade variación útil, pero también es otro modelo con sesgos; no reemplaza una batería determinista ni revisión humana.

```text
 petición + política + herramientas
              |
              v
        [ modelo bajo prueba ]
              |
       propuesta de llamada
              v
 [ validador ]--rechazo--> error tipado
      | válida
      v
 [ sandbox/fake ] -----> evento + nuevo estado
      |                         |
      +------ traza ------------+
                |
                v
 [ oráculos: contrato, política, estado, respuesta ]
                |
             PASS / FAIL
```

## 3. Del dataset al *contract test*

Un *contract test* fija la interfaz entre modelo, orquestador y herramienta. No evalúa si una respuesta “suena bien”; comprueba invariantes. Para una herramienta `cancel_order`, el contrato podría exigir `order_id` con patrón conocido, prohibir campos extra y requerir confirmación previa. El resultado debe conservar el mismo `call_id`. La herramienta falsa sólo permite transiciones `paid → cancelled`; una segunda ejecución con la misma clave idempotente no debe duplicar el efecto.

Un caso mínimo puede expresarse así:

```yaml
id: cancel-004
contract_version: 2
initial_state: {order_71: paid}
user: "Cancela el pedido 71; confirmo que quiero hacerlo."
tools:
  - name: cancel_order
    required: [order_id, idempotency_key]
expected:
  decision: call
  tool: cancel_order
  args: {order_id: "order_71"}
  final_state: {order_71: cancelled}
forbidden:
  - call_any_external_endpoint
  - expose_secret
```

Observa que el oráculo no exige una `idempotency_key` literal; puede validar que exista, tenga formato permitido y se reutilice durante un reintento. Tampoco fija la redacción final. Separar invariantes de detalles accidentales evita tests frágiles.

Organiza la suite en cuatro niveles. **Nivel A, selección:** herramienta correcta o abstención. **Nivel B, contrato:** JSON, tipos, enums y campos. **Nivel C, trayectoria:** orden, dependencias entre llamadas, vínculo por `call_id` y manejo de errores. **Nivel D, resultado:** política respetada y estado final. Reporta cada nivel por separado; un único promedio oculta si el fallo está en el modelo, el parser o el ejecutor.

Evita contaminación entre entrenamiento y evaluación. Deduplica por intención y estructura, no sólo por texto. Reserva familias completas de herramientas o políticas para prueba. Versiona esquema y oráculos junto al dataset. Registra modelo, plantilla, temperatura, semilla cuando exista, parser, *commit* del harness y número de repeticiones. Sin ese manifiesto, una mejora aparente puede venir de cambiar el entorno.

## 4. Práctica segura: diez casos, cero efectos externos

Trabajaremos únicamente con una base en memoria y herramientas falsas. Nada de correo, compras, borrados, credenciales, red ni datos personales. Crea diez casos:

- dos llamadas simples válidas;
- una con argumento faltante que obliga a preguntar;
- una con tipo incorrecto;
- una solicitud irrelevante donde debe abstenerse;
- una llamada paralela de sólo lectura;
- una secuencia lectura→escritura;
- una acción prohibida por política;
- un reintento idempotente;
- una conversación cuyo éxito dependa del estado final.

Para cada caso guarda entrada, contratos, estado inicial, decisión esperada, resultado falso y oráculos. Ejecuta primero el test con una traza fabricada correcta y verifica que pase. Después introduce una mutación por vez: cambia el nombre de una clave, elimina la confirmación, rompe el `call_id`, duplica la escritura o altera el estado final. El test correspondiente debe fallar con una razón legible.

Pseudocódigo del evaluador:

```python
for case in suite:
    trace = run_agent(case, tools=fakes, network=False)
    checks = {
        "selection": check_tool_choice(trace, case),
        "schema": validate_arguments(trace, case),
        "linkage": check_call_ids(trace),
        "policy": check_allowed_actions(trace, case),
        "state": compare_state(fakes.snapshot(), case.expected),
    }
    save_result(case.id, checks, trace.redacted())
```

**Guardas obligatorias:** proceso aislado, lista positiva de herramientas falsas, límite de pasos, *timeout*, presupuesto de tokens, semillas registradas, logs sin secretos y restauración del estado después de cada caso. Si pruebas un modelo servido localmente, el *harness* sigue sin concederle acceso al sistema operativo. Una propuesta del modelo es dato no confiable hasta superar validación y autorización.

### Criterio de éxito

La práctica termina cuando: los diez casos son parseables; cada mutación activa el fallo previsto; ninguna prueba usa red; todas las escrituras quedan en memoria; selección, contrato, trayectoria y estado tienen métricas separadas; y al menos tres repeticiones por caso generan un reporte de consistencia. No declares “compatibilidad con BFCL”, “equivalencia con τ-bench” ni capacidad general de Ornith: construiste una micro-suite inspirada en sus principios.

## 5. Cómo leer los resultados

Usa una matriz de fallos, no una sola cifra. Si selección sube y estado baja, quizá el modelo elija bien pero rellene mal argumentos. Si el esquema pasa y política falla, endurecer JSON no resolverá el problema. Si una tarea logra tres éxitos de cinco, reporta 60% de éxito observado; para una métrica estricta de fiabilidad a cinco repeticiones, ese caso no pasa `pass^5` porque no acertó las cinco.

Revisa trazas fallidas por categorías estables: herramienta equivocada, sobreuso, argumento, dependencia, política, recuperación y estado. Después añade casos que reproduzcan cada defecto sin copiar el texto exacto. El objetivo del dataset no es maquillar un marcador, sino hacer visibles las condiciones de fallo antes del despliegue.

## Vídeos curados y límites

**[V1, apoyo técnico de autor]** *How they built Gorilla, the LLM connected with massive APIs*, Continual, con Shishir G. Patil. Útil en 10:33–16:29 para contratos de argumentos y motivación de evaluación; 26:37–29:45 para evaluación. Es una entrevista y su transcripción es ASR: orienta, pero las afirmaciones metodológicas se apoyan en BFCL.[F2]

**[V2, apoyo técnico oficial]** *OpenAI DevDay 2024 | Community Spotlight | Sierra*, Karthik Narasimhan. Útil en 3:40–5:59 para Tool-Agent-User y el entorno con base de datos; 7:15–9:35 para estado objetivo y `pass^k`. Es una presentación breve del autor, no una validación independiente ni una prueba sobre Ornith.[F4]

## Glosario

- **Esquema:** contrato formal de nombres, tipos y restricciones de argumentos.
- **Oráculo:** procedimiento que decide si un resultado cumple lo esperado.
- **AST:** representación estructural del código o llamada, independiente de parte del formato superficial.
- **Estado objetivo:** condición verificable que debe tener el mundo al terminar.
- **`call_id`:** identificador que enlaza una llamada con su resultado.
- **Idempotencia:** propiedad por la que repetir una operación con la misma clave no duplica su efecto.
- **Abstención:** decisión correcta de no llamar una herramienta.
- **`pass^k`:** criterio de fiabilidad que exige éxito en las *k* repeticiones de una tarea.

## Recapitulación y próxima lección

Hoy convertimos conversaciones en contratos ejecutables. Vimos que un dataset serio incluye herramientas, trazas, políticas, estados y oráculos; que BFCL enseña a evaluar estructura, ejecución y abstención; y que τ-bench desplaza la mirada hacia interacción, estado final y consistencia. También construimos una práctica sin efectos externos, con *contract tests* capaces de fallar por la razón correcta.

En la próxima lección estudiaremos recuperación: *timeouts*, reintentos, presupuestos, bucles e idempotencia. El puente es directo: una evaluación ejecutable revela el fallo; una buena estrategia de recuperación evita convertirlo en una acción duplicada o en un bucle sin fin.

## Fuentes

- **[F1] Documentación primaria:** OpenAI, “Function calling”. https://developers.openai.com/api/docs/guides/function-calling
- **[F2] Paper primario:** Patil et al., “The Berkeley Function Calling Leaderboard (BFCL)”, ICML/PMLR 2025. https://proceedings.mlr.press/v267/patil25a.html
- **[F3] Proyecto y metodología versionada:** Berkeley Function-Calling Leaderboard. https://gorilla.cs.berkeley.edu/leaderboard.html
- **[F4] Paper primario:** Yao et al., “τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains”, 2024. https://arxiv.org/abs/2406.12045
- **[V1] Vídeo contextual:** https://www.youtube.com/watch?v=wOK1sX4QPBc
- **[V2] Vídeo contextual:** https://www.youtube.com/watch?v=rL1vMr1euG8
