Phase 13 - Lesson 01

La Interface de Herramientas — Por qué los Agentes Necesitan E/S Estructurada

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

Un modelo de lenguaje produce tokens. Un programa ejecuta acciones. La brecha entre ambos es la interfaz de herramientas: un contrato que permite al modelo solicitar una acción y al host ejecutarla. Toda stack de 2026 — llamadas de función en OpenAI, Anthropic y Gemini; tools/call de MCP; partes de tareas de A2A — es una codificación diferente del mismo ciclo de cuatro pasos. Esta lección nombra el ciclo y muestra la infraestructura mínima para ejecutarlo.

Tipo: Aprender Lenguajes: Python (stdlib, sin LLM) Prerrequisitos: Fase 11 (APIs de completado de LLM) Tiempo: ~45 minutos

Objetivos de Aprendizaje

• Explicar por qué un LLM que solo puede generar texto no puede, por sí mismo, realizar acciones en el mundo real.
• Dibujar el ciclo de llamada a herramientas de cuatro pasos (describir → decidir → ejecutar → observar) y nombrar a quién pertenece cada paso.
• Escribir una descripción de herramienta en tres partes: nombre, entrada de JSON Schema y una función ejecutora de tipo determinista.
• Distinguir entre herramientas puras y con efectos secundarios y explicar por qué la separación es importante para la seguridad.

El Problema

Un LLM emite una distribución de probabilidad sobre el siguiente token. Esa es toda su superficie de salida. Si le preguntas a un modelo de chat "cuál es el clima en Bengaluru ahora mismo", puede escribir una oración plausible, pero no puede conectarse a una API de clima. La oración podría ser correcta por coincidencia o estar desactualizada por tres días.

Cerrar esa brecha es el propósito de la interfaz de herramientas. El programa host (el runtime de tu agente, Claude Desktop, ChatGPT, Cursor o un script personalizado) anuncia una lista de herramientas invocables al modelo. El modelo, cuando decide que se necesita una acción, emite un payload estructurado que nombra una herramienta y sus argumentos. El host analiza ese payload, ejecuta la herramienta de verdad y devuelve el resultado. El ciclo continúa hasta que el modelo decide que no se necesitan más llamadas.

La primera versión de este contrato se lanzó en junio de 2023 como el parámetro "functions" de OpenAI. Anthropic lo siguió con bloques tool_use en Claude 2.1. Gemini agregó functionDeclarations unos meses después. Cada proveedor ahora expone la misma forma: una lista de herramientas tipada con JSON-Schema como entrada y una llamada de herramienta con payload JSON como salida. El Model Context Protocol (noviembre de 2024) generalizó el contrato para que un único registro de herramientas sirva a todos los modelos. A2A (abril de 2026, v1.0) aplicó la misma primitiva para la delegación de agente a agente.

El ciclo de cuatro pasos es la invariante debajo de todo esto. Todo lo demás en la Fase 13 es una elaboración.

El Concepto

Paso uno: describir

El host declara cada herramienta con tres campos.

• Nombre. Un identificador estable legible por máquina. get_weather, no "weather thing".
• Descripción. Un resumen de un párrafo en lenguaje natural. "Use cuando el usuario pregunte sobre las condiciones actuales de una ciudad específica. No lo use para datos históricos."
• Esquema de entrada. Un objeto de JSON Schema (draft 2020-12) que describe los argumentos de la herramienta.

El modelo recibe la lista. Los proveedores modernos serializan estas declaraciones en el prompt del sistema utilizando una plantilla específica del proveedor, de modo que usted, como llamador, solo maneja la forma estructurada.

Paso dos: decidir

Dada la mensaje del usuario y las herramientas disponibles, el modelo elige uno de tres comportamientos.

1. Responder directamente en texto. Sin llamada a herramientas.
2. Llamar a una o más herramientas. Emitir objetos de llamada estructurados. Con parallel_tool_calls: true (predeterminado en OpenAI y Gemini, opcional en Anthropic), el modelo puede emitir múltiples llamadas en un solo turno.
3. Rechazar. Las salidas estructuradas en modo estricto pueden producir un bloque refusal tipado en lugar de una llamada.

El payload de una llamada a una herramienta tiene tres campos estables: un id de llamada, un name de herramienta y un objeto JSON arguments. El id existe para que el host pueda correlacionar el resultado posterior con la llamada específica, lo cual es importante cuando las llamadas paralelas regresan fuera de orden.

