Agentenberechtigungen

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

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.

Der Agent ist der handelnde Principal

Jede Agentensitzung hat zwei Identitäten:

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

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.

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.

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.

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.

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?“

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.

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 nur dann, wenn seine apps:-Freigabe den Slug der App nennt oder all lautet und seine effektiven Berechtigungen project.app.read umfassen.

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 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.

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.

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.

Eine Ablehnung verstehen

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

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.

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.“

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.