# Flussi di lavoro per agenti

> Cosa ha aggiunto DuckLocal 0.4.0 per gli agenti di IA: SQL limitato, un passaggio di consegne controllato alla finestra, proposte di dashboard, registri di analisi e progetti portabili.

Source: https://ducklocal.app/docs/it/agent-workflows

::: info Novità nella 0.4.0
Tutto ciò che è descritto in questa pagina è arrivato con la [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0). Se `ducklocal check --help` non elenca `--restricted`, la tua copia è più vecchia; [aggiorna](getting-started.md) per usarlo.
:::

Un agente può già interrogare file, creare una dashboard e leggere i tuoi commenti con la [CLI](cli.md). Queste aggiunte coprono ciò che accade intorno a quel lavoro: limitare l'SQL che non ha scritto, sapere cosa ha fatto la finestra con una richiesta, lasciarti approvare una modifica e registrare come si è arrivati a una risposta.

## Limita l'SQL che non hai scritto {#restricted}

`--restricted` serve per l'SQL copiato dai dati e per una dashboard scritta da qualcun altro. La sola modalità di sola lettura non basta: protegge il file del database, mentre `COPY` può comunque scrivere ovunque tu possa e `FROM 'https://...'` può comunque inviare una richiesta.

```bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
```

| L'SQL tenta di | Risultato |
| --- | --- |
| Leggere un file sotto `--allow-read` | Consentito |
| Leggere qualsiasi altro file, per percorso, glob o `..` | Negato |
| Scrivere un file, anche sotto `--allow-read` | Negato |
| Fare `ATTACH` a un database, o crearne uno | Negato |
| Raggiungere `http`, `https`, `s3` o qualsiasi altro URL | Negato |
| `INSTALL` o `LOAD` un'estensione | Negato |
| Cambiare un'impostazione, compresi questi limiti | Negato |
| Eseguire più a lungo di `--timeout` (60 secondi per impostazione predefinita) | Interrotto, kind `timeout` |
| Usare più di `--memory-limit` (`2GB` per impostazione predefinita) | Fallisce, kind `resource_limit` |

Senza `--allow-read` nessun file è leggibile, e questo include la cartella della dashboard stessa. Un'istruzione negata esce con codice 1 e kind `policy_denied` e non ripiega mai sull'esecuzione senza restrizioni. Anche `EXPLAIN`, `PRAGMA` e un `PIVOT` di primo livello vengono rifiutati, perché l'istruzione deve essere un solo SELECT.

**Questa non è una sandbox.** I limiti sono quelli di DuckDB e DuckLocal non applica alcun isolamento del sistema operativo su nessuna piattaforma. Vincolano l'SQL, non chi sceglie i flag: un agente con una shell può togliere `--restricted`. Per contenere un agente di cui non ti fidi, esegui l'agente stesso in un container o in una VM. `schema`, `profile`, `project check` e `open --run` non girano in modalità limitata, e nemmeno la finestra quando apre una dashboard.