Paso tres: ejecutar

El host recibe la llamada, valida los argumentos contra el esquema declarado y ejecuta el ejecutor. Los argumentos no válidos significan que el modelo alucinó un campo o usó el tipo incorrecto, un modo de falla muy común en modelos débiles. Los hosts de producción hacen una de tres cosas con los argumentos no válidos: fallar rápidamente y presentar el error al modelo, reparar el JSON con un analizador estructurado o volver a intentar el modelo con el error de validación incluido en el prompt.

El ejecutor en sí es código ordinario. Python, TypeScript, un comando de shell, una consulta de base de datos. Produce un resultado, que generalmente es una cadena, pero puede ser cualquier valor JSON o un bloque de contenido estructurado (texto, imagen o referencia de recurso en MCP). El resultado debe ser serializable.

Paso cuatro: observar

El host agrega el resultado de la herramienta a la conversación (como un mensaje de rol tool con el id correspondiente) y vuelve a invocar al modelo. El modelo ahora tiene la salida de la herramienta en contexto y puede producir una respuesta final o solicitar más llamadas. Esto continúa hasta que el modelo deja de emitir llamadas o el host alcanza un límite de seguridad en el recuento de iteraciones.

La división de confianza

Las herramientas vienen en dos tipos importantes para la seguridad.

• Pura. De solo lectura, determinista, sin efectos secundarios. get_weather, search_docs, get_current_time. Segura de invocar de manera especulativa.
• Consecuente (Con efectos secundarios). Muta el estado externo; requiere validación, auditoría o confirmación del usuario. send_email, delete_file, execute_trade. Debe estar controlada por filtros de seguridad.

La "Regra de Dois" de 2026 de Meta para la seguridad de agentes establece que un solo turno puede combinar como máximo dos de: entrada no confiable, datos confidenciales, acción consecuente. La interfaz de herramientas es donde se aplica esa regla, ya sea rechazando llamadas, requiriendo confirmación del usuario o escalando alcances. Consulte la Fase 13 · 15 para ver el capítulo completo de seguridad y la Fase 14 · 09 para ver las políticas de permisos a nivel de agente.

Dónde vive el ciclo

¿Por qué no simplemente pedirle al modelo que emita JSON?

"Pedir al modelo que responda en JSON" era el patrón anterior a la invocación de funciones. Falla entre el 5 y el 15 por ciento de las veces en modelos de frontera, y mucho más en modelos más pequeños. Los modos de falla incluyen llaves faltantes, comas adicionales, campos alucinados y tipos incorrectos. Luego se necesita un paso de reparación de JSON, un reintento o un decodificador restringido.

La invocación de funciones nativas es mejor por tres razones. Primero, el proveedor entrena al modelo de extremo a extremo en la forma exacta de la llamada, por lo que la tasa de JSON válido suba al 98 o 99 por ciento en modo estricto. Segundo, el payload de la llamada se encuentra en su propio espacio de protocolo, no dentro de texto libre, por lo que una llamada a una herramienta nunca se filtra en la respuesta visible para el usuario. Tercero, los proveedores imponen el cumplimiento del esquema con decodificación restringida (modo estricto de OpenAI, tool_use de Anthropic, responseSchema de Gemini). Se garantiza que la salida se validará.

La Fase 13 · 02 analiza las tres APIs de proveedores lado a lado. La Fase 13 · 04 profundiza en las salidas estructuradas.

Cortocircuitos (Circuit Breakers)

El ciclo termina cuando el modelo deja de emitir llamadas o el host alcanza un número máximo de turnos. Los hosts de producción establecen esto entre 5 y 20 turnos. Más allá de eso, es casi seguro que se encuentre en un ciclo del que el modelo no puede salir. Claude Code tiene un valor predeterminado de 20; OpenAI Assistants de 10; el modo agente de Cursor de 25.

La alternativa (ciclos infinitos) aparece cada seis meses como autopsias de "el agente gastó $400 en llamadas de API de la noche a la mañana". No envíe a producción sin un límite.

La Fase 14 · 12 cubre la recuperación de errores y la auto-sanación en profundidad; la Fase 17 cubre los límites de tasa de producción.

