---
title: "Autorisations de l’agent"
description: "Ce qu’un agent peut faire, qui en décide et ce que la personne qui l’exécute apporte."
---

Un agent intervient sur votre projet par l’intermédiaire de l’interface CLI, de l’API, de git, des connecteurs et des Apps. Cette page explique comment Beeuni détermine ce qu’un agent peut faire.

**Un agent agit en son nom, et non au nom de la personne qui l’a lancé.** Son autorité correspond à ses autorisations Beeuni ∩ à son rôle plafond. Les autorisations suffisent à déterminer ce qu’il peut faire, comme pour une personne. Personne ne prête son propre rôle à un agent : celui-ci agit donc de la même manière, quelle que soit la personne qui l’exécute.

<a id="the-agent-is-the-acting-principal"></a>

## L’agent est l’entité qui agit

Chaque session d’agent a deux identités :

| Identité | Ce qu’elle détermine |
|---|---|
| **Entité agissante — l’agent** | Tout ce qui concerne les ressources partagées : autorisations du projet, comptes de connecteurs partagés, secrets du projet, Apps, git. |
| **Pour le compte de — la personne** | Uniquement les ressources personnelles de cette personne, et seulement dans sa propre session privée. |

Chaque agent a une identité par projet : un compte de service que Beeuni crée pour lui. Vous ne détenez jamais ses identifiants.

<a id="beeuni-permissions--the-manifest-decides"></a>

## Autorisations Beeuni — le manifeste fait foi

Chaque agent déclare ses autorisations Beeuni dans `beeuni.yaml`, sous `agents.<name>.beeuni_permissions`. Le manifeste de la branche par défaut fait foi.

```yaml
agents:
  report-writer:
    beeuni_permissions: [project.file.read, project.connector.read, project.app.read]
    connectors: [reports-dashboard-api]
    secrets: [REPORTS_API_KEY]
    apps: [reports-dashboard]
```

- La liste refuse tout par défaut. Un agent sans `beeuni_permissions` n’obtient aucune autorisation.
- `all` accorde toutes les autorisations du projet, toujours dans les limites du rôle plafond.
- `beeuni_cli` est l’ancienne syntaxe, désormais obsolète. Elle reste valide, avec un avertissement. Si les deux clés ont des valeurs différentes pour un même agent, la validation échoue.

Modifiez la liste dans **Customize → Agents → l’agent → Beeuni permissions**. L’enregistrement crée un commit de `beeuni.yaml`. Consultez [la référence du manifeste](/docs/fr/project/manifest).

<a id="the-ceiling--an-admin-decides"></a>

## Le rôle plafond — un administrateur en décide

Le rôle plafond est un rôle du projet qu’un administrateur associe au compte de service de l’agent. Les autorisations Beeuni de l’agent ne peuvent jamais le dépasser.

- **Aucun rôle associé :** le rôle plafond par défaut de l’agent s’applique. Il comprend toutes les autorisations du projet, à l’exception de `project.credentials.issue`.
- **Un rôle est associé :** `member` ou `manager`, un rôle prédéfini, ou un rôle personnalisé. L’agent ne conserve que les autorisations Beeuni également accordées par ce rôle.
- Un rôle plafond n’ajoute jamais d’autorisation. Un rôle plafond `manager` n’accorde pas à l’agent une autorisation absente de son manifeste.

Définissez le rôle plafond dans **Access hub → Projects → le projet → Add**. Sélectionnez l’agent sous **Agents**, puis choisissez un rôle. Seuls les administrateurs qui gèrent les rôles voient les agents dans le sélecteur. La liste d’accès du projet affiche le rôle plafond de chaque agent avec le badge **Agent**.

<a id="all-means-every-permission"></a>

## `all` signifie toutes les autorisations

`beeuni_permissions: all`, `"*"` et toute liste contenant `"*"` ont la même signification : toutes les autorisations du projet. Cela inclut `project.members.manage` (ajouter, modifier ou supprimer des membres du projet et leurs autorisations) et `project.delete`.

Une autorisation reste réservée aux personnes : `project.credentials.issue` (créer un jeton de projet ou un PAT limité au projet). Un jeton créé par un agent ne porterait aucune autorisation d’agent, et agirait donc en dehors de celles-ci. Le refus renvoie `403` avec `code: "agent_human_only_action"`.

