Guía para comprender, construir y optimizar agentes que llaman a API

El papel de la Inteligencia Artificial en las empresas tecnológicas está evolucionando rápidamente; los casos de uso de la IA han pasado de procesar información de manera pasiva a ser agentes capaces de ejecutar tareas. Según una encuesta de marzo de 2025 sobre la adopción de IA a nivel global realizada por Georgian y NewtonX, el 91% de los ejecutivos técnicos en empresas de crecimiento y empresas están utilizando o planean utilizar IA agente.

Los agentes que llaman a API son un ejemplo principal de este cambio hacia los agentes. Los agentes que llaman a API utilizan Modelos de Lenguaje Grande (LLM) para interactuar con sistemas de software a través de sus Interfaces de Programación de Aplicaciones (API).

Por ejemplo, al traducir comandos de lenguaje natural en llamadas a API precisas, los agentes pueden recuperar datos en tiempo real, automatizar tareas rutinarias o incluso controlar otros sistemas de software. Esta capacidad transforma a los agentes de IA en intermediarios útiles entre la intención humana y la funcionalidad del software.

Las empresas están utilizando actualmente agentes que llaman a API en varios dominios, incluyendo:

• Aplicaciones de consumo: Asistentes como Siri de Apple o Alexa de Amazon han sido diseñados para simplificar tareas diarias, como controlar dispositivos de hogar inteligentes y hacer reservas.
• Flujos de trabajo empresariales: Las empresas han desplegado agentes de API para automatizar tareas repetitivas como recuperar datos de CRM, generar informes o consolidar información de sistemas internos.
• Recuperación y análisis de datos: Las empresas están utilizando agentes de API para simplificar el acceso a conjuntos de datos propietarios, recursos basados en suscripción y API públicos para generar información.

En este artículo, utilizaré un enfoque centrado en la ingeniería para comprender, construir y optimizar agentes que llaman a API. El material de este artículo se basa en parte en la investigación y el desarrollo prácticos realizados por el Laboratorio de IA de Georgian. La pregunta motivadora para gran parte de la investigación del Laboratorio de IA en el área de agentes que llaman a API ha sido: “Si una organización tiene una API, ¿cuál es la forma más efectiva de construir un agente que pueda interactuar con esa API utilizando lenguaje natural?”

Explicaré cómo funcionan los agentes que llaman a API y cómo arquitectar y ingenierizar estos agentes para el rendimiento. Finalmente, proporcionaré un flujo de trabajo sistemático que los equipos de ingeniería pueden utilizar para implementar agentes que llaman a API.

I. Definiciones clave:

• API o Interfaz de Programación de Aplicaciones: Un conjunto de reglas y protocolos que permiten a diferentes aplicaciones de software comunicarse y intercambiar información.
• Agente: Un sistema de IA diseñado para percibir su entorno, tomar decisiones y realizar acciones para lograr objetivos específicos.
• Agente que llama a API: Un agente de IA especializado que traduce instrucciones de lenguaje natural en llamadas a API precisas.
• Agente que genera código: Un sistema de IA que asiste en el desarrollo de software escribiendo, modificando y depurando código. Si bien está relacionado, mi enfoque aquí es principalmente en agentes que llaman a API, aunque la IA también puede ayudar a construir estos agentes.
• MCP (Protocolo de Contexto de Modelo): Un protocolo, notablemente desarrollado por Anthropic, que define cómo los LLM pueden conectarse a fuentes de datos y herramientas externas.

II. Tarea principal: Traducir lenguaje natural en acciones de API

La función fundamental de un agente que llama a API es interpretar una solicitud de lenguaje natural del usuario y convertirla en una o más llamadas a API precisas. Este proceso generalmente implica:

1. Reconocimiento de intención: Comprender el objetivo del usuario, incluso si se expresa de manera ambigua.
2. Selección de herramienta: Identificar el punto final de API adecuado (o “herramienta”) de un conjunto de opciones disponibles que puede cumplir con la intención.
3. Extracción de parámetros: Identificar y extraer los parámetros necesarios para la llamada a API seleccionada del consulta del usuario.
4. Ejecución y generación de respuesta: Realizar la llamada a API, recibir la respuesta y luego sintetizar esta información en una respuesta coherente o realizar una acción posterior.

Considera una solicitud como “Hey Siri, ¿cómo está el clima hoy?”. El agente debe identificar la necesidad de llamar a una API de clima, determinar la ubicación actual del usuario (o permitir la especificación de una ubicación) y luego formular la llamada a API para recuperar la información del clima.

