エージェントの権限

エージェントが実行できること、それを決定する人、そして実行する人が提供するもの。

エージェントは、CLI、API、git、コネクタ、アプリを通じてプロジェクト上で操作します。このページでは、Beeuniがエージェントに許可する操作をどのように決定するかを説明します。

エージェントは、起動した人ではなく、エージェント自身として操作します。 エージェントの権限は、Beeuni権限 ∩ 上限ロールです。人の場合と同じように、権限だけで決まります。エージェントに他の人のロールが貸与されることはないため、誰が実行してもエージェントの操作は同じです。

操作主体はエージェント

すべてのエージェントセッションには、2つのIDがあります。

ID	決定する対象
操作主体 — エージェント	共有リソースに関するすべて：プロジェクト権限、共有コネクタアカウント、プロジェクトシークレット、アプリ、git。
代理する人 — 人	その人自身のリソースのみ。かつ、その人自身のプライベートセッション内に限ります。

各エージェントは、プロジェクトごとに1つのIDを持ちます。これはBeeuniがエージェント用に作成するサービスアカウントです。このアカウントの認証情報を持つことはありません。

Beeuni権限 — マニフェストで決定

各エージェントは、agents.<name>.beeuni_permissions配下のbeeuni.yamlでBeeuni権限を宣言します。デフォルトブランチ上のマニフェストが正とされます。

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]

リストはデフォルトで拒否されます。beeuni_permissionsがないエージェントには、権限が一切ありません。
allは、上限の範囲内で、すべてのプロジェクト権限を付与します。
beeuni_cliは非推奨の表記です。引き続き検証に通りますが、警告が表示されます。同じエージェントに異なる値を持つ両方のキーを設定すると、検証エラーになります。

Customize → Agents → エージェント → Beeuni permissionsでリストを編集します。保存するとbeeuni.yamlがコミットされます。マニフェストのリファレンスを参照してください。

上限 — 管理者が決定

上限とは、管理者がエージェントのサービスアカウントに割り当てるプロジェクトロールです。エージェントのBeeuni権限は、上限を超えることはありません。

**ロールが割り当てられていない場合：**デフォルトのエージェント上限が適用されます。project.credentials.issueを除くすべてのプロジェクト権限です。
**ロールが割り当てられている場合：**組み込みのmemberまたはmanager、あるいはカスタムロールが適用されます。エージェントが保持するのは、そのロールでも付与されているBeeuni権限のみです。
上限によって権限が追加されることはありません。manager上限を設定しても、マニフェストに記載されていない権限がエージェントに付与されることはありません。

Access hub → Projects → プロジェクト → Addで上限を設定します。Agentsでエージェントを選択し、ロールを選びます。ロールを管理する管理者だけが、選択リストにエージェントを表示できます。プロジェクトのアクセスリストでは、各エージェントの上限にAgentバッジが表示されます。

`all`はすべての権限を意味する

beeuni_permissions: all、"*"、および"*"を含むすべてのリストは、同じくすべてのプロジェクト権限を意味します。project.members.manage（プロジェクトメンバーと付与権限の追加、変更、削除）およびproject.deleteも含まれます。

人だけが持つ権限が1つあります。project.credentials.issue（プロジェクトトークンまたはプロジェクトスコープのPATを発行する権限）です。エージェントが発行したトークンにはエージェントの権限が一切含まれないため、その権限の範囲外で操作することになります。拒否された場合は、403にcode: "agent_human_only_action"を返します。

付与可能な権限ではない項目は、実行時に無視され、リストの残りは引き続き適用されます。beeuni validateと変更リクエストのマージでは、その項目がエラーとして報告されます。

project.readは逆に、エージェントが自身のプロジェクト内で常に保持する権限です。

エージェントの実行には、その権限を委ねる

エージェントを実行する人が、エージェントの権限に上限を設けることはありません。したがって、エージェントを実行する権利が権限の委譲にあたります。Beeuniは、すべての入口で「この人はこのエージェントを実行できるか」を確認します。

入口	必要な条件
セッションの作成、開始、プロンプト送信、またはエージェントの切り替え	その人がエージェントを実行できること
トリガーの手動実行	実行する人が、そのトリガーのエージェントを実行できること
エージェントセッションから子セッションを開始	親セッションの背後にいる人が、子セッションのエージェントを実行できること。そのような人がいない場合は、同じエージェントに限られます。

エージェントのPeopleタブまたはAccess hubで、「実行できる」権限を付与します。エージェントはデフォルトで非公開です。メンバーがエージェントを実行できるのは、そのメンバー本人または所属グループを指定する割り当てがある場合に限られます。

個人リソースは個人のもの

エージェントセッションが特定の人の所有するリソースにアクセスできるのは、次の両方を満たす場合だけです。

その人を代理してセッションが実行されている。
セッションがプライベートである。

個人リソースには、メンバー所有のコネクタ接続、個人用プロジェクトシークレット、個人用プロバイダーキー、およびその人自身のコンピューターがあります。共有セッション、トリガーまたはチャネルのセッション、および無人実行では、これらのリソースには一切アクセスできません。

別の人がプライベートセッションでプロンプトを送信した場合（たとえば、メンバーのプライベートセッションを開けるアカウント管理者の場合）、そのセッションは作成者を代理して操作しなくなり、その状態は元に戻りません。エージェントは自身の権限を保持します。プロンプトを送信する人が、他の人のアカウントを通じて操作することはありません。

アプリ

