🔌 API Pública del Estudio de Agentes IA
La API Pública del Estudio de Agentes IA te permite llamar, gestionar y ejecutar cualquier agente de CRMHUB desde tu propio software — sin necesidad de iniciar sesión en la plataforma.
📋 Contenido de este Tutorial
🔌 ¿Qué es la API Pública del Estudio de Agentes IA?
✨ Beneficios Clave
🛠️ Gestión de Agentes con la API Pública
📋 Endpoint: Listar Agentes
🔍 Endpoint: Obtener Agente
▶️ Endpoint: Ejecutar Agente
🔐 Autenticación OAuth
🔑 Integraciones PIT (Token de Integración Privada)
🧭 Cómo Configurar la API Pública
❓ Preguntas Frecuentes
🔌 ¿Qué es la API Pública del Estudio de Agentes IA?
Es una forma segura para que aplicaciones externas se comuniquen con CRMHUB. En el Estudio de Agentes IA, la API Pública permite que tu software liste, obtenga, y ejecute agentes de IA listos para producción de forma programática, sin iniciar sesión en el panel de CRMHUB.
Tu aplicación envía solicitudes HTTP seguras a los servidores de CRMHUB, que ejecutan el agente seleccionado y devuelven una respuesta JSON estructurada. Cada solicitud está vinculada a una cuenta específica y debe incluir autenticación correcta usando tokens bearer OAuth 2.0 o un Token de Integración Privada (PIT). Solo los agentes que están Activos en la etapa de Producción pueden accederse a través de la API Pública.
✨ Beneficios Clave
Incrusta agentes de IA dentro de apps móviles, plataformas SaaS, asistentes de voz, o herramientas internas.
Dispara flujos complejos de agentes desde automatizaciones externas (Zapier, Make, Airflow, etc.).
Centraliza la seguridad con OAuth 2.0 y tokens de acceso con alcance definido.
Aprovecha las Integraciones PIT para ejecutar agentes dentro de tu propio entorno respetando las reglas de privacidad de datos.
Devuelve JSON rico y estructurado para que los sistemas posteriores puedan procesar resultados sin NLP adicional.
🛠️ Gestión de Agentes con la API Pública
Ahora soporta gestión completa de agentes: crear, obtener, actualizar, publicar, ejecutar, y eliminar agentes de forma programática.
Acciones de gestión de agentes soportadas:
Crear Agente
Listar Agentes
Obtener Agente
Actualizar Agente
Actualizar Metadatos del Agente
Eliminar Agente
Promover a Producción y Publicar
Ejecutar Agente
Los requisitos varían según el endpoint. En general, las acciones de lectura usan acceso de solo lectura, mientras que crear, actualizar, publicar, ejecutar, y eliminar requieren acceso de escritura.
⚠️ Endpoints en desuso: algunos endpoints públicos antiguos siguen disponibles marcados como en desuso por compatibilidad. Para desarrollo nuevo, usa los endpoints actuales en vez de los que están en desuso.
📋 Endpoint: Listar Agentes
Devuelve cada agente activo para una cuenta dada.
Método: GET /agent-studio/public-api/agents
Parámetro obligatorio: locationId
Paginación opcional: limit, offset
Uso típico: mostrar un menú desplegable de agentes disponibles en tu app.
🔍 Endpoint: Obtener Agente
Obtiene los metadatos completos de un solo agente.
Método: GET /agent-studio/public-api/agents/{agentId}
Parámetro obligatorio: locationId
Devuelve: nombre, estado, nodos de herramientas, variables, etapa del ciclo de vida, y más.
▶️ Endpoint: Ejecutar Agente
Ejecuta un agente y obtiene el resultado completo en un solo payload JSON.
Método: POST /agent-studio/public-api/agents/{agentId}/execute
Cuerpo: { locationId, input, executionId? }
La primera llamada omite executionId; la respuesta devuelve uno para continuar el mismo hilo en llamadas posteriores.
🔐 Autenticación OAuth
Las APIs Públicas usan tokens bearer de OAuth 2.0. Crea una integración privada en CRMHUB o usa el flujo estándar de OAuth para obtener un token de acceso. Los tokens son JWT que deben incluirse en el encabezado de Autorización: Authorization: Bearer {access_token}
🔑 Integraciones PIT (Token de Integración Privada)
Los Tokens de Integración Privada (PIT) ofrecen una alternativa simplificada a OAuth completo cuando necesitas llamadas de servidor a servidor. Genera un PIT en Configuración de Desarrollador, dale alcance a la cuenta requerida, e inclúyelo en el encabezado de Autorización igual que un token de acceso OAuth.
🧭 Cómo Configurar la API Pública
Paso 1: Habilita Agentes IA → Estudio de Agentes IA en tu cuenta (debes tener agentes en "Producción").
Paso 2: Ve a Configuración → Desarrollador y crea una Integración Privada o una App OAuth.
Paso 3: Copia el Client ID y Client Secret (OAuth) o el valor PIT (Integración Privada).
Para OAuth: llama a POST /oauth/token con grant_type=authorization_code para intercambiar el código por un token de acceso. Guarda el token de forma segura; renuévalo según sea necesario.
Paso 4: Prueba la conexión con Listar Agentes usando el token en el encabezado Authorization.
Paso 5: Ejecuta el agente enviando el prompt en el cuerpo de la solicitud POST. Guarda el executionId devuelto si necesitas conversaciones de varios turnos.
❓ Preguntas Frecuentes
¿Hay un límite de tasa? Sí. Cada cuenta está limitada a 300 solicitudes de API por minuto en todos los endpoints del Estudio de Agentes IA.
¿Puedo transmitir respuestas parciales? Todavía no. El endpoint de Ejecutar Agente devuelve un solo objeto JSON después de completarse.
¿Los agentes deben estar en Producción? Sí. Solo los agentes con estado "Activo" en Producción son accesibles vía la API pública.
¿Qué pasa si omito locationId? La API devuelve HTTP 400.
¿Puedo llamar a la API desde JavaScript del lado del cliente? No es recomendable; siempre haz proxy desde tu backend para proteger el token.
¿Cuánto dura válido un executionId? Expira después de 30 minutos de inactividad.
¿OAuth soporta tokens de actualización? Sí, con el flujo estándar refresh_token.
¿Los tokens PIT están limitados a una sola cuenta? Sí.