¿Cómo se puede usar OpenAPI para definir interfaces de plugins de IA y de tool calling? #

El auge de los modelos de lenguaje de gran tamaño (LLM) y de los agents de IA ha creado un caso de uso nuevo e inesperado para la OpenAPI Specification: definir las interfaces mediante las cuales los sistemas de IA invocan herramientas y servicios externos. Lo que comenzó como un estándar para describir API web se ha convertido en un componente fundamental del ecosistema de plugins de IA y de function calling, que conecta a los agents inteligentes con capacidades del mundo real como búsqueda, bases de datos, sistemas de pago y mucho más.

El paradigma de los plugins de IA y del tool calling #

Los frameworks y plataformas de IA modernos permiten que los LLM invoquen funciones externas, un patrón que recibe distintos nombres: “function calling”, “tool use” o “ejecución de plugins”. En lugar de responder únicamente a partir del conocimiento con el que fue entrenado, un agent de IA puede reconocer cuándo la solicitud de un usuario requiere una acción externa, construir una llamada estructurada a una herramienta, recibir una respuesta e incorporar esos datos en su contestación.

El desafío clave es describir esas herramientas de una manera que:

1. El modelo de IA pueda entender: qué hace la herramienta, qué entradas espera y qué devuelve.
2. La plataforma anfitriona pueda enrutar: haciendo coincidir las invocaciones de herramientas con el endpoint de servicio correcto.
3. Los desarrolladores puedan mantener: en un formato que ya conocen y que se integra con la infraestructura de API existente.

OpenAPI satisface los tres requisitos, y por eso plataformas como OpenAI, Microsoft Copilot Studio y LangChain lo han adoptado como el formato estándar para describir herramientas.

Plugins de OpenAI y ChatGPT Actions #

El sistema de plugins de OpenAI, presentado en 2023 y evolucionado más tarde hacia la función Custom Actions de los GPTs, se basa directamente en documentos OpenAPI 3.x. Al configurar un GPT con una acción personalizada, los desarrolladores proporcionan la URL de un documento OpenAPI que describe la API que el GPT tiene permitido invocar.

El modelo lee el documento OpenAPI y utiliza campos como:

• info.description: para entender qué hace la API en su conjunto.
• paths[path][method].summary y .description: para entender qué hace cada operación y cuándo invocarla.
• parameters y requestBody: para entender qué entradas proporcionar.
• responses: para entender qué datos esperar a cambio.

La calidad de estas descripciones en lenguaje natural afecta directamente a lo bien que el modelo de IA sabe cuándo y cómo usar cada operación. Por lo tanto, escribir documentos OpenAPI orientados a la IA exige descripciones especialmente claras y centradas en la intención del usuario, y no solo precisión técnica.

Escribir descripciones de OpenAPI aptas para la IA #

Los documentos OpenAPI estándar escritos para desarrolladores humanos suelen contener descripciones escuetas o centradas en lo técnico. Para el consumo por parte de una IA, las descripciones deben responder a la pregunta “¿cuándo debo llamar a esto?” y no solo a “¿qué hace esto?”.

Menos eficaz (para IA):

summary: List orders
description: Returns a list of order objects.

Más eficaz (para IA):

summary: List orders
description: >
  Use this operation when the user asks about their recent purchases,
  order history, or wants to track a specific order. Returns paginated
  order data including status, items, and shipping information.

Del mismo modo, las descripciones de los parámetros deben explicar los valores esperados en términos que coincidan con las solicitudes del usuario en lenguaje natural, y no solo con los tipos de datos.

Diseño de esquemas para las salidas de las herramientas #

Cuando un agent de IA invoca una herramienta, necesita procesar la respuesta e incorporarla en una contestación coherente. Por lo tanto, los esquemas de los cuerpos de respuesta deben ser:

• Bien tipados: usar tipos explícitos en lugar de additionalProperties: true en todas partes, para que el modelo sepa qué campos esperar.
• Anotados de forma descriptiva: cada campo importante debe incluir una description que explique su significado en términos de negocio.
• Mínimos cuando sea posible: devolver solo los datos que el modelo necesita reduce el consumo de tokens y mejora la calidad de la respuesta.

LangChain y los toolkits de OpenAPI #

