# Lección 3 — Harness, APIs y tool calling: del esquema a una acción verificable

**Versión de base:** r3.2  
**Duración objetivo:** 13 minutos  
**Estado:** guion escrito; sin locución y sin publicación

## Objetivos

Al terminar esta lección podrás distinguir el modelo del harness, describir una herramienta con un schema explícito, seguir una llamada mediante `call_id` y evaluar el resultado con oráculos. También podrás diseñar una práctica donde ningún paso tenga efectos reales. La idea central es sencilla: el modelo propone una llamada; software externo decide si la valida, la autoriza y la ejecuta. Que una salida parezca JSON no demuestra que sea correcta, segura ni útil.

## 1. El modelo no ejecuta la herramienta

Un modelo produce tokens. Cuando esos tokens representan una llamada, el **harness** actúa como capa de control: presenta herramientas disponibles, interpreta la salida, valida argumentos, aplica permisos, despacha código y devuelve una observación al modelo. La **API** define cómo viajan mensajes, schemas, llamadas y resultados. La **herramienta** es la capacidad concreta: consultar inventario, calcular una cifra o preparar un borrador.

Separar estas piezas evita atribuirle magia al modelo. Un error puede nacer en la selección de herramienta, en los argumentos, en el parser, en la autenticación, en el proveedor o en la asociación entre llamada y resultado. “El agente falló” es un diagnóstico demasiado vago.

```text
Usuario
   │ solicitud
   ▼
Harness ── herramientas + schemas ──► API/modelo
   ▲                                      │
   │ resultado con el mismo call_id       │ tool call propuesta
   │                                      ▼
Validador ◄── parser ◄── {name, arguments, call_id}
   │
   ├─ rechazo seguro: error estructurado
   └─ autorización ─► ejecutor ─► herramienta simulada o real
```

El diagrama muestra dos fronteras importantes. El parser sólo convierte un protocolo de salida en una estructura interna. El ejecutor no debe recibir nada antes de validación y autorización.

## 2. El schema es un contrato, no una sugerencia

Una función expuesta al modelo necesita nombre, descripción y parámetros. JSON Schema permite declarar tipos, campos obligatorios, valores permitidos y propiedades inesperadas. Un contrato estrecho reduce ambigüedad y facilita pruebas.

```json
{
  "name": "consultar_stock",
  "description": "Consulta stock de un SKU; no compra ni reserva",
  "parameters": {
    "type": "object",
    "properties": {
      "sku": {"type": "string", "pattern": "^[A-Z0-9-]{3,20}$"},
      "almacen": {"type": "string", "enum": ["NORTE", "SUR"]}
    },
    "required": ["sku", "almacen"],
    "additionalProperties": false
  }
}
```

Este schema rechaza un `almacen` desconocido y campos extra. No comprueba que el SKU exista, que el usuario pueda verlo ni que el stock recibido sea verdadero. La conformidad estructural garantiza **forma**, no semántica, autorización o éxito de tarea. Por eso el harness necesita validación de negocio después de validar el schema.

Los modos de llamada tampoco son equivalentes. Una función nombrada o un modo obligatorio puede usar decodificación restringida, según el servidor. En modo `auto`, algunos runtimes dejan al modelo generar libremente y un parser extrae la llamada; los argumentos pueden quedar malformados. En vLLM, además, plantilla de chat y parser deben corresponder al protocolo del modelo. Aceptar el campo `strict` no implica necesariamente aplicarlo: hay que verificar el comportamiento del runtime y su versión.

## 3. `call_id`: identidad y causalidad

Imagina que el modelo solicita dos consultas en paralelo. Una tarda cincuenta milisegundos y la otra quinientos. El orden de llegada ya no identifica qué resultado pertenece a qué solicitud. Para eso existe `call_id`: cada resultado debe conservar el identificador único de su llamada.

```json
{"type":"function_call","call_id":"call_7f2","name":"consultar_stock","arguments":"{\"sku\":\"ABC-42\",\"almacen\":\"NORTE\"}"}
{"type":"function_call_output","call_id":"call_7f2","output":"{\"unidades\":8}"}
```

