CubeLabs

1. Por qué los agentes necesitan un orquestador

Un agente no es un servicio web estático ni un job convencional. Puede acumular contexto, clonar un repositorio, llamar a un modelo, abrir conexiones a herramientas y quedarse iterando. Si se ejecuta sin límites, el fallo no es solo técnico: también puede convertirse en consumo de presupuesto o en acceso excesivo a red.

AX propone describir el trabajo deseado y dejar que el control plane cree una ejecución aislada. Su diseño se apoya en Agent Substrate para los sandboxes y adopta un flujo familiar para equipos que ya usan Kubernetes: declarar, aplicar, observar y reconciliar.

2. El modelo mental: Task, Workspace, Gateway y Model

Los cuatro recursos principales separan responsabilidades. Esta división permite reutilizar un entorno preparado, limitar las salidas de red y cambiar la configuración de modelos sin mezclar todo en un prompt o en un contenedor gigante.

AX también usa el ámbito llamado atespace para organizar recursos. Piensa en él como una frontera lógica: una tarea busca sus recursos asociados dentro de ese contexto.

3. Prerrequisitos e instalación de la CLI

La versión actual de AX está en fase alfa y su README advierte que puede introducir cambios incompatibles antes de una versión estable. Para experimentar necesitas un clúster Kubernetes, ko, un registro de contenedores y una API de control de Agent Substrate accesible.

go install github.com/google/ax/cmd/ax@latest
# Añade $(go env GOPATH)/bin a PATH si es necesario
ax version

# Desde el repositorio fuente, despliega el control plane
make deploy AX_IMAGE_REPO=<tu-registro>

4. Tu primer manifiesto YAML

Un único archivo puede contener varios documentos YAML. El siguiente ejemplo declara un Workspace que obtiene un repositorio y una Task que lo usa. La propiedad debug: true habilita inspección con ax ssh, útil en laboratorio pero que debes valorar cuidadosamente en entornos compartidos.

apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  git:
    - repo: https://github.com/golang/go.git
      branch: "my-fix"
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: test
spec:
  workspaces:
    - name: golang
      goal: "Asegura que la herramienta Go está disponible"
  debug: true

5. Preparar repositorios, MCP y habilidades

El Workspace evita que cada agente arranque desde cero. Según AX, puede preconfigurar repositorios Git, servidores MCP y paquetes de habilidades para que la tarea comience con el contexto operativo mínimo. Esto reduce pasos manuales, pero también exige disciplina: solo incluye material y herramientas necesarios para esa clase de tarea.

Una práctica útil es diseñar workspaces por rol: uno de revisión de código con el repositorio y herramientas de análisis; otro de documentación con fuentes de lectura; y otro de pruebas con permisos más estrictos. Mantén las credenciales fuera del YAML y usa secretos de Kubernetes para datos sensibles.

• Reutiliza workspaces si los agentes comparten una base de herramientas.
• Versiona las ramas o revisiones Git para hacer las ejecuciones reproducibles.
• Minimiza servidores MCP y habilidades: cada integración amplía la superficie operativa.

6. Aislamiento y política de red

El Gateway es la pieza para no conceder Internet indiscriminadamente. AX documenta una lista de hosts de salida explícita; úsala para permitir únicamente la API del modelo, el proveedor Git, un registro de paquetes o servicios que el agente necesite de verdad.

El aislamiento no sustituye la revisión del código o del prompt: es una capa adicional para que una mala instrucción o una dependencia vulnerable tenga menos alcance.

7. Operar: aplicar, inspeccionar y observar

La CLI de AX tiene una forma deliberadamente parecida a kubectl. El bucle operativo comienza aplicando manifiestos y continúa con consultas de estado. No declares éxito solo porque el comando de aplicación haya terminado: observa la fase y las condiciones de la tarea.

ax apply -f examples/task.yaml
ax get tasks
ax get task task123
ax describe task task123
ax watch task task123

ax watch transmite cambios de fase y condición en directo; es la herramienta adecuada para acompañar una ejecución durante pruebas. Para auditoría, conserva tanto el manifiesto exacto como los registros de la tarea y el identificador de la revisión Git usada.

8. Depurar dentro de un sandbox

Cuando una tarea se queda bloqueada, empieza por la especificación y el estado antes de entrar al sandbox. Después, con depuración habilitada, ax ssh permite ejecutar comandos puntuales en el espacio de trabajo. Esto aclara si falta un binario, si el repositorio no se preparó o si una política de red bloqueó una llamada.

# Inspección no interactiva del workspace
ax ssh task123 -- ls -la /workspace

