# Agentenberechtigungen

Was ein Agent tun darf, wer dies entscheidet und was die Person, die ihn ausführt, dazu beiträgt.

Canonical page: https://beeuni.ai/docs/de/project/permissions

Ein Agent agiert in deinem Projekt über die CLI, die API, Git, Connectors und
Apps. Auf dieser Seite wird erklärt, wie Beeuni entscheidet, was ein Agent tun darf.

**Ein Agent handelt als er selbst, nicht als die Person, die ihn gestartet hat.** Seine Berechtigungen sind seine Beeuni-Berechtigungen ∩ seine Deckenrolle. Allein die Berechtigungen entscheiden, genau wie bei einer Person. Niemand
leiht einem Agenten die eigene Rolle, daher tut der Agent dasselbe, unabhängig davon, wer ihn ausführt.

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

## Der Agent ist der handelnde Principal

Jede Agentensitzung hat zwei Identitäten:

| Identität | Was sie bestimmt |
|---|---|
| **Handelnder Principal — der Agent** | Alles auf gemeinsam genutzten Ressourcen: Projektberechtigungen, gemeinsam genutzte Connector-Konten, Projekt-Secrets, Apps, Git. |
| **Im Auftrag von — die Person** | Nur die eigenen Ressourcen dieser Person und nur in ihrer eigenen privaten Sitzung. |

Jeder Agent hat pro Projekt eine Identität: ein Dienstkonto, das Beeuni für ihn erstellt. Du erhältst nie Zugangsdaten dafür.

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

## Beeuni-Berechtigungen — das Manifest entscheidet

Jeder Agent deklariert seine Beeuni-Berechtigungen in `beeuni.yaml` unter
`agents.<name>.beeuni_permissions`. Das Manifest im Standardbranch ist die
maßgebliche Quelle.

```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]
```

- Die Liste verweigert standardmäßig alles. Ein Agent ohne `beeuni_permissions` erhält keine Berechtigungen.
- `all` gewährt jede Projektberechtigung, bleibt aber durch die Decke begrenzt.
- `beeuni_cli` ist die veraltete Schreibweise. Sie wird weiterhin validiert, mit einer Warnung.
  Beide Schlüssel mit unterschiedlichen Werten bei einem Agenten führen zu einem Validierungsfehler.

Bearbeite die Liste unter **Customize → Agents → dem Agenten → Beeuni permissions**. Beim Speichern wird `beeuni.yaml` committet. Siehe [die Manifestreferenz](/docs/de/project/manifest).

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

## Die Decke — ein Admin entscheidet

Die Decke ist eine Projektrolle, die ein Admin an das Dienstkonto des Agenten bindet. Die Beeuni-Berechtigungen des Agenten überschreiten sie nie.

- **Keine Rolle gebunden:** Es gilt die standardmäßige Agentendecke. Sie umfasst alle Projektberechtigungen außer `project.credentials.issue`.
- **Eine Rolle gebunden:** Die integrierte Rolle `member` oder `manager` oder eine benutzerdefinierte Rolle. Der Agent behält nur die Beeuni-Berechtigungen, die auch von der Rolle gewährt werden.
- Eine Decke fügt niemals eine Berechtigung hinzu. Eine Decke vom Typ `manager` gewährt einem Agenten keine Berechtigung, die nicht in seinem Manifest aufgeführt ist.

Lege die Decke unter **Access hub → Projects → dem Projekt → Add** fest. Wähle den Agenten unter **Agents** aus und lege eine Rolle fest. Nur Admins, die Rollen verwalten, sehen Agenten in der Auswahl. In der Zugriffsliste des Projekts wird die Decke jedes Agenten mit einem **Agent**-Badge angezeigt.

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

## `all` bedeutet jede Berechtigung

`beeuni_permissions: all`, `"*"` und jede Liste, die `"*"` enthält, bedeuten dasselbe: alle Projektberechtigungen. Dazu gehören `project.members.manage` (Projektmitglieder und Berechtigungen hinzufügen, ändern oder entfernen) und `project.delete`.

Eine Berechtigung bleibt Menschen vorbehalten: `project.credentials.issue` (ein Projekttoken oder ein projektspezifisches PAT ausstellen). Ein von einem Agenten ausgestelltes Token hätte keine Agentenberechtigungen und würde daher außerhalb dieser Berechtigungen handeln. Die Ablehnung beantwortet `403` mit `code: "agent_human_only_action"`.

Ein Eintrag, der keine gewährbare Berechtigung ist, wird zur Laufzeit ignoriert; der Rest der Liste gilt weiterhin. `beeuni validate` und das Zusammenführen eines Änderungsantrags melden ihn als Fehler.

