Agentes

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. Esta página aborda arquivos de agente, habilidades e como uma sessão escolhe um agente.

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

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. Seu campo file indica o arquivo de comportamento. O mapa pode estar em um arquivo listado no manifesto em 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 para ver todos os campos de governança.

Onde fica o arquivo do agente

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.

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 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 e Um vocabulário, duas vinculações. 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 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.

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.

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.

Agentes e habilidades novos ou alterados só ficam disponíveis para sessões futuras depois que uma solicitação de alteração os incorpora à ramificação padrão. Conecte ferramentas externas antes que um agente possa usá-las; consulte Conectores.