Tutorial de configuración multiagente

Esta es la guía del lado del operador complementaria a la sección de Agents. Síguela para agregar un segundo agente a una instalación, configurar el acceso a memoria entre agentes y colocar ambos agentes en un grupo de pares en el mismo canal.

Antecedentes: cada agente tiene su propio directorio de espacio de trabajo en <install>/agents/<alias>/workspace/, elige un backend de memoria en el momento de su creación (inmutable) y está restringido por una entrada [risk_profiles.<profile>].

A lo largo de este recorrido, el único agente existente se llama primary (sustitúyelo por el que realmente use tu instalación) y el nuevo agente que se está añadiendo es researcher.

Requisitos previos

• Una entrada [agents.primary] configurada con un model_provider, risk_profile funcionales y al menos un enlace de canal.
• Una entrada [risk_profiles.<name>] que el nuevo agente heredará. Reutilizar el perfil de primary está bien para la mayoría de los usos; elige un alias más estricto (p. ej. hardened) si el nuevo agente tiene una superficie de confianza diferente.

Añadir un segundo agente

Agrega otro agente a través del panel del gateway, zerocode, o zeroclaw config set. El runtime crea <install>/agents/<alias>/workspace/ en la primera entrada al bucle del agente. En cada inicio, el bucle del agente inyecta en el prompt del sistema los archivos de identidad del workspace que existan: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, luego BOOTSTRAP.md (solo en la primera ejecución) y MEMORY.md (solo en la sesión principal). HEARTBEAT.md también es un archivo de personalidad del workspace, pero es leído por el motor de heartbeat, no se inyecta en el prompt. El editor de personalidad del panel expone SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md y MEMORY.md para su edición. Crea y edita esos archivos para darle al agente su persona. (BOOTSTRAP.md es un andamiaje de primera ejecución que el agente lee una vez y elimina; el editor no lo expone.)

Vincular un canal

Sin un canal, el agente no tiene dónde escuchar. Vincule uno a través de la lista channels del agente y luego reinicie el daemon. El agente detectará su canal en el próximo inicio.

Acceso a archivos entre agentes

De forma predeterminada, un agente solo puede leer y escribir dentro de su propio directorio de workspace. Puede otorgar a un agente acceso de lectura o escritura al workspace de otro agente (configurado a través del gateway, zerocode o zeroclaw config set). Comportamiento efectivo, p. ej., researcher con acceso de escritura otorgado a primary y de lectura a archivist:

• file_read desde researcher puede leer tanto <install>/agents/primary/workspace/ como <install>/agents/archivist/workspace/.
• file_write y file_edit desde researcher pueden escribir en <install>/agents/primary/workspace/ pero no en <install>/agents/archivist/workspace/.

Los archivos de dispositivo POSIX (/dev/null, /dev/zero, /dev/random, /dev/urandom) siempre son legibles, no se necesita configuración por agente.

Acceso a memoria entre agentes

Solo mismo backend. Para que researcher pueda recuperar memorias que primary escribió, ambos agentes deben usar el mismo backend de memoria (p. ej., ambos sqlite). El validador de esquema rechaza entradas que apuntan a un hermano en un backend diferente; el runtime nunca ve una lista de permitidos entre backends para cuando construye el wrapper de memoria por agente.

El agente vinculado siempre ve sus propias filas; la lista de permitidos es puramente aditiva. No hay forma de ocultar las propias filas de un agente a sí mismo.

Grupo de pares en un canal compartido

Dos agentes se convierten en “pares” (cada uno puede dirigirse al otro en un canal) solo cuando ambos aparecen en el mismo grupo de pares. Consulta Peer Groups.

external_peers enumera humanos o bots externos que el grupo espera en el mismo canal; el runtime acepta tráfico entrante de esos nombres de usuario como tráfico entre agentes. ignore es una lista de bloqueo por grupo que se resta del conjunto de pares resuelto que ve cada miembro, útil para excluir una cuenta de bot específica que genera ruido.

El validador de esquemas en la carga de configuración aplica:

1. La lista de channels de cada miembro incluye el channel del grupo (un agente que no escucha ahí no puede emparejarse ahí).
2. Cada miembro es un agente configurado (sin referencias colgantes).
3. read_memory_from no apunta al propio agente.

Inspeccionar la instalación