LangChain es un framework de código abierto muy popular para construir aplicaciones impulsadas por LLM. Incluye un OpenAPI Toolkit que puede ingerir un documento OpenAPI y crear automáticamente herramientas invocables para cada operación. Un agent puede entonces decidir en tiempo de ejecución qué operación invocar según la solicitud del usuario.

Esto significa que cualquier API REST existente con un documento OpenAPI 3.x bien escrito puede conectarse a un agent de LLM con una configuración mínima, lo que reduce drásticamente la barrera de entrada a la integración de IA para los proveedores de API.

Microsoft Copilot Studio y los conectores de OpenAPI #

Microsoft Copilot Studio (antes Power Virtual Agents) permite crear copilots de IA conversacional que pueden invocar API externas mediante conectores definidos con documentos OpenAPI. Estos conectores se utilizan en todo el ecosistema de Power Platform, incluidos Power Automate y Power Apps.

Los conectores personalizados de Microsoft se basan en OpenAPI 2.0 (Swagger), con extensiones como x-ms-summary y x-ms-dynamic-values que enriquecen los metadatos del conector que puede leer la IA.

La extensión x-openai-isConsequential #

OpenAI introdujo una extensión propietaria para los documentos de plugins: x-openai-isConsequential. Cuando se establece en true en una operación, indica que la acción tiene consecuencias en el mundo real (por ejemplo, enviar un correo electrónico o realizar una compra) y que la IA debe pedir confirmación al usuario antes de continuar.

paths:
  /orders:
    post:
      summary: Place a new order
      x-openai-isConsequential: true
      ...

Este es un ejemplo de cómo el mecanismo de extensiones de OpenAPI (campos con prefijo x-) permite a las plataformas de IA añadir semántica adicional sin romper la compatibilidad con el estándar OpenAPI.

Consideraciones de seguridad para las API expuestas a la IA #

Exponer una API a un agent de IA introduce consideraciones de seguridad particulares:

• Autenticación: deben usarse los securitySchemes de OpenAPI para exigir claves de API o tokens OAuth. Plataformas de IA como OpenAI admiten los esquemas de seguridad apiKey, http (Bearer) y oauth2.
• Limitación del alcance: el documento OpenAPI que se presenta a una IA debe describir únicamente los endpoints que el agent está autorizado a usar. La Overlay Specification puede ayudar a generar vistas acotadas de una API más amplia.
• Validación de entradas: las entradas generadas por una IA pueden ser inesperadas o estar mal formadas. La validación en el backend no debe basarse únicamente en el cumplimiento de los esquemas declarados en OpenAPI.
• Limitación de velocidad y prevención de abusos: los agents de IA pueden invocar herramientas con alta frecuencia. La limitación de velocidad de la API y la monitorización son esenciales.

Estándares emergentes: function calling más allá de OpenAPI #

Aunque OpenAPI está ampliamente adoptado para las interfaces de herramientas de IA, están surgiendo otros formatos:

• Formato de tool use de Anthropic: Claude usa un formato de definición de herramientas basado en JSON, inspirado vagamente en JSON Schema, y no en OpenAPI completo.
• Function calling de Gemini de Google: también usa definiciones basadas en JSON Schema.
• Model Context Protocol (MCP): el estándar abierto de Anthropic para conectar modelos de IA con fuentes de contexto y herramientas, que puede complementar o ampliar OpenAPI en sistemas con agents.

OpenAPI sigue siendo el formato más completo y con mayor soporte de herramientas para describir API HTTP, y su adopción por plataformas importantes como OpenAI y Microsoft lo convierte en el estándar de facto para las API REST accesibles desde la IA.

Conclusión #

OpenAPI ha encontrado una segunda vida transformadora como el formato estándar de descripción de interfaces para plugins de IA y sistemas de tool calling. Ya sea que se construya una GPT Action, un agent de LangChain o un conector de Copilot Studio, los desarrolladores pueden aprovechar sus documentos OpenAPI existentes, prestando atención a la redacción de descripciones aptas para la IA, la seguridad y el diseño de esquemas, para dar a los agents de IA acceso a capacidades del mundo real. A medida que el ecosistema de IA madure, el papel de OpenAPI como puente entre los agents inteligentes y la red de API de las que dependen no hará más que crecer.

Última actualización: 29 de abril de 2026.