Permisos del agente

Qué puede hacer un agente, quién lo decide y qué aporta la persona que lo ejecuta.

Un agente actúa en tu proyecto mediante la CLI, la API, git, los conectores y las Apps. Esta página explica cómo decide Beeuni qué puede hacer un agente.

Un agente actúa como tal, no como la persona que lo inició. Su autoridad es sus permisos de Beeuni ∩ su rol de límite. Los permisos son lo único que cuenta, igual que para una persona. Nadie le presta su propio rol a un agente, así que este hace lo mismo sin importar quién lo ejecute.

El agente es la entidad que actúa

Cada sesión de agente tiene dos identidades:

Cada agente tiene una identidad por proyecto: una cuenta de servicio que Beeuni crea para él. Nunca tienes credenciales para esa cuenta.

Permisos de Beeuni: decide el manifiesto

Cada agente declara sus permisos de Beeuni en beeuni.yaml, bajo agents.<name>.beeuni_permissions. El manifiesto de la rama predeterminada es la fuente de verdad.

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]

• La lista deniega el acceso de forma predeterminada. Un agente sin beeuni_permissions no recibe ningún permiso.
• all concede todos los permisos del proyecto, siempre sujetos al límite.
• beeuni_cli es la forma obsoleta. Sigue siendo válida, pero genera una advertencia. Usar ambas claves con valores distintos en un mismo agente es un error de validación.

Edita la lista en Customize → Agents → el agente → Beeuni permissions. Al guardar, se confirma beeuni.yaml. Consulta la referencia del manifiesto.

El límite: lo decide un administrador

El límite es un rol del proyecto que un administrador asigna a la cuenta de servicio del agente. Los permisos de Beeuni del agente nunca lo superan.

• Sin un rol asignado: se aplica el límite predeterminado del agente. Incluye todos los permisos del proyecto, excepto project.credentials.issue.
• Con un rol asignado: member o manager, roles integrados, o un rol personalizado. El agente conserva solo los permisos de Beeuni que también concede el rol.
• Un límite nunca agrega permisos. Un límite manager no concede al agente un permiso que no figure en su manifiesto.

Configura el límite en Access hub → Projects → el proyecto → Add. Selecciona el agente en Agents y elige un rol. Solo los administradores que gestionan roles ven agentes en el selector. La lista de acceso del proyecto muestra el límite de cada agente con una insignia Agent.

all significa todos los permisos

beeuni_permissions: all, "*" y cualquier lista que incluya "*" significan lo mismo: todos los permisos del proyecto. Esto incluye project.members.manage (agregar, cambiar o quitar miembros y concesiones del proyecto) y project.delete.

Un permiso sigue reservado a las personas: project.credentials.issue (crear un token del proyecto o un PAT con alcance limitado al proyecto). Un token creado por un agente no tendría permisos de agente, así que actuaría fuera de estos. La denegación responde a 403 con code: "agent_human_only_action".

Una entrada que no sea un permiso concedible se ignora en tiempo de ejecución y el resto de la lista sigue aplicándose. beeuni validate y la combinación de una solicitud de cambio informan de ello como un error.

project.read funciona al revés: un agente siempre lo tiene dentro de su propio proyecto.

Ejecutar un agente no le transfiere autoridad

La persona que ejecuta un agente no limita sus permisos. Por eso, el derecho a ejecutar un agente es la delegación. Beeuni comprueba «¿puede esta persona ejecutar este agente?» en cada punto de entrada:

Concede el permiso «puede ejecutar» en la pestaña People del agente o en Access hub. De forma predeterminada, los agentes están cerrados: un miembro solo puede ejecutar un agente si se le asigna directamente o por medio de uno de sus grupos.

Los recursos personales siguen siendo personales

Una sesión de agente accede a un recurso propiedad de una persona solo si se cumplen ambas condiciones:

1. La sesión se ejecuta en nombre de esa persona.
2. La sesión es privada.

Los recursos personales son las conexiones de conectores propiedad de un miembro, los secretos personales del proyecto, las claves personales de proveedor y el propio ordenador de la persona. Una sesión compartida, una sesión de desencadenador o de canal y una ejecución desatendida no acceden a ninguno de ellos.