エージェントが制限付きまたはプライベートのアプリを開けるのは、そのapps:付与にアプリのスラッグが指定されているか、allであり、かつ有効な権限にproject.app.readが含まれる場合だけです。

アプリのアクセスモード	エージェントがアクセスできる条件
公開	常に
プロジェクト	`project.app.read`が有効である
制限付きまたはプライベート	スラッグが`apps:`に含まれ、`project.app.read`が有効である
パスワード	なし

アプリのAccessダイアログには、agents.<name>.appsから読み込まれた、アクセス権のあるエージェントが表示されます。リストは、エージェントのAppsページ（Customize → Agents → エージェント → Apps）でbeeuni agents scope <agent> --apps <slug,slug>を使って、またはbeeuni.yamlへの変更リクエストで変更します。Appsページは、プロジェクトでAppsの機能フラグがオンの場合にのみ表示されます。

バックエンド

プロジェクトは、マネージドバックエンドを所有できます。これらを制御する権限は2つあります。アプリの権限と同様に、project.app.readまたはproject.app.writeを持つロールは、対応するバックエンド権限を持ちます。

権限	許可される操作
`project.backend.read`	プロジェクトのバックエンドの一覧表示と詳細の確認：名前、ステータス、URL
`project.backend.write`	バックエンドの作成と削除、およびバックエンドの管理者認証情報の読み取り。`project.backend.read`も含みます。

管理者キーを使うとバックエンドのデータとコードを完全に制御できるため、その読み取りにはproject.backend.writeが必要です。組み込みのManagerロールは両方の権限を持ちます。組み込みのMemberロールはproject.backend.readを持ちます。

エージェントとトリガーの変更

beeuni.yamlによってエージェントができることが決まるため、デフォルトブランチに変更を反映する人がエージェントの権限を左右します。エージェントにも人にも、同じ権限が適用されます。

変更リクエストのマージにはproject.gitops.mergeが必要です。
マージによってbeeuni.yamlが変更される場合は、その変更を直接行うために必要な権限も必要です。agents.* → project.agent.write；triggers → project.trigger.create、.update、または.delete；default_agent → project.agent.write。Managerロールはこれらの権限を持ち、ロールエディターはproject.gitops.mergeを受け取るロールにこれらを追加します。エージェントのbeeuni_permissionsにこれらが記載されているか、allである必要があります。したがって、マージのみを許可されたエージェントが、自身の権限を拡大することはできません。
エージェントが付与できるのは、自身が保持する権限だけです。エージェントが他のエージェントへの付与を書き込む場合（エージェントエディター、スコープおよびシークレット付与のルート、または自身がマージする変更リクエスト）、書き込みによって追加する権限、コネクタ、シークレット、アプリはすべて、書き込みを行うエージェント自身の有効な付与に含まれていなければなりません。allを付与するには、そのすべてが必要です。付与範囲を狭める、または付与を削除する操作は常に許可されます。拒否された場合は、403にcode: "agent_grant_escalation"を返します。
デフォルトブランチへの直接プッシュでは、変更リクエストが省略されます。エージェントセッションにはproject.gitops.ref.anyと、項目2にあるすべての権限が必要です。プッシュされたマニフェストは反映前に検証できないため、エージェントは付与されるすべての権限（all権限、コネクタ、シークレット、アプリ）も保持していなければなりません。そうでない場合は、変更リクエストが作成されます。
拒否された場合は、403にcode: "agent_scope_insufficient"（エージェント）または"project_role_insufficient"（人）と、不足しているactionを返します。マニフェストを読み取れない場合、マージは503にcode: "CR_GOVERNANCE_UNVERIFIED"とRetry-Afterを返します。再試行してください。
上限は管理者専用のIAM状態です。マニフェストが上限を超えることはありません。

拒否の内容を確認する

認証チェックで発生するすべての403には、codeとactionが含まれます。

`code`	意味	対処方法
`agent_scope_insufficient`	`action`がエージェントのBeeuni権限に含まれていない	`agents.<name>.beeuni_permissions`に追加する
`agent_ceiling_insufficient`	`action`がエージェントの上限ロールの範囲外である	管理者が上限を引き上げる
`agent_not_accessible`	その人はこのエージェントを実行できない	その人にエージェントの実行権限を付与する
`agent_grant_escalation`	この書き込みによって、書き込みを行うエージェントが保持していない権限が別のエージェントに付与される	書き込みを行うエージェントが保持する権限だけを付与するか、人が変更を行う
`project_role_insufficient`	その人自身のロールが`action`を拒否している	その人のプロジェクトロールを変更する

監査

すべてのエージェント操作には3つのフィールドが記録されます。actorはエージェント、on_behalf_ofは人またはnull、initiatorはhuman、trigger、またはchannelです。トリガー実行には人が記録されません。

ダッシュボードで確認する

Customize → Agents → エージェント → Beeuni permissionsを開きます。このエージェントにできることパネルには、次の情報が表示されます。

beeuni.yamlで宣言されたBeeuni権限
上限ロール、またはデフォルトのエージェント上限
人だけに許可された権限、project.credentials.issue
有効な権限：「このエージェントを実行できる人は、これらの権限で操作します。」

適用範囲

このページは、beeuni.yaml内のagents:でプロジェクトが宣言するすべてのエージェントに適用されます。agents:マップのないプロジェクトは、管理対象のエージェントを宣言していないため、有効にするものはありません。以前のランチャーロール方式に戻す切り替えはありません。