Para la solicitud “Hey Siri, ¿cómo está el clima hoy?”, una llamada a API de ejemplo podría verse así:

GET /v1/weather?location=Nueva%20York&units=metric

Los desafíos iniciales de alto nivel son inherentes a este proceso de traducción, incluyendo la ambigüedad del lenguaje natural y la necesidad de que el agente mantenga el contexto a lo largo de interacciones de múltiples pasos.

Por ejemplo, el agente a menudo debe “recordar” partes anteriores de una conversación o resultados de llamadas a API anteriores para informar acciones actuales. La pérdida de contexto es un modo de falla común si no se gestiona explícitamente.

III. Arquitectura de la solución: Componentes y protocolos clave

Construir agentes que llaman a API efectivos requiere un enfoque arquitectónico estructurado.

1. Definir “herramientas” para el agente

Para que un LLM utilice una API, las capacidades de esa API deben describirse de una manera que el LLM pueda entender. Cada punto final de API o función a menudo se representa como una “herramienta”. Una definición de herramienta robusta incluye:

• Una descripción clara y en lenguaje natural del propósito y la funcionalidad de la herramienta.
• Una especificación precisa de sus parámetros de entrada (nombre, tipo, si es requerido u opcional y una descripción).
• Una descripción de la salida o datos que la herramienta devuelve.

2. El papel del Protocolo de Contexto de Modelo (MCP)

MCP es un habilitador crítico para un uso de herramientas más estandarizado y robusto por parte de los LLM. Proporciona un formato estructurado para definir cómo los modelos pueden conectarse a fuentes de datos y herramientas externas.

La estandarización de MCP es beneficiosa porque permite una integración más fácil de herramientas diversas, promueve la reutilización de definiciones de herramientas en diferentes agentes o modelos. Además, es una buena práctica para los equipos de ingeniería, comenzando con especificaciones de API bien definidas, como una especificación OpenAPI. Herramientas como Stainless.ai están diseñadas para ayudar a convertir estas especificaciones OpenAPI en configuraciones MCP, simplificando el proceso de hacer que las API estén “listas para el agente”.

3. Marcos de agente y elecciones de implementación

Varios marcos pueden ayudar a construir el agente en sí. Estos incluyen:

• Pydantic: Si bien no es exclusivamente un marco de agente, Pydantic es útil para definir estructuras de datos y garantizar la seguridad de tipos para las entradas y salidas de herramientas, lo cual es importante para la confiabilidad. Muchas implementaciones de agentes personalizados utilizan Pydantic para esta integridad estructural.
• mcp_agent de LastMile: Este marco está diseñado específicamente para trabajar con MCP, ofreciendo una estructura más opinada que se alinea con las prácticas para construir agentes efectivos como se describe en investigaciones de lugares como Anthropic.
• Marco interno: También es cada vez más común utilizar agentes de IA que generan código (utilizando herramientas como Cursor o Cline) para ayudar a escribir el código de plantilla para el agente, sus herramientas y la lógica circundante. La experiencia del Laboratorio de IA de Georgian trabajando con empresas en implementaciones de agentes muestra que esto puede ser excelente para crear marcos personalizados muy mínimos.

IV. Ingeniería para la confiabilidad y el rendimiento

Garantizar que un agente realice llamadas a API de manera confiable y tenga un buen rendimiento requiere un esfuerzo de ingeniería enfocado. Dos formas de hacerlo son (1) creación y validación de conjunto de datos y (2) ingeniería y optimización de prompts.

1. Creación y validación de conjunto de datos

Entrenar (si corresponde), probar y optimizar un agente requiere un conjunto de datos de alta calidad. Este conjunto de datos debe consistir en consultas de lenguaje natural representativas y sus secuencias de llamadas a API deseadas o resultados.

• Creación manual: Curar manualmente un conjunto de datos garantiza precisión y relevancia, pero puede ser laborioso.
• Generación sintética: Generar datos de forma programática o utilizando LLM puede escalar la creación de conjuntos de datos, pero este enfoque presenta desafíos significativos. La investigación del Laboratorio de IA de Georgian encontró que garantizar la corrección y la complejidad realista de las llamadas a API y las consultas generadas sintéticamente es muy difícil. A menudo, las preguntas generadas eran demasiado triviales o imposiblemente complejas, lo que hace que sea difícil medir el rendimiento matizado del agente. La validación cuidadosa de los datos sintéticos es absolutamente crítica.

