API

Tools personalizadas

Deja que la IA llame a tu API en medio de una conversación

Descripción general

Una tool personalizada es un endpoint tuyo que el agente puede llamar mientras habla con un cliente: consultar un crédito por cédula, revisar stock, abrir un ticket. Tú describes cuándo aplica y qué parámetros necesita; la IA decide cuándo llamarla, llena los parámetros con lo que dijo el cliente y responde con lo que devolvió tu API. Hasta 15 tools por agente.

Definición

Cada tool es una entrada con estos campos:

`name`	Nombre técnico con el que la IA la llama: letras, números y guión bajo (consultar_credito).
`description`	Cuándo usarla y qué devuelve. Es lo que la IA lee para decidir; escríbela como instrucción («Consulta un crédito por cédula; devuelve saldo y cuotas»).
`parameters`	Lista de {name, type (string \| number \| boolean \| enum), description, required, enum_values}. La IA los llena con lo que dijo el cliente.
`method + endpoint`	GET, POST, PUT o DELETE y la URL completa.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (nombre y valor de header que tú eliges) o BASIC (usuario y contraseña).
`headers`	Headers extra que van en cada llamada.
`body_template`	Plantilla JSON opcional con {{param}}. Sin ella, POST/PUT mandan los parámetros como objeto JSON.
`response_path`	Ruta con puntos opcional (data.results) a la parte de la respuesta que la IA debe leer.

Cómo se hace la llamada

GET y DELETE agregan los parámetros a la URL como query string. POST y PUT los mandan como body JSON: o el body_template ya rellenado. Los headers de auth y los extra van en cada llamada. Responde 2xx con JSON: la IA recibe el body (o la parte de response_path) como texto y lo usa para contestar. Un código distinto de 2xx le llega a la IA como «API returned <status>» y le dice al cliente que no pudo consultar; no hay reintentos automáticos.

Cómo crear una

Canvas (newui.tbit.app): pregunta «¿qué tools personalizadas tengo?» → la lista tiene «Nueva tool…»; cada fila abre la tool con Editar. Un formulario pide todo lo de arriba; los secretos que dejes vacíos al editar se conservan.
MCP (Claude, ChatGPT…): list_custom_tools para leerlas, manage_custom_tool con action=create | update | delete. El cambio se propone y tú lo confirmas.
App de la plataforma: Integraciones → API personalizada.

Ejemplo: crear desde el MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

Qué recibe tu endpoint

Con el ejemplo de arriba, cuando un cliente pregunta por su crédito la IA llama:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Buenas prácticas

Escribe la descripción para la IA, no para un desarrollador: cuándo usarla y qué vuelve.
Marca como obligatorio solo lo que la IA debe pedirle al cliente; lo demás dale un valor por defecto de tu lado.
Mantén los GET idempotentes: la IA puede llamar la misma tool dos veces en una conversación si el primer intento falló.
Devuelve JSON pequeño y plano. Usa response_path si tu API envuelve los resultados.