# Dozvole agenta

Šta agent sme da radi, ko o tome odlučuje i čime doprinosi osoba koja ga pokreće.

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

Агент делује на вашем пројекту преко CLI-ја, API-ја, git-а, конектора и
апликација. Ова страница објашњава како Beeuni одлучује шта агент може да ради.

**Агент делује као он сам, а не као особа која га је покренула.** Његов ауторитет је
пресек његових Beeuni дозвола и његове улоге-ограничења. Само дозволе одлучују,
као и код особе. Нико
не позајмљује агенту сопствену улогу, па агент ради исто без обзира на то ко га покреће.

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

## Агент је субјект који извршава радњу

Свака сесија агента има два идентитета:

| Идентитет | О чему одлучује |
|---|---|
| **Субјект који извршава радњу — агент** | Све на дељеним ресурсима: дозволе пројекта, дељени налози конектора, тајне пројекта, апликације и git. |
| **У име — особа** | Само ресурси те особе, и то само у њеној приватној сесији. |

Сваки агент има један идентитет по пројекту: сервисни налог који Beeuni
креира за њега. Никада немате његове акредитиве.

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

## Beeuni дозволе — манифест одлучује

Сваки агент наводи своје Beeuni дозволе у `beeuni.yaml`, под
`agents.<name>.beeuni_permissions`. Манифест на подразумеваној грани је
меродавни извор.

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

Једна дозвола остаје доступна само људима: `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/sr/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/sr/feature-flags/apps).

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

## Бекенди

Пројекат може да поседује Управљани бекенди пројекта. Њима управљају две дозволе.
Оне прате дозволе за апликације: улога која има `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>

## Ревизија

Свака радња агента бележи три поља: `actor` је агент,
`on_behalf_of` је особа или `null`, а `initiator` је `human`,
`trigger` или `channel`. Покретање окидача не бележи особу.

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

## Приказ у контролној табли

Отворите **Customize → Agents → агент → Beeuni permissions**. Панел **What this
agent can do** приказује:

- Beeuni дозволе наведене у `beeuni.yaml`,
- улогу-ограничење или **Default agent ceiling**,
- једину дозволу само за људе, `project.credentials.issue`,
- ефективне дозволе: „Особе које смеју да покрену овог агента делују са овим дозволама.“

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

## Опсег

Ова страница важи за сваког агента којег пројекат наведе под `agents:` у
`beeuni.yaml`. Пројекат без мапе `agents:` не дефинише агента којим се управља, па нема шта да се укључује. Не постоји могућност повратка на стари модел улоге покретача.