# Permisos del agente

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

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

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.

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

## El agente es la entidad que actúa

Cada sesión de agente tiene dos identidades:

| Identidad | Qué determina |
|---|---|
| **Entidad que actúa — el agente** | Todo lo relacionado con recursos compartidos: permisos del proyecto, cuentas compartidas de conectores, secretos del proyecto, Apps y git. |
| **En nombre de — la persona** | Solo los recursos propios de esa persona, y únicamente en su propia sesión privada. |

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

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

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

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

- 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](/docs/es/project/manifest).

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

## 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**.

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

## `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.

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

## 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:

| Punto de entrada | Requisito |
|---|---|
| Crear o iniciar una sesión, enviarle una instrucción o cambiar su agente | La persona puede ejecutar el agente |
| Activar manualmente un desencadenador | La persona que lo activa puede ejecutar el agente del desencadenador |
| Iniciar una sesión secundaria desde una sesión de agente | La persona asociada a la sesión principal puede ejecutar el agente de la sesión secundaria. Si no hay ninguna persona asociada, solo puede hacerlo el mismo agente. |

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.

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

## 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](/docs/es/feature-flags/apps) 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`.

| Modo de acceso de la App | Se admite al agente cuando… |
|---|---|
| Pública | Siempre |
| Del proyecto | `project.app.read` es efectivo |
| Restringida o privada | El slug está en `apps:` y `project.app.read` es efectivo |
| Con contraseña | Nunca |

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](/docs/es/feature-flags/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.

| Permiso | Permite |
|---|---|
| `project.backend.read` | Consultar y revisar los Backends del proyecto: nombre, estado y URL |
| `project.backend.write` | Crear y eliminar Backends, y leer las credenciales de administrador de un Backend. Incluye `project.backend.read` |

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

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

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

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

## Interpretar una denegación

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

| `code` | Significado | Solución |
|---|---|---|
| `agent_scope_insufficient` | `action` no figura entre los permisos de Beeuni del agente | Agrégalo a `agents.<name>.beeuni_permissions` |
| `agent_ceiling_insufficient` | `action` supera el límite del rol del agente | Un administrador amplía el límite |
| `agent_not_accessible` | La persona no puede ejecutar este agente | Concédele acceso al agente |
| `agent_grant_escalation` | El cambio concede a un agente algo que el agente que lo realiza no tiene | Concede solo lo que tiene quien realiza el cambio o haz que una persona lo cambie |
| `project_role_insufficient` | El rol propio de la persona deniega `action` | Cambia su rol en el proyecto |

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

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

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

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

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

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