---
title: "Permissões do agente"
description: "O que um agente pode fazer, quem decide isso e o que a pessoa que o executa contribui."
---

Um agente atua no seu projeto por meio da CLI, da API, do git, dos conectores e dos Apps. Esta página explica como o Beeuni decide o que um agente pode fazer.

**Um agente atua como ele mesmo, não como a pessoa que o iniciou.** A autoridade dele é suas permissões do Beeuni ∩ sua função de teto. Somente as permissões decidem, da mesma forma que decidem para uma pessoa. Ninguém
empresta sua própria função a um agente, portanto o agente faz a mesma coisa independentemente de quem o execute.

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

## O agente é o principal atuante

Cada sessão de agente tem duas identidades:

| Identidade | O que ela decide |
|---|---|
| **Principal atuante — o agente** | Tudo em recursos compartilhados: permissões do projeto, contas de conectores compartilhadas, segredos do projeto, Apps e git. |
| **Em nome de — a pessoa** | Somente os recursos próprios daquela pessoa, e apenas na sessão privada dela. |

Cada agente tem uma identidade por projeto: uma conta de serviço que o Beeuni cria para ele. Você nunca possui uma credencial para essa conta.

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

## Permissões do Beeuni — o manifesto decide

Cada agente declara suas permissões do Beeuni em `beeuni.yaml`, em `agents.<name>.beeuni_permissions`. O manifesto na branch padrão é a fonte de verdade.

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

- A lista nega por padrão. Um agente sem `beeuni_permissions` não recebe nenhuma permissão.
- `all` concede todas as permissões do projeto, ainda limitado pelo teto.
- `beeuni_cli` é a forma obsoleta. Ela ainda é validada, com um aviso. A presença das duas chaves com valores diferentes em um agente é um erro de validação.

Edite a lista em **Customize → Agents → o agente → Beeuni permissions**. Um salvamento faz commit de `beeuni.yaml`. Consulte [a referência do manifesto](/docs/pt/project/manifest).

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

## O teto — um administrador decide

O teto é uma função do projeto que um administrador vincula à conta de serviço do agente. As permissões do Beeuni do agente nunca excedem esse teto.

- **Nenhuma função vinculada:** aplica-se o teto padrão do agente. Ele inclui todas as permissões do projeto, exceto `project.credentials.issue`.
- **Uma função vinculada:** `member` ou `manager` integradas, ou uma função personalizada. O agente mantém apenas as permissões do Beeuni que a função também concede.
- Um teto nunca adiciona uma permissão. Um teto `manager` não dá ao agente uma permissão que o manifesto dele não liste.

Defina o teto em **Access hub → Projects → o projeto → Add**. Selecione o agente em **Agents** e escolha uma função. Somente administradores que gerenciam funções veem agentes no seletor. A lista de acesso do projeto mostra o teto de cada agente com um selo **Agent**.

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

## `all` significa todas as permissões

`beeuni_permissions: all`, `"*"` e qualquer lista que contenha `"*"` significam a mesma coisa: todas as permissões do projeto. Isso inclui `project.members.manage` (adicionar, alterar ou remover membros e concessões do projeto) e `project.delete`.

Uma permissão continua exclusiva das pessoas: `project.credentials.issue` (emitir um token do projeto ou um PAT com escopo no projeto). Um token emitido por um agente não teria permissões de agente, portanto atuaria fora delas. A recusa responde `403` com `code: "agent_human_only_action"`.

Uma entrada que não seja uma permissão concedível é ignorada em tempo de execução, e o restante da lista continua valendo. `beeuni validate` e uma solicitação de alteração de merge a relatam como erro.

`project.read` é o inverso: um agente sempre a possui dentro do próprio projeto.

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

## Executar um agente empresta sua autoridade

A pessoa que executa um agente não o limita. Portanto, o direito de executar um agente é a delegação. O Beeuni verifica “esta pessoa pode executar este agente” em todos os pontos de entrada:

| Ponto de entrada | Obrigatório |
|---|---|
| Criar, iniciar ou enviar um prompt para uma sessão; trocar o agente dela | A pessoa pode executar o agente |
| Acionar manualmente um gatilho | A pessoa que o aciona pode executar o agente do gatilho |
| Iniciar uma sessão filha a partir de uma sessão de agente | A pessoa por trás do agente pai pode executar o agente filho. Sem uma pessoa por trás dele, somente o mesmo agente. |

Conceda “pode executar” na guia **People** do agente ou no Access hub. Os agentes são fechados por padrão: um membro só executa um agente quando uma atribuição o nomeia ou nomeia um de seus grupos.

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

## Recursos pessoais continuam pessoais

Uma sessão de agente acessa um recurso pertencente a uma pessoa somente quando as duas condições são verdadeiras:

1. A sessão é executada em nome dessa pessoa.
2. A sessão é privada.

Recursos pessoais são conexões de conectores pertencentes a membros, segredos pessoais do projeto, chaves pessoais de provedores e o próprio computador da pessoa. Uma sessão compartilhada, uma sessão de gatilho ou canal e uma execução sem supervisão não acessam nenhum deles.

Quando outra pessoa envia um prompt para uma sessão privada — por exemplo, um administrador da conta que pode abrir as sessões privadas dos membros — a sessão deixa de atuar em nome do criador, permanentemente. O agente mantém suas próprias permissões. A pessoa que envia o prompt nunca atua pelas contas de outra pessoa.

## Apps

