Agents

Un agente es un archivo Markdown que ejecuta el entorno de sesión; el manifiesto solo controla su acceso.

Un agent est un fichier Markdown qui définit le comportement du moteur dans une session. Cette page présente les fichiers d’agent, les compétences et la façon dont une session choisit un agent.

Un moteur exécute chaque session

Une session utilise un moteur d’agent : harness standard (par défaut) ou harness expérimental. Les moteurs indiquent comment un projet en sélectionne un et ce que chacun prend en charge.

Les deux lisent les agents du projet dans agents/ et ses compétences dans skills/. harness standard lit aussi les fichiers qu’il est le seul à utiliser dans harnesses/opencode/. harness expérimental lit les siens dans harnesses/pi/.

Les projets créés avant 2026-09 conservent leurs agents et leurs compétences dans .beeuni/opencode/. Beeuni prend en charge les deux structures.

Un agent se compose de deux fichiers

Chaque agent comporte deux parties :

Comportement — un fichier Markdown, agents/<name>.md par défaut. Ses métadonnées définissent le modèle, le mode et les règles d’autorisation. Son corps constitue le prompt système.
Gouvernance — une entrée dans la map agents de beeuni.yaml, indexée par le nom de l’agent. Elle définit les accès autorisés à l’agent : connecteurs, secrets, compétences, Apps, autorisations Beeuni et outils. Son champ file indique le fichier de comportement. La map peut se trouver dans un fichier que le manifeste répertorie sous imports: ; default_agent reste dans beeuni.yaml.

Le manifeste ne définit jamais de prompt ni de mode. Le fichier .md ne définit jamais les accès à la plateforme. Consultez la référence du manifeste pour connaître tous les champs de gouvernance.

Emplacement du fichier d’agent

agents:
  support:
    file: agents/support.md

file est un chemin relatif au dépôt. Il doit se terminer par .md.
Il ne doit pas commencer par /. Il ne doit contenir aucun segment . ou ...
En l’absence de file, Beeuni lit agents/<name>.md, puis .beeuni/opencode/agents/<name>.md.
Lorsque le tableau de bord enregistre un agent doté de .md, il écrit file avec ce chemin.
L’API refuse de modifier file. Pour déplacer un agent, déplacez son .md et mettez à jour file dans beeuni.yaml au cours du même commit.

Les règles complètes sur les chemins figurent dans la référence du manifeste.

La gouvernance refuse tout accès par défaut

Un agent sans clé connectors, secrets, skills, apps ou beeuni_permissions ne bénéficie d’aucun de ces accès. apps répertorie les Apps Beeuni que l’agent peut ouvrir lorsqu’une App est restreinte ou privée. Cette autorisation constitue la deuxième des deux associations : l’agent détient aussi un rôle de principal service_account — son plafond d’accès — et une session ne peut faire que ce que les deux autorisent. Consultez Autorisations des agents et Un vocabulaire, deux associations. Définissez un champ sur all pour accorder un accès complet, ou indiquez des noms précis. default_agent dans beeuni.yaml désigne l’agent qu’une session lance si vous n’en demandez aucun.

Définissez chaque autorisation depuis le tableau de bord — Customize → Agents → l’agent, une page par ensemble d’autorisations dans la barre Accès : Skills, Connectors, Secrets, Apps, Beeuni permissions — ou depuis la CLI avec beeuni agents scope <agent> (--secrets, --connectors, --apps). La page Apps n’apparaît que lorsque le feature flag Apps du projet est activé. Quel que soit le chemin utilisé, le même bloc agents.<name> est écrit dans beeuni.yaml.

Les projets hérités beeuni.toml (v1) répertorient les agents dans un tableau plutôt que dans une map et accordent un accès complet par défaut. Définissez des autorisations précises pour restreindre l’accès. Consultez la référence du manifeste.

Les compétences apportent du savoir-faire à un agent

Une compétence est un fichier Markdown situé dans skills/<name>/SKILL.md. Le moteur charge les compétences à la demande : Beeuni n’injecte pas leur contenu dans chaque prompt. Avec harness standard, l’agent appelle l’outil skill. Avec harness expérimental, le prompt système répertorie le nom et la description de chaque compétence, et l’agent lit le fichier. L’autorisation skills de l’agent dans beeuni.yaml détermine les compétences qu’il peut charger.

Comment une session choisit son agent

La création d’une session accepte un agent_name. Beeuni lance cet agent pour la session. Si vous omettez agent_name, Beeuni utilise default_agent du projet. Définissez l’agent par défaut depuis le tableau de bord, l’API ou le SDK. Chaque méthode écrit default_agent dans beeuni.yaml et valide la modification sur la branche par défaut du projet.

Un agent agit en son propre nom : il utilise ses autorisations Beeuni dans les limites de son rôle, quel que soit l’utilisateur qui le lance. Le démarrage d’une session ne prête pas à l’agent votre propre rôle. Consultez Autorisations des agents.

Les agents et les compétences nouveaux ou modifiés ne sont disponibles pour les sessions suivantes qu’après la fusion d’une demande de modification dans la branche par défaut. Connectez les outils externes avant qu’un agent puisse les utiliser ; consultez Connecteurs.