# エージェントの権限

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

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

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

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

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

## 操作主体はエージェント

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

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

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

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

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

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

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

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

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

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

## 上限 — 管理者が決定

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<a id="apps"></a>

## アプリ

エージェントが制限付きまたはプライベートの[アプリ](/docs/ja/feature-flags/apps)を開けるのは、その`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](/docs/ja/feature-flags/apps)の機能フラグがオンの場合にのみ表示されます。

<a id="backends"></a>

## バックエンド

プロジェクトは、マネージドバックエンドを所有できます。これらを制御する権限は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`を持ちます。

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

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

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

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

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

## 拒否の内容を確認する

認証チェックで発生するすべての`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`を拒否している | その人のプロジェクトロールを変更する |

<a id="audit"></a>

## 監査

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

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

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

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

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

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

## 適用範囲

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