[Cosa limita l'SQL eseguito da un agente](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md) contiene il modello di minaccia completo e cosa è stato testato su ogni piattaforma.

## Resta al passo con la finestra {#handoff}

`ducklocal open` in passato riportava soltanto la consegna. Ora due flag riportano come si è conclusa una richiesta e proteggono dall'agire su una finestra che è cambiata.

```bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
```

- `--wait` attende fino a 5 minuti e aggiunge `status`, `tab_id`, `result_status`, `error` e `revision` all'output.
- `--if-revision REV` non apre nulla se la finestra non mostra più quella revisione, ed esce con codice 1 e kind `stale`. Rileggi lo stato prima di riprovare. Anche una persona che digita in un'altra scheda lo rende obsoleto, di proposito.

`--state` ora riporta anche:

| Campo | Significato |
| --- | --- |
| `schema_version`, `revision` | La versione del contratto e un token di ciò che mostra la finestra |
| `actions` | Che fine hanno fatto le richieste recenti: `stale`, `queued`, `running`, `opened`, `succeeded` o `failed` |
| `limits` | I limiti delle anteprime. Una lettura non restituisce mai un risultato intero |
| `connections` | L'endpoint e la regione di S3, e nome, tipo, posizione e indirizzo di ogni database collegato. **Mai una chiave** |
| `result.reach` | `local`, `remote` o `unknown`, dedotto solo dall'SQL, e se ha usato la tua chiave S3 |
| `sql_withheld` | `true` quando l'SQL di una scheda può contenere una credenziale, e il testo viene sostituito |
| `scope`, su ogni grafico | Quanta parte della sua query disegna il grafico |

`reach` può vedere solo ciò che l'SQL nomina, quindi una vista locale su dati remoti risulta `local`. Leggere uno di questi dati non effettua alcuna richiesta di rete, quindi `location: "remote"` dice dove si trova un database, non che risponda ancora.

Un agente può vedere che S3 è configurato senza vedere la chiave, ma l'SQL che esegue con `open --run` può comunque usare quella chiave.

Il [contratto di passaggio di consegne](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md) elenca ogni campo e tipo di errore, e lo [schema JSON](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json) descrive lo stato.

## Proponi una modifica a una dashboard {#propose}

Quando vuoi approvare una modifica, un agente può proporla invece di modificare il file:

```bash
ducklocal propose sales.dash --status                  # note current_hash
ducklocal propose sales.dash --from new.dash --note "Split revenue by region" --based-on HASH
ducklocal propose sales.dash --status                  # pending, applied or rejected
```

La specifica resta com'è, e la scheda della dashboard mostra che c'è una modifica in attesa. Fai clic su **Rivedi** per eseguire l'SQL proposto e vedere il diff e i controlli, poi fai clic su **Applica** o **Rifiuta**.

- Solo tu puoi applicare una proposta, nella finestra. Non c'è un comando per farlo.
- Applicare conserva la versione precedente come `sales.dash.bak`, e viene rifiutato se la specifica è cambiata dalla proposta.
- Rifiutare lascia la specifica intatta.
- Fare clic su **Rivedi** esegue l'SQL proposto, quindi una proposta di cui non ti fidi può raggiungere tutto ciò che può raggiungere l'SQL della dashboard. Esegui prima `check --restricted` su di essa.

## Registra come si è arrivati a un'analisi {#session}

Imposta `DUCKLOCAL_SESSION`, e `query`, `check`, `propose` e `open` registrano ciascuno quello che hanno fatto:

```bash
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20
```

Senza quella variabile non viene registrato nulla. Il file contiene testo SQL e delle specifiche, la dimensione e l'ora di modifica di ogni origine, e la forma di ogni risultato, mai le sue righe. Gli errori vengono conservati fino a 500 caratteri e possono citare valori, quindi tieni il file fuori dalle cartelle condivise a meno che tu non voglia condividerle.

Ogni passo e ogni conclusione ha `doubts`, calcolato quando leggi il file: cosa è fallito, è stato interrotto o è cambiato da allora. Un elenco vuoto significa che non si sa nulla contro di esso, non che sia giusto.

L'SQL che può contenere una credenziale viene omesso. Quel controllo si basa su parole come `secret`, `token` e `access_key`, quindi anche una colonna con uno di quei nomi nasconde la sua query.

## Mantieni un'analisi spostabile {#project}

```bash
ducklocal project init             # write ducklocal-project.json
ducklocal project check            # what a move would break
ducklocal project relink --source orders --to data/2026/orders.csv
```

Un `ducklocal-project.json` è facoltativo. Elenca le dashboard di una cartella e ciò di cui hanno bisogno; i dati sono referenziati, mai copiati. Aprirlo nella finestra apre quelle dashboard.

`project check` riporta `ok`, `portable`, `problems` (ciascuno con un `hint`) e `limitations`, ed esce con 0 qualunque cosa trovi, quindi leggi l'output. Non accede mai alla rete né installa nulla. Il fatto che passi non dimostra che i dati siano gli stessi. `project relink` modifica le tue dashboard e conserva ogni vecchia versione come `NAME.dash.bak`.

## Un esempio completo {#worked-example}

[Una chiave trapelata, indagata da un agente e da una persona](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation) percorre una settimana inventata di CloudTrail dalla prima query a una dashboard revisionata. Un test esegue la metà dell'agente a ogni modifica. Nessuno ha ancora fatto clic sulla metà della finestra di questo esempio, e il suo README indica quali passi sono.
