Autorizzazioni dell’agente

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

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.

L’agente è il soggetto che agisce

Ogni sessione di un agente ha due identità:

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

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

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.

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.

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.

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:

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.

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.

App

Un agente apre un’app 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.

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.

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.

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.

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.

Interpretare un rifiuto

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

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.

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

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.