Cuando otra persona envía una instrucción a una sesión privada —por ejemplo, un administrador de cuentas que puede abrir las sesiones privadas de los miembros—, la sesión deja de actuar en nombre de su creador para siempre. El agente conserva sus propios permisos. La persona que envía la instrucción nunca actúa a través de las cuentas de otra persona.

Apps

Un agente abre una App restringida o privada solo si su concesión apps: incluye el slug de la App o es all, y sus permisos efectivos incluyen project.app.read.

El cuadro de diálogo Access de la App muestra los agentes que tienen acceso, según agents.<name>.apps. Cambia la lista en la página Apps del agente (Customize → Agents → el agente → Apps), con beeuni agents scope <agent> --apps <slug,slug>, o mediante una solicitud de cambio a beeuni.yaml. La página Apps solo aparece cuando el proyecto tiene activada la marca de función Apps.

Backends

Un proyecto puede tener backends gestionados. Dos permisos los controlan. Siguen el mismo criterio que los permisos de Apps: un rol que tenga project.app.read o project.app.write también tiene el permiso correspondiente para Backend.

La clave de administrador otorga control total sobre los datos y el código de un Backend, por lo que leerla requiere project.backend.write. El rol Manager integrado tiene ambos permisos. El rol Member integrado tiene project.backend.read.

Cambiar agentes y desencadenadores

beeuni.yaml determina lo que pueden hacer los agentes, así que quien incorpore un cambio a la rama predeterminada determina lo que pueden hacer. Los mismos permisos rigen para un agente y para una persona:

1. Para combinar una solicitud de cambio se necesita project.gitops.merge.
2. Una combinación que cambie beeuni.yaml también requiere el permiso necesario para la ruta directa de ese cambio: agents.* → project.agent.write; triggers → project.trigger.create, .update o .delete; default_agent → project.agent.write. El rol Manager incluye estos permisos, y el editor de roles los agrega a cualquier rol que reciba project.gitops.merge. El beeuni_permissions del agente debe incluirlos o ser all. Por tanto, un agente que solo puede combinar cambios no puede ampliar sus propios permisos.
3. Un agente solo concede lo que tiene. Cuando un agente modifica la concesión de cualquier agente (en el editor de agentes, las rutas de alcance y concesión de secretos, o una solicitud de cambio que combina), todos los permisos, conectores, secretos y Apps que añada deben estar incluidos en la propia concesión efectiva del agente que realiza el cambio. Para conceder all se necesitan todos esos elementos. Siempre se permite restringir o eliminar una concesión. La denegación responde a 403 con code: "agent_grant_escalation".
4. Enviar los cambios directamente a la rama predeterminada omite la solicitud de cambio. Una sesión de agente necesita project.gitops.ref.any y todos los permisos del punto 2. Como no es posible comprobar el manifiesto enviado antes de incorporarlo, el agente también debe tener todas las concesiones (permisos, conectores, secretos y Apps de all). De lo contrario, abre una solicitud de cambio.
5. Una denegación responde a 403 con code: "agent_scope_insufficient" (agente) o "project_role_insufficient" (persona) y el action que falta. Si no se puede leer el manifiesto, la combinación responde a 503 con code: "CR_GOVERNANCE_UNVERIFIED" y Retry-After. Vuelve a intentarlo.
6. El límite es un estado IAM exclusivo de administradores. El manifiesto nunca lo supera.

Interpretar una denegación

Cada 403 de una comprobación de autorización incluye code y action:

Auditoría

Cada acción del agente registra tres campos: actor es el agente, on_behalf_of es la persona o null, y initiator es human, trigger o channel. Una ejecución de desencadenador no registra a ninguna persona.

Consultarlo en el panel de control

Abre Customize → Agents → el agente → Beeuni permissions. El panel What this agent can do muestra:

• los permisos de Beeuni declarados en beeuni.yaml,
• el rol de límite o Default agent ceiling,
• el único permiso reservado a personas, project.credentials.issue,
• los permisos efectivos: «Las personas que pueden ejecutar este agente actúan con estos permisos».

Alcance

Esta página se aplica a todos los agentes que un proyecto declara en agents:, dentro de beeuni.yaml. Si un proyecto no tiene el mapa agents:, no declara ningún agente sujeto a estas reglas, por lo que no hay nada que activar. No existe una opción para volver al antiguo modelo de roles del iniciador.