Une entrée qui ne correspond pas à une autorisation pouvant être accordée est ignorée à l’exécution ; le reste de la liste continue de s’appliquer. `beeuni validate` et une fusion de demande de modification la signalent comme erreur.

`project.read` est l’inverse : un agent la possède toujours au sein de son propre projet.

<a id="running-an-agent-lends-its-authority"></a>

## Exécuter un agent lui confère une autorité

La personne qui exécute un agent ne limite pas ses autorisations. Le droit d’exécuter un agent constitue donc la délégation. Beeuni vérifie « cette personne peut-elle exécuter cet agent ? » à chaque point d’entrée :

| Point d’entrée | Condition requise |
|---|---|
| Créer ou démarrer une session, lui envoyer une invite ; changer d’agent | La personne peut exécuter l’agent |
| Déclencher manuellement un déclencheur | La personne qui le déclenche peut exécuter l’agent associé |
| Démarrer une session enfant depuis une session d’agent | La personne à l’origine de la session parente peut exécuter l’agent de la session enfant. S’il n’y a aucune personne à l’origine de la session, seul le même agent peut le faire. |

Accordez le droit « peut exécuter » dans l’onglet **People** de l’agent ou dans l’Access hub. Par défaut, les agents sont fermés : un membre ne peut exécuter un agent que si une attribution le désigne, lui ou l’un de ses groupes.

<a id="personal-resources-stay-personal"></a>

## Les ressources personnelles restent personnelles

Une session d’agent n’accède à une ressource appartenant à une personne que si les deux conditions suivantes sont réunies :

1. La session s’exécute pour le compte de cette personne.
2. La session est privée.

Les ressources personnelles comprennent les connexions de connecteurs appartenant à un membre, les secrets personnels du projet, les clés personnelles du fournisseur et l’ordinateur de la personne. Une session partagée, une session de déclencheur ou de canal, ainsi qu’une exécution sans supervision n’accèdent à aucune de ces ressources.

Quand une autre personne envoie une invite à une session privée — par exemple, un administrateur de compte qui peut ouvrir les sessions privées des membres —, la session cesse définitivement d’agir pour le compte de son créateur. L’agent conserve ses propres autorisations. La personne qui envoie l’invite n’agit jamais par l’intermédiaire des comptes d’une autre personne.

## Apps

Un agent n’ouvre une [App](/docs/fr/feature-flags/apps) à accès restreint ou privée que si son autorisation `apps:` nomme le slug de l’App ou vaut `all`, et que ses autorisations effectives comprennent `project.app.read`.

| Mode d’accès à l’App | L’agent est admis lorsque |
|---|---|
| Public | Toujours |
| Projet | `project.app.read` est effective |
| Accès restreint ou privé | Le slug figure dans `apps:` et `project.app.read` est effective |
| Mot de passe | Jamais |

La boîte de dialogue **Access** de l’App répertorie les agents qui y ont accès, d’après `agents.<name>.apps`. Modifiez la liste dans la page **Apps** de l’agent (Customize → Agents → l’agent → Apps), avec `beeuni agents scope <agent> --apps <slug,slug>`, ou au moyen d’une demande de modification vers `beeuni.yaml`. La page Apps n’apparaît que si le projet a activé l’indicateur de fonctionnalité [Apps](/docs/fr/feature-flags/apps).

## Backends

Un projet peut posséder des backends de projet gérés. Deux autorisations les régissent. Elles suivent les autorisations Apps : un rôle qui possède `project.app.read` ou `project.app.write` possède l’autorisation Backend correspondante.

| Autorisation | Permet de |
|---|---|
| `project.backend.read` | Répertorier et examiner les Backends du projet : nom, état et URL |
| `project.backend.write` | Créer et supprimer des Backends, et lire les identifiants d’administration d’un Backend. Inclut `project.backend.read` |

La clé d’administration donne le contrôle total des données et du code d’un Backend ; sa lecture nécessite donc `project.backend.write`. Le rôle prédéfini Manager possède les deux autorisations. Le rôle prédéfini Member possède `project.backend.read`.

<a id="changing-agents-and-triggers"></a>

## Modifier des agents et des déclencheurs