# Ejecutar una prueba dentro de la tarea
ax ssh task123 -- python3 main.py

# Ver el contexto Kubernetes que usa la CLI
ax ctx

9. Suspender, reanudar y controlar costes

Una capacidad distintiva de AX es pausar una tarea inactiva y continuarla más tarde. Los comandos ax suspend y ax resume encajan especialmente bien con agentes que requieren revisión humana, que esperan una dependencia externa o que trabajan en lotes.

ax suspend task task123
# Revisa coste, estado y artefactos antes de continuar
ax resume task task123

# Cuando termina el experimento
ax delete task task123

Define reglas operativas antes de escalar: duración máxima, número máximo de reintentos, presupuesto por tarea, criterios de suspensión y responsable de reanudar. Un agente «autónomo» sigue necesitando límites explícitos y trazabilidad.

10. Diseño de una operación lista para producción

La ruta madura no es lanzar miles de tareas de golpe. Construye primero un caso de uso acotado: una Task con un Workspace reproducible, un Gateway de mínimo privilegio y un Model referenciado mediante secreto. Después mide tasas de éxito, duración, consumo, errores por integración y calidad de la salida.

AX está orientado a throughput alto y clústeres de gran escala, pero las mismas prácticas sirven en un piloto pequeño: declarar el entorno, aislar el agente y medir su comportamiento.

Apéndice práctico: condiciones, límites y contexto

La documentación de conceptos de AX aporta detalles que conviene traducir a decisiones operativas. Una Task declara la imagen y el comando, solicitudes y límites de cómputo, variables de entorno, una referencia a Gateway y uno o varios Workspaces. Cada Workspace se monta en su propia ruta; el primero sirve como directorio de trabajo del comando. Es una separación útil: el manifiesto describe con precisión qué se ejecuta y qué entorno recibe.

El estado resumido vive en status.phase, con valores como Running, Suspended, Failed o Terminating. Las condiciones aportan el motivo concreto. Para automatizaciones, no esperes un tiempo fijo: espera que WorkspaceReady sea verdadero y que Ready confirme que la tarea ya está en ejecución. Al suspender, AX marca Ready como falso con el motivo TaskSuspended; al reanudarlo, vuelve a estar listo.

Patrón de manifiesto responsable

Antes de convertir un experimento en servicio, documenta el objetivo de cada recurso. Un Workspace puede llevar un goal: una descripción en lenguaje natural del entorno que necesita la tarea. El runner puede usarla durante el arranque para completar la preparación, por ejemplo instalando una toolchain o dependencias. Esa comodidad no elimina la necesidad de reproducibilidad: fija versiones, conserva el YAML y prueba el resultado en una imagen controlada.

# Checklist previo a aplicar un manifiesto AX
# 1. ¿Qué repositorio y revisión se montan?
# 2. ¿Qué host y puerto necesita cada integración?
# 3. ¿Qué CPU/memoria y duración máxima puede consumir?
# 4. ¿Cuál es la condición observable de éxito?
# 5. ¿Quién puede usar ax ssh y durante cuánto tiempo?

La configuración Model también merece una frontera propia. No es el modelo en sí, sino un recurso nombrado que concentra proveedor, identificador de modelo, parámetros de generación —como temperatura— y una referencia al secreto Kubernetes con la clave. Centralizarlo facilita rotar secretos, fijar una versión de modelo o ajustar parámetros sin buscar credenciales repartidas por todas las definiciones de tareas.

Finalmente, la granularidad de AX permite que una tarea sea el trabajo completo o un nodo de un árbol mayor que un agente crea al descomponer un problema. Mantener esas unidades pequeñas hace posible aislarlas, suspenderlas y eliminarlas. En otras palabras: escala la composición de tareas, no los permisos implícitos.

Laboratorio: de un agente aislado a un equipo de tareas

Para fijar los conceptos, plantea una automatización de mantenimiento de un repositorio. El objetivo no es «usar un agente», sino producir un resultado comprobable: detectar una dependencia vulnerable, proponer un cambio en una rama y ejecutar las pruebas del proyecto. Divide ese objetivo en tareas de tamaño pequeño para que cada una tenga límites, entradas y salida observables.

Con este diseño, el Gateway de inventario quizá solo necesite Git y la API de modelo; el de validación podría no necesitar salida a Internet una vez materializado el Workspace. No heredes permisos de una etapa a otra por defecto. Cada excepción debe justificarse por la tarea, no por la conveniencia de compartir una configuración amplia.

Ejercicio guiado