Um agente abre um [App](/docs/pt/feature-flags/apps) restrito ou privado somente quando sua concessão `apps:` nomeia o slug do App ou é `all`, e suas permissões efetivas incluem `project.app.read`.

| Modo de acesso do App | O agente é admitido quando |
|---|---|
| Público | Sempre |
| Projeto | `project.app.read` é efetivo |
| Restrito ou privado | O slug está em `apps:` e `project.app.read` é efetivo |
| Senha | Nunca |

A caixa de diálogo **Access** do App lista os agentes com acesso, com base em `agents.<name>.apps`. Altere a lista na página **Apps** do agente (Customize → Agents → o agente → Apps), com `beeuni agents scope <agent> --apps <slug,slug>` ou com uma solicitação de alteração para `beeuni.yaml`. A página Apps aparece somente quando o projeto está com a flag de recurso [Apps](/docs/pt/feature-flags/apps) ativada.

## Backends

Um projeto pode possuir Convex Backends hospedados pelo próprio cliente. Duas permissões os governam. Elas seguem as permissões dos Apps: uma função que possui `project.app.read` ou `project.app.write` possui a permissão correspondente de Backend.

| Permissão | Permite |
|---|---|
| `project.backend.read` | Listar e inspecionar os Backends do projeto: nome, status e URL |
| `project.backend.write` | Criar e excluir Backends e ler as credenciais de administrador de um Backend. Implica `project.backend.read` |

A chave de administrador dá controle total sobre os dados e o código de um Backend, portanto sua leitura exige `project.backend.write`. A função integrada Manager possui ambas as permissões. A função integrada Member possui `project.backend.read`.

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

## Alterar agentes e gatilhos

`beeuni.yaml` define o que os agentes podem fazer; portanto, quem incorpora uma alteração na branch padrão define os agentes. As mesmas permissões decidem para um agente e para uma pessoa:

1. Fazer merge de uma solicitação de alteração exige `project.gitops.merge`.
2. Um merge que altera `beeuni.yaml` também exige a permissão necessária para a rota direta dessa alteração: `agents.*` → `project.agent.write`; `triggers` → `project.trigger.create`, `.update` ou `.delete`; `default_agent` → `project.agent.write`. A função Manager possui essas permissões, e o editor de funções as adiciona a qualquer função que receba `project.gitops.merge`. O `beeuni_permissions` do agente deve listá-las ou ser `all`. Assim, um agente que só pode fazer merge não consegue ampliar a própria autoridade.
3. Um agente concede somente o que possui. Quando um agente grava a concessão de qualquer agente (o editor de agentes, as rotas de escopo e concessão de segredos ou uma solicitação de alteração que ele incorpora), toda permissão, conector, segredo e App adicionados pela gravação devem estar na própria concessão efetiva do agente que grava. Conceder `all` exige todos eles. Restringir ou remover uma concessão é sempre permitido. Uma recusa responde `403` com `code: "agent_grant_escalation"`.
4. Um push direto para a branch padrão ignora a solicitação de alteração. Uma sessão de agente exige `project.gitops.ref.any` e todas as permissões do item 2. O manifesto enviado não pode ser verificado antes de chegar à branch, portanto o agente também deve possuir cada concessão (permissões `all`, conectores, segredos e Apps). Caso contrário, ele abre uma solicitação de alteração.
5. Uma recusa responde `403` com `code: "agent_scope_insufficient"` (agente) ou `"project_role_insufficient"` (pessoa) e o `action` ausente. Quando o manifesto não pode ser lido, o merge responde `503` com `code: "CR_GOVERNANCE_UNVERIFIED"` e `Retry-After`. Tente novamente.
6. O teto é um estado IAM exclusivo do administrador. O manifesto nunca o excede.

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

## Ler uma recusa

Cada `403` proveniente de uma verificação de autorização contém `code` e `action`:

| `code` | Significado | Correção |
|---|---|---|
| `agent_scope_insufficient` | `action` não está nas permissões do Beeuni do agente | Adicione-o a `agents.<name>.beeuni_permissions` |
| `agent_ceiling_insufficient` | `action` está fora da função de teto do agente | Um administrador aumenta o teto |
| `agent_not_accessible` | A pessoa não pode executar este agente | Conceda o agente a ela |
| `agent_grant_escalation` | A gravação dá a um agente algo que o agente que grava não possui | Conceda somente o que o autor possui ou peça a uma pessoa para fazer a alteração |
| `project_role_insufficient` | A própria função da pessoa nega `action` | Altere a função dela no projeto |

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

## Auditoria

Cada ação de agente registra três campos: `actor` é o agente, `on_behalf_of` é a pessoa ou `null`, e `initiator` é `human`, `trigger` ou `channel`. Uma execução de gatilho não registra nenhuma pessoa.

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

## Veja no dashboard

Abra **Customize → Agents → o agente → Beeuni permissions**. O painel **What this agent can do** mostra:

- as permissões do Beeuni declaradas em `beeuni.yaml`,
- a função de teto ou **Default agent ceiling**,
- a única permissão exclusiva de humanos, `project.credentials.issue`,
- as permissões efetivas: “As pessoas que podem executar este agente atuam com estas permissões.”

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

## Escopo

Esta página se aplica a todos os agentes que um projeto declara em `agents:` dentro de `beeuni.yaml`. Um projeto sem um mapa `agents:` não declara nenhum agente governado, portanto não há nada para ativar. Não existe uma opção para voltar ao antigo modelo de função do launcher.