No confundas el identificador de respuesta, el identificador interno del ítem y `call_id`. Sus nombres varían entre APIs. Tu representación interna debe documentar cuál enlaza llamada y resultado. Rechaza resultados sin pareja, IDs duplicados o un `call_id` inventado por el cliente. Registra el ID en logs, pero nunca lo uses por sí solo como credencial o permiso.

Una traza mínima conserva: petición del usuario, versión del schema, salida cruda, resultado del parser, decisión del validador, decisión de autorización, inicio y fin de ejecución, error tipado y resultado asociado. Así puedes localizar una ruptura sin guardar secretos ni datos innecesarios.

## 4. Oráculos: cómo saber si funcionó

Un **oráculo** es una regla verificable que decide si un caso pasó. Comparar sólo la respuesta final favorece textos convincentes aunque la trayectoria sea incorrecta. Evalúa por niveles:

1. **Selección:** ¿eligió `consultar_stock` y evitó herramientas irrelevantes?
2. **Argumentos:** ¿el JSON se parsea y satisface schema y reglas de negocio?
3. **Correlación:** ¿cada resultado conserva exactamente su `call_id`?
4. **Trayectoria:** ¿respetó dependencias, orden y límite de llamadas?
5. **Resultado:** ¿la respuesta final coincide con el estado controlado del simulador?
6. **Operación:** ¿latencia, coste, timeouts y errores quedan dentro del presupuesto?
7. **Seguridad:** ¿no hubo acceso fuera de alcance ni efectos laterales no aprobados?

Un caso positivo puede exigir `sku=ABC-42`, `almacen=NORTE`, una sola llamada y la frase final “8 unidades”. Casos negativos deben cubrir JSON truncado, campo extra, enum inválido, herramienta inexistente, timeout, dos resultados cruzados y `call_id` desconocido. El oráculo no debería depender de “se ve bien”; debe producir evidencia comparable, por ejemplo `PASS`, código de error y traza sanitizada.

### Del test unitario a la prueba de extremo a extremo

No mezcles todas las capas en una única métrica. Primero prueba el schema con objetos escritos a mano. Después prueba el parser con salidas crudas representativas del protocolo del modelo. A continuación usa un modelo simulado que emita llamadas predeterminadas para comprobar despacho, correlación y manejo de errores. Sólo al final conecta un modelo real y mide la tarea completa. Esta escalera permite distinguir un fallo determinista del harness de la variabilidad del modelo.

Congela en cada reporte la versión del modelo, runtime, plantilla, parser, schema y configuración de muestreo. Si cambias una de ellas, has creado otra condición experimental. Repite los casos suficientes veces para detectar fallos intermitentes, pero informa tanto éxito de tarea como tasa de llamadas malformadas. Un promedio único puede ocultar que una ruta peligrosa falla poco, pero con gran impacto.

Las pruebas de contrato también deben ejecutarse contra la frontera de la API. Verifica que `arguments` llega como objeto o cadena según el protocolo esperado, que los errores conservan tipo y que streaming no despacha JSON incompleto. En una respuesta por fragmentos, acumula argumentos hasta el evento de finalización; nunca ejecutes al recibir el primer delta. Finalmente, añade un oráculo de parada: tras éxito, error terminal o agotamiento de presupuesto, ninguna llamada adicional puede ejecutarse.

## 5. Seguridad antes de ejecución

Considera todos los argumentos generados por el modelo como entrada no confiable. Aplica lista permitida de herramientas, schema cerrado, normalización mínima y reglas de negocio independientes. Usa credenciales de mínimo privilegio en el ejecutor, no en el prompt. Separa lectura de escritura. Para acciones con dinero, borrado, publicación o mensajes externos, exige confirmación humana vinculada a los argumentos exactos.

Añade timeout, límite de tamaño, cuota de llamadas y política de reintentos sólo para fallos transitorios. Una llamada con validación fallida no se arregla repitiéndola a ciegas. Las herramientas de shell o código requieren sandbox, sistema de archivos restringido, red denegada por defecto y límites de CPU y memoria. Sanitiza los resultados: una herramienta también puede devolver instrucciones maliciosas o datos sensibles.

## 6. No uses wrappers opacos

Un wrapper que oculta schema, petición, parser, reintentos o errores impide aprender y auditar el sistema. “El SDK lo resolvió” no es una explicación. En esta lección, la integración debe permitir inspeccionar:

