Cómo crear una tool para consultar una API externa

Conectar un agente de IA a una API externa mediante una tool en Python es el paso que transforma un asistente básico en uno productivo. Si tienes un agente con datos quemados en el prompt y quieres que consuma información real, aquí verás cómo construir esa función y enlazarla al agente para consultar un catálogo dinámico.

El problema de partida es claro: nuestro primer agente ya estaba desplegado, pero tenía su listado de productos escrito directamente en el prompt. Eso funciona para demostrar, pero no sirve en un ambiente productivo donde la información vive en un API y cambia constantemente.

Por qué una tool reemplaza los datos quemados en el prompt

Cuando quemas un catálogo dentro del prompt, cada cambio de inventario te obliga a editar el texto del agente. Poco escalable. La solución es una tool: una función de Python que el agente llama cuando la necesita.

En el flujo que construimos, el agente de productos recibe la intención del usuario y solicita una función llamada obtener recomendaciones [00:38]. Esa función consulta un API público que devuelve el catálogo en formato JSON, y aquí viene lo interesante: ese paso no tiene nada que ver con inteligencia artificial. Es Python común y corriente que hace request, parsea y filtra.

¿Qué es una tool en un agente de IA? Es una función de Python que el agente puede ejecutar para extender sus capacidades, como consultar una API o una base de datos. El agente decide cuándo llamarla según la intención del usuario.

Una vez la tool obtiene el listado, lo filtra y lo devuelve en JSON al agente. El agente decide qué hacer con esa información: presentarla como tabla, texto plano, HTML o describir cada producto según lo que definas en el prompting.

Cómo se construye la función obtener recomendaciones

Dentro de la carpeta de tools creamos un fichero nuevo llamado recomendaciones e importamos request [02:00]. Luego definimos una URL con el listado de productos, que si la abres en el navegador es simplemente un API get con un JSON de productos [02:14]. Esta URL perfectamente podría ser un API construido por ti.

La función obtener recomendaciones recibe tres elementos y devuelve una lista [02:36]:

• Una categoría, que es el tipo de producto que busca el usuario.
• Un presupuesto, para filtrar por rango de precio.
• Una respuesta en forma de lista de productos recomendados.

Aquí entra un concepto clave que diferencia una función normal de una función para agentes: es obligatorio describir qué hace la función, cuáles son sus argumentos y cuál es su tipo de respuesta [02:44]. ¿Por qué? Porque el agente lee ese texto para determinar en qué momento usarla o no.

¿Por qué debo describir los argumentos de una tool? Porque el LLM usa esa descripción textual para decidir cuándo llamar la función y qué datos enviarle. Sin una buena descripción, el agente no sabe cuándo ni cómo invocarla.

La lógica interna es sencilla: hacemos un request a la URL con un timeout de 10 segundos [03:34], convertimos la respuesta a JSON, generamos un array llamado recomendaciones y recorremos el catálogo aplicando dos filtros: uno por presupuesto y otro por categoría [04:00]. Según esos filtros, devolvemos la lista de productos.

Todo el código fuente está en el repositorio del área de recursos, junto con un archivo en texto plano por si prefieres copiar y pegar el bloque directamente.

Qué hace que las funciones sean herramientas extendidas

Los LLMs en los que se basan los agentes están diseñados para procesar la intención en texto. Pero lo que buscamos de un agente no es solo que responda: queremos capacidades extendidas como consultar una base de datos, llamar un API externa o hacer procesamientos complejos [05:00].

Ahí es donde las funciones se convierten en herramientas extendidas del agente. La tool recibe la solicitud del LLM, filtra los productos y los devuelve en JSON. El formato de retorno no es tan importante, porque al agente le puedes indicar que lea el JSON y lo transforme al formato que necesites.

Cómo configurar el agente para que use la tool

Con la tool lista, hay que identificar qué agente la necesita. En este caso es el agente de recomendaciones, que antes tenía el catálogo quemado [05:36].

El proceso para enlazarla es directo:

1. Agregar al final un array de tools con obtener recomendaciones [05:53].
2. Verificar el import, que Antigravity hizo automático, pero conviene siempre revisar [06:00].
3. Eliminar el catálogo quemado y escribir en el prompt: para recomendar productos al usuario, utiliza la función de obtener recomendaciones [06:20].

Fíjate que no describimos los componentes ni las variables que recibe la función dentro del prompt. Eso funciona gracias a la descripción que ya hicimos en la propia función, con la que el LLM sabe internamente qué objetos necesita para llamarla y en qué momento hacerlo.

Cómo se ve el agente consultando la API en vivo

Al correr el agente y abrirlo en el navegador, la prueba es reveladora. Escribimos hola, quiero comprar una camisa y lo primero que ocurre es una transferencia al agente de recomendaciones [07:00].

Como el agente sabe que necesita presupuesto y categoría, los solicita. Le decimos que queremos una camisa casual con 1.000 dólares [07:20]. En ese momento el agente reconoce que tiene una tool disponible y hace el llamado. Puede hacer cuantos llamados desee, y cuando la respuesta le conviene, nos responde.

El resultado: nos recomienda dos productos, una classic white y una classic black [07:53]. La diferencia importante es que estos datos ya no vienen del agente, sino de la API externa consultada en tiempo real.

Con esto tienes un pool de agentes mucho más robusto. ¿Ya imaginas cómo conectar tu propio API de negocio a un agente? Cuéntame en los comentarios qué fuente de datos te gustaría integrar primero.