Hacia dónde va la Fase 13 a partir de aquí

• Las Lecciones 02 a 05 pulen la superficie de llamada a herramientas a nivel de proveedor.
• Las Lecciones 06 a 14 generalizan el ciclo en MCP.
• Las Lecciones 15 a 18 defienden el ciclo contra servidores hostiles, usuarios adversarios y superficies de configuración de autenticación remota no autenticadas.
• Las Lecciones 19 a 22 extienden el patrón a la colaboración de agente a agente, la observabilidad, el enrutamiento y el empaquetado.
• La Lección 23 lanza un ecosistema completo utilizando cada primitiva.

Cada lección restante es una elaboración de este ciclo de cuatro pasos. Manténgalo en mente como la variante.

Use It

code/main.py ejecuta el ciclo de cuatro pasos sin un LLM. Una función decodificadora falsa ("fake decider") simula el modelo mediante la coincidencia de patrones (pattern-matching) en el mensaje del usuario; el ejecutor, el validador de esquemas y el arnés del paso de observación son reales. Ejecútelo para ver toda la coreografía de solicitud/respuesta con estados intermedios imprimibles, y luego reemplace el decodificador falso con cualquier proveedor real en una lección posterior.

Qué observar:

• El registro de herramientas (tool registry) guarda tres campos por herramienta: nombre, descripción, esquema y una referencia al ejecutor.
• El validador es un subconjunto mínimo de JSON Schema (tipos, campos obligatorios, enum, min/max) escrito únicamente con la biblioteca estándar (stdlib). La lección Fase 13 · 04 ofrece una implementación más completa.
• El ciclo limita el número de iteraciones a cinco. Los agentes de producción necesitan exactamente este tipo de cortocircuito (circuit breaker).

Ship It

Esta lección produce outputs/skill-tool-interface-reviewer.md. Dada una definición provisional de herramienta (nombre + descripción + esquema + bosquejo del ejecutor), la habilidad (skill) la audita para comprobar su idoneidad para el ciclo: si el nombre es estable para la máquina, si la descripción es un resumen de uso completo, si el esquema utiliza JSON Schema 2020-12 correctamente y si la clasificación pura-vs-consecuente es explícita.

Ejercicios

1. Agregue una cuarta herramienta a code/main.py llamada get_stock_price(ticker). Escriba su descripción como "Use cuando el usuario solicite el precio actual de una acción por su ticker. No lo use para precios históricos o resúmenes de mercado." Ejecute el arnés y confirme que el decodificador falso dirija las consultas que mencionen tickers a la nueva herramienta.

2. Rompa el validador de esquemas. Pase una llamada cuyo objeto arguments carezca de un campo obligatorio y confirme que el host la rechaza antes de la ejecución. Luego, pase una llamada con un campo adicional desconocido. Decida: ¿el host debería rechazar o ignorar? Justifique su elección con un argumento de seguridad.

3. Clasifique cada herramienta en el arnés como pura o consecuente. Agregue una etiqueta consequential: true a las entradas del registro que lo necesiten y cambie el ciclo para imprimir una línea del tipo "confirmaría con el usuario" cada vez que se elija una herramienta consecuente. Esta es la forma del filtro de confirmación que todo host de producción necesita.

4. Dibuje el ciclo de cuatro pasos en papel con la tabla de columnas de proveedores completada para su cliente favorito (Claude Desktop, Cursor, ChatGPT o un stack personalizado). Haga una referencia cruzada con la variante específica de MCP en la Fase 13 · 06.

5. Lea la guía de invocación de funciones de OpenAI de principio a fin. Identifique el único campo que se encuentra en la solicitud pero no en el ciclo de cuatro pasos tal como se presenta aquí. Explique qué agrega y por que es conveniente más que esencial.

Términos Clave

Lectura Adicional

• OpenAI — Function calling guide — referencia canónica para declaraciones de herramientas y formatos de llamada al estilo OpenAI
• Anthropic — Tool use overview — formato de bloque tool_use / tool_result de Claude
• Google — Gemini function calling — functionDeclarations y semántica de llamadas en paralelo en Gemini
• Model Context Protocol — Specification 2025-11-25 — la generalización agnóstica del proveedor para la interfaz de herramientas
• JSON Schema — 2020-12 release notes — el dialecto de esquema que habla cada API de herramienta moderna