Powers: conecta cualquier API a tus agentes por webhook

La distancia entre un chatbot y un agente útil se llama acción. Un chatbot describe cómo cancelar una suscripción; un agente la cancela. En Arko, esa capacidad de actuar sobre tus sistemas se entrega con Powers: herramientas que el agente invoca durante la conversación y que, por debajo, no son más que una llamada a una API tuya. Si tu servicio expone un endpoint, ya puedes convertirlo en una herramienta que el agente usa cuando corresponde.

Qué es un Power, en concreto

Un Power es la descripción de una acción y un webhook que la ejecuta. La descripción le dice al agente qué hace la herramienta y qué datos necesita para usarla; el webhook es la URL de tu API que Arko invoca con esos datos cuando el agente decide llamarla. El modelo nunca toca tu backend directamente: razona sobre la conversación, decide que hace falta la herramienta, arma los parámetros y Arko dispara el webhook por él. Tú recibes una petición HTTP normal, con un cuerpo JSON, y respondes con el resultado.

Esta separación importa. Significa que tu lógica de negocio, tus permisos y tus validaciones siguen viviendo en tu servidor, donde ya los tienes probados. El agente no ejecuta código tuyo ni conoce tus secretos: solo pide que se ejecute una acción que tú definiste, con parámetros que tú validas antes de actuar.

Conectar tu primera API

El flujo mínimo para conectar una API por webhook tiene cuatro piezas, y ninguna requiere que reescribas tu backend:

• El nombre y la descripción de la herramienta: qué hace, en lenguaje que el modelo entienda (ej: «consulta el estado de un pedido por su número»).
• Los parámetros: qué datos necesita y de qué tipo, para que el agente los extraiga de la conversación (ej: número de pedido, correo del cliente).
• La URL del webhook: el endpoint de tu API que recibirá la petición cuando el agente use la herramienta.
• La respuesta esperada: qué devuelve tu endpoint, para que el agente sepa interpretar el resultado y contárselo al usuario.

Con esas cuatro piezas, el agente ya puede resolver una petición como «¿dónde está mi pedido 4821?»: extrae el número, invoca el Power, tu API responde el estado y el agente lo comunica en el tono que le instruiste. No escribiste una línea de pegamento entre el modelo y tu servicio; describiste la herramienta y Arko hizo de puente.

Describir bien es más importante que programar bien

El punto donde un Power triunfa o fracasa es su descripción. El agente decide cuándo usar una herramienta leyendo lo que dice que hace, así que una descripción vaga produce dos fallos opuestos: la herramienta no se usa cuando debía, o se usa cuando no correspondía. Describe cada Power por su efecto observable, no por su implementación: «reembolsa un cargo al cliente» le dice más al modelo que «llama a POST /v3/refunds». Y sé explícito con los parámetros: si un campo es obligatorio, dilo; si tiene un formato, indícalo con un ejemplo.

Mantén el control de lo que el agente puede hacer

Dar herramientas de acción a un agente exige la misma disciplina que dar permisos a un empleado nuevo: el mínimo necesario. Que un agente pueda consultar un pedido no significa que deba poder cancelarlo; que pueda crear un ticket no lo habilita a cerrar la cuenta de un cliente. Separa las acciones de solo lectura de las que mutan estado, y trata las segundas con más cautela: validación estricta en tu endpoint, límites de monto o de frecuencia, y —para operaciones sensibles— un paso de confirmación antes de ejecutar.

Tu webhook es la última línea de defensa, y debe comportarse como tal. Nunca confíes en que los parámetros llegan correctos solo porque los armó el modelo: valida cada campo como validarías la entrada de un formulario público. El agente propone; tu backend dispone. Esa frontera es lo que te permite darle capacidades reales sin ceder el control de tu negocio.

Depurar cuando algo no dispara

Cuando un Power no se comporta como esperabas, el problema casi siempre está en un extremo de la conversación, no en el medio. Si la herramienta no se usa cuando debería, revisa su descripción: probablemente no le dice al agente con claridad cuándo aplica. Si se usa pero con parámetros incompletos, revisa cómo pides los datos: quizá el agente no tenía forma de conocerlos y debía preguntarlos antes. Si tu API responde error, revisa que el formato de la respuesta sea el que declaraste. Depurar Powers es, casi siempre, afinar descripciones y contratos, no reescribir lógica.