Guía de comprensión, construcción y optimización de agentes de llamas API

El papel de la inteligencia synthetic en las empresas de tecnología está evolucionando rápidamente; Los casos de uso de IA han evolucionado del procesamiento de información pasiva a agentes proactivos capaces de ejecutar tareas. Según una encuesta de marzo de 2025 sobre la adopción international de IA realizada por Georgian y NewtonxSegún los informes, el 91% de los ejecutivos técnicos en la etapa de crecimiento y las empresas empresas están utilizando o planean usar AI de Agentic.

Los agentes de llamadas API son un ejemplo principal de este cambio a los agentes. Los agentes de llamado API aprovechan los modelos de lenguaje grandes (LLM) para interactuar con los sistemas de software program a través de sus interfaces de programación de aplicaciones (API).

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

Actualmente, las empresas están utilizando agentes de llamado API en varios dominios, incluidos:

• Aplicaciones de consumo: Asistentes como Alexa de Apple’s Siri o Amazon han sido diseñados para simplificar las tareas diarias, como controlar los dispositivos Good House y hacer reservas.
• Flujos de trabajo empresariales: las empresas han implementado agentes 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 API para simplificar el acceso a conjuntos de datos patentados, recursos basados ​​en suscripción y API públicas para generar información.

En este artículo utilizaré un enfoque centrado en la ingeniería para la comprensión, la construcción y la optimización de los agentes de llamado API. El materials en 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 los agentes de llamas 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 pure?”

Explicaré cómo funcionan los agentes de llamadas API y cómo arquitectando e diseñando con éxito a estos agentes para su rendimiento. Finalmente, proporcionaré un flujo de trabajo sistemático que los equipos de ingeniería pueden usar para implementar agentes de llamado API.

I. Definiciones clave:

• API o interfaz de programación de aplicaciones: Un conjunto de reglas y protocolos que permiten diferentes aplicaciones de software program para comunicar e intercambiar información.
• Agente: Un sistema de IA diseñado para percibir su entorno, tomar decisiones y tomar medidas para lograr objetivos específicos.
• Agente API-llame: Un agente de IA especializado que traduce instrucciones de lenguaje pure en llamadas de API precisas.
• Agente generador de código: Un sistema de IA que ayuda al desarrollo de software program mediante el código de escritura, modificación y depuración. Mientras está relacionado, mi enfoque aquí es principalmente en agentes que llamar API, aunque la IA también puede ayudar construir estos agentes.
• MCP (Protocolo de contexto del modelo): Un protocolo, especialmente desarrollado por antrópicoDefinición de cómo los LLM pueden conectarse y utilizar herramientas externas y fuentes de datos.

II. Tarea central: traducir el lenguaje pure en acciones API

La función elementary de un agente de llamado API es interpretar la solicitud de lenguaje pure de un usuario y convertirla en una o más llamadas API precisas. Este proceso generalmente implica:

1. Reconocimiento de la intención: Comprender el objetivo del usuario, incluso si se expresa de manera ambigua.
2. Selección de herramientas: Identificación de los puntos finales de API apropiados, o “herramientas”, de un conjunto de opciones disponibles que pueden cumplir con la intención.
3. Extracción de parámetros: Identificar y extraer los parámetros necesarios para las llamadas API seleccionadas de la consulta del usuario.
4. Generación de ejecución y respuesta: Hacer las llamadas API, recibir la (s) respuesta (s) y luego sintetizar esta información en una respuesta coherente o realizar una acción posterior.

Considere una solicitud como: “Hola Siri, ¿cómo es el clima hoy?” El agente debe identificar la necesidad de llamar a una API meteorológica, determinar la ubicación precise del usuario (o permitir la especificación de una ubicación) y luego formular la llamada API para recuperar la información meteorológica.

Para la solicitud “Hola Siri, ¿cómo es el clima hoy?”, Una llamada de API de muestra podría parecer:

Get /v1 /climate? Ubicación = nuevopercent20york & unidades = métrica

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

Por ejemplo, el agente a menudo debe “recordar” partes anteriores de una conversación o resultados anteriores de llamadas de API para informar las 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

La construcción de agentes efectivos de llamadas API requiere un enfoque arquitectónico estructurado.

1. Definición de “herramientas” para el agente

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

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

2. El papel del protocolo de contexto del modelo (MCP)

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

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

3. Agentes marcos y opciones de implementación

Varios marcos pueden ayudar a construir el agente mismo. 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 tipo para las entradas y salidas de herramientas, lo cual es importante para la confiabilidad. Muchas implementaciones de agentes personalizados aprovechan Pydantic para esta integridad estructural.
• MCP_AGENT de Lastmile: Este marco está diseñado específicamente para funcionar con MCPS, ofreciendo una estructura más obstinada que se alinea con las prácticas para construir agentes efectivos como se describe en investigaciones de lugares como Anthrope.
• Marco interno: También es cada vez más común usar agentes generadores de código AI (usando herramientas como Cursor o Cline) para ayudar a escribir el código de Boilerplate para el agente, sus herramientas y la lógica circundante. La experiencia de laboratorio de inteligencia synthetic de Georgian trabajando con empresas en implementaciones de agente muestra que esto puede ser excelente para crear marcos mínimos y personalizados.

