Tool OpenAPI

La plantilla openapi conecta un agente con una API entera a partir de su spec OpenAPI, sin dar de alta las llamadas una a una: importas el spec y cada operación que actives es una función para el modelo, nombre_operacion. Por debajo, cada operación es una petición HTTP ya configurada: mismos secretos, mismas variables, mismos filtros de respuesta y mismos mensajes de error.

Se crea en Tools → Nueva instancia → OpenAPI.

Solo un administrador la engancha

Como http_request, guarda credenciales del administrador que la configuró: un usuario que no es administrador no puede añadirla a sus agentes o inferencias.

Importar el spec

Al crearla se elige de dónde sale el spec:

• Desde una URL (https://api.example.com/openapi.json). Si está en tu red (localhost, 10.x…), marca Está en una red interna. No se mandan credenciales: un spec que exige autenticación se pega o se sube.
• Pegado o fichero, en JSON o YAML.

Importar enseña qué trae: cuántas operaciones, cuáles no se pueden importar y por qué, qué autenticación declara y la URL base. Se admiten OpenAPI 3.0, 3.1 y 3.2. Swagger 2.0 no: hay que convertirlo antes (por ejemplo con swagger2openapi, o en editor.swagger.io → Edit → Convert to OpenAPI 3).

Una foto, no un enlace

Lo que se guarda es una foto del spec al importarlo. Si la API cambia después, la tool no cambia sola: Comprobar coherencia dice qué ha cambiado y te deja traer las operaciones nuevas y quitar las que ya no están (más abajo).

La tool nace con todas las operaciones desactivadas: el modelo no recibe nada hasta que actives las que quieras ofrecerle.

Qué se importa y qué no

Cada operación se convierte en una función: sus parámetros de ruta, query y cabecera son argumentos del modelo, y un cuerpo JSON va entero en un argumento body. Las descripciones del spec (summary, description de la operación y de cada parámetro, enum, example, default) son lo que lee el modelo para decidir cuándo y cómo llamar: un spec bien descrito es media tool hecha.

Para que todos los proveedores acepten las funciones, el esquema se simplifica al subconjunto que entienden todos (el mismo que en http_request):

En el spec	Al importar
$ref internos (#/components/...)	Se resuelven.
$ref a otro fichero o URL	No se siguen (la operación queda fuera). Empaqueta el spec en un solo fichero, por ejemplo con redocly bundle.
allOf	Se fusiona en un objeto.
oneOf / anyOf	Se queda la primera opción, con un aviso.
nullable, type: [T, "null"]	[T, "null"].
const	Un enum de un valor.
Esquemas recursivos, o de más de 5 niveles	Se cortan, con aviso.
Esquemas que se abren unos en otros ($ref que apuntan a componentes que a su vez apuntan a otros, muchas veces por nivel)	Si expandirlos cuesta demasiado, la operación queda fuera con su motivo. Ningún spec público grande que hayamos probado (Stripe, OpenAI, Jira…) se acerca.
Propiedades readOnly	Fuera del cuerpo.
Nombres con guiones (page-size)	El argumento pasa a page_size; a la API le llega page-size.
Objetos en la query o en una cabecera	Fuera (si son obligatorios, la operación entera).
Cuerpo multipart/form-data, binario…	Solo se admiten JSON y formulario urlencoded.
Parámetros de cookie	Fuera.

Lo que se simplificó sale como aviso en cada operación, y lo que no se pudo importar, al final de la lista con su motivo.

Operaciones

La sección Operaciones tiene una fila por operación, agrupadas por etiqueta (tags), con un filtro y una casilla por grupo. Al desplegar una se edita todo:

• Nombre de la función: el sufijo que va detrás del nombre de la tool. Sale del operationId.
• Descripción para el modelo: viene del spec. La descripción de la tool se añade detrás, en todas: úsala para el contexto de la API («la tienda online de Acme»).
• Parámetros, en modo guiado o en JSON Schema, con el mismo editor que http_request.
• Ruta, query y cabeceras propias de la operación, y el cuerpo.
• Salida propia: un filtro, TOON, un tamaño o unos mensajes de error solo para esta operación.
• Probar esta operación (guarda antes si hay cambios).

Pocas funciones, mejor

Cada función activada viaja en todos los turnos: cuesta tokens y, con muchas, el modelo elige peor. Activa solo lo que vaya a usar el agente. A partir de 30 sale un aviso, y más de 100 no se pueden activar a la vez.

Petición: URL base y credenciales

• URL base: esquema, host y, si lo hay, el prefijo común (https://api.example.com/v2). Al escribir se proponen los servers del spec. Todas las operaciones van detrás.
• Cabeceras y query de la tool: van en todas las operaciones. Las credenciales (una X-Api-Key, un Authorization: Bearer …) se marcan como secretas: se guardan cifradas, no vuelven a mostrarse y solo se mandan a esa URL base (si la cambias, hay que volver a escribirlas). Si el spec declara su autenticación (securitySchemes), sale un botón Añadir fila por cada una. OAuth 2 no se soporta: usa Reenviar el token del usuario o un token fijo.
• Permitir red interna y Reenviar el token del usuario: como en http_request.

Respuesta

Qué le llega al modelo de cada respuesta: entera o filtrada (ruta JSON o expresión regular), en TOON si sale más corta, el tamaño máximo, el plazo y los mensajes de error por código. Vale para todas las operaciones salvo las que tengan salida propia. Las respuestas se marcan por defecto como no fiables (<untrusted_document>): es una API de terceros, y el modelo no debe obedecer lo que diga.

Comprobar coherencia

En Spec de origen, Comprobar ahora vuelve a leer el spec (de su URL, o el texto que pegues si se importó pegado) y lo compara con lo que hay en la tool.

Si el spec trae operaciones nuevas o ya no tiene alguna de las de la tool, pregunta si quieres aplicarlo, con una casilla por operación:

• Nuevas en el spec: marcadas de entrada. Llegan al final de la lista, desactivadas, con su nombre de función (si choca con uno que ya tienes, se numera).
• Ya no están en el spec: sin marcar. Las que están activadas lo dicen: esas ya fallan, porque la API no las tiene.

Aplicar lleva lo marcado al formulario; como cualquier otro cambio, no cuenta hasta que guardas. Lo que no marques sigue en la lista por si lo quieres más tarde. Las operaciones que ya tenías no se tocan: ni lo que hayas editado ni si están activadas.

Además avisa de lo que hay que ajustar a mano en Operaciones, sobre todo en las activadas:

• Fallos: un parámetro que se manda y el spec ya no tiene, uno nuevo obligatorio que no se manda, o un cuerpo que pasa a ser obligatorio, desaparece o cambia de tipo.
• Avisos: una operación cuyos parámetros o esquema han cambiado desde la importación, o una URL base que ya no está entre los servidores del spec.

Preparar el spec

Muchos specs están pensados para personas o para generar SDKs, no para un agente: descripciones vacías, operationId crípticos, cientos de operaciones. Merece la pena prepararlo antes de importarlo. Este prompt sirve con cualquier asistente (pégale el spec detrás):

Vas a preparar un spec OpenAPI para que un agente de IA use la API a través de function calling.
Cada operación se convertirá en una función: el modelo solo verá el operationId, la descripción
de la operación y el esquema de sus parámetros. Devuélveme el spec completo, en YAML, con estos
cambios y sin inventar endpoints ni campos que no existan:

1. Si es Swagger 2.0, conviértelo a OpenAPI 3.1. Resuelve los $ref a otros ficheros para que
   quede un único documento.
2. Quita las operaciones que un agente no debería usar: administración, borrados masivos,
   webhooks, subida de ficheros binarios, autenticación (login, refresh)… Si dudas, déjala y
   márcala con un comentario.
3. Cada operación con un operationId corto en snake_case que diga qué hace
   (list_orders, get_order, create_refund).
4. Cada operación con un summary de una línea y una description que diga cuándo usarla, cuándo
   no, qué devuelve y cualquier dependencia ("necesita el id que devuelve list_orders").
5. Cada parámetro y cada propiedad del cuerpo con description: qué es, formato y unidades,
   y un example si ayuda. Usa enum para los valores cerrados y default cuando lo haya.
6. Evita oneOf/anyOf: si hay alternativas, quédate con la más común y describe las demás en la
   description. Evita objetos libres (additionalProperties sin properties) en lo que el
   agente tenga que rellenar.
7. Marca como readOnly lo que la API devuelve pero no acepta (ids, fechas de creación).
8. Deja servers con la URL base real y components.securitySchemes con la autenticación que use
   la API.