Cada agente configurado se encuentra bajo una entrada agents.<alias> con su perfil de riesgo, proveedor de modelo, backend de memoria y conjunto de canales.

Los comandos de ciclo de vida zeroclaw agents realizan la cascada completa del estado propio solo en compilaciones con gateway y agent-runtime habilitados, incluido el binario distribuido estándar. Una CLI con funcionalidad reducida sigue modificando la configuración, pero indica que el estado propio no se propagó en cascada. Usa el panel del gateway o un binario con ambas funcionalidades habilitadas para las operaciones siguientes cuando exista estado propio.

Renombrar un agente

Utiliza el control de cambio de nombre para el agente en Config > Agents en el panel de control del gateway, o ejecuta:

zeroclaw agents rename researcher analyst

Ambas superficies reescriben las referencias al alias, persisten la configuración, mueven el espacio de trabajo predeterminado por alias y vuelven a apuntar el estado propio de memory, cron, ACP y sesión. Las rutas de espacio de trabajo personalizadas no se mueven porque no se derivan del alias. El alias reservado default no puede renombrarse desde ni hacia.

Lea los avisos en la respuesta. La configuración renombra los commits antes de la migración del espacio de trabajo y del estado propio, por lo que los avisos identifican un efecto secundario que aún requiere atención. La misma solicitud de renombrado de la API de gateway puede reemitirse para reintentar el residuo que quedó bajo el alias anterior.

Eliminar un agente

Usa el control de eliminación en Config > Agents, o previsualiza y aplica la operación de CLI:

zeroclaw agents delete researcher --dry-run
zeroclaw agents delete researcher --yes

1. Revise la vista previa de impacto y elimine cada bloqueador que reporte. Los bloqueadores de configuración comunes son un heartbeat habilitado propiedad del agente y un enlace de canal habilitado que ningún otro agente habilitado posee. La vista previa también enumera las referencias indirectas que la cascada eliminará automáticamente.
2. Finaliza cualquier sesión ACP activa. El panel las incluye en su vista previa; la CLI las verifica cuando --yes se ejecuta, después de la vista previa de solo configuración --dry-run.
3. Confirma la eliminación del dashboard o ejecuta el comando CLI con --yes. La operación elimina el agente y las referencias débiles de la configuración primero, luego ejecuta la cascada de estado en propiedad.
4. Inspecciona <data_dir>/agents/_deleted/<alias>-<timestamp>/ y los registros del gateway antes de confiar en el resultado del archivo o la limpieza.

La cascada de estado propiedad intenta:

• mover el espacio de trabajo configurado al archivo de eliminación;
• escribe los datos de memoria exportada, cron y ACP bajo cascade/;
• purga las filas de memoria del agente y los cron jobs;
• eliminar sus sesiones ACP no activas;
• borra la atribución de agentes de las sesiones de conversación retenidas; y
• escribe manifest.json con recuentos y advertencias mostradas.

Estos efectos secundarios son de mejor esfuerzo. Una exportación o escritura de archivo puede fallar mientras la limpieza posterior continúa. Verifique las entradas aplicables de workspace/, cascade/*.json y manifest.json en lugar de asumir que el archivo está completo. La CLI imprime las advertencias de cascada detectadas. La API de eliminación también las devuelve, pero el panel de control no las muestra actualmente; los operadores del panel de control también deben verificar los registros del gateway.

No sustituyas este flujo por ediciones directas de TOML, zeroclaw config set, eliminación manual del espacio de trabajo ni eliminación mediante SQL. Esas vías no ejecutan la cascada de referencias y de estado propio de la puerta de enlace.

No hay un comando de restauración automatizado. Conserva el archivo de eliminación hasta que ya no lo necesites para inspección o recuperación manual.

Verificar

Observa el flujo de registros combinado; cada línea ahora debería llevar los prefijos [<alias>] o [system]:

zeroclaw daemon 2>&1 | grep '\[researcher\]'   # solo las líneas del researcher
zeroclaw daemon 2>&1 | grep '\[system\]'       # solo líneas de boot/migración/scheduler

Si las comprobaciones de límites funcionan, file_read /dev/null desde cualquier agente tiene éxito (lista de permitidos de archivos de dispositivo POSIX), file_read fuera del workspace + lista de acceso falla con Path escapes workspace directory, y file_write a un elemento hermano de solo lectura en la lista de permitidos falla con el mismo mensaje.