`beeuni.yaml` détermine ce que les agents peuvent faire : toute personne qui intègre une modification à la branche par défaut détermine donc ce que les agents peuvent faire. Les mêmes autorisations s’appliquent aux agents et aux personnes :

1. La fusion d’une demande de modification nécessite `project.gitops.merge`.
2. Une fusion qui modifie `beeuni.yaml` nécessite également l’autorisation requise par la voie directe pour cette modification : `agents.*` → `project.agent.write` ; `triggers` → `project.trigger.create`, `.update` ou `.delete` ; `default_agent` → `project.agent.write`. Le rôle Manager possède ces autorisations, et l’éditeur de rôles les ajoute à tout rôle qui obtient `project.gitops.merge`. Le `beeuni_permissions` de l’agent doit les inclure ou valoir `all`. Un agent qui ne peut que fusionner ne peut donc pas étendre ses propres autorisations.
3. Un agent n’accorde que ce qu’il possède. Lorsqu’un agent modifie les autorisations d’un agent (dans l’éditeur d’agents, les routes de portée et d’octroi de secrets, ou une demande de modification qu’il fusionne), chaque autorisation, connecteur, secret et App ajouté doit figurer dans ses propres autorisations effectives. Pour accorder `all`, il doit posséder chacun de ces éléments. La restriction ou la suppression d’une autorisation est toujours permise. Un refus renvoie `403` avec `code: "agent_grant_escalation"`.
4. Un envoi directement vers la branche par défaut contourne la demande de modification. Une session d’agent nécessite `project.gitops.ref.any` et toutes les autorisations du point 2. Comme le manifeste envoyé ne peut pas être vérifié avant son intégration, l’agent doit aussi posséder toutes les autorisations qu’il accorde (autorisations `all`, connecteurs, secrets et Apps). Sinon, il ouvre une demande de modification.
5. Un refus renvoie `403` avec `code: "agent_scope_insufficient"` (agent) ou `"project_role_insufficient"` (personne) et indique l’élément `action` manquant. Si le manifeste ne peut pas être lu, la fusion renvoie `503` avec `code: "CR_GOVERNANCE_UNVERIFIED"` et `Retry-After`. Réessayez.
6. Le rôle plafond est un état IAM réservé aux administrateurs. Le manifeste ne le dépasse jamais.

<a id="read-a-denial"></a>

## Comprendre un refus

Chaque `403` émis par une vérification d’autorisation comprend `code` et `action` :

| `code` | Signification | Solution |
|---|---|---|
| `agent_scope_insufficient` | `action` ne figure pas dans les autorisations Beeuni de l’agent | Ajoutez-le à `agents.<name>.beeuni_permissions` |
| `agent_ceiling_insufficient` | `action` dépasse le rôle plafond de l’agent | Un administrateur relève le rôle plafond |
| `agent_not_accessible` | La personne n’est pas autorisée à exécuter cet agent | Accordez-lui l’accès à l’agent |
| `agent_grant_escalation` | La modification accorde à un agent un droit que l’agent qui la rédige ne possède pas | N’accordez que les droits possédés par la personne qui rédige, ou demandez à une personne d’effectuer la modification |
| `project_role_insufficient` | Le rôle de la personne refuse `action` | Modifiez son rôle dans le projet |

## Audit

Chaque action d’un agent consigne trois champs : `actor` désigne l’agent, `on_behalf_of` désigne la personne ou `null`, et `initiator` vaut `human`, `trigger` ou `channel`. Une exécution par déclencheur ne consigne aucune personne.

<a id="see-it-in-the-dashboard"></a>

## Afficher ces informations dans le tableau de bord

Ouvrez **Customize → Agents → l’agent → Beeuni permissions**. Le panneau **What this agent can do** affiche :

- les autorisations Beeuni déclarées dans `beeuni.yaml`,
- le rôle plafond ou **Default agent ceiling**,
- l’unique autorisation réservée aux personnes, `project.credentials.issue`,
- les autorisations effectives : « Les personnes autorisées à exécuter cet agent agissent avec ces autorisations. »

<a id="scope"></a>

## Portée

Cette page s’applique à tous les agents qu’un projet déclare sous `agents:` dans `beeuni.yaml`. Un projet sans carte `agents:` ne déclare aucun agent régi par ces règles ; il n’y a donc rien à activer. Il n’existe pas de retour à l’ancien modèle de rôle du lanceur.