# Jugadores virtuales e instrucciones del agente — propuesta de contrato v2 **Estado:** decisión de producto del 6 de octubre de 2026 y propuesta de diseño. Cada juego debe declarar en sus propiedades si admite jugadores virtuales e incluir las instrucciones de sus agentes. Los nombres de campos siguientes son propuestos; todavía no hay esquemas ejecutables, controlador IA, API de plazas virtuales ni runtime compatible. El [formato v1](format-and-protocol.md) no cambia ni admite estos campos por existir este documento. ## 1. Propiedad del juego Una plaza de jugador puede tener un controlador humano o virtual. El motor mantiene asientos, turnos, acciones, información privada y resultados; la plataforma vincula cada asiento a una persona autorizada o a una instancia de agente limitada a esa partida. Una instancia virtual no es una cuenta humana, una sesión de navegador ni una pantalla compartida. El paquete de juego es la fuente de su soporte IA: modalidades compatibles, número de plazas virtuales, perfiles, dificultades, instrucciones y comportamiento ante fallos. La plataforma ejecuta únicamente perfiles publicados por el equipo y puede deshabilitarlos por disponibilidad, seguridad o presupuesto. No habilita IA en un juego que no la declare. La sala permite elegir los perfiles publicados antes del inicio y muestra qué plazas son virtuales. Los humanos confirman esa configuración al marcarse listos. Cambiarla invalida los listos; al comenzar se fijan controlador, perfil, dificultad y versión/digest del paquete. No se sustituye automáticamente a una persona desconectada por IA ni se cambia su controlador en una partida activa. ## 2. Extensión del manifiesto Se propone `virtualPlayers` como propiedad opcional del futuro `game.json` v2, coordinada con el [perfil multidispositivo](multi-device-profile.md) y el perfil ejecutable Go. Su ausencia significa que el juego no admite jugadores virtuales. No cambia por sí sola las versiones del protocolo ni de presentación: sus ampliaciones se definirán expresamente al crear los contratos ejecutables. Fragmento ilustrativo para Conecta 4, no manifiesto instalable: ```json { "virtualPlayers": { "profileVersion": 1, "minHumans": 1, "maxVirtualPlayers": 1, "profiles": [ { "id": "connect4-player", "version": "1.0.0", "labelKey": "agents.connect4.name", "modes": ["personal", "mesa"], "controllerId": "connect4-strategy-v1", "instructions": { "path": "agents/connect4/instructions.md", "locale": "es" }, "difficulties": ["easy", "normal", "hard"], "defaultDifficulty": "normal", "limits": { "decisionTimeoutMs": 2000, "maxAttempts": 2 }, "onFailure": "block-without-result" } ] } } ``` `players.min/max` sigue contando todas las plazas, humanas y virtuales. `minHumans`, `maxVirtualPlayers`, modos y combinaciones de perfiles deben ser compatibles con esos límites y con las reglas. Esta primera propuesta requiere al menos una persona; las simulaciones sin humanos serían un perfil de pruebas separado. Cada modo referenciado debe existir. Las claves de nombre, dificultad y explicación visible se traducen según la [política de idiomas](../platform/localization.md). `controllerId` referencia un adaptador registrado y versionado por el servidor: puede usar estrategia local en Go o un agente basado en modelo de lenguaje. No es una ruta ejecutable, una URL arbitraria ni permiso para instalar código. Cada dificultad necesita una configuración comprobable para ese controlador; escribir «difícil» en las instrucciones no demuestra su nivel. Los valores de tiempo e intentos del ejemplo son propuestas, no presupuestos medidos. Las instrucciones son obligatorias en cada perfil y pertenecen al propio paquete. Su ruta debe permanecer dentro de él, existir y figurar con sus bytes y hash en el inventario/lock. Cambiarlas exige una nueva versión/digest de paquete y perfil; las partidas existentes conservan los anteriores. No se descargan instrucciones mutables durante la partida. Su inclusión no obliga a servirlas al navegador: el catálogo expone solo la descripción pública del agente. ## 3. Contenido de las instrucciones El juego proporciona el objetivo del jugador, las reglas que necesita conocer, el significado de su vista, las acciones y parámetros disponibles, el papel cooperativo o competitivo y las pautas de estrategia/dificultad. También explica la información que permanece oculta y el formato de respuesta. Estas instrucciones complementan las reglas ejecutables; no crean acciones, permisos ni resultados que el motor no permita. Ejemplo del contenido de `agents/connect4/instructions.md`: > Ocupas una plaza de Conecta 4. Tu objetivo es conseguir cuatro fichas propias alineadas en horizontal, vertical o diagonal y evitar que lo consiga el rival. Recibes el tablero visible, tu ficha, la dificultad y las ofertas vigentes. Cuando puedas actuar, selecciona una oferta `drop` y una columna incluida en sus restricciones. Para la dificultad normal, prioriza una victoria inmediata, después bloquear una victoria inmediata rival y después construir amenazas propias. Devuelve únicamente una acción estructurada compatible con el esquema proporcionado. No inventes columnas disponibles ni modifiques el tablero: el motor coloca la ficha y confirma el resultado. En un controlador de estrategia Go, la implementación de estos criterios se revisa junto con el documento y sus fixtures. En un controlador con modelo de lenguaje, el adaptador incorpora las instrucciones versionadas al contexto del agente. La interfaz de decisión es común; el motor nunca interpreta lenguaje natural para aplicar una jugada. La entrada contiene solo la proyección autorizada de ese asiento (`view`, `context`, eventos visibles necesarios y `availableActions`), con la revisión/precondición de las ofertas. Las reglas y definiciones públicas necesarias pueden acompañarla; no se entrega el estado global, manos ajenas, futuras tiradas, chat, credenciales ni datos de cuenta. La salida es una propuesta `action: { type, payload }`, validada contra los esquemas y las reglas del juego. El servidor genera la identidad del comando y deriva el asiento del vínculo interno; la respuesta del agente no puede elegir otro actor. La misma restricción se aplica a instrucciones, recursos y memoria: no incluyen bancos de soluciones, semillas de azar, preguntas futuras ni secretos de otras plazas para eludir la proyección. Que un archivo forme parte del paquete no autoriza enviarlo al controlador; el publicador revisa el contexto completo y cada recurso permitido. Los modos del ejemplo deben existir en `interaction.modes`; admitir IA en `mesa` no le asigna un móvil, una TV ni un QR. La instancia recibe una proyección interna propia autorizada, independiente de `TVBoard`/`Desktop`/`Mobil`. El [perfil temporal](synchronization-profile.md) restringe juegos de reacción: el agente no conoce la pregunta antes de apertura, y competir por velocidad con humanos exige reglas publicadas de demora/dificultad. Sin ese perfil aprobado no se habilita IA en carreras; el coste/latencia de un modelo no se compensa como ping humano. Textos de jugadores y contenido narrativo se tratan como datos, no como instrucciones que puedan ampliar permisos. La plataforma fija las herramientas y restricciones del adaptador; un archivo del juego no concede acceso libre a red, archivos o base de datos. Un eventual proveedor externo recibe exclusivamente la proyección mínima autorizada y exige una evaluación propia antes de habilitarse. ## 4. Ejecución, fallos y recuperación El controlador pertenece a tareas del servidor, separado de las funciones puras de reglas. La deliberación, incluida cualquier llamada a modelo, se realiza fuera de los bloqueos y transacciones de sala/partida. El juego declara límites de decisión y de intentos; la plataforma aplica además sus cuotas de concurrencia, cómputo y coste. Un intento no reinicia indefinidamente el presupuesto de la decisión. El trabajo pendiente y su generación se persisten con la transición que habilita actuar al agente. El worker obtiene su proyección autorizada y una precondición; calcula una propuesta; guarda de forma duradera el sobre elegido y su `commandId`; y lo entrega al mismo caso de uso que valida comandos humanos. Una recuperación consulta/reenvía ese mismo sobre. Workers concurrentes deben reclamar el trabajo y elegir una única propuesta persistida; no pueden confirmar dos movimientos por el mismo trabajo. Cada oportunidad de actuar tiene identidad duradera, vencimiento y presupuesto total de tiempo/intentos. `decisionTimeoutMs` limita el tiempo total de deliberación de esa oportunidad, no se renueva por cada llamada; `maxAttempts` limita todos sus intentos, incluidos fallos y propuestas obsoletas. Reprogramar, reiniciar proceso o cambiar de worker conserva ambos contadores. Una nueva oportunidad solo nace de una transición de reglas que la habilite, no de un bucle de reintento. Reclamar el trabajo usa lease con generación: una respuesta de un worker sustituido no puede elegir o sobrescribir la decisión confirmada. El futuro contrato interno identifica los recibos por partida + instancia virtual autorizada + `commandId`, con huella del sobre completo. Reutilizar el identificador con otra acción o precondición se rechaza. Este vínculo se deriva del trabajo duradero y no de un `actor` enviado por el agente; no altera la identidad basada en principal humano del protocolo v1. El worker llama al servicio de aplicación dentro del backend, sin crear una cuenta ficticia ni hacer HTTP a su propia API. Antes de aplicar se revalidan el vínculo de la instancia, la política actual, versiones, fase, revisión y legalidad. Una propuesta obsoleta no se aplica: se comprueba si el agente sigue habilitado y se programa una nueva decisión dentro de presupuestos acotados. Una respuesta ilegal, timeout o fallo del proveedor no concede una victoria ni permite al agente saltarse validaciones. `onFailure: block-without-result` expresa indisponibilidad operativa recuperable, separada del resultado. Al agotar los límites se registra el incidente y se detienen decisiones nuevas hasta recuperación autorizada; no se mantiene un bloqueo SQL. Cualquier estrategia alternativa o salida por plazo necesita declaración versionada, validación y pruebas propias antes de ofrecerse. No se oculta un cambio de dificultad/controlador durante la partida. El bloqueo debe coordinarse con los plazos de juego: no puede prometer ausencia de resultado mientras un timeout paralelo adjudica derrota por ese mismo fallo. El paquete declara qué reloj pausa, un máximo de recuperación y la salida al agotarlo; en una ronda temporizada se aplica también la política de incidentes del perfil temporal. No reabre respuestas ni borra puntuaciones ya confirmadas. El ejemplo anterior omite deliberadamente esa política operativa completa y **no es publicable** hasta concretarla. La recuperación autorizada tampoco renueva intentos ilimitadamente ni cambia dificultad a escondidas. El historial conserva las acciones aceptadas, recibos y configuración del controlador, instrucciones/digest, dificultad y versión efectiva del adaptador/modelo utilizado. Si hay memoria del agente, debe ser duradera, limitada y aislada por instancia/partida; no comparte secretos entre plazas. La reproducción del juego utiliza las acciones confirmadas y la traza de azar del motor, no vuelve a consultar al agente ni presupone que un modelo produzca siempre la misma respuesta. No se requiere almacenar razonamiento interno ni payloads privados completos en logs. ## 5. Admisión y protección Una IA se identifica como virtual y no puede asumir anfitrión, tutela, contactos, credenciales humanas ni permisos de chat. En salas protegidas no sustituye al adulto responsable que exige la política vigente. Jugar una persona contra agentes requiere definir expresamente la modalidad de práctica y su admisión antes de habilitarla para invitados o menores; rellenar plazas no elude los permisos actuales. Este perfil autoriza acciones de juego estructuradas. Conversación, voz o narración generada visible serían capacidades adicionales, con contratos de contenido y protección propios; no se habilitan por adjuntar instrucciones al agente. También los nombres/avatares de agentes y sus descripciones pasan por publicación y proyecciones seguras. ## 6. Aceptación e implementación Antes de publicar soporte IA se necesitan esquemas v2 y perfil Go ejecutables, contrato de controlador, representación de plazas virtuales, tareas/decisiones duraderas y operaciones autorizadas de configuración en sala. El bootstrap solo podrá anunciarlo cuando ese corte esté implementado y verificado. La aceptación comprueba propiedades y archivos obligatorios; versiones/hashes; compatibilidad de modos, plazas y dificultades; acciones válidas y ausencia de información ajena; límites y fallos; respuesta obsoleta; duplicados y workers concurrentes; reinicio antes/después de guardar decisión o confirmar acción; revocación; memoria aislada; idiomas y protección. Conecta 4 será el primer ensayo; Hundido y Brisca comprobarán después los límites de información oculta.