Para una evaluación crítica, un conjunto de datos más pequeño, de alta calidad y verificado manualmente a menudo proporciona información más confiable que un conjunto de datos sintético grande y ruidoso.

2. Ingeniería y optimización de prompts

El rendimiento de un agente basado en LLM se ve influenciado en gran medida por los prompts utilizados para guiar su razonamiento y selección de herramientas.

• Un prompt efectivo implica definir claramente la tarea del agente, proporcionar descripciones de herramientas disponibles y estructurar el prompt para fomentar la extracción precisa de parámetros.
• La optimización sistemática utilizando marcos como DSPy puede mejorar significativamente el rendimiento. DSPy permite definir los componentes del agente (por ejemplo, módulos para la generación de pensamiento, selección de herramientas, formato de parámetros) y luego utiliza un enfoque similar a un compilador con ejemplos de disparo de su conjunto de datos para encontrar prompts o configuraciones optimizados para estos componentes.

V. Un camino recomendado hacia agentes de API efectivos

Desarrollar agentes de IA que llaman a API robustos es una disciplina de ingeniería iterativa. Basado en los hallazgos de la investigación del Laboratorio de IA de Georgian, los resultados pueden mejorarse significativamente utilizando un flujo de trabajo sistemático como el siguiente:

1. Comenzar con definiciones de API claras: Comience con especificaciones de API bien estructuradas para las API con las que interactuará el agente.
2. Establecer acceso a herramientas estandarizado: Convierta sus especificaciones de API en MCP. Herramientas como Stainless.ai pueden facilitar esto, creando una forma estandarizada para que su agente comprenda y utilice sus API.
3. Implementar el agente: Elija un marco o enfoque adecuado. Esto podría implicar el uso de Pydantic para el modelado de datos dentro de una estructura de agente personalizada o el uso de un marco como mcp_agent de LastMile que se basa en MCP.
   • Antes de hacer esto, considere conectar el MCP a una herramienta como Claude Desktop o Cline, y utilice manualmente esta interfaz para sentir cómo un agente genérico puede usarlo, cuántas iteraciones suele tomar usar el MCP correctamente y cualquier otro detalle que pueda ahorrar tiempo durante la implementación.
4. Curar un conjunto de datos de evaluación de calidad: Cree manualmente o valide cuidadosamente un conjunto de datos de consultas y interacciones de API deseadas. Esto es crucial para pruebas y optimización confiables.
5. Optimizar prompts y lógica del agente: Utilice marcos como DSPy para perfeccionar los prompts y la lógica interna del agente, utilizando su conjunto de datos para impulsar mejoras en la precisión y la confiabilidad.

VI. Un ejemplo ilustrativo del flujo de trabajo

Aquí hay un ejemplo simplificado que ilustra el flujo de trabajo recomendado para construir un agente que llama a API:

Paso 1: Comenzar con definiciones de API claras

Imagina una API para gestionar una lista de tareas simple, definida en OpenAPI:

openapi: 3.0.0

info:

título: API de lista de tareas

versión: 1.0.0

rutas:

/tareas:

publicar:

resumen: Agregar una nueva tarea

cuerpo de la solicitud:

requerido: true

contenido:

aplicación/json:

esquema:

tipo: objeto

propiedades:

descripción:

tipo: cadena

respuestas:

‘201’:

descripción: Tarea creada con éxito

obtener:

resumen: Obtener todas las tareas

respuestas:

‘200’:

descripción: Lista de tareas

Paso 2: Establecer acceso a herramientas estandarizado

Convierta la especificación de OpenAPI en configuraciones de Protocolo de Contexto de Modelo (MCP). Utilizando una herramienta como Stainless.ai, esto podría producir:

Paso 3: Implementar el agente

Utilizando Pydantic para el modelado de datos, cree funciones que correspondan a las herramientas de MCP. Luego, utilice un LLM para interpretar consultas de lenguaje natural y seleccionar la herramienta y parámetros adecuados.

Paso 4: Curar un conjunto de datos de evaluación de calidad

Cree un conjunto de datos:

Paso 5: Optimizar prompts y lógica del agente

Utilice DSPy para perfeccionar los prompts, centrándose en instrucciones claras, selección de herramientas y extracción de parámetros utilizando el conjunto de datos curado para la evaluación y la mejora.

Al integrar estos bloques de construcción, desde definiciones de API estructuradas y protocolos de herramientas estandarizados hasta prácticas de datos rigurosas y optimización sistemática, los equipos de ingeniería pueden construir agentes de IA que llaman a API más capaces, confiables y mantenibles.