# Agenti

Un agente è un file Markdown eseguito dall’host della sessione; il manifest ne regola solo l’accesso.

Canonical page: https://beeuni.ai/docs/it/project/agents

Un agente è un file Markdown che definisce il comportamento dell’harness in una
[sessione](/docs/it/work/sessions). Questa pagina illustra i file degli agenti, le skill e
il modo in cui una sessione sceglie un agente.

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

## Un harness esegue ogni sessione

Una sessione esegue un agent harness: harness standard (quello predefinito) o harness sperimentale.
[Harness](/docs/it/work/harnesses) elenca come un progetto ne seleziona uno e quali funzionalità
supporta ciascuno.

Entrambi leggono gli agenti del progetto da `agents/` e le skill da `skills/`.
harness standard legge anche i file usati solo da esso da `harnesses/opencode/`. harness sperimentale
legge i propri da `harnesses/pi/`.

I progetti creati prima del 2026-09 mantengono agenti e skill in
`.beeuni/opencode/`. Beeuni legge entrambi i layout.

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

## Un agente è composto da due file

Ogni agente ha due parti:

- **Comportamento** — un file Markdown, `agents/<name>.md` per impostazione predefinita. Il suo
  frontmatter definisce il modello, la modalità e le regole di autorizzazione. Il corpo è il
  prompt di sistema.
- **Governance** — una voce nella mappa `agents` di `beeuni.yaml`, indicizzata per nome dell’agente.
  Definisce a cosa può accedere l’agente: connettori, segreti, skill, App,
  autorizzazioni Beeuni e [strumenti](/docs/it/project/tools#who-may-use-which-tool).
  Il campo `file` indica il file del comportamento.
  La mappa può trovarsi in un file elencato nel manifest in
  [`imports:`](/docs/it/project/manifest#imports); `default_agent` resta in `beeuni.yaml`.

Il manifest non definisce mai un prompt o una modalità. Il file `.md` non definisce
mai l’accesso alla piattaforma. Consulta [il riferimento del manifest](/docs/it/project/manifest) per
l’elenco completo dei campi di governance.

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

### Dove si trova il file dell’agente

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

- `file` è un percorso relativo al repository. Deve terminare con `.md`.
- Non deve iniziare con `/`. Non deve contenere un segmento `.` o `..`.
- Se manca `file`, Beeuni legge `agents/<name>.md`, poi
  `.beeuni/opencode/agents/<name>.md`.
- Quando la dashboard salva un agente che ha un `.md`, scrive `file` con quel percorso.
- L’API rifiuta di modificare `file`. Per spostare un agente, sposta il suo `.md` e
  aggiorna `file` in `beeuni.yaml` nello stesso commit.

Tutte le regole sui percorsi sono descritte nel
[riferimento del manifest](/docs/it/project/manifest#the-agent-file).

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

## La governance nega l’accesso per impostazione predefinita

Un agente privo delle chiavi `connectors`, `secrets`, `skills`, `apps` o `beeuni_permissions` non ottiene
nessuno di questi accessi. `apps` elenca le [App Beeuni](/docs/it/feature-flags/apps#agents-and-apps)
che l’agente può aprire quando un’App è limitata o privata. Questa concessione è il secondo dei due binding: l’agente
ha anche un ruolo come principal `service_account` — il suo limite massimo — e una
sessione può fare solo ciò che entrambi consentono. Consulta
[Autorizzazioni degli agenti](/docs/it/project/permissions) e
[Un vocabolario, due binding](/docs/it/accounts#one-vocabulary-two-bindings). Imposta un campo su `all` per concedere l’accesso completo, oppure elenca
nomi specifici. `default_agent` in `beeuni.yaml` indica l’agente avviato da una sessione
quando non ne richiedi uno.

Imposta ogni concessione dalla dashboard — Personalizza → Agenti → l’agente, una pagina
per ogni tipo di concessione nella barra Accesso: Skill, Connettori, Segreti, App, autorizzazioni Beeuni — oppure dalla CLI con `beeuni agents scope <agent>`
(`--secrets`, `--connectors`, `--apps`). La pagina App compare solo quando nel progetto è attivo il flag di funzionalità [App](/docs/it/feature-flags/apps). Ogni percorso
scrive lo stesso blocco `agents.<name>` in `beeuni.yaml`.

I progetti legacy `beeuni.toml` (v1) elencano gli agenti in un array, non in una mappa, e
concedono l’accesso completo per impostazione predefinita. Imposta concessioni specifiche per limitare l’accesso. Consulta
[il riferimento del manifest](/docs/it/project/manifest).

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

## Le skill forniscono competenze a un agente

Una skill è un file Markdown in `skills/<name>/SKILL.md`.
L’harness carica una skill su richiesta: Beeuni non inserisce il contenuto delle skill
in ogni prompt. In harness standard l’agente chiama lo strumento `skill`. In harness sperimentale, il
prompt di sistema elenca il nome e la descrizione di ogni skill e l’agente legge
il file. La concessione `skills` dell’agente in `beeuni.yaml`
controlla quali skill può caricare.

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

## Come una sessione sceglie il proprio agente

La creazione di una sessione accetta un `agent_name`. Beeuni avvia quell’agente per la
sessione. Se ometti `agent_name`, Beeuni usa il valore `default_agent` del progetto.
Imposta l’agente predefinito dalla dashboard, dall’API o dall’SDK. Ognuno scrive
`default_agent` in `beeuni.yaml` e invia la modifica al branch predefinito del progetto.

Un agente agisce come se stesso: usa le proprie autorizzazioni Beeuni entro i limiti del suo ruolo,
a prescindere da chi lo avvia. Avviare una sessione non trasferisce all’agente il tuo ruolo.
Consulta [Autorizzazioni degli agenti](/docs/it/project/permissions).

Gli agenti e le skill nuovi o modificati diventano disponibili nelle sessioni future solo dopo che una
[richiesta di modifica](/docs/it/work/change-requests) li ha uniti al branch predefinito. Collega gli strumenti esterni prima che un agente possa usarli; consulta
[Connettori](/docs/it/connect/connectors).