---
title: "Agentes"
description: "Um agente é um arquivo Markdown que o executor da sessão executa; o manifesto controla apenas o acesso dele."
---

Um agente é um arquivo Markdown que define como o executor atua em uma
[sessão](/docs/pt/work/sessions). Esta página aborda arquivos de agente, habilidades e
como uma sessão escolhe um agente.

<a id="a-harness-runs-every-session"></a>

## Um executor roda em cada sessão

Uma sessão executa um executor de agente: harness padrão (o padrão) ou harness experimental.
[Executores](/docs/pt/work/harnesses) lista como um projeto seleciona um e o que
cada um oferece.

Ambos leem os agentes do projeto em `agents/` e as habilidades em `skills/`.
O harness padrão também lê os arquivos que só ele usa em `harnesses/opencode/`. O harness experimental
lê os próprios arquivos em `harnesses/pi/`.

Projetos criados antes de 2026-09 mantêm agentes e habilidades em
`.beeuni/opencode/`. O Beeuni lê os dois formatos.

<a id="an-agent-is-two-files"></a>

## Um agente consiste em dois arquivos

Cada agente tem duas partes:

- **Comportamento** — um arquivo Markdown, `agents/<name>.md` por padrão. Seu
  frontmatter define o modelo, o modo e as regras de permissão. O corpo é o
  prompt de sistema.
- **Governança** — uma entrada no mapa `agents` de `beeuni.yaml`, identificada pelo nome do agente. Ela define o que o agente pode acessar: conectores, segredos, habilidades, Apps,
  permissões do Beeuni e [ferramentas](/docs/pt/project/tools#who-may-use-which-tool).
  Seu campo `file` indica o arquivo de comportamento.
  O mapa pode estar em um arquivo listado no manifesto em
  [`imports:`](/docs/pt/project/manifest#imports); `default_agent` permanece em `beeuni.yaml`.

O manifesto nunca define um prompt ou modo. O arquivo `.md` nunca define
acesso à plataforma. Consulte [a referência do manifesto](/docs/pt/project/manifest) para
ver todos os campos de governança.

<a id="where-the-agent-file-lives"></a>

### Onde fica o arquivo do agente

```yaml
agents:
  support:
    file: agents/support.md
```

- `file` é um caminho relativo ao repositório. Deve terminar em `.md`.
- Não pode começar com `/`. Não pode conter um segmento `.` ou `..`.
- Sem `file`, o Beeuni lê `agents/<name>.md` e, em seguida,
  `.beeuni/opencode/agents/<name>.md`.
- Quando o painel salva um agente que tem um `.md`, ele grava `file` com esse caminho.
- A API não permite alterar `file`. Para mover um agente, mova seu `.md` e
  atualize `file` em `beeuni.yaml` no mesmo commit.

As regras completas para caminhos estão na
[referência do manifesto](/docs/pt/project/manifest#the-agent-file).

<a id="governance-is-deny-by-default"></a>

## A governança nega o acesso por padrão

Um agente sem a chave `connectors`, `secrets`, `skills`, `apps` ou `beeuni_permissions` não recebe
nenhum desses acessos. `apps` lista os [Apps do Beeuni](/docs/pt/feature-flags/apps#agents-and-apps)
que o agente pode abrir quando um App é restrito ou privado. Essa concessão é a segunda das duas vinculações: o agente
também tem uma função como principal `service_account` — seu limite máximo — e uma
sessão só pode fazer o que ambas permitem. Consulte
[Permissões do agente](/docs/pt/project/permissions) e
[Um vocabulário, duas vinculações](/docs/pt/accounts#one-vocabulary-two-bindings). Defina um campo como `all` para conceder acesso total ou liste
nomes específicos. `default_agent` em `beeuni.yaml` identifica o agente que uma sessão
inicia quando você não especifica nenhum.

Defina cada concessão no painel — Personalizar → Agentes → o agente; uma página
por conjunto de concessões na seção Acesso: Habilidades, Conectores, Segredos, Apps, permissões do Beeuni — ou pela CLI com `beeuni agents scope <agent>`
(`--secrets`, `--connectors`, `--apps`). A página Apps aparece apenas quando a
flag de recurso [Apps](/docs/pt/feature-flags/apps) está ativada para o projeto. Todos os caminhos
gravam o mesmo bloco `agents.<name>` em `beeuni.yaml`.

Projetos legados `beeuni.toml` (v1) listam agentes em uma matriz, não em um mapa, e
concedem acesso total por padrão. Defina concessões específicas para restringir o acesso. Consulte
a [referência do manifesto](/docs/pt/project/manifest).

<a id="skills-give-an-agent-know-how"></a>

## As habilidades dão conhecimento ao agente

Uma habilidade é um arquivo Markdown em `skills/<name>/SKILL.md`.
O executor carrega uma habilidade sob demanda — o Beeuni não insere o conteúdo das habilidades
em todos os prompts. No harness padrão, o agente chama a ferramenta `skill`. No harness experimental, o
prompt de sistema lista o nome e a descrição de cada habilidade, e o agente lê
o arquivo. A concessão de `skills` do agente em `beeuni.yaml`
define quais habilidades ele pode carregar.

<a id="how-a-session-picks-its-agent"></a>

## Como uma sessão escolhe seu agente

Ao criar uma sessão, é possível especificar um `agent_name`. O Beeuni inicia esse agente na
sessão. Se você omitir `agent_name`, o Beeuni usa o `default_agent` do projeto.
Defina o agente padrão pelo painel, pela API ou pelo SDK. Cada opção grava
`default_agent` em `beeuni.yaml` e confirma a alteração na ramificação
padrão do projeto.

Um agente age como ele mesmo: com as permissões do Beeuni dentro da função que define seu limite máximo,
independentemente de quem o executa. Iniciar uma sessão não empresta ao agente a sua própria função.
Consulte [Permissões do agente](/docs/pt/project/permissions).

Agentes e habilidades novos ou alterados só ficam disponíveis para sessões futuras depois que uma
[solicitação de alteração](/docs/pt/work/change-requests) os incorpora à ramificação padrão.
Conecte ferramentas externas antes que um agente possa usá-las; consulte
[Conectores](/docs/pt/connect/connectors).