El módulo 4 terminó con una frontera dibujada con precisión: DocuBot sabe — responde con fuentes sobre todo lo que dice la documentación de Nubelia — pero no puede hacer. La pregunta que dejamos en el aire, "¿cuántas tareas tiene ahora mismo mi proyecto Atlas?", no tiene respuesta en ninguna wiki: el dato vive en la API de Nubelia, cambia cada minuto, y ningún pipeline RAG del mundo lo va a recuperar de una colección de chunks. En esta lección cruzamos esa frontera con el mecanismo llamado function calling (o tool use): le describimos al modelo qué funciones tenemos, el modelo decide cuándo y con qué argumentos conviene llamarlas, y nuestro código las ejecuta y le devuelve el resultado. Es probablemente la idea con peor nombre de todo el ecosistema — el modelo no llama a ninguna función — y a la vez una de las más transformadoras: es la pieza que separa un chatbot de un asistente que opera sobre tu sistema. Aquí construiremos la primera herramienta de DocuBot, consultar_proyecto, y cerraremos por fin la pregunta de Atlas.

1. La idea clave: el modelo decide, tu código ejecuta
2. Definir una herramienta: JSON Schema y descripciones que son prompt engineering
3. El flujo completo con el SDK: tool_use → ejecutar → tool_result → respuesta final
4. La primera herramienta de DocuBot: consultar_proyecto contra la API de Nubelia
5. Cuando la herramienta falla: errores como tool_result con is_error
6. tool_choice: elección automática, forzada y prohibida
7. Function calling como evolución de "pedir JSON" (02-03)

Desmontemos primero el malentendido que da nombre a la técnica. En function calling el LLM no ejecuta absolutamente nada: no tiene acceso a tu red, ni a tu base de datos, ni a la API de Nubelia. Lo único que hace el modelo es lo que siempre ha hecho — generar tokens —, solo que ahora puede generar un tipo especial de salida estructurada que significa "quiero que llames a esta función con estos argumentos". Tu aplicación lee esa petición, decide si la atiende, ejecuta la función con código Python normal y corriente, y le devuelve el resultado al modelo en un segundo turno para que redacte la respuesta final.

Esta división de trabajo tiene consecuencias importantes, todas buenas:

• El control es tuyo. Entre el tool_use y la ejecución hay una línea de código Python que escribes tú. Puedes validar los argumentos, aplicar permisos, registrar la llamada o negarte a ejecutarla. El modelo propone; tu código dispone.
• La seguridad se razona como siempre. La función que ejecutas es código tuyo con las credenciales de tu aplicación — le aplican los mismos principios de toda la vida, empezando por el de mínimo privilegio: una herramienta de consulta debe usar credenciales de solo lectura. consultar_proyecto no puede borrar nada porque el código que la implementa no sabe borrar nada. (Las acciones de escritura y sus salvaguardas llegan en 05-02, y los ataques que explotan herramientas, en 06-01.)
• El modelo aporta lo que ningún if puede: entender que "¿cómo va Atlas?", "dime el estado de mi proyecto Atlas" y "how many open tasks in Atlas?" son la misma intención, y traducirla a una llamada con argumentos correctos.

Para que el modelo pueda pedir una función, primero hay que describírsela. Cada herramienta se define con tres piezas:

La description merece que nos detengamos: es prompt engineering. Todo lo aprendido en el módulo 2 aplica aquí — el modelo decidirá si usa la herramienta, y con qué argumentos, basándose casi exclusivamente en ese texto. Compara:

La segunda versión hace tres cosas que la primera no: delimita el cuándo sí con ejemplos (few-shot en miniatura, 02-02), delimita el cuándo no (evita que el modelo llame a la API para preguntas de documentación), y anuncia qué devuelve (el modelo redactará mejor la respuesta final sabiendo qué esperar).

Veamos el mecanismo con el SDK anthropic que usamos desde 03-01 — el flujo es conceptualmente idéntico en OpenAI, Google o Mistral (cambian los nombres de campo: tools/tool_calls/function, pero el baile es el mismo). Los pasos:

1. Primera llamada: envías la pregunta y la lista de herramientas (parámetro tools).
2. Si el modelo decide usar una, la respuesta llega con stop_reason == "tool_use" y un bloque de contenido de tipo tool_use con name, input (los argumentos, ya como dict) y un id de correlación.
3. Tu código ejecuta la función correspondiente.
4. Segunda llamada: reenvías la conversación completa — incluida la respuesta del asistente con su bloque tool_use — y añades un mensaje de usuario con un bloque tool_result que referencia aquel id.
5. El modelo, ya con el dato en la mano, redacta la respuesta final (stop_reason == "end_turn").

