Agenti

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

Un agente è un file Markdown che definisce il comportamento dell’harness in una sessione. Questa pagina illustra i file degli agenti, le skill e il modo in cui una sessione sceglie un agente.

Un harness esegue ogni sessione

Una sessione esegue un agent harness: harness standard (quello predefinito) o harness sperimentale. Harness 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.

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. Il campo file indica il file del comportamento. La mappa può trovarsi in un file elencato nel manifest in 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 per l’elenco completo dei campi di governance.

Dove si trova il file dell’agente

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.

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 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 e Un vocabolario, due binding. 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. 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.

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.

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.

Gli agenti e le skill nuovi o modificati diventano disponibili nelle sessioni future solo dopo che una richiesta di modifica li ha uniti al branch predefinito. Collega gli strumenti esterni prima che un agente possa usarli; consulta Connettori.