Gestionar agentes de IA

Tu aplicación puede proponer agentes de IA de canal: asistentes que responden cuando los mencionan y ejecutan tareas programadas, con el comportamiento de un agente publicado en AI Studio. Es lo más delicado que puede hacer una aplicación en UTILIA OS, porque un proceso automático decide con los permisos de qué persona trabaja el agente. Por eso tiene tres puertas y, además, cada agente necesita la aprobación de una persona antes de hacer nada.

Requisitos

• El plan de tu organización incluye la capacidad «Agentes de canal» del Chat (que a su vez necesita AI Studio).
• Un Super Administrador ha asignado a tu aplicación el scope chat:agents:manage:external. No entra en ningún paquete de scopes, ni siquiera en chat:full: hay que elegirlo a propósito. Para solo consultar los agentes basta chat:agents:view.
• En cada canal, la concesión de tu aplicación incluye «Gestionar agentes de IA en nombre de tu equipo».

Las puertas

El agente nace pendiente

Cuando tu aplicación propone un agente, la respuesta es 202 Accepted y el agente queda en PENDING_APPROVAL: no responde a menciones ni ejecuta tareas hasta que un administrador del canal lo aprueba en UTILIA OS. Tu aplicación no puede aprobar sus propios agentes.

Para aprobar hace falta el permiso «Gestionar agentes creados por apps» (CHAT_APP_AGENTS_MANAGE) y ser propietario o administrador del canal. Si quien aprueba no es la persona cuyos permisos presta el agente, la interfaz le pide una confirmación adicional. Tu aplicación se entera del resultado por webhook.

Con los permisos de quién: onBehalfOfUserId

Un agente no tiene permisos propios: trabaja con los de una persona real, la que indicas en onBehalfOfUserId al proponerlo. Esa persona tiene que estar activa, poder gestionar agentes (CHAT_AGENTS_MANAGE) y ser miembro del canal. En cada ejecución, UTILIA OS recorta las herramientas del agente a lo que esa persona puede hacer en ese momento: tu aplicación nunca amplía sus permisos.

Lo que estos endpoints no aceptan nunca: el modelo, el proveedor de IA, la temperatura ni claves de proveedores. El agente usa la configuración de IA por defecto de UTILIA OS. Tampoco puedes cambiar el agente de AI Studio (aiAssetId) de uno ya instalado: sería otro agente.

Endpoints

Todos cuelgan de un canal con acceso: /api/external/v1/chat/channels/:channelId/agents.

Para proponer un agente son obligatorios onBehalfOfUserId, aiAssetId (un agente publicado de AI Studio al que esa persona tenga acceso) y displayName (hasta 200 caracteres). Puedes limitar sus herramientas (allowedTools), si responde a menciones (respondsToMentions), cuántos mensajes publica al día (maxDailyMessages, hasta 100) y su acceso a la web.

Si al configurarlo cambias sus herramientas o su acceso a la web, el agente vuelve a PENDING_APPROVAL y deja de trabajar hasta una nueva aprobación. Los cambios de nombre, icono o color no la necesitan.

Ejemplo

import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: process.env.UTILIA_API_KEY, // utl_xxx
});
 
// 1) Solicitar el alta. onBehalfOfUserId es OBLIGATORIO: es la persona cuyos
//    permisos prestará el agente. Responde 202 y el agente nace PENDING_APPROVAL.
const agente = await sdk.chat.agents.install('cnv_8f3a21', {
  onBehalfOfUserId: 'usr_7a1b',
  aiAssetId: 'ast_vigia',
  displayName: 'Vigía de incidencias',
  allowedTools: ['crm_clients', 'crm_opportunities'],
  respondsToMentions: true,
  maxDailyMessages: 20,
});
 
console.log(agente.status); // 'PENDING_APPROVAL' -> aún no ejecuta
 
// 2) Listar los agentes que ESTA app ha creado en el canal, con su estado.
const agentes = await sdk.chat.agents.list('cnv_8f3a21');
for (const a of agentes) {
  console.log(a.displayName, a.status);
}
 
// 3) Configurar. Ampliar allowedTools devuelve el agente a PENDING_APPROVAL.
await sdk.chat.agents.update('cnv_8f3a21', agente.id, {
  displayName: 'Vigía de incidencias (pro)',
});
 
// 4) Pausar y reanudar (solo desde ACTIVE / PAUSED respectivamente).
await sdk.chat.agents.pause('cnv_8f3a21', agente.id);
await sdk.chat.agents.resume('cnv_8f3a21', agente.id);
 
// 5) Retirar del canal. Si publicó mensajes, se conserva como histórico.
const resultado = await sdk.chat.agents.remove('cnv_8f3a21', agente.id);
console.log(resultado.removed, resultado.retainedAsHistory);

Al retirar un agente que ya había publicado mensajes, no se borra: se conserva como histórico (retainedAsHistory en la respuesta).

Tope de coste de IA

Quien puede editar la aplicación fija un tope mensual de coste de IA para los agentes de tu aplicación, en la pestaña «Chat» de la configuración de la aplicación. Si en un mes los agentes lo superan, se pausan solos, llega el aviso CHAT_AGENT_BUDGET_EXCEEDED y no vuelven a responder hasta que se amplíe el tope o empiece el mes siguiente. Este tope se suma a la cuota de IA de tu organización.

Cuantas menos herramientas y menos mensajes diarios tenga un agente, más barato y más fácil de aprobar será.

Avisos

Estos avisos llegan solo a la aplicación que creó el agente, si tiene el scope chat:events:subscribe y los ha declarado en su webhook, aunque ya no tenga acceso al canal:

Declara los eventos con estos nombres en mayúsculas; los nombres internos con puntos no valen. Cómo recibirlos y verificarlos está en Webhooks de chat.

Siguiente paso

Cómo se ve la aprobación desde el lado del equipo, y cómo se añade un agente desde el propio Chat, está en Añadir un agente de IA a un canal.