IV. Ingeniería para la fiabilidad y el rendimiento

Asegurar que un agente realice llamadas API de manera confiable y se desempeña bien requiere un esfuerzo de ingeniería enfocado. Dos formas de hacer esto son (1) creación y validación del conjunto de datos y (2) ingeniería y optimización rápida.

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

La capacitación (si corresponde), las pruebas y la optimización de un agente requiere un conjunto de datos de alta calidad. Este conjunto de datos debe consistir en consultas de lenguaje pure representativo y sus correspondientes secuencias o resultados de llamadas API deseadas.

• Creación handbook: Currar manualmente un conjunto de datos asegura una alta precisión y relevancia, pero puede ser intensiva en el trabajo.
• Generación sintética: Generar datos programáticamente o usar LLM puede escalar la creación del conjunto de datos, pero este enfoque presenta desafíos significativos. La investigación del laboratorio de IA de Georgia encontró que garantizar la corrección y la complejidad realista de las llamadas y consultas API generadas sintéticamente es muy difícil. A menudo, las preguntas generadas eran demasiado triviales o imposiblemente complejas, lo que dificulta medir el rendimiento de los agentes matizados. 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 y verificado manualmente a menudo proporciona concepts más confiables que una sintética grande y ruidosa.

2. Ingeniería y optimización rápida

El rendimiento de un agente basado en LLM está fuertemente influenciado por las indicaciones utilizadas para guiar su razonamiento y selección de herramientas.

• La solicitud efectiva implica definir claramente la tarea del agente, proporcionar descripciones de las herramientas disponibles y estructurar el indicador para fomentar la extracción precisa de los parámetros.
• Optimización sistemática utilizando marcos como Dspy puede mejorar significativamente el rendimiento. DSPY le permite definir los componentes de su agente (por ejemplo, módulos para la generación de pensamientos, selección de herramientas, formato de parámetros) y luego utiliza un enfoque comparable al compilador con ejemplos de pocos disparos de su conjunto de datos para encontrar indicaciones o configuraciones optimizadas para estos componentes.

V. Una ruta recomendada a agentes de API efectivos

El desarrollo de agentes de IA de llamadas de API robustas 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. Comience con definiciones de API claras: Comience con bien estructurado Especificaciones de OpenAPI Para las API que interactuará su agente.
2. Estandarizar el acceso a la herramienta: Convierta sus especificaciones de OpenApi en MCP Herramientas como Inoxidable.ai puede facilitar esto, creando una forma estandarizada para que su agente comprenda y use sus API.
3. Implementar el agente: Elija un marco o enfoque apropiado. Esto podría implicar usar Pydantico Para el modelado de datos dentro de una estructura de agente personalizado o aprovechar un marco como MCP_AGENT de Lastmile que se construye alrededor de MCP.
   • Antes de hacer esto, considere conectar el MCP a una herramienta como Claude Desktop o Cline, y use manualmente esta interfaz para tener una concept de qué tan bien puede usarlo un agente genérico, cuántas iteraciones generalmente se necesita para usar el MCP correctamente y cualquier otro detalle que pueda ahorrarle tiempo durante la implementación.
4. Curado un conjunto de datos de evaluación de calidad: Crear o validar meticulosamente un conjunto de datos de consultas e interacciones API esperadas. Esto es crítico para pruebas y optimización confiables.
5. Optimizar las indicaciones y la lógica del agente: Emplear marcos como Dspy Para refinar las indicaciones y la lógica interna de su agente, utilizando su conjunto de datos para impulsar mejoras en precisión y 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 de llamado API:

Paso 1: Comience con definiciones de API claras

Think about una API para administrar una lista de tareas pendientes, definida en OpenAPI:

Openapi: 3.0.0

Información:

Título: API de la lista de tareas pendientes

Versión: 1.0.0

Caminos:

/tareas:

correo:

Resumen: Agregue una nueva tarea

requestbody:

Requerido: Verdadero

contenido:

Aplicación/JSON:

esquema:

Tipo: Objeto

propiedades:

descripción:

Tipo: cadena

respuestas:

‘201’:

Descripción: Tarea creada con éxito

conseguir:

Resumen: Obtenga todas las tareas

respuestas:

‘200’:

Descripción: Lista de tareas

Paso 2: Estandarizar el acceso a la herramienta

Convierta la especificación de OpenAPI en configuraciones del protocolo de contexto del modelo (MCP). Usando una herramienta como Stainless.Ai, esto podría producir:

Paso 3: implementa el agente

Usando Pydantic para el modelado de datos, cree funciones correspondientes a las herramientas MCP. Luego, use un LLM para interpretar consultas de lenguaje pure y seleccione la herramienta y los parámetros apropiados.

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

Crear un conjunto de datos:

Paso 5: optimizar las indicaciones y la lógica del agente

Use DSPY para refinar las indicaciones, 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 rigurosas prácticas de datos y optimización sistemática, los equipos de ingeniería pueden construir agentes de IA API más capaces, confiables y mantenibles.