multica-creating-agents

Création d'agents Multica

Voici le contrat relatif au processus de création d’agents Multica : ce que les points d’entrée de création acceptent, ce que le serveur valide et rejette, comment chaque champ est stocké, et quels champs le démon lit réellement au moment de la réclamation. Il ne s’agit pas d’un manuel des paramètres — il énonce des faits tracés à partir du code source, et chaque affirmation est étayée par une référence « fichier:ligne » dans references/creating-agents-source-map.md.

Démarrage rapide (inspection en lecture seule)

Ces commandes lisent l’état et n’ont aucun effet secondaire :

multica agent get  --output json      # enregistrement complet de l’agent persisté
multica agent skills list  --output json   # liaisons de compétences actuelles
multica agent env get  --output json  # environnement en texte clair (propriétaire/administrateur uniquement, accès refusé aux agents)

La commande «agent get » renvoie l’agent enregistré, y compris les champs runtime_id, model, thinking_level, service_tier, custom_args, has_custom_env, custom_env_key_count et skills. Elle ne renvoie jamais le champ custom_env en texte clair.

Modèle de base

Un agent est une ligne au niveau de l’espace de travail (table agent). Sa création s’effectue via une seule requête POST /api/agents (multica agent create). Au moment de la réclamation d’une tâche, le démon relit la ligne de l’agent et assemble la charge utile d’exécution — ce sont donc les champs persistés, et non la sortie au moment de la création, qui servent de base à l’exécution de l’agent.

Deux champs de texte distincts, souvent confondus :

• « description » est un résumé du catalogue. Elle est stockée et affichée dans les listes ; le démon ne l’injecte PAS dans l’invite d’exécution de l’agent. Considérez-la uniquement comme des métadonnées destinées à l’utilisateur. Limitée à 255 points de code Unicode.
• «instructions » correspond au contrat de comportement d’exécution. Le démon le lit au moment de la demande et le transmet au fournisseur en tant qu’instructions persistantes de l’agent. Le persona, les responsabilités, les limites, la sortie et les règles d’escalade doivent figurer ici, et non dans la « description ».

Points d’entrée CLI / API

Appel minimal de création (--name et --runtime-id sont tous deux obligatoires) :

multica agent create --name  --runtime-id  \
  --description "" \
  --instructions "" \
  --output json

runAgentCreate construit un corps JSON et l’envoie à /api/agents. Il n’ ajoute une clé que lorsque son indicateur a été fourni —description/instructions avec une valeur non vide ; le reste (runtime-config, custom-args, model, thinking-level, service-tier, visibility, …) est pris en compte si l’indicateur est Changed — ainsi, les indicateurs omis reprennent les valeurs par défaut du serveur plutôt que d’envoyer des chaînes vides.

Le corps HTTP (CreateAgentRequest) accepte : name, description, instructions, avatar_url, runtime_id, runtime_config, custom_env, custom_args, model, thinking_level, service_tier, visibility, max_concurrent_tasks, mcp_config.

Contrats de champs

Valeurs par défaut en cas d’omission : runtime_config → {}, custom_env → {}, custom_args → [], avatar_url → un emoji aléatoire :, visibility → private, max_concurrent_tasks → 6 (tous matérialisés côté serveur avant l’insertion).custom_args/runtime_config sont de type []string/any et marshalés tels quels — le rejet lié à la structure JSON a lieu dans la CLI, et non dans le gestionnaire de création.

thinking_level n’est validé qu’au niveau du fournisseur : les fournisseurs à catalogue fixe rejetent un littéral non reconnu, tandis que les fournisseurs à catalogue dynamique tels que Codex/OpenCode acceptent un jeton syntaxiquement valide. Une valeur non prise en charge par le modèle choisi n’est PAS rejetée ici — le démon vérifie son catalogue de modèles local au moment de l’exécution, consigne un avertissement et omet la redéfinition incompatible.

Définissez-le depuis l’interface CLI avec l’option --thinking-level lors de la création et de la mise à jour d’un agent, à l’instar de --model: ce drapeau sert simplement de relais vers le champ de niveau supérieur thinking_level, et lors d’une mise à jour, une chaîne vide (--thinking-level "") le réinitialise à la valeur par défaut du runtime. L’interface en ligne de commande (CLI) ne répertorie délibérément pas les niveaux valides — ceux-ci sont spécifiques au runtime et au modèle (Claude utilise actuellement low|medium|high|xhigh|max; les valeurs de Codex sont déterminées à partir du catalogue de modèles du runtime). Elle transmet le jeton, le serveur applique le filtre « fixed-enum » ou « safe-token » du fournisseur, et le démon effectue la vérification exacte du modèle et du niveau. Un runtime dont le fournisseur ne dispose pas de concept de réflexion rejette toute valeur non vide avec un code d’erreur 400.