Los puntos 2 y 4 esconden los dos detalles que más errores causan: el bloque tool_use del asistente debe volver en el historial (si no, el modelo no sabe qué pidió), y el tool_result va dentro de un mensaje con rol user — desde el punto de vista de la conversación, el resultado de la herramienta es algo que "le cuentas" al modelo, y debe ser el primer contenido de ese mensaje.

Vamos a construirlo de verdad. Como en este curso no tenemos una API de Nubelia desplegada, la simulamos con un módulo mock — la gracia didáctica es que al modelo le da exactamente igual: él solo ve la definición de la herramienta y los resultados; que detrás haya un dict o un microservicio con base de datos es invisible desde su lado de la frontera.

Ahora la definición de la herramienta y su despachador, en un módulo nuevo que crecerá durante el módulo:

Y el flujo completo. Fíjate en que reutilizamos llamar_con_reintentos (03-02) y MODELO (03-01) sin tocarlos — las herramientas son un parámetro más de la llamada. Lo que sí necesitamos es un sistema nuevo: el SYSTEM_DOCUBOT de 02-01 ordena basarse exclusivamente en el bloque <documentacion>, y esa regla, perfecta para RAG, dejaría a la herramienta sin uso. Añadimos a prompts.py una variante (y subimos PROMPT_VERSION, como manda 02-04):

Una ejecución típica:

La pregunta que en 01-04 nos servía de ejemplo de lo imposible acaba de tener respuesta — y con el dato real del sistema, no con una alucinación plausible. Tres observaciones antes de seguir:

• bloque.input llega como dict ya parseado por el SDK. Aun así, trátalo como entrada no confiable: el modelo puede pasar un nombre de proyecto que no existe o un valor inesperado. Nuestra defensa está en obtener_proyecto (normaliza y valida), no en confiar en el modelo.
• El resultado viaja como texto (por eso el json.dumps): un tool_result es contenido para el modelo, y JSON compacto y con claves descriptivas es un formato que entiende de maravilla. No hace falta prosa.
• Este flujo resuelve un paso de herramienta y termina. Si el modelo necesitara encadenar varias llamadas (consultar la documentación y luego la API), haría falta un bucle — exactamente el tema de 05-02, no lo adelantemos.

Ya viste el try/except en el código anterior; ahora la filosofía. Cuando una herramienta falla, la peor opción es dejar que la excepción reviente el flujo, y la segunda peor es devolver al usuario un traceback. La opción buena es la que implementamos: devolver el error al modelo como tool_result con is_error: True, con un mensaje de error informativo — y dejar que el modelo haga lo que mejor sabe: explicarlo en lenguaje natural.

Pregunta: "¿cómo va mi proyecto Zafiro?". La herramienta lanza ProyectoNoEncontrado con nuestro mensaje ("No existe ningún proyecto llamado 'Zafiro'. Proyectos disponibles: Atlas, Boreal, Cierzo."), y el modelo responde algo como:

Fíjate en la cadena de valor: el mensaje de la excepción también es prompt engineering. Como incluimos la lista de proyectos disponibles en el error, el modelo puede ofrecer alternativas en vez de un "no existe" seco. Escribe los errores de tus herramientas pensando en que su lector es un LLM que va a re-explicarlos: qué falló, por qué, y qué se puede hacer. Y la misma regla de siempre: en el mensaje de error, nada de secretos ni detalles internos (rutas, SQL, stack traces) — irían directos al contexto del modelo y, potencialmente, a la respuesta del usuario.

Por defecto el modelo decide libremente si usa una herramienta o responde directamente. El parámetro tool_choice te da el mando cuando lo necesitas:

El tercer caso es más útil de lo que parece y conecta directamente con la siguiente sección: si fuerzas una herramienta concreta, el modelo siempre genera un bloque tool_use con argumentos que cumplen tu input_schema. Es decir: acabas de conseguir salida estructurada garantizada.

En 02-03 montamos el contrato JSON de DocuBot pidiendo el formato en el prompt y defendiéndonos con limpiar_json y validar_contrato — el modelo a veces envolvía el JSON en prosa o en vallas de código, y había que limpiarlo. Function calling es la versión industrializada de aquella idea:

La última fila es la moraleja: function calling elimina la fontanería sintáctica, pero la validación defensiva de valores no se jubila — que {"nombre": "Zafiro"} sea JSON perfecto no hace que Zafiro exista. El instinto de 02-03 ("no confíes, valida") sigue siendo la ley; solo ha cambiado dónde aplicarlo.