- payload enviado a la API, sin secretos;
- schema exacto y su versión;
- salida cruda y estructura parseada;
- mapa explícito `nombre → función`;
- política de autorización y reintentos;
- resultado, error y `call_id`;
- métricas y oráculos ejecutados.

Puedes usar una biblioteca, pero no delegar el entendimiento. Si ofrece una función `run_agent()` que sólo devuelve texto final, activa trazas o reemplázala por llamadas API directas para la práctica. La abstracción es aceptable cuando reduce repetición y conserva observabilidad; es opaca cuando no puedes explicar qué ejecutó, con qué argumentos y por qué.

## 7. Práctica segura: laboratorio sin efectos reales

Construye un harness mínimo para `consultar_stock`, pero conecta la herramienta a un diccionario local inmutable: `ABC-42/NORTE → 8` y `XYZ-10/SUR → 0`. No uses red, credenciales, base de datos ni sistema de archivos fuera del directorio de práctica.

**Paso 1.** Define el schema anterior y asigna `schema_version="1.0"`.  
**Paso 2.** Implementa un parser que produzca `{name, arguments, call_id}` o un error tipado.  
**Paso 3.** Valida JSON, schema, herramienta permitida y reglas de negocio antes del despacho.  
**Paso 4.** Ejecuta sólo el simulador y devuelve un objeto `function_call_output` con el mismo `call_id`.  
**Paso 5.** Limita el episodio a dos llamadas, dos segundos y cero reintentos para errores permanentes.  
**Paso 6.** Ejecuta ocho casos: dos válidos y seis fallos, incluyendo `call_id="call_inexistente"`.  
**Paso 7.** Guarda una tabla con entrada, decisión, código, ID esperado, ID observado y veredicto.

Criterio de aprobación: ocho oráculos deterministas pasan; ninguna ruta toca recursos externos; los logs no contienen secretos; el harness termina de forma explícita ante cada fallo. Como ampliación, lanza dos consultas simuladas en paralelo con demoras distintas y demuestra que los resultados se recomponen por ID, no por orden.

## 8. Fuentes, etiquetas y límite del vídeo

- **[FUENTE PRIMARIA — API]** OpenAI, *Function calling*: flujo de cinco pasos, herramientas descritas con schema y asociación del resultado mediante `call_id`. https://developers.openai.com/api/docs/guides/function-calling
- **[FUENTE PRIMARIA — RUNTIME]** vLLM 0.20.0, *Tool Calling*: modos `named`, `required`, `auto` y `none`; diferencias de restricción; selección explícita de parser y plantilla. https://docs.vllm.ai/en/v0.20.0/features/tool_calling/
- **[FUENTE ACADÉMICA — DIAPOSITIVAS]** CMU AI Agents 2026, *Tool Use for Language Model Agents*: schemas, parsing, IDs, APIs, seguridad y evaluación por capas. https://www.cmu-agents.com/slides/lecture-02-tool-use.pdf
- **[VÍDEO — APOYO PEDAGÓGICO]** Graham Neubig, `jXChFB4JSyw`. El transcript no fue recuperado; no se cita literalmente. Las afirmaciones se anclan en el PDF oficial.
- **[VÍDEO — APOYO DEL MANTENEDOR]** vLLM Office Hours #48, `N4qRxarKYFE`, tramo útil 29:05–48:20. La ASR es parcial y se excluye la demo final opaca. Para comportamiento técnico manda la documentación versionada.

**Límite:** los vídeos orientan y contextualizan; no prueban por sí solos compatibilidad, seguridad ni calidad de un modelo. Esta lección no presenta una demo como benchmark ni extrapola resultados a Ornith sin una prueba reproducible.

## Recapitulación

Tool calling es un sistema, no un truco de prompting. El schema restringe la forma; el harness valida, autoriza y ejecuta; la API transporta estados; `call_id` preserva causalidad; y los oráculos convierten impresiones en pruebas. La seguridad exige privilegio mínimo, simulación inicial, límites y confirmación para efectos reales. Finalmente, evita wrappers opacos: si no puedes ver el contrato, la traza y el criterio de éxito, todavía no puedes confiar en la integración.