service_tier est le contrôle de vitesse Codex de première classe correspondant. Définissez-le avec --service-tier lors de la création/mise à jour ; utilisez --service-tier "" lors de la mise à jour pour l’effacer. Le catalogue de modèles du runtime gère à la fois la disponibilité et la copie d’affichage (actuellement « priority », affichée comme « Fast »). Le serveur accepte les identifiants de catalogue Codex futurs sûrs, tandis que le démon vérifie la paire modèle/niveau exacte avant l’exécution et omet toute redéfinition obsolète et incompatible. Les agents sans modèle explicite échouent en état « closed » car le modèle effectif de config.toml est inconnu.

modèle vs custom_args

« model » est une colonne persistante de premier ordre que le démon lit directement. Les `custom_args` sont des arguments bruts de l’interface CLI du fournisseur. L’aide de la CLI indique que certains fournisseurs (codex app-server, openclaw) rejettent l’option `--model` dans les `custom_args` — mais il s’agit d’une recommandation documentée de la CLI, et non d’une contrainte imposée par le serveur ; rien dans le gestionnaire de création n’inspecte les `custom_args` à la recherche d’un indicateur de modèle.

Environnement et secrets

`custom_env` contient des informations confidentielles. L’interface CLI propose trois canaux d’entrée ; deux d’entre eux permettent de garder les secrets hors de l’historique du shell et de la liste des processus :

multica agent create --name  --runtime-id  --custom-env-stdin --output json
multica agent create --name  --runtime-id  --custom-env-file <0600-json> --output json

--custom-env-stdin lit l’objet JSON à partir de l’entrée standard ; --custom-env-file le lit à partir d’un fichier (mode recommandé : 0600). Le troisième canal, --custom-env , place la valeur sur la ligne de commande où l’historique du shell et la commande ps peuvent la voir — à éviter pour les véritables secrets.

Faits relatifs à la lecture (voici les hypothèses erronées à éviter) :

• Les ressources de l’agent n’exposent jamais custom_env en clair. Les commandes agent list/get/create/update et les événements WS renvoient uniquement has_custom_env (booléen) et custom_env_key_count (entier).
• La lecture des valeurs en clair nécessite l’utilisation du point de terminaison GETdédié /api/agents/{id}/env (multica agent env get). Son accès est réservé au propriétairede l’espace de travail etaux membres administrateurs, et les agents n’y ont pas accès, quel que soit le rôle du membre à l’origine de la requête — un agent en cours d’exécution ne peut pas lire les secrets d’un autre agent.
• L’écriture de valeurs après la création ne passe PAS par la mise à jour de l’agent. Le gestionnaire de mise à jour générique rejette tout champ `custom_env` avec un code d’erreur 400 (« utilisez PUT /api/agents/{id}/env »). Les écritures d’environnement en texte clair sont gérées par PUT /api/agents/{id}/env (définition de l’environnement d’un agent Multica), qui est réservée au propriétaire ou à l’administrateur et génère une ligne d’audit.

mcp_config

mcp_config correspond à la configuration du serveur MCP de l’agent (un objet JSON tel que {"mcpServers": {…}}). Il s’agit également d’informations confidentielles — les entrées MCP intègrent systématiquement des jetons API — et offre les trois mêmes canaux d’entrée que custom_env, aussi bien lors dela création que de la mise à jour de l’agent:

multica agent create --name  --runtime-id  --mcp-config-file <0600-json> --output json
multica agent update  --mcp-config-stdin --output json
multica agent update  --mcp-config 'null'   # efface la configuration

--mcp-config-stdin / --mcp-config-file: permet de ne pas enregistrer la valeur dans l’historique du shell ni dans ps; ce n’est pas le cas avec l’option en ligne --mcp-config . L'interface CLI requiert unobjet JSON ou la valeur littérale null; un tableau de niveau supérieur ou une valeur primitive est rejeté côté client, et une entrée stdin/fichier vide génère une erreur plutôt que d'effacer silencieusement la configuration.

