Crea y administra agentes por API

Igual que los Powers, los agentes son un recurso completo en la API: se crean, se listan, se editan y se borran. Es la base para cualquier integración que necesite generar agentes de forma programática —una plataforma que ofrece un agente por cliente, por ejemplo— en vez de crearlos uno por uno desde el panel.

Crear un agente

Crear un agente pide un nombre y, opcionalmente, un contenido —el system prompt, hasta 5000 caracteres— y una lista de powers por su id, con un máximo de veinte en el cuerpo de la petición. Ojo con dos límites distintos ahí: los ids de Powers ajenos o inexistentes se ignoran en silencio, y la capacidad real de powers vinculados por agente es de cinco —mandar más ids válidos de los que tu plan permite dispara un error de capacidad, no un error de validación del cuerpo.

memory, web e images solo aplican con JWT

Estos tres indicadores controlan si el agente tiene memoria persistente, búsqueda web y generación de imágenes. Cuando la petición viene autenticada con una API key en vez de un JWT de usuario, los tres se fuerzan a false sin importar qué mandes en el cuerpo. Si tu integración de servidor necesita crear agentes con memoria activa, esa creación tiene que pasar por una sesión de usuario, no por una key.

El detalle expande los Powers

• El listado de agentes trae el contenido truncado, sin el detalle de sus powers.
• El detalle de un agente trae cada power vinculado con su webhook completo —url, método, cabecera— y sus parámetros.

Actualizar el set de Powers es un reemplazo, no una suma

Actualizar un agente con un arreglo de powers no agrega a lo que ya había: reemplaza el set completo. Arko calcula la diferencia entre lo que el agente tenía vinculado y lo que le mandaste, desvincula lo que ya no aparece y vincula lo nuevo. Si tu intención era agregar un power sin tocar los demás, tienes que mandar la lista completa —los existentes más el nuevo—, no solo el que quieres sumar.

Borrar un agente es una cascada completa

Eliminar un agente no deja rastros sueltos: borra también sus chats, los mensajes de esos chats, las llamadas a herramientas registradas y los vínculos con sus powers. Es irreversible, así que si tu integración borra agentes de forma automática —por ejemplo, al dar de baja a un cliente— conviene confirmar antes que de verdad se quiere perder también el historial de conversaciones.