Agentes de IA, OpenAPI y UTCP
La API se describe en dos documentos públicos (no necesitan clave), pensados para que un agente de IA descubra y use las operaciones por sí solo:
| Documento | URL |
|---|---|
| OpenAPI 3.0 | https://api.kellu.co/api/v1/openapi.json |
| Manual UTCP | https://api.kellu.co/utcp |
| Referencia interactiva | https://api.kellu.co/api/v1/reference |
Cada operación tiene un operationId estable (por ejemplo list_clients o get_sale_note) y una
descripción en inglés: qué devuelve, qué filtros acepta y qué
permiso requiere. La lista completa está en Recursos y operaciones.
Dale al agente una clave propia, solo con los permisos que necesita (ver
Permisos). Sin clients:read, por ejemplo, el agente nunca ve el correo ni el
teléfono de tus clientes. Como las claves son de solo lectura, un agente con clave no puede modificar
datos.
Si quieres que un asistente como Claude o ChatGPT también cree, edite o envíe (clientes, trabajos, cotizaciones, notas de venta, recordatorios, tickets), usa el conector de IA: se conecta con la cuenta de un usuario, con sus mismos permisos, y sus herramientas de escritura no están en el documento OpenAPI ni en el manual UTCP.
Manual UTCP
UTCP (Universal Tool Calling Protocol) permite que un agente llame a la API
directamente, sin un servidor intermedio. El manual de Kellu (/utcp) trae una herramienta por
operación: su nombre es el operationId, sus entradas son los parámetros de la operación y sus
salidas, la respuesta.
Ejemplo con el cliente TypeScript (@utcp/sdk y @utcp/http):
import { UtcpClient, UtcpClientConfigSerializer } from '@utcp/sdk'
import '@utcp/http' // registra el tipo de llamada "http"
// La clave se lee de la variable <nombre del manual>_API_KEY → kellu_API_KEY.
// export kellu_API_KEY=kellu_sk_TU_CLAVE
const config = new UtcpClientConfigSerializer().validateDict({
manual_call_templates: [
{ name: 'kellu', call_template_type: 'http', http_method: 'GET', url: 'https://api.kellu.co/utcp' },
],
})
const client = await UtcpClient.create(process.cwd(), config)
const tools = await client.getTools()
console.log(tools.map((tool) => tool.name)) // ["kellu.get_api_key_info", "kellu.list_clients", …]
const clients = await client.callTool('kellu.list_clients', { search: 'andes', limit: 5 })
Dos detalles del cliente UTCP:
- La variable de la clave lleva el nombre del manual como prefijo. El manual pide la variable
API_KEY; registrado comokellu, el cliente la busca comokellu_API_KEY, sin probar el nombre sin prefijo. Si lo registras con otro nombre, la variable cambia (erp→erp_API_KEY). - Los nombres de las herramientas llevan el mismo prefijo:
kellu.list_clients,kellu.get_work_order, etc.
Conversores OpenAPI → herramientas
Si tu framework de agentes convierte documentos OpenAPI en herramientas, apúntalo a
https://api.kellu.co/api/v1/openapi.json:
- Cada operación tiene
operationId,summaryydescription. - La autenticación está declarada como esquema
bearer: configura el encabezadoAuthorization: Bearer kellu_sk_…. - Los esquemas no usan
oneOf,anyOfniallOf, y solo tienen referencias internas, para que los conversores los traduzcan sin pérdida.
Ejemplo con el conversor de @utcp/http:
import { OpenApiConverter } from '@utcp/http'
const specUrl = 'https://api.kellu.co/api/v1/openapi.json'
const spec = (await (await fetch(specUrl)).json()) as Record<string, unknown>
const manual = new OpenApiConverter(spec, { specUrl, callTemplateName: 'kellu' }).convert()
console.log(manual.tools.length) // 19
Errores para el agente
Los errores tienen siempre la forma { "error": { "code", "message", "requestId", "details"? } }.
Indícale al agente que decida por code (por ejemplo, ante insufficient_scope debe informar qué
permiso falta, que viene en details.requiredScope) y que respete Retry-After ante un 429. Detalle
en Paginación y errores.