Componentes internos del runtime

Esta página es el complemento de arquitectura detallada de la sección de Agentes: explica cómo el runtime aplica los permisos por agente, delimita la memoria y atribuye los registros. Para configurar y ejecutar agentes, empieza por Agentes; para la referencia de campos a nivel de esquema, consulta Configuración; para los pasos de configuración en vivo, consulta Configuración multiagente.

Modelo de permisos

El SecurityPolicy efectivo de cada agente se construye con SecurityPolicy::for_agent(config, alias):

Parte del perfil de riesgo del agente ([risk_profiles.<profile>]).
Establece el límite en el directorio de espacio de trabajo por agente (<install>/agents/<alias>/workspace/).
Recorrer [agents.<alias>.workspace.access]:
- Read → el workspace del proceso hermano queda en la lista de permitidos de solo lectura.
- Write → el workspace hermano se incluye en la lista de permitidos solo de escritura.
- ReadWrite → el espacio de trabajo del hermano se añade a la lista de permitidos de lectura y escritura.
Si [agents.<alias>.workspace.unrestricted_filesystem] es true, desactive workspace_only.

La lista de permitidos de solo lectura es respetada por file_read y por otras herramientas de lectura, incluidos los comandos git_operations de status, diff, log, branch, stash-list y worktree-list. El comando worktree-list solo devuelve las entradas cuya ruta de worktree se resuelve y cuyos metadatos de Git pueden validarse mediante el permiso de lectura aplicable. La lista de permitidos de lectura y escritura controla file_write, file_edit, los comandos de git_operations clasificados como escritura (incluidos worktree add/remove/prune) y las invocaciones de la herramienta de shell que tocan rutas. Un workspace hermano de solo escritura no está disponible para git_operations: Git debe leer los metadatos del repositorio antes de cualquier operación. Los destinos de worktree y los metadatos .git/gitdir/commondir de los worktrees enlazados deben estar dentro del permiso aplicable. git_operations rechaza los enlaces simbólicos en cualquier parte de esos metadatos en lugar de seguirlos, incluso cuando su destino final estaría permitido de otro modo. Las invocaciones de Git descartan las variables GIT_* heredadas; configura la identidad de commit en la configuración de Git del repositorio o global en lugar de usar variables de entorno. Los comandos de solo lectura suprimen las integraciones ejecutables configuradas en el repositorio y la resolución de identidad mediante mailmap; además, su formato de log fijo usa los campos de autor sin procesar, por lo que estos comandos nunca leen .mailmap ni mailmap.file. Prohíben el transporte de Git y desactivan la obtención implícita de objetos promisor, de modo que una lectura que necesite un objeto de clonado parcial no disponible falla en lugar de iniciar un transporte seleccionado por el repositorio. Los comandos de escritura conservan los hooks y filtros habituales de Git cuando el operador concede acceso de lectura y escritura, y aplican el límite de sandbox configurado para cada agente. Con [runtime] kind = "docker", los comandos de git_operations clasificados como escritura se rechazan antes de lanzar cualquier comando de Git de escritura, porque Git no entra en el contenedor de runtime; los comandos clasificados como lectura no cambian, y la herramienta de shell sigue siendo la ruta de comandos dentro del contenedor. En el modo de runtime nativo, un sandbox no-op no confina a Git. Solo el backend de Landlock extiende ese sandbox a las raíces hermanas configuradas; otros backends de sandbox pueden rechazar escrituras fuera del workspace del agente, montar el workspace como solo lectura, omitir el workspace u ocultar la configuración global de Git. Consulta Sandboxing para el comportamiento de cada backend. Los archivos de dispositivo POSIX (/dev/null, /dev/zero, /dev/random, /dev/urandom) siempre son legibles, para que los idiomas de shell sigan funcionando sin configuración por agente.

Las generaciones de SubAgent aplican la regla de que un proceso hijo no puede escalar más allá de su proceso padre. La lista completa de ejes del validador y el comportamiento de compartición de presupuesto están documentados en Delegation → Permission inheritance.

Rondas de una sola herramienta

Las rondas de una sola herramienta solicitan como máximo una llamada de herramienta nativa por respuesta del proveedor. El bucle del agente existente ejecuta esa llamada, registra su resultado y pide al proveedor la siguiente respuesta dentro del mismo turno del usuario. El modelo puede narrar entre llamadas, pero la narración no es obligatoria ni la genera ZeroClaw.

Este modo está desactivado de forma predeterminada. En ZeroCode Config, establece runtime_profiles.<profile>.single_tool_rounds en true y selecciona ese perfil con agents.<alias>.runtime_profile. Un valor sin definir o false mantiene el comportamiento por lotes. La configuración es independiente de parallel_tools, que controla la concurrencia de ejecución de un lote admitido y no cuántas llamadas puede devolver el proveedor.

