Tinkay

Construir una acción para Tinkay AI

Exponer un endpoint propio para que la IA consulte tu sistema durante la conversación.

Antes de empezar

  • Un endpoint HTTPS que responda en menos de 5 segundos
  • Plan Avanzado o superior

Una acción es un endpoint tuyo que Tinkay AI puede llamar cuando la conversación lo necesita. Es lo que separa una IA que repite documentación de una que responde con el estado real de la cuenta.

1. Escribí el endpoint

Recibe los parámetros que definas y devuelve JSON plano. Cuanto más simple, mejor lo usa la IA.

SubscriptionsController.cs
[ApiController][Route("internal/billing")]public class SubscriptionsController : ControllerBase{    [HttpGet("subscriptions/{workspace}")]    public async Task<IActionResult> Get(string workspace)    {        if (!Request.Headers.TryGetValue("X-Tinkay-Signature", out var signature))            return Unauthorized();        var sub = await _billing.FindAsync(workspace);        if (sub is null) return NotFound(new { error = "workspace_not_found" });        return Ok(new        {            plan = sub.Plan,            seats = sub.Seats,            next_invoice_at = sub.NextInvoiceAt,            status = sub.Status        });    }}

2. Registrala en Tinkay

  1. Entrá a Tinkay AI, Acciones y tocá Nueva acción.
  2. Poné un nombre claro: la IA lo usa para decidir cuándo llamarla. Consultar suscripción funciona mejor que getSub.
  3. Describí qué devuelve, en una línea.
  4. Definí método, URL y parámetros, marcando cuáles son obligatorios.
  5. Probala desde el AI Test Lab con una consulta real.

3. Contrato y errores

Qué esperamos de tu endpoint

CampoTipoDescripción
Tiempo de respuesta5 sPasado ese tiempo se corta y la IA responde con lo que sabe.
Códigos2xx / 4xx / 5xxUn 4xx se interpreta como dato no encontrado; un 5xx como falla temporal.
CuerpoJSON planoObjetos anidados o listas largas confunden a la IA. Devolvé lo justo.
Autenticaciónheader firmadoEnviamos X-Tinkay-Signature para que valides el origen.

No devuelvas datos sensibles que no quieras que la IA repita: todo lo que responde el endpoint puede terminar en el chat.

4. Observá su uso

Los eventos ai.action_called y ai.action_failed te dan visibilidad de cada llamada, con duración y estado.

En Tinkay AI, Acciones ves las ejecuciones de los últimos 30 días por acción.

Cómo saber que quedó bien

  • En el AI Test Lab, la pestaña Avanzado muestra la llamada con su duración y respuesta.
  • La IA usa el dato devuelto en su respuesta, sin inventar.
  • Si el endpoint falla, la conversación se deriva a una persona.