# Ambientes de execução

Uma sessão executa um ambiente de agente: harness padrão ou harness experimental. Esta página lista como um projeto seleciona um deles e o que cada um oferece.

Canonical page: https://beeuni.ai/docs/pt/work/harnesses

Um harness é o runtime do agente dentro do sandbox de uma sessão. Ele executa o loop do modelo, chama ferramentas e produz a transcrição. O Beeuni tem dois: **harness padrão** (o padrão) e **harness experimental**. Uma sessão executa exatamente um deles.

Ambos os harnesses leem o mesmo projeto: `beeuni.yaml`, os arquivos do agente em `agents/`, as skills em `skills/`, a raiz `AGENTS.md` e `memory/`. Os clientes (web, CLI, TUI, mobile, SDK) leem ambos pela mesma API de sessão. As diferenças são os recursos de sessão na [matriz](#what-each-harness-supports) abaixo e os arquivos que cada harness lê para sua própria configuração.

<a id="how-a-session-selects-its-harness"></a>

## Como uma sessão seleciona seu harness

O Beeuni decide quando uma sessão inicia, reinicia ou retoma. Uma sessão em execução mantém seu harness até esse momento.

| Regra, em ordem | Harness |
| --- | --- |
| A flag `llm_gateway` do projeto está desativada | harness padrão |
| A flag `pi_harness` do projeto está ativada | harness experimental |
| `beeuni.yaml` define `runtime: pi` | harness experimental |
| Qualquer outra situação | harness padrão |

- O harness experimental chama modelos somente pelo gateway LLM do Beeuni. Um projeto com `llm_gateway` desativado inicia o harness padrão, independentemente da flag ou do manifesto. Consulte [Modelos](/docs/pt/project/models).
- `runtime` é uma chave de manifesto de `beeuni_version: 2`. Um projeto `beeuni.toml` legado não pode defini-la. Consulte [a referência do manifesto](/docs/pt/project/manifest).
- `pi_harness` é uma flag de recurso por projeto, desativada por padrão. Consulte [Flags de recursos](/docs/pt/feature-flags).

Para ver qual harness uma sessão executa, leia `harness.id` na resposta `GET /beeuni/health` do daemon do sandbox: `opencode` ou `pi`.

<a id="what-each-harness-supports"></a>

## O que cada harness oferece

Um harness lista os recursos opcionais de sessão que disponibiliza no array `capabilities` de `GET /beeuni/health`. Um cliente oculta um controle quando `capabilities` da sessão não contém o ID. A verificação do SDK é `runtimeSupports`.

<a id="both-harnesses"></a>

### Ambos os harnesses

| Recurso | harness padrão | harness experimental |
| --- | --- | --- |
| Turnos de chat, streaming, parada | Sim | Sim |
| `.md` do agente: prompt, `model`, `variant`, `mode`, `permission`, `temperature`, `top_p`, `steps` | Sim | Sim. O harness experimental não aplica `options` (opções do provedor). |
| [Acesso a ferramentas](/docs/pt/project/tools#who-may-use-which-tool) por agente (`agents.<name>.tools` em `beeuni.yaml`: `all`, `none`, uma lista, `exclude`) | Sim | Sim |
| Regras de `permission` por agente e solicitações de permissão | Sim | Sim |
| Perguntas (ferramenta `question`) | Sim | Sim |
| Arquivo de regras `AGENTS.md` da raiz do projeto, ou `CLAUDE.md` quando a raiz não tem `AGENTS.md` | Sim. O harness padrão também lê o arquivo nos diretórios-pai de `/workspace` e lê `/workspace` enquanto executa uma versão de configuração. | Sim, somente o arquivo da raiz. Ele faz parte do prompt do sistema da sessão e de cada subagente. [Com versões de configuração ativadas](#agentsmd-on-pi), o harness experimental lê a cópia da versão. |
| Subagentes (ferramenta `task`), `session.subagents` | Sim | Sim: `general`, `explore` (somente leitura) e cada agente do projeto com `mode: subagent` ou `all`. Um subagente não pode iniciar outro subagente. |
| Skills (`skills/` e as skills `beeuni-*` gerenciadas), com a concessão `skills` do agente | Sim. O agente carrega uma skill com a ferramenta `skill`. | Sim. O prompt do sistema lista cada skill concedida; o agente lê o arquivo. |
| [Ferramentas do Beeuni](/docs/pt/project/tools#beeuni-tools-in-beeuniyaml): `web_search`, `image_search`, `scrape_webpage`, `memory`, `show`. Todas as cinco sem uma chave `tools:` em `beeuni.yaml`; com uma, as que ela lista como `beeuni:<name>` | Sim | Sim |
| [Ferramentas do projeto](/docs/pt/project/tools) (`tools:` em `beeuni.yaml`) | Sim | Sim |
| [Versões de configuração](/docs/pt/work/runtime#config-convergence), `config.release.v1` | Sim | Sim |
| Compactar (resumir) a conversa, sob demanda e automaticamente próximo ao limite da janela de contexto do modelo, `session.compact` | Sim | Sim. Uma solicitação ao modelo que excede a janela compacta e tenta novamente uma vez. |
| Comandos slash do projeto, `session.commands` | Sim, de `commands/` no diretório de configuração do harness padrão. | Sim, dos templates de prompt em `prompts/` no diretório de configuração do harness experimental e nos pacotes do harness experimental. O harness experimental não lê `commands/` do harness padrão. |
| Terminal no sandbox (PTY) | Sim | Sim |
| Ferramentas `bash`, `read`, `write`, `edit`, `glob`, `grep`; [segredos](/docs/pt/project/secrets) no shell; a CLI `beeuni` | Sim | Sim |

As ferramentas do Beeuni e do projeto são [neutras em relação ao harness](/docs/pt/project/tools): o daemon do sandbox executa um módulo por ferramenta para ambos os harnesses, com os mesmos nomes, argumentos e saída. O harness experimental as chama no processo do daemon; o harness padrão as chama por meio de um plugin escrito pelo daemon. Ambos recebem a mesma lista: uma ferramenta do Beeuni que a chave `tools:` do projeto não lista não está disponível para nenhum dos dois. Um projeto que ainda tenha cópias das ferramentas do Beeuni em `harnesses/opencode/tools/` mantém suas cópias no harness padrão até excluí-las.

As ferramentas web seguem as chaves de permissão `websearch` (`web_search`, `image_search`) e `webfetch` (`scrape_webpage`) em ambos os harnesses. No harness padrão, essas ferramentas não podem perguntar: uma regra `ask` as nega. No harness experimental, uma regra `ask` gera uma solicitação de permissão. No harness experimental, um comando `memory` que altera um arquivo segue `edit`, e `view` segue `read`; no harness padrão, somente uma regra `memory` controla a ferramenta.

<a id="agentsmd-on-pi"></a>

### `AGENTS.md` no harness experimental

O harness experimental coloca o `AGENTS.md` da raiz do projeto no prompt do sistema como uma seção, `<project_instructions path="AGENTS.md">`, depois do prompt do agente. Uma raiz sem `AGENTS.md` fornece `CLAUDE.md`, como no harness padrão. O harness experimental não lê `AGENTS.md` em subdiretórios nem em diretórios-pai.

- **Origem.** Com [versões de configuração](/docs/pt/work/runtime#config-convergence) desativadas, o harness experimental lê `/workspace/AGENTS.md`. Com elas ativadas, lê a cópia na versão e nunca a de `/workspace`: uma edição em `/workspace` chega à sessão depois de ser mesclada ao branch base. Com elas ativadas e sem uma versão disponível (`config.source: image-default`), o harness experimental não lê `AGENTS.md`, assim como não lê nenhuma skill do projeto.
- **Quando.** O harness experimental lê o arquivo quando o runtime inicia, quando sua configuração é recarregada (uma nova versão, um push de `/beeuni/env`) e depois de uma atualização do repositório. Ele não o lê antes de cada turno. Uma nova versão chega ao turno seguinte sem reinicialização; um turno em andamento mantém o arquivo antigo.
- **Ignorado.** Um arquivo vazio, um arquivo que não seja regular e um link simbólico que resolva para fora do repositório não adicionam nada. Os dois últimos gravam um aviso no log do daemon.
- **Verificação.** `harness.details.agentsMd` na `GET /beeuni/health` do daemon identifica o arquivo carregado pelo harness experimental: `source` (`release` ou `workspace`), `path`, `bytes` e `sha` (os primeiros 12 caracteres hexadecimais do sha256). É `null` quando o harness experimental não carregou nenhum.

<a id="opencode-only-today"></a>

### Somente no harness padrão atualmente

| Recurso | Capacidade | harness padrão | harness experimental |
| --- | --- | --- | --- |
| Retroceder até uma mensagem e restaurá-la. Editar e reenviar usa o retrocesso. | `session.rewind` | Sim | Não |
| Servidores MCP (`mcp` em `opencode.jsonc`) | `session.mcp` | Sim | Nenhum cliente MCP. [Conectores](/docs/pt/connect/connectors) funcionam nos dois harnesses pela CLI `beeuni connectors`. |
| Lista de tarefas (ferramenta `todowrite`) e cartão do plano | `session.todo` | Sim | Não. O cartão do plano permanece vazio. |
| Anexar o próprio cliente de terminal do harness (`beeuni connect`, TUI `Alt+o`) | `session.attach` | Sim | Não. Consulte [TUI](/docs/pt/cli#sessions). |
| Documento de configuração do runtime (`/global/config`) | `session.config` | Sim | Não. Agentes e modelos vêm do projeto em ambos. |
| Criar um fork de uma sessão em uma mensagem | `session.fork` | Sim | Não |
| Um comando shell executado como turno | `session.shell` | Sim | Não |
| Provedores de modelos sem o gateway LLM | — | Sim | Não. O harness experimental precisa de `llm_gateway` ativado. |

Uma sessão harness experimental responde a uma solicitação de um recurso que não oferece com `501 feature_not_supported`, ou com `404` para um documento que não possui (`/global/config`). Ela não ignora a solicitação.

<a id="harness-configuration-files"></a>

## Arquivos de configuração do harness

Cada harness tem um diretório para os arquivos lidos somente por ele.

| | harness padrão | harness experimental |
| --- | --- | --- |
| Diretório | `harnesses/opencode/` ou `opencode.config_dir` | `harnesses/pi/` ou `pi.config_dir` |
| Diretório legado | `.beeuni/opencode/` | `.beeuni/pi/` |
| Conteúdo | `opencode.jsonc`, `plugins/`, `tools/`, `commands/` | `settings.json`, `extensions/`, `skills/`, `prompts/` |
| Extensões | Plugins e ferramentas exclusivas do harness padrão nesse diretório | [Pacotes do harness experimental](/docs/pt/project/manifest#harnesses) em `harnesses.pi.packages` e arquivos de extensão em `extensions/` |

Uma sessão harness experimental não lê `opencode.jsonc`, `plugins/`, `tools/` nem `commands/`. Uma sessão harness padrão não lê o diretório do harness experimental. Uma ferramenta necessária para ambos os harnesses é uma [ferramenta do projeto](/docs/pt/project/tools), declarada em `beeuni.yaml`, não um arquivo em nenhum dos diretórios.

Os pacotes do harness experimental vêm de packages. Um pacote pode adicionar ferramentas que o harness experimental não possui, como um adaptador MCP ou uma ferramenta de tarefas. O Beeuni carrega o pacote; ele não testa pacotes de terceiros.