Deux différences entre mcp_config et custom_env:

• Il PEUT être configuré via la mise à jour de l’agent. Contrairement à custom_env, mcp_config ne dispose pas d’un point de terminaison audité dédié — la requête PUT générique /api/agents/{id} l’accepte. Trois états possibles selon le corps brut de la requête : champ omis → aucun changement ; null → effacement ; objet → remplacement.
• Il est sérialisé à la lecture, mais expurgé.Les méthodes get/list de l’agent renvoient mcp_config uniquement aux appelants autorisés à consulter les secrets de l’agent ; sinon, le champ est null et mcp_config_redacted est vrai. Les acteurs de l’agent ne le voient jamais , et un espace de travail peut forcer l’expurgation pour tout le monde.

La prise en charge par les fournisseurs n’est pas uniforme : Qwen Code accepte un mcp_config géré via un fichier JSON temporaire 0600 appartenant au démon et transmis avec l’option --mcp-config; il est supprimé à la fin de l’exécution. Laissez le champ non défini (null) pour hériter des paramètres natifs de Qwen Code.

Liaison des compétences

La création d’un agent ne lie AUCUNE compétence de l’espace de travail — le liaison est un appel distinct effectué après la création de l’agent. Deux verbes distincts :

• add est additif — il fusionne les identifiants fournis avec les liaisons existantes (POST /api/agents/{id}/skills/add).
• set remplace tout — il écrase l’intégralité de la liste de liaisons par exactement les identifiants fournis (PUT /api/agents/{id}/skills) ; --skill-ids '' efface tout.

multica agent skills add  --skill-ids  --output json
multica agent skills list  --output json

Au moment de la requête, le démon assemble d’abord les compétences de l’agent en tant que compétences liées à l’espace de travail, puis ajoute les compétences intégrées à la plateforme. La fonction `LoadAgentSkills` charge le contenu de chaque compétence liée ainsi que ses fichiers associés ; les compétences intégrées sont intégrées au moment de la compilation et chargées à partir du fichier `SKILL.md` et des fichiers associés. Les deux parviennent au fournisseur sous forme de contenu de compétence — c’est pourquoi la capacité doit figurer dans une compétence liée, et non être insérée dans les instructions.

Effets secondaires nécessitant une validation

En lecture seule (sans risque) : récupération de l’agent, liste des compétences de l’agent, récupération de l’environnement de l’agent.

Modification d’état (nécessite une instruction explicite — ne pas exécuter de manière spéculative) :

• multica agent create — insère une nouvelle ligne d’agent.
• multica agent skills add / set — modifie les liaisons (set est destructif : il supprime les liaisons qui ne figurent pas dans la nouvelle liste).
• multica agent env set — écrase l’intégralité de la carte custom_env et écrit une ligne d’audit.

Idées fausses courantes

• «La description correspond à l’invite. » Ce n’est pas le cas — seules les instructions parviennent à l’ environnement d’exécution. Une description détaillée avec des instructions vides génère un shell nommé sans contrat d’exploitation.
• « La commande create lie les compétences de l’agent. » Ce n’est pas le cas ; effectuez la liaison explicitement par la suite.
• «La mise à jour de l’agent peut modifier l’environnement. » Ce n’est pas le cas — elle renvoie un code d’erreur 400 sur custom_env; utilisez le point de terminaison env.
• «mcp_config se comporte comme custom_env lors d’une mise à jour. » Ce n’est pas le cas — mcp_config PEUT être configuré via agent update (--mcp-config), avec --mcp-config null pour effacer ; seul custom_env est géré par le point de terminaison env dédié.
• «La commande get de l’agent affiche les valeurs d’environnement. » Elle n’affiche que has_custom_env et custom_env_key_count.
• « Une combinaisonthinking_level/model non valide est détectée lors de la création. » Seul un littéral inconnu au niveau du fournisseur l’est — les incohérences spécifiques au modèle échouent lors de l’exécution.
• «set et add sont interchangeables pour les compétences. » set remplace toutes les liaisons ; l’utiliser alors que vous vouliez utiliser add supprime silencieusement des capacités.

Références

references/creating-agents-source-map.md établit une correspondance entre chaque contrat ci-dessus et son fichier : ligne dans l’arborescence actuelle, l’effet en exécution et une commande de vérification sûre en lecture seule.