Esta es una función para desarrolladores. Para obtener la URL base de la API de Chateea y confirmar tus credenciales, escribe a soporte de Chateea en [email protected].
Para qué sirve
- Integrar agentes en apps móviles, plataformas propias, asistentes de voz o herramientas internas.
- Disparar agentes desde automatizaciones externas.
- Centralizar la seguridad con OAuth 2.0 y tokens con permisos limitados.
- Recibir JSON estructurado, fácil de procesar por otros sistemas sin trabajo extra.
Requisitos
- Cada solicitud está ligada a tu cuenta mediante el parámetro
locationId(el identificador de tu cuenta). - La solicitud debe autenticarse con un token OAuth 2.0 o con un token de integración privada.
- Solo se puede acceder a agentes que estén activos en la etapa de producción.
Acciones disponibles
La API cubre el ciclo de vida completo del agente:
Los requisitos de permisos, contexto de cuenta y parámetros pueden variar según el endpoint. Algunos endpoints antiguos siguen disponibles pero están marcados como obsoletos: para desarrollos nuevos usa siempre los actuales, porque los obsoletos pueden eliminarse en versiones futuras.
Endpoints principales
Listar agentes
Devuelve todos los agentes activos de tu cuenta. Útil, por ejemplo, para mostrar un desplegable de agentes en tu app.Consultar un agente
Devuelve los metadatos completos de un agente: nombre, estado, nodos de herramientas, variables, etapa del ciclo de vida y más. Útil para revisar sus variables antes de ejecutarlo.Ejecutar un agente
Ejecuta el agente y devuelve el resultado completo en un solo JSON.executionId. La respuesta te devuelve uno: guárdalo y envíalo en las siguientes llamadas para continuar la misma conversación.
Autenticación
Tienes dos opciones:
En ambos casos, el token va en el encabezado de autorización:
Cómo configurarlo
1
Ten un agente en producción
En Agentes de IA → Agent Studio, confirma que el agente que quieres usar está activo y en la etapa de producción.
2
Crea tu credencial
Ve a Configuración → Integraciones privadas y crea una integración privada con los permisos de Agent Studio que necesites. Copia el token generado y guárdalo en un lugar seguro. Si vas a usar OAuth, pide a soporte los datos de tu aplicación.
3
Si usas OAuth, obtén el token de acceso
Intercambia el código de autorización por un token de acceso con
grant_type=authorization_code. Guarda el token de forma segura y renuévalo cuando expire.4
Prueba la conexión listando tus agentes
agentId de los agentes que vas a ejecutar.5
Ejecuta el agente
executionId que recibes si necesitas una conversación de varios turnos.Límites y comportamiento
Preguntas frecuentes
¿El agente tiene que estar en producción?
¿El agente tiene que estar en producción?
Sí. Solo los agentes activos en la etapa de producción son accesibles por la API pública.
¿Puedo recibir la respuesta mientras se genera?
¿Puedo recibir la respuesta mientras se genera?
Todavía no. El endpoint de ejecución devuelve un único objeto JSON cuando el agente termina.
¿OAuth admite tokens de renovación?
¿OAuth admite tokens de renovación?
Sí. Usa el flujo estándar de OAuth 2.0 con
refresh_token para renovar el acceso sin intervención del usuario.¿Cuánto cuesta ejecutar un agente por API?
¿Cuánto cuesta ejecutar un agente por API?
Lo mismo que ejecutarlo desde Chateea: Agent Studio se cobra por uso desde la billetera de tu cuenta. Revisa cómo se cobra el uso de la IA.
Artículos relacionados
Agentes personalizados
Crea agentes con tus instrucciones y tu base de conocimiento.
Integraciones privadas
Genera tokens para conectar tu software con Chateea.