Tutoriel de configuration multi-agents

Ceci est le guide complémentaire côté opérateur de la section Agents. Suivez-le pour ajouter un deuxième agent à une installation, configurer l’accès à la mémoire entre agents, et placer les deux agents dans un groupe de pairs sur le même canal.

Contexte : chaque agent possède son propre répertoire de travail dans <install>/agents/<alias>/workspace/, choisit un backend de mémoire à sa création (immuable), et est contrôlé par une entrée [risk_profiles.<profile>].

Tout au long de ce guide, l’agent unique existant est appelé primary (remplacez-le par celui que votre installation utilise réellement) et le nouvel agent ajouté est researcher.

Prérequis

• Une entrée [agents.primary] configurée avec un model_provider, un risk_profile fonctionnels, et au moins une liaison de canal.
• Une entrée [risk_profiles.<name>] dont le nouvel agent héritera. Réutiliser le profil de primary convient pour la plupart des usages ; choisissez un alias plus strict (par exemple hardened) si le nouvel agent présente une surface de confiance différente.

Ajouter un deuxième agent

Ajoutez un autre agent via le tableau de bord de la passerelle, zerocode, ou zeroclaw config set. Le runtime crée <install>/agents/<alias>/workspace/ lors de la première entrée dans la boucle d’agent. À chaque démarrage, la boucle d’agent injecte dans l’invite système les fichiers d’identité du workspace qui existent : AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, puis BOOTSTRAP.md (première exécution uniquement) et MEMORY.md (session principale uniquement). HEARTBEAT.md est également un fichier de personnalité du workspace, mais il est lu par le moteur de heartbeat et non injecté dans l’invite. L’éditeur de personnalité du tableau de bord expose SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md et MEMORY.md pour modification. Créez et modifiez ces fichiers pour donner à l’agent sa persona. (BOOTSTRAP.md est un échafaudage de première exécution que l’agent lit une seule fois puis supprime ; l’éditeur ne l’expose pas.)

Lier un canal

Sans canal, l’agent n’a nulle part où écouter. Associez-en un via la liste channels de l’agent, puis redémarrez le daemon. L’agent prendra en charge son canal au prochain démarrage.

Accès aux fichiers inter-agents

Par défaut, un agent ne peut lire et écrire que dans son propre répertoire d’espace de travail. Vous pouvez accorder à un agent un accès en lecture ou en écriture à l’espace de travail d’un autre agent (configuré via la passerelle, zerocode ou zeroclaw config set). Comportement effectif, p. ex. researcher avec accès en écriture à primary et en lecture à archivist :

• file_read depuis researcher peut lire à la fois <install>/agents/primary/workspace/ et <install>/agents/archivist/workspace/.
• file_write et file_edit de researcher peuvent écrire dans <install>/agents/primary/workspace/ mais pas dans <install>/agents/archivist/workspace/.

Les fichiers de périphériques POSIX (/dev/null, /dev/zero, /dev/random, /dev/urandom) sont toujours lisibles, aucune configuration par agent n’est nécessaire.

Accès mémoire inter-agents

Uniquement avec le même backend. Pour permettre à researcher de rappeler les mémoires écrites par primary, les deux agents doivent utiliser le même backend de mémoire (par ex. tous deux sqlite). Le validateur de schéma rejette les entrées qui pointent vers un agent frère sur un backend différent ; le runtime ne voit jamais de liste d’autorisation inter-backend au moment où il construit le wrapper de mémoire par agent.

L’agent lié voit toujours ses propres lignes ; la liste d’autorisation est purement additive. Il n’existe aucun moyen de masquer les propres lignes d’un agent vis-à-vis de lui-même.

Groupe de pairs sur un canal partagé

Deux agents deviennent « pairs » (chacun peut s’adresser à l’autre sur un canal) uniquement lorsque les deux apparaissent dans le même groupe de pairs. Voir Peer Groups.

external_peers répertorie les humains ou les bots externes que le groupe attend sur le même canal ; le runtime accepte le trafic entrant provenant de ces noms d’utilisateur comme du trafic inter-agents. ignore est une liste de blocage par groupe qui se soustrait de l’ensemble de pairs résolu que chaque membre voit, utile pour exclure un compte de bot spécifique qui est bruyant.

Le validateur de schéma appliqué au chargement de la configuration impose :

1. La liste channels de chaque membre inclut le channel du groupe (un agent qui n’y écoute pas ne peut pas s’y appairer).
2. Chaque membre est un agent configuré (aucune référence orpheline).
3. read_memory_from ne pointe pas vers l’agent lui-même.

Inspecter l’installation

