# Harness

Una sessione esegue un harness per agenti, harness standard o harness sperimentale. In questa pagina trovi come un progetto ne seleziona uno e le funzionalità supportate da ciascuno.

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

Un harness è il runtime dell’agente all’interno della sandbox di una sessione. Esegue il ciclo del modello, chiama gli strumenti e produce la trascrizione. Beeuni ne offre due: **harness standard** (predefinito) e **harness sperimentale**. Ogni sessione ne esegue esattamente uno.

Entrambi gli harness leggono lo stesso progetto: `beeuni.yaml`, i file dell’agente in
`agents/`, le skill in `skills/`, il `AGENTS.md` radice e `memory/`. I client (web, CLI, TUI, dispositivi mobili, SDK) li leggono entrambi tramite la stessa API di sessione. Le differenze riguardano le funzionalità di sessione nella
[matrice](#what-each-harness-supports) qui sotto e i file che ciascun harness legge per la propria configurazione.

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

## Come una sessione seleziona il proprio harness

Beeuni decide quando una sessione viene avviata, riavviata o ripresa. Una sessione in esecuzione mantiene il proprio harness fino a quel momento.

| Regola, in ordine | Harness |
| --- | --- |
| Il flag `llm_gateway` del progetto è disattivato | harness standard |
| Il flag `pi_harness` del progetto è attivato | harness sperimentale |
| `beeuni.yaml` imposta `runtime: pi` | harness sperimentale |
| Qualsiasi altro caso | harness standard |

- harness sperimentale chiama i modelli solo tramite il gateway LLM di Beeuni. Un progetto con `llm_gateway` disattivato avvia harness standard, indipendentemente dal flag o da quanto indicato nel manifest. Vedi [Modelli](/docs/it/project/models).
- `runtime` è una chiave del manifest `beeuni_version: 2`. Un progetto legacy `beeuni.toml` non può impostarla. Vedi [il riferimento del manifest](/docs/it/project/manifest).
- `pi_harness` è un flag di funzionalità per progetto, disattivato per impostazione predefinita. Vedi
  [Flag di funzionalità](/docs/it/feature-flags).

Per sapere quale harness esegue una sessione, leggi `harness.id` nella risposta `GET /beeuni/health` del daemon della sandbox: `opencode` o `pi`.

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

## Funzionalità supportate da ciascun harness

Un harness elenca le funzionalità di sessione opzionali che fornisce nell’array `capabilities` di `GET /beeuni/health`. Un client nasconde un controllo quando `capabilities` della sessione non contiene l’id. Il controllo dell’SDK è `runtimeSupports`.

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

### Entrambi gli harness

| Funzionalità | harness standard | harness sperimentale |
| --- | --- | --- |
| Turni di chat, streaming, interruzione | Sì | Sì |
| `.md` dell’agente: prompt, `model`, `variant`, `mode`, `permission`, `temperature`, `top_p`, `steps` | Sì | Sì. harness sperimentale non applica `options` (opzioni del provider). |
| [Accesso agli strumenti](/docs/it/project/tools#who-may-use-which-tool) per agente (`agents.<name>.tools` in `beeuni.yaml`: `all`, `none`, un elenco, `exclude`) | Sì | Sì |
| Regole `permission` per agente e richieste di autorizzazione | Sì | Sì |
| Domande (strumento `question`) | Sì | Sì |
| Il file delle regole `AGENTS.md` nella radice del progetto, oppure `CLAUDE.md` se la radice non contiene `AGENTS.md` | Sì. harness standard legge anche il file nelle directory genitrici di `/workspace` e legge `/workspace` mentre applica una release di configurazione. | Sì, solo il file radice. Fa parte del prompt di sistema della sessione e di ogni subagente. [Con le release di configurazione attive](#agentsmd-on-pi), harness sperimentale legge la copia della release. |
| Subagenti (strumento `task`), `session.subagents` | Sì | Sì: `general`, `explore` (sola lettura) e ogni agente del progetto con `mode: subagent` o `all`. Un subagente non può avviare un altro subagente. |
| Skill (`skills/` e le skill gestite di `beeuni-*`), con l’autorizzazione `skills` dell’agente | Sì. L’agente carica una skill con lo strumento `skill`. | Sì. Il prompt di sistema elenca ogni skill autorizzata; l’agente legge il file. |
| [Strumenti Beeuni](/docs/it/project/tools#beeuni-tools-in-beeuniyaml): `web_search`, `image_search`, `scrape_webpage`, `memory`, `show`. Tutti e cinque se in `beeuni.yaml` non è presente la chiave `tools:`; se è presente, quelli indicati come `beeuni:<name>` | Sì | Sì |
| [Strumenti di progetto](/docs/it/project/tools) (`tools:` in `beeuni.yaml`) | Sì | Sì |
| [Release di configurazione](/docs/it/work/runtime#config-convergence), `config.release.v1` | Sì | Sì |
| Compattare (riepilogare) la conversazione, su richiesta e automaticamente quando si avvicina alla finestra di contesto del modello, `session.compact` | Sì | Sì. Una richiesta al modello che supera la finestra compatta la conversazione e viene ritentata una volta. |
| Comandi slash del progetto, `session.commands` | Sì, da `commands/` nella directory di configurazione di harness standard. | Sì, dai modelli di prompt in `prompts/` nella directory di configurazione di harness sperimentale e nei pacchetti harness sperimentale. harness sperimentale non legge `commands/` di harness standard. |
| Terminale nella sandbox (PTY) | Sì | Sì |
| Strumenti `bash`, `read`, `write`, `edit`, `glob`, `grep`; [segreti](/docs/it/project/secrets) nella shell; CLI `beeuni` | Sì | Sì |

Gli strumenti Beeuni e gli strumenti di progetto sono [indipendenti dall’harness](/docs/it/project/tools): il daemon della sandbox esegue un modulo per ogni strumento, per entrambi gli harness, con gli stessi nomi, argomenti e output. harness sperimentale li chiama nel processo del daemon; harness standard li chiama tramite un plugin scritto dal daemon. Entrambi gli harness ricevono lo stesso elenco: uno strumento Beeuni non incluso nella chiave `tools:` del progetto non è disponibile in nessuno dei due. Un progetto che conserva copie degli strumenti Beeuni in `harnesses/opencode/tools/` mantiene le proprie copie in harness standard finché non le elimina.

Gli strumenti web seguono le chiavi di autorizzazione `websearch` (`web_search`, `image_search`) e `webfetch` (`scrape_webpage`) in entrambi gli harness. In harness standard questi strumenti non possono chiedere: una regola `ask` li nega. In harness sperimentale una regola `ask` genera una richiesta di autorizzazione. In harness sperimentale, un comando `memory` che modifica un file segue `edit` e `view` segue `read`; in harness standard lo strumento è regolato solo da una regola `memory`.

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

### `AGENTS.md` su harness sperimentale

harness sperimentale inserisce `AGENTS.md` del progetto nella radice del prompt di sistema come un’unica sezione, `<project_instructions path="AGENTS.md">`, dopo il prompt dell’agente. Se la radice non contiene `AGENTS.md`, usa `CLAUDE.md`, come in harness standard. harness sperimentale non legge alcun `AGENTS.md` in una sottodirectory o directory genitrice.

- **Origine.** Con le [release di configurazione](/docs/it/work/runtime#config-convergence) disattivate, harness sperimentale legge `/workspace/AGENTS.md`. Quando sono attive, harness sperimentale legge la copia nella release e non quella in `/workspace`: una modifica in `/workspace` raggiunge la sessione dopo l’unione nel ramo di base. Se sono attive e non c’è una release disponibile (`config.source: image-default`), harness sperimentale non legge alcun `AGENTS.md`, così come non legge alcuna skill di progetto.
- **Quando.** harness sperimentale legge il file all’avvio del runtime, quando la configurazione viene ricaricata (una nuova release, un push di `/beeuni/env`) e dopo un aggiornamento del repository. Non lo legge prima di ogni turno. Una nuova release diventa disponibile al turno successivo senza riavvio; un turno già in corso mantiene il file precedente.
- **Esclusioni.** Un file vuoto, un file che non è un file regolare e un collegamento simbolico che rimanda al di fuori del repository non aggiungono nulla. Gli ultimi due casi generano un avviso nel log del daemon.
- **Verifica.** `harness.details.agentsMd` nella risposta `GET /beeuni/health` del daemon indica il file caricato da harness sperimentale: `source` (`release` o `workspace`), `path`, `bytes` e `sha` (i primi 12 caratteri esadecimali del suo sha256). Vale `null` quando harness sperimentale non ha caricato alcun file.

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

### Funzionalità disponibili oggi solo in harness standard

| Funzionalità | Capacità | harness standard | harness sperimentale |
| --- | --- | --- | --- |
| Tornare a un messaggio e ripristinarlo. Modifica e nuovo invio usa il riavvolgimento. | `session.rewind` | Sì | No |
| Server MCP (`mcp` in `opencode.jsonc`) | `session.mcp` | Sì | Nessun client MCP. [I connettori](/docs/it/connect/connectors) funzionano su entrambi gli harness tramite la CLI `beeuni connectors`. |
| Elenco delle attività (strumento `todowrite`) e scheda del piano | `session.todo` | Sì | No. La scheda del piano rimane vuota. |
| Collegare il client terminale dell’harness (`beeuni connect`, TUI `Alt+o`) | `session.attach` | Sì | No. Vedi [TUI](/docs/it/cli#sessions). |
| Documento di configurazione runtime (`/global/config`) | `session.config` | Sì | No. Agenti e modelli provengono dal progetto in entrambi gli harness. |
| Creare un fork di una sessione a un messaggio | `session.fork` | Sì | No |
| Eseguire un comando shell come turno | `session.shell` | Sì | No |
| Provider di modelli senza il gateway LLM | — | Sì | No. harness sperimentale richiede `llm_gateway` attivo. |

Una sessione harness sperimentale risponde a una richiesta per una funzionalità che non offre con `501 feature_not_supported`, oppure con `404` per un documento che non ha (`/global/config`). Non ignora la richiesta.

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

## File di configurazione degli harness

Ogni harness ha una directory dedicata ai file letti solo da quell’harness.

| | harness standard | harness sperimentale |
| --- | --- | --- |
| Directory | `harnesses/opencode/`, oppure `opencode.config_dir` | `harnesses/pi/`, oppure `pi.config_dir` |
| Directory legacy | `.beeuni/opencode/` | `.beeuni/pi/` |
| Contenuti | `opencode.jsonc`, `plugins/`, `tools/`, `commands/` | `settings.json`, `extensions/`, `skills/`, `prompts/` |
| Estensioni | Plugin e strumenti esclusivi di harness standard in quella directory | [Pacchetti harness sperimentale](/docs/it/project/manifest#harnesses) in `harnesses.pi.packages` e file di estensione in `extensions/` |

Una sessione harness sperimentale non legge `opencode.jsonc`, `plugins/`, `tools/` o `commands/`. Una sessione harness standard non legge la directory di harness sperimentale. Uno strumento necessario a entrambi gli harness è uno [strumento di progetto](/docs/it/project/tools), dichiarato in `beeuni.yaml`, non un file presente in una delle due directory.

I pacchetti harness sperimentale provengono da packages. Un pacchetto può aggiungere strumenti non disponibili in harness sperimentale, ad esempio un adattatore MCP o uno strumento per le attività. Beeuni carica il pacchetto, ma non verifica i pacchetti di terze parti.