# Autorizzazioni dell’agente

Cosa può fare un agente, chi lo decide e cosa apporta la persona che lo esegue.

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

Un agente opera sul tuo progetto tramite CLI, API, git, connettori e
app. Questa pagina spiega come Beeuni decide cosa può fare un agente.

**Un agente agisce come se stesso, non come la persona che lo ha avviato.** La sua autorità è data dalle autorizzazioni Beeuni ∩ dal suo ruolo limite. Sono le autorizzazioni a decidere, proprio come per una persona. Nessuno
presta il proprio ruolo a un agente, quindi l'agente si comporta allo stesso modo, chiunque lo esegua.

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

## L'agente è il soggetto che agisce

Ogni sessione di un agente ha due identità:

| Identità | Cosa determina |
|---|---|
| **Soggetto che agisce — l'agente** | Tutto ciò che riguarda le risorse condivise: autorizzazioni del progetto, account dei connettori condivisi, segreti del progetto, app e git. |
| **Per conto di — la persona** | Solo le risorse di quella persona e solo nella sua sessione privata. |

Ogni agente ha una sola identità per progetto: un account di servizio che Beeuni
crea per lui. Non possiedi mai credenziali per quell'account.

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

## Autorizzazioni Beeuni: decide il manifest

Ogni agente dichiara le proprie autorizzazioni Beeuni in `beeuni.yaml`, alla voce
`agents.<name>.beeuni_permissions`. Il manifest nel branch predefinito è la fonte di verità.

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

- L'elenco nega tutto per impostazione predefinita. Un agente senza `beeuni_permissions` non ottiene alcuna autorizzazione.
- `all` concede tutte le autorizzazioni del progetto, sempre entro i limiti del ruolo limite.
- `beeuni_cli` è la forma deprecata. È ancora convalidata, con un avviso.
  Usare entrambe le chiavi con valori diversi per un agente causa un errore di convalida.

Modifica l'elenco in **Customize → Agents → l'agente → Beeuni permissions**. Il salvataggio esegue il commit di `beeuni.yaml`. Consulta [il riferimento del manifest](/docs/it/project/manifest).

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

## Il limite: decide un amministratore

Il limite è un ruolo del progetto che un amministratore associa all'account di servizio dell'agente. Le autorizzazioni Beeuni dell'agente non lo superano mai.

- **Nessun ruolo associato:** si applica il limite predefinito dell'agente. Include tutte le autorizzazioni del progetto tranne `project.credentials.issue`.
- **Ruolo associato:** `member` o `manager` predefinito, oppure un ruolo personalizzato. L'agente conserva solo le autorizzazioni Beeuni concesse anche dal ruolo.
- Un limite non aggiunge mai un'autorizzazione. Un limite `manager` non concede all'agente un'autorizzazione che non compare nel manifest.

Imposta il limite in **Access hub → Projects → il progetto → Add**. Seleziona l'agente in **Agents** e scegli un ruolo. Nel selettore gli agenti sono visibili solo agli amministratori che gestiscono i ruoli. L'elenco di accesso del progetto mostra il limite di ogni agente con il badge **Agent**.

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

## `all` significa tutte le autorizzazioni

`beeuni_permissions: all`, `"*"` e qualsiasi elenco che contenga `"*"` significano la stessa cosa: tutte le autorizzazioni del progetto. Questo include `project.members.manage`
(aggiungere, modificare o rimuovere membri e concessioni del progetto) e `project.delete`.

Un'autorizzazione resta riservata alle persone: `project.credentials.issue` (creare un token del progetto o un PAT limitato al progetto). Un token creato da un agente non avrebbe autorizzazioni da agente e agirebbe quindi al di fuori di esse. Il rifiuto restituisce `403` con `code: "agent_human_only_action"`.

Una voce che non è un'autorizzazione concedibile viene ignorata in fase di esecuzione e il resto dell'elenco continua ad applicarsi. `beeuni validate` e l'unione di una richiesta di modifica la segnalano come errore.