• Olvidar reenviar el turno del asistente. El error más frecuente del flujo: mandar el tool_result sin haber añadido antes {"role": "assistant", "content": respuesta.content} al historial. La API rechazará la petición — el tool_result referencia un tool_use_id que, sin ese mensaje, no existe en la conversación.
• Descripciones de herramienta escuálidas. "Consulta un proyecto" produce llamadas de más (para preguntas de documentación) y de menos (para formulaciones indirectas). Trata la description con el mismo rigor que trataste SYSTEM_DOCUBOT: cuándo sí, cuándo no, ejemplos.
• Creer que el esquema valida por ti. El input_schema garantiza forma, no verdad. Valida los valores en tu función (¿existe el proyecto?, ¿el rango es razonable?) como si los hubiera tecleado un desconocido — porque, en cierto modo, así es.
• No contemplar el camino sin herramienta. Con tool_choice: auto, el modelo puede responder directamente (stop_reason == "end_turn"). Si tu código asume que siempre habrá un bloque tool_use, ese next(...) lanzará StopIteration en la primera pregunta trivial. Comprueba siempre stop_reason primero.
• Varios tool_use en un mismo turno. El modelo puede pedir más de una herramienta a la vez (llamadas paralelas). Nuestro flujo de hoy procesa una porque su única herramienta no da para más; el bucle de 05-02 iterará sobre todos los bloques. Si te ocurre antes, responde con un tool_result por cada tool_use_id.
• Errores de herramienta que no ayudan a nadie. KeyError: 'zafiro' como tool_result obliga al modelo a improvisar. Escribe errores con contexto y alternativas — y sin filtrar información interna.

1. Segunda herramienta: listar_proyectos. Añade a herramientas.py una herramienta sin argumentos que devuelva la lista de proyectos del usuario (nombre y estado), y amplía ejecutar_herramienta. Prueba con "¿qué proyectos tengo ahora mismo?" y con "¿cómo va Atlas?" para comprobar que el modelo elige la herramienta correcta en cada caso.
2. El error como conversación. Con el código de la lección, haz la pregunta "¿cuántas tareas tiene mi proyecto Zafiro?" y observa la respuesta. Después, empobrece a propósito el mensaje de ProyectoNoEncontrado (déjalo en "error") y repite. Compara ambas respuestas finales y escribe en una frase la conclusión.
3. Extracción estructurada con herramienta forzada. Define una herramienta extraer_consulta cuyo input_schema tenga categoria (enum con las 6 categorías de prompt_clasificacion() de 02-02) y proyecto (string opcional). Llámala con tool_choice: {"type": "tool", "name": "extraer_consulta"} sobre la pregunta "no me deja facturar las horas del proyecto Boreal" y examina bloque.input. ¿Qué pieza de 02-03 acabas de sustituir?

1. Definición y despacho:

Con "¿qué proyectos tengo?" el modelo debe elegir listar_proyectos; con "¿cómo va Atlas?", consultar_proyecto. Si se confunde, la palanca es la description (¡no el código!).

2. Con el error rico, el modelo responde con alternativas concretas ("tus proyectos son Atlas, Boreal y Cierzo, ¿te referías a alguno?"). Con "error" a secas, el modelo solo puede decir que algo falló, o peor, especular sobre el motivo. Conclusión en una frase: la calidad de la respuesta final ante un fallo está limitada por la calidad del mensaje de error que devuelve tu herramienta — los errores de las herramientas son parte del prompt.

3. Esquema y llamada:

Acabas de sustituir el tándem "pedir JSON en el prompt + limpiar_json": con la herramienta forzada no hay prosa que limpiar ni vallas de código que quitar. validar_contrato (la validación semántica) seguiría teniendo trabajo — el enum garantiza que categoria es una de las seis, pero nadie garantiza que sea la correcta.

DocuBot acaba de hacer algo que ningún RAG podía: responder con un dato que no estaba escrito en ningún sitio cuando arrancó la conversación. El mecanismo, una vez desmontado el nombre, es honesto y simple — el modelo decide qué función llamar y con qué argumentos, tu código ejecuta y le devuelve el resultado, el modelo redacta —, y sus piezas son viejas conocidas con ropa nueva: la description es prompt engineering (módulo 2), el input_schema es el contrato JSON de 02-03 con garantías sintácticas de fábrica, los errores como tool_result con is_error son la degradación elegante de 03-02 contada al modelo, y tool_choice forzado nos regala de paso la extracción estructurada más robusta que conocemos. Pero nuestra responder_con_herramienta() tiene una limitación estructural que quizá ya te haya hecho ruido: ejecuta un paso de herramienta y termina. Si el usuario pregunta "¿mi proyecto Atlas supera el límite de tareas de mi plan?", hacen falta dos consultas — la documentación para el límite del plan, la API para las tareas de Atlas — y una comparación entre ambas. Eso ya no es un flujo de dos llamadas: es un bucle en el que el modelo razona, actúa, observa el resultado y decide si necesita seguir. Ese bucle tiene nombre — agente — y es exactamente lo que construimos en la siguiente lección, donde además el RAG del módulo 4 sufrirá una transformación elegante: de pipeline a herramienta.