CUGA de IBM: dos docenas de apps agentic y un harness ligero | Keryc
CUGA pone en tu mano lo que normalmente es la parte aburrida y frágil de cualquier agente: la tuberia, el estado, los guardrails y la orquestacion. ¿Quieres escribir la logica de negocio y no reconstruir la infraestructura cada vez? Entonces esto te interesa. Instalalo con pip install cuga y mira las cuga-apps: 24 ejemplos de un solo archivo que prueban el enfoque en la practica.
Qué hace CUGA y por qué importa
CUGA es un agent harness open source de IBM que toma la orquestacion por ti. El ciclo de planificacion, ejecucion, llamadas a herramientas, manejo de estado y pasos de reflexion ya estan resueltos. Lo que te queda es la parte creativa: la lista de herramientas que el agente puede usar y el prompt.
¿Suena a promesa grande? Lo interesante no es una sola de sus piezas, sino que vienen preensambladas. Eso significa que configuras en vez de cablear. Si ya escribiste una ruta FastAPI, puedes leer cualquiera de estos ejemplos linea por linea y entenderlo sin aprender un framework nuevo.
Arquitectura minima que realmente salva trabajo
La idea central es simple: el agente planifica antes de actuar, ejecuta mezclando llamadas a herramientas y codigo generado, guarda variables y se refleja para corregir planes rotos. Esa maquinaria hace que modelos mas pequeños y open-weight aguanten tareas largas, porque el harness carga trabajo que muchos modelos asumirian.
Cuatro argumentos. El model viene de una fabrica que lee una variable de entorno y puede hablar con OpenAI, Anthropic, watsonx, Ollama o un modelo local. tools y special_instructions son lo que realmente escribes. cuga_folder guarda estado y politicas.
Tools, MCP y la convencion que salva runs fragiles
Las apps mezclan dos tipos de herramientas: las especificas inline y las genericas provistas por servidores MCP. La ventaja es practica: escribes la funcion que es tuya y pides prestado web search, geocoding o bibliotecas de conocimiento sin montarlas.
Patron de herramienta inline:
Una funcion Python normal con una docstring que explica su uso.
El harness decide cuando llamarla.
Convencion importante sobre respuestas: cada herramienta debe devolver un sobre pequeño y consistente. Exito:
{"ok": true, "data": {...}}
Fallo:
{"ok": false, "code": "...", "error": "..."}
Ese detalle es clave. Si una herramienta lanza una excepcion desnuda el planner puede morir. Si devuelve el sobre de fallo, CUGA sabe manejarlo y seguir o replanear.
Las MCP servers publicas alojadas para las demos contienen 36 herramientas utiles: busqueda web, arXiv, geocoding, finanzas, etc. Un puente simple los enlaza y la galeria en vivo incluye un MCP Tool Explorer para probar cada herramienta antes de integrarla en un agente.
Planificacion, modos y coste-latencia
CUGA expone tres diales de razonamiento configurables sin tocar codigo: Fast, Balanced y Accurate. Esos modos ajustan el tradeoff entre coste y latencia. La idea practica es que no siempre necesitas el modelo mas grande: con el harness, un gpt-oss-120b puede bastar para muchas apps.
Tambien incluye CodeAct: mezcla de llamadas a herramientas y ejecucion de codigo generado en un sandbox que tu controlas (local, Docker/Podman o nube). Eso permite que la misma definicion de agente se ejecute rapido en entorno de desarrollo o gobernado en produccion cambiando solo la configuracion.
Politicas y governance integradas
CUGA no deja la gobernanza como algo que agregas despues. El runtime trae un sistema de politicas que se versiona en el .cuga folder y que se aplica en distintos momentos del flujo.
Tipos de politica:
Intent Guard: puede rechazar una peticion antes de que el agente elija herramientas.
Tool Approval: pide aprobacion humana antes de ejecutar una herramienta arriesgada.
Tool Guide: dirige como se debe usar una herramienta sin reescribirla.
Playbook: fija un procedimiento aprobado para tareas recurrentes.
Output Formatter: obliga la respuesta final a tener una forma concreta.
CustomPolicy: escape hatch para reglas especificas.
La timing importa: Intent Guard corre antes de elegir herramientas; Tool Approval corre despues de que el agente genera su codigo y revisa que herramientas usa; Output Formatter corre al final. Los disparadores no son solo coincidencia de palabras, tambien usan un store semantico (sqlite-vec) para emparejar la intencion real.
Ejemplo rapido de bloqueo por intencion:
await agent.policies.add_intent_guard(
name="Block force-push",
keywords=["--force", "--no-verify"],
response="Blocked: destructive git flags are not permitted.",
)
Multi-agent, skills y aprendizaje en trabajo
Cuando una tarea crece, en vez de ampliar un solo contexto, CUGA propone dividir: un CugaSupervisor delega a especialistas CugaAgent, cada uno con su contexto y herramientas. El supervisor solo decide delegar, manteniendo la superficie de planificacion manejable.
Las skills son carpetas con un SKILL.md que el agente incorpora solo cuando hace falta. Con ALTK-Evolve, un agente puede refinar una skill desde sus propias ejecuciones, asi lo que aprendes hoy mejora futuras corridas.
Ouroboros, una aplicacion de ejemplo, muestra esto en practica: un supervisor sobre siete especialistas que generan pipelines de lead-gen. Anadir un octavo especialista es una linea de fabrica, no una reescritura del coordinador.
Produccion soberana: Boundary Isolation y Sovereign Core
El despliegue gobernado no obliga a reescribir el agente. IBM llevo CUGA a lo que llaman Sovereign Core, donde cada agente corre en contenedores transitorios y aislados dentro del mismo limite logico del cliente. Modelo, datos, y control plane estan dentro del limite.
Por defecto las demos corren con gpt-oss-120b air-gapped. Cada paso de razonamiento emite trazas OpenTelemetry locales hacia Grafana Tempo en-tenant. En otras palabras: nada sale del boundary y la misma definicion de agente se redeploya tal cual.
Como empezar rapido con las cuga-apps
Pasos basicos:
git clone https://github.com/cuga-project/cuga-apps.git
cd build
cp .env.example .env # configura LLM_PROVIDER + LLM_MODEL y claves opcionales
docker compose up --build # la primera compilacion es grande
# abre http://localhost:8080
O simplemente instalas el runtime: pip install cuga y exploras la galeria en vivo. Abre apps/ibm_cloud_advisor/main.py para ver el patron completo: una herramienta inline que pregunta el catalogo IBM y las llamadas a MCP. Cambia el system prompt, agrega una herramienta y observa el comportamiento.
Consejos practicos y trampas comunes
Sigue la convencion del sobre de herramienta: evita excepciones desnudas.
Empieza desde apps etiquetadas como ship-ready, por ejemplo el Cloud Advisor o el Movie Recommender.
Si una tarea es larga, la reflexion y el tracking de variables que trae CUGA suelen ser las diferencias entre exito y fracaso.
Para gobernanza, piensa en controlar las pocas herramientas que tocan el exterior en vez de inventar toda la capa de control desde cero.
La leccion final es sencilla: un agente puede ser un archivo que entiendes. Escribe las herramientas y el prompt, y deja que el harness cargue la complejidad. Cuando la aplicacion escale, la gobernanza ya esta en el runtime y el mismo agente se puede redeployar en entornos cerrados. ¿Listo para probarlo? Clonea, instala y juega con una app; la caja de herramientas ya esta armada.