`project.read` è l'opposto: un agente ne è sempre titolare all'interno del proprio progetto.

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

## Eseguire un agente non gli presta la propria autorità

La persona che esegue un agente non ne limita le autorizzazioni. Pertanto, il diritto di eseguire un agente è la delega. Beeuni verifica «questa persona può eseguire questo agente?» a ogni punto di accesso:

| Punto di accesso | Requisito |
|---|---|
| Creare, avviare o inviare un prompt a una sessione; cambiarne l'agente | La persona può eseguire l'agente |
| Avviare manualmente un trigger | La persona che lo avvia può eseguire l'agente del trigger |
| Avviare una sessione figlia da una sessione di un agente | La persona associata all'agente principale può eseguire l'agente figlio. Se non è associata alcuna persona, può farlo solo lo stesso agente. |

Concedi il diritto di esecuzione nella scheda **People** dell'agente o nell'Access hub. Per impostazione predefinita, gli agenti sono chiusi: un membro può eseguire un agente solo se un'assegnazione indica lui o uno dei suoi gruppi.

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

## Le risorse personali restano personali

Una sessione di un agente accede a una risorsa appartenente a una persona solo quando sono vere entrambe le condizioni:

1. La sessione viene eseguita per conto di quella persona.
2. La sessione è privata.

Le risorse personali sono le connessioni ai connettori di proprietà dei membri, i segreti personali del progetto, le chiavi personali dei provider e il computer della persona. Una sessione condivisa, una sessione avviata da un trigger o da un canale e un'esecuzione non presidiata non accedono a nesbeeuni di queste risorse.

Quando un'altra persona invia un prompt a una sessione privata, per esempio un amministratore dell'account che può aprire le sessioni private dei membri, la sessione smette definitivamente di agire per conto del suo creatore. L'agente mantiene le proprie autorizzazioni. La persona che invia il prompt non agisce mai tramite gli account di un'altra persona.

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

## App

Un agente apre un'[app](/docs/it/feature-flags/apps) con accesso limitato o privata solo quando la concessione `apps:` include lo slug dell'app oppure è `all`, e le sue autorizzazioni effettive includono `project.app.read`.

| Modalità di accesso all'app | L'agente può accedere quando |
|---|---|
| Pubblica | Sempre |
| Progetto | `project.app.read` è effettiva |
| Con accesso limitato o privata | Lo slug è in `apps:` e `project.app.read` è effettiva |
| Protetta da password | Mai |

La finestra di dialogo **Access** dell'app elenca gli agenti autorizzati, in base a `agents.<name>.apps`. Modifica l'elenco nella pagina **Apps** dell'agente (Customize → Agents → l'agente → Apps), con `beeuni agents scope <agent> --apps <slug,slug>` oppure tramite una richiesta di modifica a `beeuni.yaml`. La pagina Apps compare solo quando nel progetto è attivato il flag della funzionalità [Apps](/docs/it/feature-flags/apps).

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

## Backend

Un progetto può disporre di Convex Backend ospitati autonomamente. Due autorizzazioni ne regolano l'accesso. Seguono le autorizzazioni delle app: un ruolo che include `project.app.read` o `project.app.write` include la corrispondente autorizzazione per i Backend.

| Autorizzazione | Consente di |
|---|---|
| `project.backend.read` | Elencare e ispezionare i Backend del progetto: nome, stato e URL |
| `project.backend.write` | Creare ed eliminare Backend e leggere le credenziali di amministrazione di un Backend. Include `project.backend.read` |

La chiave di amministrazione offre il pieno controllo sui dati e sul codice di un Backend, quindi per leggerla serve `project.backend.write`. Il ruolo predefinito Manager include entrambe le autorizzazioni. Il ruolo predefinito Member include `project.backend.read`.

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

## Modificare agenti e trigger

`beeuni.yaml` determina cosa possono fare gli agenti; quindi, chiunque integri una modifica nel branch predefinito determina il comportamento degli agenti. Le stesse autorizzazioni valgono per un agente e per una persona:

1. Per unire una richiesta di modifica serve `project.gitops.merge`.
2. Un'unione che modifica `beeuni.yaml` richiede anche l'autorizzazione necessaria per il percorso diretto di quella modifica: `agents.*` → `project.agent.write`;
   `triggers` → `project.trigger.create`, `.update` o `.delete`;
   `default_agent` → `project.agent.write`. Il ruolo Manager include queste autorizzazioni e l'editor dei ruoli le aggiunge a qualsiasi ruolo riceva `project.gitops.merge`. L'`beeuni_permissions` dell'agente deve includerle oppure essere `all`. Un agente che può solo eseguire un'unione non può quindi ampliare le proprie autorizzazioni.
3. Un agente concede solo ciò di cui dispone. Quando un agente modifica le concessioni di un agente (tramite l'editor degli agenti, gli endpoint per ambiti e concessioni di segreti o una richiesta di modifica che unisce), ogni autorizzazione, connettore, segreto e app aggiunti devono essere inclusi nelle concessioni effettive dell'agente che scrive. Concedere `all` li richiede tutti. Restringere o rimuovere una concessione è sempre consentito. Un rifiuto restituisce `403` con `code: "agent_grant_escalation"`.
4. Un push diretto al branch predefinito salta la richiesta di modifica. Una sessione di un agente necessita di `project.gitops.ref.any` e di tutte le autorizzazioni del punto 2. Il manifest inviato non può essere verificato prima dell'integrazione, quindi l'agente deve anche disporre di ogni concessione (autorizzazioni `all`, connettori, segreti e app). In caso contrario, apre una richiesta di modifica.
5. Un rifiuto restituisce `403` con `code: "agent_scope_insufficient"` (agente) o `"project_role_insufficient"` (persona) e l'`action` mancante. Se non è possibile leggere il manifest, l'unione restituisce `503` con `code: "CR_GOVERNANCE_UNVERIFIED"` e `Retry-After`. Riprova.
6. Il limite è uno stato IAM riservato agli amministratori. Il manifest non lo supera mai.

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

## Interpretare un rifiuto

Ogni `403` generato da un controllo di autorizzazione include `code` e `action`:

| `code` | Significato | Soluzione |
|---|---|---|
| `agent_scope_insufficient` | `action` non è incluso nelle autorizzazioni Beeuni dell'agente | Aggiungilo a `agents.<name>.beeuni_permissions` |
| `agent_ceiling_insufficient` | `action` non rientra nel ruolo limite dell'agente | Un amministratore aumenta il limite |
| `agent_not_accessible` | La persona non può eseguire questo agente | Concedile l'accesso all'agente |
| `agent_grant_escalation` | La modifica concede a un agente qualcosa di cui l'agente che scrive non dispone | Concedi solo ciò di cui dispone chi scrive oppure chiedi a una persona di apportare la modifica |
| `project_role_insufficient` | Il ruolo della persona nega `action` | Modifica il ruolo della persona nel progetto |

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

## Verifica

Ogni azione di un agente registra tre campi: `actor` è l'agente,
`on_behalf_of` è la persona o `null`, e `initiator` è `human`,
`trigger` o `channel`. Un'esecuzione avviata da un trigger non registra alcuna persona.

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

## Verificare nella dashboard

Apri **Customize → Agents → l'agente → Beeuni permissions**. Il pannello **What this
agent can do** mostra:

- le autorizzazioni Beeuni dichiarate in `beeuni.yaml`,
- il ruolo limite oppure **Default agent ceiling**,
- l'unica autorizzazione riservata alle persone, `project.credentials.issue`,
- le autorizzazioni effettive: «Le persone che possono eseguire questo agente agiscono con queste autorizzazioni».

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

## Ambito

Questa pagina si applica a ogni agente dichiarato dal progetto in `agents:` in
`beeuni.yaml`. Un progetto senza una mappa `agents:` non dichiara alcun agente soggetto a queste regole, quindi non c'è nulla da attivare. Non è possibile tornare al vecchio modello basato sui ruoli del launcher.