Autoworker Hub expone una API HTTP para administrar tenants alojados de trabajadores de IA, sus ejecuciones, almacenamiento compartido, skills, trabajos cron, credenciales y política del operador.
Este documento describe el contrato orientado al cliente. Omite de forma intencional los aspectos internos del despliegue del host y los detalles privados de implementación del runtime.
URL base
Use la URL del Hub proporcionada por su operador:
https://<hub-host>
Todos los endpoints de administración tienen su raíz en /v1, salvo que se indique lo contrario.
Autenticación
Los endpoints de administración requieren:
Authorization: Bearer <token>
Los endpoints de webhook usan el esquema de verificación del proveedor ascendente correspondiente. Los endpoints de callback del runtime del tenant son privados para los runtimes de los tenants y no son API generales para clientes.
Formato de respuesta
Las respuestas correctas son JSON, salvo que un endpoint transmita eventos o descargue bytes de archivos de forma explícita.
Los errores usan JSON de tipo problema con campos estables como:
{
"code": "invalid_argument",
"message": "detalle legible para una persona",
"status": 400
}
Endpoints principales
Estado y metadatos
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/healthz | Comprobación de actividad. |
GET | /v1/readyz | Comprobación de disponibilidad. |
GET | /v1/version | Versión del Hub y metadatos del runtime. |
Tenants
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants | Lista los tenants. |
POST | /v1/tenants | Crea y aprovisiona un tenant. |
GET | /v1/tenants/{tenantId} | Obtiene un tenant. |
PATCH | /v1/tenants/{tenantId} | Actualiza los metadatos y los ajustes deseados de un tenant. |
DELETE | /v1/tenants/{tenantId} | Elimina un tenant. |
GET | /v1/tenants/{tenantId}/access | Lee el estado de acceso de un tenant. |
PUT | /v1/tenants/{tenantId}/access | Establece el estado de acceso de un tenant. |
Los identificadores de tenant son identificadores de ruta. Trátelos como cadenas opacas que deben cumplir las reglas de validación de la API.
Ciclo de vida del agente del tenant
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/agent | Obtiene el estado actual del agente del tenant. |
POST | /v1/tenants/{tenantId}/agent/start | Inicia o activa el agente del tenant. |
POST | /v1/tenants/{tenantId}/agent/stop | Detiene el agente del tenant. |
POST | /v1/tenants/{tenantId}/agent/restart | Reinicia el agente del tenant. |
GET | /v1/tenants/{tenantId}/agent-card | Devuelve la Agent Card A2A pública del tenant. |
Ejecuciones y eventos
| Método | Ruta | Propósito |
|---|---|---|
POST | /v1/tenants/{tenantId}/runs | Inicia una ejecución de un trabajador de IA administrado. |
GET | /v1/tenants/{tenantId}/runs/{runId} | Obtiene el estado y los metadatos de una ejecución. |
GET | /v1/tenants/{tenantId}/runs/{runId}/events | Transmite los eventos de una ejecución. |
POST | /v1/tenants/{tenantId}/runs/{runId}/stop | Detiene una ejecución en curso. |
POST | /v1/tenants/{tenantId}/runs/{runId}/approval | Resuelve una aprobación de ejecución pendiente. |
Los flujos de eventos de ejecución son respuestas de larga duración. Los clientes deben gestionar las reconexiones y los estados terminales de las ejecuciones.
Archivos del tenant
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/files | Lista las raíces y los directorios de archivos visibles para el tenant. |
GET | /v1/tenants/{tenantId}/files/content | Lee contenido de archivo que admite vista previa de texto. |
GET | /v1/tenants/{tenantId}/files/download | Descarga un archivo visible para el tenant. |
GET | /v1/tenants/{tenantId}/runtime-inspection | Inspecciona las rutas resueltas del runtime del tenant y el entorno sin secretos. |
Solo se exponen las raíces visibles para el tenant. Los secretos, el estado privado del runtime y las áreas privadas de otros tenants no forman parte de la API de archivos.
Claves del entorno del tenant
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/env | Lista los nombres y metadatos de las claves de entorno delimitadas por tenant. |
PUT | /v1/tenants/{tenantId}/env/{name} | Establece una clave aceptada delimitada por tenant. |
DELETE | /v1/tenants/{tenantId}/env/{name} | Elimina una clave delimitada por tenant. |
Solo se pueden establecer nombres aceptados, delimitados por tenant y con formato de secreto. Las claves del runtime administradas por el Hub están reservadas.
Skills
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/skills | Lista las skills instaladas del tenant. |
GET | /v1/tenants/{tenantId}/skills/{category}/{skill}/files | Lista los archivos de una skill. |
GET | /v1/tenants/{tenantId}/skill-files/{skillPath} | Lee un archivo de una skill. |
PUT | /v1/tenants/{tenantId}/skills/{skillName}/state | Establece el estado habilitado o deshabilitado de una skill. |
Cron del agente
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/agent-cron | Lista los trabajos cron del agente del tenant. |
POST | /v1/tenants/{tenantId}/agent-cron | Crea un trabajo cron del agente. |
GET | /v1/tenants/{tenantId}/agent-cron/{jobId} | Obtiene un trabajo cron. |
PATCH | /v1/tenants/{tenantId}/agent-cron/{jobId} | Actualiza un trabajo cron. |
DELETE | /v1/tenants/{tenantId}/agent-cron/{jobId} | Elimina un trabajo cron. |
POST | /v1/tenants/{tenantId}/agent-cron/{jobId}/pause | Pausa un trabajo cron. |
POST | /v1/tenants/{tenantId}/agent-cron/{jobId}/resume | Reanuda un trabajo cron. |
POST | /v1/tenants/{tenantId}/agent-cron/{jobId}/run | Activa de inmediato un trabajo cron. |
El esquema de los trabajos cron pertenece al runtime del agente del tenant. El Hub transmite las definiciones de los trabajos y devuelve la respuesta del runtime.
Grupos compartidos y archivos compartidos
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/share-groups | Lista los grupos compartidos. |
POST | /v1/share-groups | Crea un grupo compartido. |
GET | /v1/share-groups/{groupId} | Obtiene un grupo compartido. |
PATCH | /v1/share-groups/{groupId} | Actualiza un grupo compartido. |
DELETE | /v1/share-groups/{groupId} | Elimina un grupo compartido. |
PUT | /v1/share-groups/{groupId}/members/{tenantId} | Establece el acceso de un miembro. |
DELETE | /v1/share-groups/{groupId}/members/{tenantId} | Elimina un miembro. |
GET | /v1/tenants/{tenantId}/shares | Lista los recursos compartidos visibles para un tenant. |
Las operaciones con archivos compartidos están delimitadas por tenant y grupo compartido:
/v1/tenants/{tenantId}/shares/{groupId}/list
/v1/tenants/{tenantId}/shares/{groupId}/read
/v1/tenants/{tenantId}/shares/{groupId}/stat
/v1/tenants/{tenantId}/shares/{groupId}/grep
/v1/tenants/{tenantId}/shares/{groupId}/find
/v1/tenants/{tenantId}/shares/{groupId}/write
/v1/tenants/{tenantId}/shares/{groupId}/mkdir
/v1/tenants/{tenantId}/shares/{groupId}/move
/v1/tenants/{tenantId}/shares/{groupId}/remove
Las operaciones de lectura requieren pertenecer al recurso compartido. Las operaciones de modificación requieren acceso de escritura a ese recurso.
Superficies A2A en el borde
| Método | Ruta | Propósito |
|---|---|---|
POST | /a2a/{tenantId} | Endpoint A2A del tenant. |
GET | /a2a/{tenantId}/.well-known/agent.json | Metadatos públicos del agente. |
GET | /a2a/{tenantId}/.well-known/agent-card.json | Agent Card pública. |
GET | /v1/tenants/{tenantId}/a2a-peers | Lista los pares presentados. |
POST | /v1/tenants/{tenantId}/a2a-peers | Presenta un par. |
GET | /v1/tenants/{tenantId}/a2a-peers/{peerId} | Obtiene un par. |
DELETE | /v1/tenants/{tenantId}/a2a-peers/{peerId} | Elimina un par. |
POST | /a2a/callbacks/{messageId} | Acepta una actualización asíncrona de Task de un par autenticada mediante capacidad. |
GET | /v1/peer-callback-outbox/metrics | Devuelve métricas agregadas y duraderas de entrega de callbacks. |
Las respuestas asíncronas de pares usan la configuración de notificaciones push A2A y una capacidad de callback por mensaje, no el bearer de control del Hub. Las actualizaciones de Task completadas, fallidas y canceladas se confirman de forma duradera antes del acuse de recibo. Los duplicados terminales exactos son idempotentes; se rechazan las transiciones en conflicto. Los fallos transitorios de callback se reintentan durante un máximo de 24 horas y persisten tras reinicios del Hub.
Credenciales y secretos
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/tenants/{tenantId}/a2a-credentials | Devuelve las credenciales A2A del tenant. |
GET | /v1/tenants/{tenantId}/api-credentials | Devuelve las credenciales de API delimitadas por tenant. |
POST | /v1/tenants/{tenantId}/api-credentials/rotate | Rota las credenciales de API delimitadas por tenant. |
GET | /v1/secrets | Lista los metadatos de secretos administrados. |
POST | /v1/secrets | Registra un secreto administrado sin devolver su contenido. |
GET | /v1/secrets/{secretId} | Devuelve los metadatos de un secreto administrado. |
DELETE | /v1/secrets/{secretId} | Elimina los metadatos y el contenido de un secreto administrado. |
POST | /v1/secrets/{secretId}:replace-material | Sustituye el contenido de solo escritura de un secreto. |
POST | /v1/secrets/{secretId}:refresh | Actualiza un secreto OAuth2. |
POST | /v1/secrets/{secretId}:rotate | Rota un secreto administrado de clave de API. |
POST | /v1/secrets:refresh-due | Actualiza todos los secretos OAuth2 que correspondan. |
El contenido de los secretos es de solo escritura. Las API de lectura solo devuelven metadatos y estado.
Flavors, versiones y evaluaciones
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/hermes-agent/releases | Lista las versiones instaladas del agente. |
POST | /v1/hermes-agent/releases | Registra o instala una versión. |
GET | /v1/hermes-agent/releases/{releaseId} | Obtiene una versión. |
DELETE | /v1/hermes-agent/releases/{releaseId} | Elimina una versión inactiva y sin usar. |
POST | /v1/hermes-agent/releases/{releaseId}:activate | Promueve una versión. |
GET | /v1/flavors | Lista el catálogo de flavors. |
POST | /v1/flavors | Instala un paquete de flavor. |
GET | /v1/flavors/{flavorId} | Obtiene una ficha del catálogo de flavors. |
GET | /v1/flavors/{flavorId}/versions/{flavorVersion} | Obtiene una versión de flavor. |
DELETE | /v1/flavors/{flavorId}/versions/{flavorVersion} | Elimina una versión de flavor sin usar. |
GET | /v1/flavors/{flavorId}/versions/{flavorVersion}/contents | Devuelve el contenido renderizable de un flavor. |
GET | /v1/flavors/{flavorId}/versions/{flavorVersion}/eval-suites | Lista los conjuntos de evaluación de un flavor. |
POST | /v1/flavors/{flavorId}/versions/{flavorVersion}/eval-runs | Inicia una ejecución de evaluación. |
POST | /v1/flavors/{flavorId}/versions/{flavorVersion}:deprecate | Marca como obsoleta una versión de flavor. |
GET | /v1/eval-runs | Lista las ejecuciones de evaluación. |
GET | /v1/eval-runs/{evalRunId} | Obtiene una ejecución de evaluación. |
POST | /v1/eval-runs/{evalRunId}:cancel | Cancela una ejecución de evaluación. |
Política y configuración
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/agent-policy | Devuelve la política de agentes para todo el Hub. |
PUT | /v1/agent-policy | Sustituye la política de agentes para todo el Hub. |
GET | /v1/agent-features | Lista las funciones conocidas de los agentes. |
GET | /v1/agent-specialization | Obtiene la especialización predeterminada de los agentes alojados. |
PUT | /v1/agent-specialization | Sustituye la especialización predeterminada. |
DELETE | /v1/agent-specialization | Deshabilita la especialización predeterminada. |
GET | /v1/tenants/{tenantId}/agent-policy | Obtiene la política efectiva y la anulación de un tenant. |
PUT | /v1/tenants/{tenantId}/agent-policy | Sustituye la anulación de la política de un tenant. |
DELETE | /v1/tenants/{tenantId}/agent-policy | Elimina la anulación de la política de un tenant. |
GET | /v1/config/tenant-impact | Devuelve la vista de configuración con impacto en los tenants. |
PATCH | /v1/config/tenant-impact | Prepara cambios de configuración con impacto en los tenants. |
POST | /v1/config/tenant-impact:apply | Aplica los cambios de configuración preparados. |
Métricas y claves empresariales
| Método | Ruta | Propósito |
|---|---|---|
GET | /v1/metrics/runs | Lista las métricas de ejecuciones. |
GET | /v1/metrics/runs/{runId} | Obtiene una ficha de métricas de una ejecución. |
GET | /v1/metrics/schedules | Lista las métricas de las programaciones. |
GET | /v1/metrics/usage/aggregate | Agrega las métricas de uso. |
GET | /v1/admin/business-keys | Lista las claves empresariales. |
POST | /v1/admin/business-keys | Crea una clave empresarial. |
DELETE | /v1/admin/business-keys/{businessKeyId} | Elimina una clave empresarial. |
Webhooks
| Método | Ruta | Propósito |
|---|---|---|
POST | /webhooks/telegram | Eventos de mensajes de la API de bots de Telegram. |
Los cuerpos de los webhooks los define el proveedor.
Endpoints de callback del runtime no destinados a clientes
Las rutas bajo /v1/tenant-runtime/{tenantId}/... están reservadas para callbacks
del runtime del tenant y para el proxy del runtime administrado por el Hub. Los
clientes externos no deben llamarlas directamente, salvo que implementen un runtime
de tenant compatible y tengan la credencial del runtime del tenant.