`project.read` gilt umgekehrt: Ein Agent besitzt diese Berechtigung immer innerhalb seines eigenen Projekts.

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

## Wer einen Agenten ausführt, verleiht ihm keine eigenen Berechtigungen

Die Person, die einen Agenten ausführt, begrenzt ihn nicht. Das Recht, einen Agenten auszuführen, ist also die Delegation. Beeuni prüft an jedem Einstiegspunkt: „Darf diese Person diesen Agenten ausführen?“

| Einstiegspunkt | Erforderlich |
|---|---|
| Sitzung erstellen, starten oder ihr einen Prompt senden; Agent wechseln | Die Person darf den Agenten ausführen |
| Einen Trigger manuell auslösen | Die Person, die ihn auslöst, darf den Agenten des Triggers ausführen |
| Eine untergeordnete Sitzung aus einer Agentensitzung starten | Die Person hinter der übergeordneten Sitzung darf den Agenten der untergeordneten Sitzung ausführen. Gibt es keine Person dahinter, ist nur derselbe Agent zulässig. |

Gewähre das Recht „darf ausführen“ im Tab **People** des Agenten oder im Access hub. Agenten sind standardmäßig geschlossen: Ein Mitglied darf einen Agenten nur ausführen, wenn eine Zuweisung es selbst oder eine seiner Gruppen nennt.

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

## Persönliche Ressourcen bleiben persönlich

Eine Agentensitzung kann nur dann auf eine Ressource zugreifen, die einer Person gehört, wenn beides zutrifft:

1. Die Sitzung wird im Auftrag dieser Person ausgeführt.
2. Die Sitzung ist privat.

Zu den persönlichen Ressourcen gehören mitgliedereigene Connector-Verbindungen, persönliche Projekt-Secrets, persönliche Provider-Schlüssel und der eigene Computer der Person. Auf sie kann weder über eine gemeinsam genutzte Sitzung noch über eine Trigger- oder Kanalsitzung noch über einen unbeaufsichtigten Lauf zugegriffen werden.

Wenn eine andere Person einer privaten Sitzung einen Prompt sendet — zum Beispiel ein Kontoadministrator, der die privaten Sitzungen von Mitgliedern öffnen kann — handelt die Sitzung dauerhaft nicht mehr im Auftrag ihres Erstellers. Der Agent behält seine eigenen Berechtigungen. Die Person, die den Prompt sendet, handelt niemals über die Konten einer anderen Person.

## Apps

Ein Agent öffnet eine eingeschränkte oder private [App](/docs/de/feature-flags/apps) nur dann, wenn seine `apps:`-Freigabe den Slug der App nennt oder `all` lautet und seine effektiven Berechtigungen `project.app.read` umfassen.

| App-Zugriffsmodus | Der Agent erhält Zugriff, wenn |
|---|---|
| Öffentlich | Immer |
| Projekt | `project.app.read` effektiv ist |
| Eingeschränkt oder privat | Der Slug in `apps:` steht und `project.app.read` effektiv ist |
| Passwort | Nie |

Der **Access**-Dialog der App führt die Agenten mit Zugriff auf, ermittelt aus `agents.<name>.apps`. Ändere die Liste auf der **Apps**-Seite des Agenten (Customize → Agents → dem Agenten → Apps), mit `beeuni agents scope <agent> --apps <slug,slug>` oder über einen Änderungsantrag an `beeuni.yaml`. Die Apps-Seite wird nur angezeigt, wenn im Projekt das Feature-Flag [Apps](/docs/de/feature-flags/apps) aktiviert ist.

## Backends

Ein Projekt kann Verwaltete Projekt-Backends besitzen. Für sie gelten zwei Berechtigungen. Sie entsprechen den Apps-Berechtigungen: Eine Rolle mit `project.app.read` oder `project.app.write` besitzt auch die passende Backend-Berechtigung.

| Berechtigung | Ermöglicht |
|---|---|
| `project.backend.read` | Backends des Projekts auflisten und prüfen: Name, Status und URL |
| `project.backend.write` | Backends erstellen und löschen sowie die Admin-Zugangsdaten eines Backends lesen. Beinhaltet `project.backend.read` |

Der Administratorschlüssel ermöglicht die vollständige Kontrolle über Daten und Code eines Backends. Daher ist zum Lesen `project.backend.write` erforderlich. Die integrierte Manager-Rolle besitzt beide Berechtigungen. Die integrierte Member-Rolle besitzt `project.backend.read`.

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

## Agenten und Trigger ändern

`beeuni.yaml` bestimmt, was Agenten tun dürfen. Wer also eine Änderung im Standardbranch einspielt, bestimmt, was Agenten tun dürfen. Für Agenten und Personen gelten dieselben Berechtigungen:

