--- title: "Riferimento del manifest" description: "Ogni chiave di beeuni.yaml v2, con valori predefiniti, limiti e regole di convalida." --- Il manifest è il file che la piattaforma considera autorevole per un progetto. Questa pagina elenca tutte le chiavi `beeuni.yaml` (v2), il relativo tipo, il valore predefinito e le modalità di convalida della piattaforma. Per una versione in linguaggio semplice, consulta [Il tuo progetto](/docs/it/project). ## Due livelli di configurazione Un progetto Beeuni ha due livelli di configurazione con responsabilità distinte e non sovrapposte. - **Configurazione Beeuni** — `beeuni.yaml` nella radice del repository definisce l’ambiente del progetto, gli agenti, gli strumenti, i connettori e i trigger. I template sandbox possono fare riferimento a un Dockerfile personalizzato. - **Configurazione dell'agente** — i file degli agenti, le skill e i file dell'harness. L'harness dell'agente li legge nella sandbox e in locale. | Percorso | Contenuto | | --- | --- | | `beeuni.yaml` | Il manifest: agenti e risorse a cui ciascuno può accedere, trigger, connettori, env, template sandbox. | | `agents/.md` | Un agente: frontmatter e prompt di sistema. `agents..file` lo indica. | | `skills//SKILL.md` | Una skill. Ogni harness la carica. | | `memory/` | La memoria del progetto. | | `tools/.ts` | Gli strumenti del progetto, uno per modulo. `tools:` li dichiara; ogni harness li esegue. Vedi [Strumenti](/docs/it/project/tools). | | `harnesses/opencode/` | File letti solo da harness standard: `opencode.jsonc`, `plugins/`, `tools/`, `commands/`. `opencode.config_dir` rimanda qui. | I progetti creati prima del 2026-09 conservano agenti e skill in `.beeuni/opencode/` e la memoria in `.beeuni/memory/`. Beeuni legge entrambi i layout. Il collegamento tra le due parti è il file `.md` dell'agente. Una chiave del manifest `agents.` controlla il file indicato da `agents..file`, oppure `agents/.md` se `file` è omesso. Ogni campo comportamentale si trova solo nel frontmatter e nel corpo di quel file `.md`, mai in `beeuni.yaml`: - prompt di sistema - `model`, `mode` - `temperature`, `top_p` - `steps`, `permission` Il blocco `agents:` del manifest definisce solo la governance: quali agenti possono essere avviati e quali risorse ciascuno può usare. Il validatore la applica. Rifiuta un blocco agente v2 che contiene un campo comportamentale, con un errore che indica il file `.md` dell'agente. ## Posizione e versioni Qualsiasi repo con un manifest valido nella radice è un progetto Beeuni. `beeuni.yaml` (v2, solo YAML) è il formato attuale per i nuovi progetti, creati dal flusso web "Create project" e da `beeuni init`. `beeuni.toml` (v1) continua a funzionare per i progetti esistenti, ma la piattaforma non accetta nuove funzionalità v2. Consulta [TOML legacy](/docs/it/project/legacy-toml) per lo schema v1 e i passaggi per la migrazione da v1 a v2. `beeuni_version: 2` richiede YAML: un file `.toml` che dichiara `beeuni_version: 2` non supera la convalida. Un manifest che dichiara una versione superiore a `2` viene rifiutato senza eccezioni, così la piattaforma non interpreta mai in modo errato un campo futuro. Le chiavi di primo livello sconosciute vengono ignorate, quindi puoi inserire nel file i tuoi metadati. `validateManifest()` è l'unico controllo alla base di `beeuni ship`, della verifica di unione delle richieste di modifica e di `beeuni validate`. Le stesse regole si applicano ovunque, quindi tutto ciò che viene unito a `main` è strutturalmente valido. Lo schema è pubblico e viene generato dallo stesso pacchetto: - [`beeuni.v2.schema.json`](/schema/beeuni.v2.schema.json) - [`beeuni.v1.schema.json`](/schema/beeuni.v1.schema.json) - [`beeuni.schema.json`](/schema/beeuni.schema.json) (in base a `beeuni_version`) Per convalidare il file nell'editor, indica a un `beeuni.yaml` lo schema v2 oppure scaricalo dalla CLI: ```yaml # yaml-language-server: $schema=https://beeuni.ai/schema/beeuni.v2.schema.json beeuni_version: 2 ``` ```bash beeuni schema --version 2 ``` ## Esempio completo ```yaml beeuni_version: 2 default_agent: beeuni project: name: my-project description: What this project is. env: required: [DATABASE_URL] optional: [STRIPE_API_KEY, WEBHOOK_SLACK_SECRET] sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 opencode: config_dir: harnesses/opencode agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md sandbox: ml connectors: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] triggers: - slug: daily-digest type: cron agent: beeuni cron: '0 0 9 * * 1-5' timezone: America/Los_Angeles prompt: | Summarize yesterday's commits. Open a CR against main. ``` ## Chiavi di primo livello | Chiave | Obbligatoria | Note | | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `beeuni_version` | sì | deve essere `2` | | `default_agent` | sì | deve indicare un agente dichiarato e abilitato | | `imports` | no | altri file YAML o directory i cui `triggers`, `connectors`, `agents`, `apps` e `tools` vengono uniti a questo manifest. Vedi [`imports:`](#imports) | | `tools` | no | gli strumenti disponibili in ogni sessione: nome dello strumento → percorso del modulo relativo al repo, oppure `beeuni:` per uno strumento Beeuni. Se è presente la chiave `tools`, le sessioni ricevono solo gli strumenti Beeuni elencati. Ogni harness li esegue. Vedi [`tools:`](#tools) | | `runtime` | no | `"opencode"` (predefinito) o `"pi"`: l'harness dell'agente avviato da una sessione all'interno della sandbox; `pi` esegue harness sperimentale all'interno del daemon della sandbox e legge gli stessi file `.md` dell'agente e le sue skill. Il flag di funzionalità `pi_harness` del progetto seleziona harness sperimentale anche senza questa riga. harness sperimentale richiede il flag `llm_gateway`; senza, la sessione avvia harness standard. | | `harnesses.pi.packages` | no | i pacchetti harness sperimentale caricati dalle sessioni harness sperimentale del progetto. Vedi [`harnesses:`](#harnesses) | | `pi.config_dir` | no | `harnesses/pi`, poi `.beeuni/pi` se presente. `settings.json`, `extensions/`, `skills/` e `prompts/` nativi di harness sperimentale. | | `project.name` / `project.description` | no | metadati di visualizzazione; la piattaforma non legge `project.name` per il nome visualizzato del progetto | | `env.required` / `env.optional` | no | nomi delle variabili env; `required` è solo indicativo e non viene mai applicato all'avvio della sessione | | `sandbox` / `sandbox.templates` / `sandbox.default` | no | immagine/i sandbox e hardware | | `opencode.config_dir` | no | `harnesses/opencode` predefinito, poi il `.beeuni/opencode` legacy | | `triggers` | no | elenco di trigger cron, webhook e monitor | | `connectors` | no | elenco di definizioni di connettori | | `policy.default_mode` | no | `allow_all` (predefinito) o `risk`; modalità di approvazione dei connettori a livello di progetto | | `agents` | sì | mappa di governance nome-blocco; non deve essere vuota. Con `imports`, la mappa può trovarsi in un file importato | ## `imports:` Suddividi un manifest tra harness sperimentaleù file YAML. Usalo quando `beeuni.yaml` diventa troppo grande per stare in una schermata: 30 trigger con prompt su harness sperimentaleù righe, un connettore per team, un file per gruppo di agenti. ```yaml # beeuni.yaml beeuni_version: 2 default_agent: beeuni imports: - triggers/ # a directory: every .yaml and .yml file below it - agents.yaml # a single file agents: beeuni: connectors: all ``` ```text beeuni.yaml agents.yaml triggers/ reports/ weekly.yaml monthly.yaml dockets/ freedom-forever.yaml ``` ```yaml # triggers/reports/weekly.yaml triggers: - slug: weekly-report name: Cross-Sector Weekly Report type: cron agent: galileo cron: "0 15 * * 0" prompt: |- Build the weekly report. ``` La piattaforma legge il file radice, risolve tutte le importazioni e lavora sul documento risultante. Convalida, scansioni dei trigger, autorizzazioni degli agenti e sincronizzazione dei connettori operano tutte sullo stesso manifest. Un trigger in un file può indicare un agente dichiarato in un altro. **Regole** 1. Un percorso è relativo alla radice del repository. `..`, i percorsi assoluti e i glob vengono rifiutati. 2. Un import di directory include ogni file `.yaml` e `.yml` al suo interno, a qualsiasi profondità, ordinato per percorso. Gli altri file vengono ignorati. 3. Un file importato dichiara `triggers`, `connectors`, `agents`, `apps`, `tools` e `imports`. Ogni altra chiave (`beeuni_version`, `default_agent`, `runtime`, `project`, `env`, `opencode`, `sandbox`, `policy`, `policies`) resta nel file radice. Un file importato che ne imposta una non supera la validazione. 4. Un file importato può importare altri file. Il limite è di 8 livelli e 200 file. Un ciclo è un errore. Un file raggiunto due volte viene unito una sola volta. 5. Un nome, un file. Uno slug di trigger, uno slug di connettore, un nome di agente, un nome di app o un nome di strumento dichiarato in due file è un errore che indica entrambi i file. Nulla sovrascrive silenziosamente. 6. Le voci vengono unite nell'ordine: prima il file importatore, poi i relativi import nell'ordine elencato. Un import non valido interrompe l'intero manifest, come farebbe un errore di sintassi YAML. `beeuni validate`, `beeuni ship` e il controllo di unione della richiesta di modifica lo segnalano prima che raggiunga `main`: ```text imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file ``` **Le modifiche vanno apportate al file che dichiara la voce.** Quando la dashboard, l'API o `beeuni triggers enable|disable|rm` modifica un trigger, un connettore, un agente o un'app dichiarati da un file importato, viene scritto solo quel file. Il file radice non viene riscritto. Una nuova voce viene scritta nel file radice. Spostala manualmente in un file importato se vuoi che si trovi lì. `imports` richiede `beeuni.yaml`. Un manifest `beeuni.toml` ignora la chiave. ## `tools:` Gli strumenti che riceve una sessione, per nome. Un valore può avere una di due forme: | Forma | Significato | | --- | --- | | `beeuni:` | Uno strumento Beeuni (`web_search`, `image_search`, `scrape_webpage`, `memory`, `show`), gestito da Beeuni. La chiave deve essere ``. | | Un percorso di modulo relativo al repository | Uno strumento del progetto, in qualsiasi cartella. Con il nome di uno strumento Beeuni, il modulo sostituisce lo strumento Beeuni. | ```yaml tools: web_search: beeuni:web_search image_search: beeuni:image_search scrape_webpage: beeuni:scrape_webpage memory: tools/memory.ts # replaces the Beeuni memory tool lookup_order: tools/lookup_order.ts crm_note: integrations/crm/note.ts ``` harness standard e harness sperimentale eseguono lo stesso modulo. Il contratto del modulo, `beeuni tools ls`, `beeuni tools eject` e la migrazione da `harnesses/opencode/tools/` sono descritti in [Tools](/docs/it/project/tools). **Regola di selezione.** - Nesbeeuni chiave `tools`, né nel file radice né in un file importato: le sessioni ricevono tutti e cinque gli strumenti Beeuni. Ogni progetto creato prima che l'elenco esistesse continua ad averli. - Una chiave `tools`, anche vuota (`tools: {}` o `tools:` con tutte le righe eliminate): le sessioni ricevono solo gli strumenti Beeuni elencati, come `beeuni:` o come percorso di modulo. Una chiave `tools` in un file importato viene conteggiata. Elimina una riga `beeuni:` per rimuovere quello strumento da ogni agente. Usa [`agents..tools`](/docs/it/project/tools#who-may-use-which-tool) per limitarlo a un agente. **Errori.** - Un nome usa snake_case: `^[a-z][a-z0-9_]{0,63}$`. - Un nome di strumento dell'harness (`bash`, `read`, `write`, `edit`, `apply_patch`, `glob`, `grep`, `list`, `task`, `question`, `todowrite`, `webfetch`, `websearch`, `skill`, `lsp`, `invalid`, `execute`, `plan_exit`, `pty_*`) è un errore. - Un percorso termina con `.ts`, `.js`, `.mts`, `.mjs`, `.cts` o `.cjs`. Non deve iniziare con `/` o `-`, né contenere un segmento `.` o `..`. - `beeuni:` sotto un'altra chiave è un errore. Sotto il nome di uno strumento Beeuni, ad esempio `web_search: beeuni:image_search`: ```text tools.web_search: deve essere `beeuni:web_search` (lo strumento Beeuni) oppure un percorso relativo al repository verso un modulo .ts o .js (ad es. `tools/web_search.ts`) che lo sostituisce. ``` - `beeuni:` per un nome che non è uno strumento Beeuni, ad esempio `web_serch: beeuni:web_serch`: ```text tools.web_serch: deve essere un percorso relativo al repository verso un modulo .ts o .js (ad es. `tools/web_serch.ts`). `beeuni:` nomina uno strumento Beeuni con il proprio nome: `web_search: beeuni:web_search`, `image_search: beeuni:image_search`, `scrape_webpage: beeuni:scrape_webpage`, `memory: beeuni:memory`, `show: beeuni:show`. ``` - `beeuni validate` segnala anche un modulo dichiarato che non esiste. Un valore `beeuni:` non richiede alcun file. **Avvisi.** Un avviso non interrompe mai `beeuni validate`. - Una chiave `tools` che non elenca nessuno dei cinque strumenti Beeuni: ```text tools: le sessioni di questo progetto non ricevono alcuno strumento Beeuni (web_search, image_search, scrape_webpage, memory, show). Aggiungi `: beeuni:` per mantenerne uno. ``` Intercetta i progetti che aggiungono il primo strumento proprio e rimuovono accidentalmente i cinque strumenti. - Un `tools` di un agente che nomina uno strumento Beeuni che il progetto non carica: ```text agents.beeuni.tools: "show" è uno strumento Beeuni che questo progetto non carica: aggiungi `show: beeuni:show` sotto il livello superiore `tools` oppure rimuovilo qui. ``` ## `project:` Metadati facoltativi, rivolti alle persone: `name` e `description`. La piattaforma non legge questa tabella per alcuno scopo: il nome visualizzato di un progetto proviene dal relativo record nel database. Considerala documentazione per chi legge il repository. ## `env:` Dichiara i nomi delle variabili d'ambiente necessarie alle sessioni. I valori risiedono nella pagina Environment variables della dashboard, mai inline nel manifest. La piattaforma li decritta e li inietta come normali variabili d'ambiente all'avvio della sessione. ```yaml env: required: [DATABASE_URL] optional: [STRIPE_API_KEY] ``` | Campo | Tipo | Note | | ---------- | ---------- | -------------------------------------------------------------------------------------------------------- | | `required` | `string[]` | Informativo. La dashboard chiede questi valori all'utente, ma l'avvio della sessione non si blocca se manca un valore. | | `optional` | `string[]` | Disponibile alle sessioni se impostato. L'assenza non è un problema. | I nomi delle variabili d'ambiente corrispondono a `^[A-Z_][A-Z0-9_]*$`. Secrets Manager limita un nome a 64 caratteri: un nome harness sperimentaleù lungo viene analizzato qui, ma non potrà mai ricevere un valore. Anche i nomi che iniziano con `BEEUNI_` non potranno mai ricevere un valore. Mantieni i nomi entro 64 caratteri ed evita il prefisso `BEEUNI_`. Contratto completo: [Secrets](/docs/it/project/secrets). ## `sandbox:` e `sandbox.templates` Un elenco di immagini sandbox denominate e avviabili. Facoltativo: senza voci, ogni sessione avvia l'immagine predefinita della piattaforma. Ogni template richiede esattamente uno tra `dockerfile` (relativo al repository) o `image` (un riferimento Docker pubblico, con tag o digest fissato). ```yaml sandbox: templates: - slug: ml name: ML Development dockerfile: Dockerfile.ml cpu: 4 memory: 16 disk: 50 ``` | Campo | Tipo | Predefinito | Note | | ------------ | ------ | ------------------- | --------------------------------------------------------------------------------- | | `slug` | string | — | Obbligatorio. Unico per progetto. `default` è riservato. | | `name` | string | slug | Etichetta visualizzata nel selettore della dashboard. | | `dockerfile` | string | — | Percorso relativo al repository. Incompatibile con `image`. | | `image` | string | — | Immagine Docker pubblica, con tag o digest bloccato. Incompatibile con `dockerfile`. | | `entrypoint` | string | del livello runtime | Sostituisce l'entrypoint del container. | | `cpu` | int | predefinito del provider | Core vCPU. Limite: 1–32. | | `memory` | int | predefinito del provider | RAM in GiB. Limite: 1–128. | | `disk` | int | predefinito del provider | Disco in GiB. Limite: 1–500. | | `container_runtime` | bool | `false` | Esegue Docker nella sandbox con rete bridge e overlay. Vedi [Runtime](/docs/it/work/runtime#docker-in-the-sandbox). | Ogni valore deve essere un numero intero positivo. Un valore inferiore al minimo non supera la convalida e genera un errore. Un valore superiore al massimo supera la convalida con un avviso, poi viene limitato in fase di esecuzione. Le GPU non sono supportate: dichiarare `gpu` genera un avviso, non un errore. Vedi [Runtime](/docs/it/work/runtime) per sapere cosa aggiunge il livello runtime alla tua immagine. ### `sandbox.default` Imposta `default` su `sandbox` per definire un template come predefinito per l'intero progetto. Ogni sessione, trigger e canale lo avvierà senza dover specificare uno slug. ```yaml sandbox: default: dev templates: - slug: dev dockerfile: Dockerfile.dev ``` `default` deve indicare un template dichiarato in questo manifest oppure il valore riservato `"default"` per l'immagine della piattaforma. Un agente può selezionare il proprio ambiente con `agents..sandbox`. Il valore deve indicare un template del manifest o della dashboard, oppure `"default"`. ```yaml agents: researcher: sandbox: ml ``` La risoluzione del template della sessione segue quest'ordine: 1. `sandbox_slug` esplicito della sessione. 2. `sandbox` dell'agente selezionato. 3. `sandbox.default` del progetto. 4. `"default"` della piattaforma. I trigger cron, i trigger webhook, le pianificazioni e i canali usano il template dell'agente selezionato. Una modifica alle specifiche (`cpu`, `memory`, `disk`, `container_runtime` o all'immagine stessa) ricrea lo snapshot del progetto. Le nuove dimensioni si applicano alla sessione successiva, non a quella in corso. ## `opencode:` Indica dove si trova la directory di configurazione di harness standard. È facoltativo e ha un valore predefinito. ```yaml opencode: config_dir: harnesses/opencode ``` | Campo | Tipo | Predefinito | Note | | ------------ | ------ | ----------------------------------------------- | ------------------------ | | `config_dir` | string | `harnesses/opencode`, poi `.beeuni/opencode` | Directory relativa al repository. | Se `config_dir` non è impostato, Beeuni usa il primo tra `harnesses/opencode` e `.beeuni/opencode` che contiene un `opencode.json` o un `opencode.jsonc`. Questa directory contiene solo i file letti da harness standard: `opencode.jsonc`, `plugins/`, `tools/` e `commands/`. Gli agenti e le competenze si trovano nella radice del repository, in `agents/` e `skills/`. `opencode.jsonc` resta il registro nativo di harness standard per plugin, server MCP, provider e autorizzazioni: non duplicare queste impostazioni nel manifest. Vedi [Agents](/docs/it/project/agents). ## `harnesses:` Impostazioni specifiche per harness. `pi.config_dir` indica una directory relativa al repository contenente la configurazione nativa di harness sperimentale (predefinita: `harnesses/pi`, poi `.beeuni/pi`). La directory viene importata all'avvio di harness sperimentale. `pi.packages` è separato: installa i pacchetti di `harnesses.pi.packages` nel manifest per ogni agente. Al momento esiste una sola chiave di pacchetto: `pi.packages`, i pacchetti harness sperimentale caricati da ogni sessione harness sperimentale del progetto (`runtime: pi` o il flag `pi_harness`). Un pacchetto è qualsiasi elemento disponibile su packages: estensioni (strumenti, hook, comandi), competenze e prompt inclusi nel pacchetto. ```yaml runtime: pi harnesses: pi: packages: - npm:pi-web-access@0.30.0 # pinned extension version - source: npm:pi-mcp-adapter@2.36.0 extensions: ["extensions/*.ts"] # load only these files of the package skills: [] # load none of its skills - ./harnesses/pi/audit.ts # an extension file in this repository ``` | Forma della voce | Significato | | --- | --- | | `npm:@` | Un pacchetto npm a una versione esatta. Un intervallo di versioni o una versione mancante non supera la convalida. | | `./` | Un file di estensione o una directory di pacchetto in questo repository. Non può uscire dal repository tramite `..`. | | `{ source, extensions, skills, prompts, themes }` | La stessa origine con i filtri di inclusione/esclusione di harness sperimentale. Se si omette il filtro, viene caricato tutto; `[]` non carica nulla. | Sono ammesse al massimo 20 voci. Le origini Git non sono accettate. ### Per agente Un agente può aggiungere i propri pacchetti e rimuovere quelli di primo livello, tramite `agents..harnesses`: ```yaml harnesses: pi: packages: [npm:pi-web-access@0.30.0] # every agent agents: researcher: harnesses: pi: packages: [npm:@juicesharp/rpiv-todo@2.11.0] # researcher only reviewer: harnesses: pi: exclude: [pi-web-access] # reviewer loads no web tools ``` - I pacchetti di un agente sono l'elenco di primo livello, meno i suoi `exclude`, harness sperimentaleù i suoi `packages`. - Se una voce dell'agente riguarda un pacchetto presente anche nell'elenco di primo livello, per quell'agente sostituisce la voce di primo livello (con un'altra versione o altri filtri). - `exclude` elenca i nomi dei pacchetti (`pi-web-access`, `@scope/name`) o i percorsi `./` così come compaiono nell'elenco di primo livello. Non accetta mai una versione. - Ogni elenco distinto di pacchetti viene compilato una sola volta. Gli agenti con lo stesso elenco condividono la compilazione. - I pacchetti appartengono all'agente con cui viene avviata una sessione. Un subagente avviato da un altro agente con lo strumento `task` usa solo gli strumenti standard dell'area di lavoro (`bash`, `read`, `write`, `edit`, `glob`, `grep`), non i propri pacchetti né quelli dell'agente principale; gli hook delle estensioni dell'agente principale continuano ad applicarsi alle sue chiamate. Avvia una sessione con quell'agente per usare i suoi pacchetti. Come arrivano i pacchetti in una sessione: 1. L'unione della richiesta di modifica che aggiorna questo elenco compila i pacchetti una volta per la piattaforma sandbox, con gli script di installazione disattivati. Ogni estensione viene precompilata in un unico file minificato. La compilazione conserva gli altri file del pacchetto, tranne il codice già contenuto in quel file, le dichiarazioni di tipo, le mappe sorgente e i file README e CHANGELOG nella radice. I progetti con lo stesso elenco condividono la compilazione. 2. Una sessione nuova o riavviata scarica la compilazione mentre clona il repository e carica direttamente ogni estensione. Una sessione non esegue mai `npm install` né compila un pacchetto. 3. Un pacchetto che non può essere precompilato (per esempio, se il suo `pi.extensions` usa glob) funziona comunque: la sessione lo carica dai pacchetti installati, ma l'operazione richiede harness sperimentaleù tempo. Se il codice di un pacchetto legge uno dei file esclusi dalla compilazione, aggiungi un filtro `extensions` alla sua voce: anche in questo caso la sessione lo caricherà dai pacchetti installati. 4. Una sessione avviata prima che la compilazione sia disponibile si avvia senza i pacchetti del progetto e avvia la compilazione; la sessione successiva li avrà. Beeuni installa anche un insieme di pacchetti di sistema in ogni sessione harness sperimentale. Una voce di progetto per lo stesso pacchetto sostituisce la versione di sistema. Un repository può anche contenere estensioni native di harness sperimentale in `.pi/extensions/*.ts`; harness sperimentale le carica senza una voce nel manifest. Le estensioni vengono eseguite senza interfaccia terminale: strumenti, hook e comandi funzionano; i widget utilizzabili solo da terminale non fanno nulla. ## `triggers:` Un elenco di definizioni cron, webhook e monitoraggio. Ogni voce avvia una sessione che esegue `prompt` come primo messaggio. ```yaml triggers: - slug: daily-digest type: cron cron: '0 0 9 * * 1-5' prompt: Summarize yesterday's commits. ``` | Campo | Obrigatório | Padrão | Observações | | -------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | | `slug` | sim | — | `[a-z0-9][a-z0-9_-]{0,127}`, exclusivo entre os gatilhos. | | `type` | sim | — | `cron`, `webhook` ou `monitor` (experimental). | | `prompt` | sim | — | Não pode estar vazio. Aceita modelos. | | `name` | não | slug | Rótulo legível. | | `agent` | não | `default_agent` | Deve corresponder a uma chave em `agents:`. Omita para usar `default_agent`; não escreva o literal `default`. | | `enabled` | não | `true` | `false` ignora a entrada. | | `model` | não | resolvido no momento do disparo | Formato de conexão `provider/model`. Fixa a sessão disparada nesse modelo. Consulte [Models](/docs/it/project/models). | | `session_mode` | não | `fresh` | `fresh`, `reuse`, `pinned` ou `keyed`. | | `session_id` | obrigatório para `pinned` | — | Sessão exata para receber um novo prompt. | Os gatilhos cron precisam de exatamente um entre `cron` (uma expressão de 6 campos) e `run_at` (um timestamp ISO-8601 único), além de `timezone` como nome IANA. Os gatilhos de webhook precisam de `secret_env`, o nome de um segredo que usa entrega `broker` com o consumidor `connector`. Os gatilhos de monitor precisam de `run` (um comando relativo ao repositório) e `mode` (`poll` ou `stream`), e rejeitam todos os campos de cron e webhook. Para consultar a referência completa dos campos, a configuração das credenciais, os modelos de payload, os endpoints e a estratégia de sessão, consulte [Triggers](/docs/it/connect/triggers). ## `connectors:` Uma lista de ferramentas externas que um agente pode chamar. A definição fica no git; as credenciais ficam na plataforma, nunca no manifesto. Consulte [Connectors](/docs/it/connect/connectors) para ver o modelo conceitual. ```yaml connectors: - slug: gmail-read name: Gmail read only provider: pipedream app: gmail authorization_strategy: user policies: - match: search_email action: always_run ``` | Campo | Obrigatório | Observações | | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `slug` | sim | `[a-z0-9][a-z0-9_-]{0,127}`, exclusivo entre os conectores. | | `provider` | sim | `pipedream`, `mcp`, `openapi`, `postman`, `graphql`, `http` ou `channel`. | | `name` | não | Nome de exibição. O padrão é o slug. | | `authorization_strategy` | não | `project` ou `user`. Se omitido, o padrão é `project`. Uma estratégia de projeto usa as conexões ativas do projeto. Uma estratégia de usuário usa apenas a conexão do membro que está agindo. | | `enabled` | não | O padrão é `true`. | | `credential` | não | Apenas `shared` é compatível. O modo obsoleto `per_user` gera um erro fatal. | | `sensitive` | não | O padrão é `false`. `true` define `require_approval` como padrão para ações sem correspondência, inclusive leituras. As regras explícitas de projeto e conector ainda são avaliadas primeiro. | Campos específicos do provedor: | Provedor | Campo obrigatório | Observações | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `pipedream` | `app` | `account` opcional; o padrão é o slug. | | `mcp` | `url` | `transport`: `http` (padrão) ou `sse`. | | `openapi` | `spec` | Uma URL ou caminho relativo ao repositório. | | `postman` | `spec` | Uma URL ou caminho de Collection JSON, um manifesto `.postman/api` ou uma URL de workspace do Postman. | | `graphql` | `endpoint` | `spec` opcional (SDL). | | `http` | `base_url` | `spec` opcional. | | `channel` | `platform` | `slack`, `teams`, `email` ou `voice`. | | `computer` | — | Gerenciado pela API. Não é possível declará-lo manualmente. Cada computador conectado é uma de suas contas. Consulte [Computers](/docs/it/connect/computers). | Os conectores `channel` raramente precisam de uma entrada escrita manualmente — conectar um canal pelo painel cria uma para você. Consulte [Slack & channels](/docs/it/connect/slack). Os slugs `beeuni_slack`, `beeuni_teams`, `beeuni_email` e `computer` pertencem à plataforma; usá-los com outro provedor é um erro de validação. O conector `computer` é criado quando o primeiro membro conecta um computador, pois os IDs de máquina são identidades do plano de controle da conta e não devem constar no manifesto. `connectors.auth`: facoltativo, per i provider diversi da `pipedream`. `type` è `bearer`, `basic`, `custom`, `api_key`, `oauth1`, `hmac`, `aws_sigv4`, `mtls` o `none` (predefinito). `oauth1` è limitato ai provider `openapi`, `postman` e `http`. `in` è `header` (predefinito), `query` o `cookie`. `name` è obbligatorio quando `type` è `custom` o `api_key`. `connectors.policies`: un elenco di coppie `{match, action}`. `match` è un glob applicato ai nomi degli strumenti. `action` è `always_run`, `require_approval` o `block`. Le policy appartengono al connettore. Tutte le connessioni sotto quel connettore usano le stesse policy. `policy.default_mode`: una chiave di primo livello, distinta da `connectors:`, che imposta la modalità di approvazione dei connettori a livello di progetto. Può assumere il valore `allow_all` (predefinito; viene eseguito ogni strumento non corrispondente) oppure `risk` (richiede l'approvazione per le chiamate non corrispondenti di scrittura e distruttive). Impostala con `beeuni connectors policy set --default ` — vedi [CLI](/docs/it/cli). ## Canali v2 rimuove `channels:` dallo schema. L'instradamento dei canali agli agenti (oggi Slack, Microsoft Teams, email e voce) è uno stato operativo in tempo reale, non una configurazione dichiarativa. Si imposta dalla pagina Canali del dashboard o tramite comandi in chat, lo stesso confine che mantiene le credenziali fuori da git. La connessione di un canale crea comunque una voce `connectors` con `provider: channel` che l'agente può chiamare. Vedi [Slack e canali](/docs/it/connect/slack). La tabella `[[channels]]` di v1 è trattata in [TOML legacy](/docs/it/project/legacy-toml). ## `agents:` Una mappa da nome a blocco, indicizzata per nome dell'agente. Questa mappa serve solo alla governance: stabilisce cosa può usare un agente, mai cosa dice o fa. Questo blocco è il **secondo dei due binding**: un principal riceve i ruoli da Beeuni e un agente porta inoltre le autorizzazioni Beeuni dichiarate qui. Una sessione può fare solo ciò che entrambi consentono. Vedi [Un vocabolario, due binding](/docs/it/accounts#one-vocabulary-two-bindings). ```yaml default_agent: beeuni agents: beeuni: file: agents/beeuni.md connectors: all secrets: all beeuni_permissions: all skills: all release-bot: file: agents/release-bot.md connectors: [github] connectors_required: [github] beeuni_permissions: [project.gitops.push] secrets: [GITHUB_AGENT_TOKEN] ``` | Campo | Predefinito | Note | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | _(chiave della mappa)_ | — | `[a-z0-9][a-z0-9_-]{0,127}`, univoco per progetto. Senza `file`, è anche il nome del file `.md`. | | `file` | `agents/.md` | Percorso relativo al repository del `.md` dell'agente. Vedi [Il file dell'agente](#the-agent-file). | | `enabled` | `true` | `false` considera l'agente non dichiarato: la piattaforma non lo avvierà. | | `connectors` | `none` | Quali slug di connettori può chiamare questo agente. `all` indica tutti i connettori. | | `connectors_required` | `none` | Deprecato: viene analizzato e ignorato. L'avvio della sandbox non è harness sperimentaleù subordinato alla presenza di connettori; una chiamata a un connettore senza connessioni restituisce `connector_not_connected` con un link per connettersi. Se presente, deve comunque essere un sottoinsieme di `connectors`. | | `secrets` | `none` | Quali segreti del progetto riceve questo agente come variabili d'ambiente della sandbox. Rinominato rispetto a `env` di v1. | | `beeuni_permissions` | `none` | Quali autorizzazioni Beeuni (azioni del progetto) può esercitare questo agente tramite CLI, API o git. `all` indica tutte le autorizzazioni del progetto, sempre limitate dal ruolo massimo dell'agente e senza includere le autorizzazioni riservate agli esseri umani. `beeuni_cli` è la forma deprecata: è ancora accettata, con un avviso di convalida; impostare entrambe con valori diversi è un errore. | | `skills` | `none` | Quali skill può caricare questo agente. | | `apps` | `none` | Quali slug di Beeuni App può aprire questo agente quando l'App è `restricted` o `private`. `all` indica tutte le App del progetto. Vedi [Agenti e App](/docs/it/feature-flags/apps#agents-and-apps). | | `tools` | `all` | Quali strumenti può usare questo agente: strumenti dell'harness, di Beeuni e del progetto. `all`, `none`, un elenco (solo quelli) oppure `{ exclude: [...] }` (tutti tranne quelli). La precedente forma a mappa `{ bash: false }` funziona ancora. Diversamente dalle autorizzazioni sopra, se `tools` è omesso sono consentiti tutti gli strumenti. Vedi [Chi può usare quali strumenti](/docs/it/project/tools#who-may-use-which-tool). | | `repository_access` | `true` | Se le nuove sessioni ricevono il repository del progetto. `false` disabilita la distribuzione del repository e l'accesso al repository tramite le credenziali di sessione. Le sessioni esistenti mantengono la policy salvata. | v2 nega per impostazione predefinita: se `connectors`, `secrets`, `beeuni_permissions`, `skills` o `apps` è omesso per un agente dichiarato, viene risolto in `none`. Concedi esplicitamente ogni autorizzazione necessaria all'agente, come fa l'agente `beeuni` dello starter qui sopra. Un progetto che migra da v1 deve concedere nuovamente tutte le autorizzazioni manualmente: in v1, se omesso, `env` (segreti) assume il valore `all`, l'opposto di v2. `connectors_personal` resta un alias di input deprecato per `connectors_required`. I nuovi manifest devono usare `connectors_required`. Il valore `authorization_strategy` del connettore stabilisce se l'autorizzazione appartiene al progetto o al membro. Le autorizzazioni `beeuni_permissions` provengono da un insieme fisso di autorizzazioni con ambito di progetto (`project.read`, `project.gitops.push`, `project.gitops.merge`, `project.gitops.ref.any`, `project.trigger.*`, `project.secret.*`, `project.connector.*` e altre). Le autorizzazioni con ambito account — `member.*`, `billing.*`, `project.create` — non possono mai essere concesse a un agente. Esegui `beeuni validate --scopes` all'interno di una sessione per visualizzare l'elenco aggiornato delle autorizzazioni concedibili. ### Il file dell'agente `agents..file` indica il `.md` dell'agente, relativo alla radice del repository. ```yaml agents: support: file: agents/support.md ``` - Il percorso deve terminare con `.md`. - Il percorso non deve iniziare con `/` o `-`. Non deve contenere segmenti `.` o `..`, né segmenti vuoti. - Ogni segmento può contenere solo lettere, cifre, `_`, `-`, `.` e spazi. - Se `file` è omesso, Beeuni legge `agents/.md`, poi `.beeuni/opencode/agents/.md`. Se è impostato `opencode.config_dir`, il secondo percorso è `/agents/.md`. - Quando il dashboard salva un agente con un `.md`, scrive `file` con quel percorso. - L'API rifiuta una richiesta che modifica `file` (`400`, codice `invalid_config`). Per spostare un agente, sposta il suo `.md` e aggiorna `file` in `beeuni.yaml` nello stesso commit. `beeuni validate` e il controllo di merge della richiesta di modifica rifiutano un `file` non valido, segnalando un errore su `agents..file`. ## Quando le modifiche alla configurazione hanno effetto - Una modifica a un manifest, `agents/`, `skills/` o a una directory di configurazione di harness standard si applica solo dopo che una richiesta di modifica viene unita a `main`. Le sessioni e i trigger leggono il branch predefinito, non i branch delle sessioni. - Una modifica al cron o al webhook di un trigger viene rilevata dallo scheduler entro pochi secondi dall'unione. - Una modifica all'immagine della sandbox o all'hardware ricrea lo snapshot. La nuova specifica si applica alla sessione successiva, non a quella corrente. - Una modifica al valore di un secret nella dashboard viene risolta al momento della creazione della sandbox. Si applica alla sessione successiva, non a una sessione in esecuzione. ## Regole di andata e ritorno Le modifiche nella dashboard sono operazioni di lettura-modifica-scrittura sul file che dichiara la voce: `beeuni.yaml` o un [file importato](#imports). Per mantenere puliti i diff tra le modifiche nell'interfaccia e quelle durante la sessione: 1. Mantieni `beeuni_version` come prima chiave. 2. All'interno di una voce di trigger, ordina i campi `slug`, `name`, `type`, `agent`, `enabled`, poi i campi specifici del tipo e infine `prompt`. 3. Se aggiungi un trigger webhook prima di impostarne il secret, elenca il nome del secret in `env.optional`. Lascia il trigger `enabled: false` finché il valore non è inserito. ### Accesso al repository Imposta `agents..repository_access` su `false` per gli agenti che non necessitano dei file sorgente del progetto. Possono comunque creare file nella sandbox e usare gli strumenti, i secret e i connettori autorizzati. Impostalo su `true` per gli agenti che necessitano del repository. Le autorizzazioni Git restano separate. Modifica questa impostazione nell'editor dell'agente, in **Workspace → Project repository access**. L'impostazione si applica alle nuove sessioni. Le sessioni esistenti mantengono la policy salvata, anche dopo la sostituzione del runtime. ```yaml agents: support: repository_access: false engineer: repository_access: true ``` Il campo deprecato `workspace` resta leggibile: `branch` significa `true` e `runtime` significa `false`. Le configurazioni legacy `read` continuano a rifiutare la creazione della sessione finché non sostituisci il campo con un booleano esplicito. Non esiste una modalità di repository in sola lettura. I campi vecchi e nuovi in conflitto vengono rifiutati. L'editor e l'SDK inviano `repository_access`. Per l'accesso disabilitato, l'API memorizza anche `workspace: runtime` come mirror di compatibilità. Questo preserva la restrizione per le repliche API meno recenti durante il rollout o il rollback. Le letture dell'API omettono il mirror. I manifest scritti manualmente che usano solo `repository_access` richiedono l'API aggiornata.