Chaque agent configuré se trouve sous une entrée agents.<alias> avec son profil de risque, son fournisseur de modèle, son backend de mémoire et son ensemble de canaux.

Les commandes de cycle de vie zeroclaw agents exécutent la cascade complète de l’état détenu uniquement dans les builds où gateway et agent-runtime sont activés, y compris le binaire distribué standard. Une CLI à fonctionnalités réduites modifie tout de même la configuration, mais indique que l’état détenu n’a pas été mis en cascade. Utilisez le tableau de bord de la gateway ou un binaire où les deux fonctionnalités sont activées pour les opérations ci-dessous lorsque l’état détenu existe.

Renommer un agent

Utilisez le contrôle de renommage pour l’agent sous Config > Agents dans le tableau de bord de la passerelle, ou exécutez :

zeroclaw agents rename researcher analyst

Les deux interfaces réécrivent les références à l’alias, enregistrent la configuration, déplacent l’espace de travail par défaut propre à l’alias et réaffectent la mémoire, les tâches cron, l’état ACP et l’état de session associés. Les chemins d’espace de travail personnalisés ne sont pas déplacés, car ils ne sont pas dérivés de l’alias. L’alias réservé default ne peut pas être utilisé comme alias source ou destination lors d’un renommage.

Lisez les avertissements dans la réponse. La configuration renomme les commits avant la migration de workspace et d’owned-state, donc les avertissements identifient un effet secondaire qui nécessite encore une attention. La même requête de renommage de gateway API peut être réémise pour réessayer les résidus laissés sous l’ancien alias.

Supprimer un agent

Utilisez le contrôle de suppression sous Config > Agents, ou prévisualisez et appliquez l’opération CLI :

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

1. Examinez l’aperçu d’impact et résolvez chaque bloqueur signalé. Les bloqueurs de configuration courants sont un heartbeat activé appartenant à l’agent et une liaison de canal activée qu’aucun autre agent activé ne possède. L’aperçu liste également les références légères que la cascade supprimera automatiquement.
2. Mettez fin à toutes les sessions ACP actives. Le tableau de bord les inclut dans son aperçu ; la CLI les vérifie lors de l’exécution de --yes, après l’aperçu --dry-run limité à la configuration.
3. Confirmez la suppression dans le tableau de bord ou exécutez la commande CLI avec --yes. L’opération supprime d’abord l’agent et les références souples de la config, puis exécute la cascade de l’état possédé.
4. Inspectez <data_dir>/agents/_deleted/<alias>-<timestamp>/ et les journaux de la passerelle avant de vous fier au résultat de l’archivage ou du nettoyage.

La cascade d’état possédé tente de :

• déplacer l’espace de travail configuré vers l’archive de suppression ;
• écrire les données de mémoire exportée, cron et ACP sous cascade/ ;
• purger les lignes de mémoire de l’agent et les tâches cron ;
• supprimer ses sessions ACP non actives ;
• supprimer l’attribution de l’agent des sessions de conversation conservées ; et
• écrit manifest.json avec les décomptes et les avertissements affichés.

Ces effets de bord sont fournis au mieux. Une exportation ou une écriture de fichier d’archive peut échouer pendant que le nettoyage ultérieur se poursuit. Vérifiez les entrées workspace/, cascade/*.json et manifest.json applicables plutôt que de supposer que l’archive est complète. La CLI affiche les avertissements de cascade remontés. L’API de suppression les retourne également, mais le tableau de bord ne les affiche pas actuellement ; les opérateurs du tableau de bord doivent également consulter les journaux de la passerelle.

Ne remplacez pas ce flux par des modifications TOML directes, zeroclaw config set, une suppression manuelle de l’espace de travail ou une suppression SQL. Ces chemins n’exécutent pas la cascade de références et d’état possédé de la passerelle.

Il n’existe pas de commande de restauration automatique. Conservez l’archive de suppression jusqu’à ce que vous n’en ayez plus besoin pour l’inspection ou la récupération manuelle.

Vérifier

Examinez le flux de journaux fusionné ; chaque ligne doit désormais comporter le préfixe [<alias>] ou [system] :

zeroclaw daemon 2>&1 | grep '\[researcher\]'   # researcher's lines only
zeroclaw daemon 2>&1 | grep '\[system\]'       # lignes de démarrage/migration/planification uniquement

Si les contrôles de limites fonctionnent, file_read /dev/null depuis n’importe quel agent réussit (liste d’autorisation des fichiers de périphérique POSIX), file_read en dehors de l’espace de travail + la liste d’accès échoue avec Path escapes workspace directory, et file_write vers un homologue autorisé en lecture seule échoue avec le même message.