Permissões do agente

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.

O agente é o principal atuante

Cada sessão de agente tem duas identidades:

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.

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.

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.

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.

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.

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:

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.

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

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

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.

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.

Ler uma recusa

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

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.

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

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.