1. Zum Zusammenführen eines Änderungsantrags ist `project.gitops.merge` erforderlich.
2. Ändert ein Merge `beeuni.yaml`, ist außerdem die Berechtigung erforderlich, die der direkte Weg für diese Änderung voraussetzt: `agents.*` → `project.agent.write`;
   `triggers` → `project.trigger.create`, `.update` oder `.delete`;
   `default_agent` → `project.agent.write`. Die Manager-Rolle besitzt diese Berechtigungen, und der Rollen-Editor fügt sie jeder Rolle hinzu, der `project.gitops.merge` gewährt wird. Sie müssen in den `beeuni_permissions` des Agenten aufgeführt sein oder dieser muss `all` sein. Ein Agent, der nur zusammenführen darf, kann sich also nicht selbst mehr Rechte verschaffen.
3. Ein Agent gewährt nur, was er selbst besitzt. Wenn ein Agent die Berechtigungen eines Agenten festlegt (im Agenten-Editor, über die Routen für Geltungsbereiche und Secret-Freigaben oder durch einen von ihm zusammengeführten Änderungsantrag), muss jede durch die Änderung hinzugefügte Berechtigung, jeder Connector, jedes Secret und jede App in den eigenen effektiven Berechtigungen des ändernden Agenten enthalten sein. Zum Gewähren von `all` sind sie alle erforderlich. Das Einschränken oder Entfernen einer Freigabe ist immer zulässig. Eine Ablehnung beantwortet `403` mit `code: "agent_grant_escalation"`.
4. Ein direkter Push in den Standardbranch umgeht den Änderungsantrag. Eine Agentensitzung benötigt `project.gitops.ref.any` und alle Berechtigungen aus Punkt 2. Das gepushte Manifest kann vor dem Einspielen nicht geprüft werden. Daher muss der Agent auch jede Freigabe besitzen (Berechtigungen, Connectoren, Secrets und Apps aus `all`). Andernfalls wird ein Änderungsantrag geöffnet.
5. Eine Ablehnung beantwortet `403` mit `code: "agent_scope_insufficient"` (Agent) oder `"project_role_insufficient"` (Person) sowie der fehlenden `action`. Kann das Manifest nicht gelesen werden, beantwortet der Merge `503` mit `code: "CR_GOVERNANCE_UNVERIFIED"` und `Retry-After`. Versuche es erneut.
6. Die Decke ist ein IAM-Status, der nur von Admins festgelegt werden kann. Das Manifest überschreitet sie niemals.

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

## Eine Ablehnung verstehen

Jede `403` aus einer Autorisierungsprüfung enthält `code` und `action`:

| `code` | Bedeutung | Lösung |
|---|---|---|
| `agent_scope_insufficient` | `action` ist nicht in den Beeuni-Berechtigungen des Agenten enthalten | Füge es zu `agents.<name>.beeuni_permissions` hinzu |
| `agent_ceiling_insufficient` | `action` liegt außerhalb der Deckenrolle des Agenten | Ein Admin hebt die Decke an |
| `agent_not_accessible` | Die Person darf diesen Agenten nicht ausführen | Gewähre der Person Zugriff auf den Agenten |
| `agent_grant_escalation` | Durch die Änderung erhält ein Agent etwas, das der ändernde Agent selbst nicht besitzt | Gewähre nur, was der ändernde Agent besitzt, oder lass die Änderung von einer Person vornehmen |
| `project_role_insufficient` | Die eigene Rolle der Person verweigert `action` | Ändere die Projektrolle der Person |

## Audit

Jede Agentenaktion erfasst drei Felder: `actor` ist der Agent,
`on_behalf_of` ist die Person oder `null`, und `initiator` ist `human`,
`trigger` oder `channel`. Bei einem Trigger-Lauf wird keine Person erfasst.

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

## Im Dashboard ansehen

Öffne **Customize → Agents → dem Agenten → Beeuni permissions**. Das Panel **Was dieser Agent tun kann** zeigt:

- die in `beeuni.yaml` deklarierten Beeuni-Berechtigungen,
- die Deckenrolle oder **Standardmäßige Agentendecke**,
- die einzige Berechtigung, die Menschen vorbehalten ist: `project.credentials.issue`,
- die effektiven Berechtigungen: „Personen, die diesen Agenten ausführen dürfen, handeln mit diesen Berechtigungen.“

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

## Geltungsbereich

Diese Seite gilt für jeden Agenten, den ein Projekt unter `agents:` in
`beeuni.yaml` deklariert. Ein Projekt ohne `agents:`-Zuordnung deklariert keinen verwalteten Agenten, daher muss nichts aktiviert werden. Es gibt keine Möglichkeit, zum alten Modell mit Launcher-Rollen zurückzukehren.