Solo las rutas de proveedor compatibles activan la política. Si la ruta seleccionada o cualquier alternativa accesible carece de soporte, ZeroClaw mantiene el comportamiento por lotes y muestra una vez por turno un aviso de limitación. Con una política activa, una respuesta que contenga múltiples llamadas a herramientas, nativas o recuperadas, falla antes de que cualquiera de esas llamadas se ejecute o entre en el historial de intercambio de herramientas. El uso de la solicitud al proveedor rechazada sigue contabilizándose en el total de tokens y costes. La narración transmitida puede haber sido ya visible; ZeroClaw no reproduce una respuesta que infrinja la política.

Las aprobaciones de herramientas, los recibos, la cancelación y los límites de iteración mantienen su comportamiento actual. Las llamadas secuenciales pueden requerir más solicitudes al proveedor, aumentar la latencia y alcanzar max_tool_iterations antes. Para revertir, establezca single_tool_rounds en false o elimínelo en el perfil de ejecución seleccionado.

Modelo de memoria

Cada agente tiene su propia instancia de Arc<dyn Memory>. La factoría (zeroclaw_memory::create_memory_for_agent) realiza el dispatch según el tipo de backend:

SQLite / Postgres / Lucid: almacén compartido a nivel de instalación. La tabla agents asigna alias → UUID, y la tabla memories contiene agent_id que hace referencia a ese UUID. La fábrica envuelve el backend interno en AgentScopedMemory, que estampa el UUID del agente vinculado en cada almacenamiento mediante store_with_agent y filtra cada recuperación mediante recall_for_agents con la lista de permitidos resuelta. Las concesiones estructuradas pueden filtrar además cada agente hermano a nombres de categoría exactos; el agente vinculado siempre ve todas sus propias categorías.
Markdown: directorio por agente. Cada MarkdownMemory de un agente escribe en <install>/agents/<alias>/workspace/MEMORY.md y en memory/YYYY-MM-DD.md. Como Markdown no conserva categorías personalizadas por fila, el validador de configuración y la fábrica rechazan las concesiones limitadas por categoría para este backend; solo se aceptan concesiones de hermanos sin restricciones. El wrapper sigue filtrando de forma defensiva cualquier construcción directa de pares.
Qdrant: colección compartida, indexada por payload. El campo de payload agent_id es la atribución por agente; recall_for_agents sobrecarga la obtención y posfiltra por payload.
None: stub sin operación. El wrapper sigue existiendo para que la ruta de ejecución sea uniforme.

Cross-backend cross-agent memory no está soportada: el validador de esquema al cargar la configuración rechaza las entradas de read_memory_from que apuntan a un agente hermano en un backend diferente. Las concesiones por categoría son de coincidencia exacta y no transitivas; una categoría desconocida no coincide con ninguna fila.

Ciclo de vida de renombrado y eliminación

Usa los controles de agente del panel del gateway o la CLI dedicada zeroclaw agents para renombrar y eliminar. En la compilación estándar con gateway y agent-runtime habilitados, ambas superficies ejecutan las cascadas de referencias y de estado propio; eliminar directamente o volver a asignar la clave de agents.<alias> en TOML o mediante un configurador genérico no lo hace. Una CLI con funciones reducidas sigue actualizando las referencias de configuración, pero advierte que el estado propio no se propagó en cascada, así que usa una compilación con ambas funciones habilitadas para las operaciones de ciclo de vida.

Ambas operaciones hacen persistente el cambio de configuración antes de ejecutar efectos secundarios sobre el estado propio. Renombrar reescribe primero las referencias de configuración, después mueve el espacio de trabajo predeterminado de cada alias y vuelve a apuntar el estado de memoria, cron, ACP y sesión. Eliminar primero rechaza las referencias duras y las sesiones ACP activas, después elimina la entrada de configuración y las referencias blandas antes de intentar archivar el espacio de trabajo, exportar y limpiar el estado propio y borrar la atribución de sesión.

Los efectos secundarios posteriores a la persistencia son de mejor esfuerzo e informan los fallos detectados, pero los fallos de escritura en el archivo pueden aparecer únicamente en los registros del gateway. Las advertencias de cambio de nombre indican que se debe reintentar el mismo cambio de nombre mediante la API del gateway para converger los residuos que quedaron bajo el alias anterior. Tras la eliminación, verifique el contenido del archivo y los registros antes de depender del archivo para la recuperación. La restauración automatizada no es compatible.

Consulta la guía de configuración de múltiples agentes para conocer los controles actuales, los bloqueos, la estructura del archivo y las comprobaciones del operador.

No compatible actualmente

Acceso a memoria entre agentes y backends (p. ej., un agente SQLite leyendo las filas de un agente Postgres).
Restauración automatizada desde un archivo de eliminación de agente.
Espacios de nombres de secretos por agente: existe un único SecretStore para todo el espacio de trabajo.
Extensiones del formato wire de Lucid para el ámbito entre agentes.