Producto: Agentes

Los agentes encapsulan runtimes y capacidades de ejecucion. Un agente puede usar modelos, skills, credenciales y targets segun el workspace.

Conceptos

• agente: runtime o herramienta capaz de ejecutar trabajo
• perfil de ejecucion: configuracion predeterminada de modelo, modo y skills
• skill: conocimiento o instruccion reusable
• dispatch: proceso que reclama y lanza tareas automaticas

Reglas

• El agente no debe resolver secretos desde la UI.
• Las credenciales se inyectan en runtime.
• El workspace limita que credenciales y targets puede usar una tarea.
• Los fallos de runtime deben quedar en comentarios, output o auditoria.

Modelos

El modelo por defecto puede variar por perfil. No conviene cambiar el modelo global por coste hasta tener metricas; primero se mide:

• tiempo medio por tarea
• fallos por agente
• reintentos
• coste estimado
• tareas que requieren gate final de mayor calidad

Perfiles De Intencion IA

La UI no debe obligar al usuario a pensar en proveedor, runtime y modelo cada vez que crea una tarea. Para uso diario se ofrece un selector corto de intencion:

• rapido: triage, resumen y tareas rutinarias. Prioriza latencia/coste y usa modo lite.
• razonamiento: planificacion, producto y analisis con mas contexto.
• codigo: implementacion con repo, tests y evidencia tecnica.
• revision: QA, review, riesgos y gates antes de cerrar.
• local: preferencia por runner/modelo local cuando el proyecto declare capacidad real.

Estos perfiles no sustituyen a execution_profiles. Son una capa de producto sobre ellos. El selector rellena defaults de modelo, modo operativo, perfil funcional y agente preferente cuando existen en el workspace, pero cada tarea puede sobreescribirlos.

Contrato recomendado en tarea:

• tag model-profile:<clave> para filtrado y auditoria rapida;
• execution_contract.model_profile.key para trazabilidad estable;
• execution_contract.preferred_model, preferred_agent, profile_slug, execution_mode y operating_mode como defaults visibles;
• nunca hacer fallback silencioso de proveedor/modelo si cambia la forma real de ejecucion.

Regla de venta: el producto vende tipos de trabajo verificables, no una lista magica de modelos. La infraestructura decide si ese perfil se resuelve con SaaS worker, runner local, repo remoto o modelo local, y debe dejar evidencia de la decision.

Configuracion Flexible

OPS no debe limitarse a una lista fija de agentes o modelos. La lista visible puede sugerir valores conocidos, pero el sistema debe aceptar nuevos modelos siempre que el agente/runtime los soporte.

Separacion de conceptos:

• agente: configuracion OPS que representa una capacidad de ejecucion.
• runtime: binario, servicio o proceso que ejecuta realmente.
• proveedor: origen del modelo o credencial.
• modelo: identificador entendido por el runtime.
• profile/subagente: capa funcional orientada al usuario, con rol, skillset, politica de salida y defaults operativos.

Configuracion De Perfiles

Los perfiles deben ser suficientemente explicitos para que una persona entienda que puede hacer cada uno sin abrir el prompt completo.

Campos recomendados:

• usage_mode: si el perfil se usa como principal, delegado o ambos.
• permission_level: nivel operativo esperado (read_only, propose, edit, operate).
• max_steps: limite orientativo de iteraciones para evitar ejecuciones interminables.
• temperature: valor recomendado para respuestas mas deterministas o creativas.
• category: area funcional visible en el catalogo.
• preferred_agent: runtime preferido cuando exista capacidad real.
• allowed_scopes y forbidden_scopes: limites comprensibles para humanos y agentes.
• required_outputs: evidencias o entregables minimos para considerar la tarea completa.

Estos campos viven en metadata para evitar una migracion prematura, pero el backend debe normalizarlos y descartar valores no validos. La UI puede mostrarlos como configuracion de gobierno, no como detalle tecnico oculto.

Direccion De Producto

Cuando el catalogo crezca, la entidad visible principal para el usuario debe ser el subagente/profile y no el runtime tecnico.

Razon:

• un runtime como opencode o codex no expresa por si solo el tipo de trabajo;
• un profile si puede representar roles como frontend-implementer, code-review-gate o seo-architect;
• el runtime puede cambiar sin romper la identidad operativa del subagente.

Regla recomendada:

• UI de catalogo: centrada en profiles/subagentes.
• UI tecnica/infra: centrada en agents/runtimes, credenciales y workers.

Regla operativa:

• OpenCode es el runtime preferente del workspace interno mientras este configurado.
• Hermes es valido si una tarea, perfil, plantilla o workspace lo selecciona explicitamente.
• Hermes no debe usarse como fallback silencioso.
• Codex, ClaudeCode, Minimax, modelos locales u otros proveedores solo deben anunciarse si el worker puede ejecutarlos realmente.
• Los aliases de modelo no deben ocultar cambios de proveedor. Si minimax2.7 se ejecuta con OpenAI por emergencia, debe figurar como override operativo, no como alias permanente.

La referencia tecnica canonica vive en el portal tecnico interno, dentro del contrato operativo SaaS multitenant.

Activacion Sin Borrado

Estado actual:

• agentes tecnicos: tienen active y pueden desactivarse sin borrar;
• perfiles/subagentes: tienen active, categoria y filtros de estado;
• skills: estan aisladas por workspace y tienen borrado logico, pero todavia necesitan active para pausarse sin retirarlas.

Regla de producto: el usuario debe poder pausar capacidades sin perder configuracion. Borrar debe ser una accion secundaria, con confirmacion y solo cuando no haya dependencias activas.