# Flux de travail des agents

> SQL restreint, passation vérifiée vers la fenêtre, propositions de tableau de bord, enregistrements d'analyse et projets portables dans DuckLocal 0.4.0.

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

::: info Nouveau dans la 0.4.0
Tout ce qui figure sur cette page est arrivé avec [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0). Si `ducklocal check --help` n'affiche pas `--restricted`, votre copie est plus ancienne ; [mettez-la à jour](getting-started.md) pour l'utiliser.
:::

Un agent peut déjà interroger des fichiers, construire un tableau de bord et lire vos commentaires avec la [CLI](cli.md). Ces ajouts couvrent ce qui entoure ce travail : limiter du SQL qu'il n'a pas écrit, savoir ce que la fenêtre a fait d'une requête, vous laisser approuver une modification et enregistrer comment une réponse a été obtenue.

## Limiter le SQL que vous n'avez pas écrit {#restricted}

`--restricted` s'adresse au SQL copié depuis des données et à un tableau de bord écrit par quelqu'un d'autre. Le mode lecture seule ne suffit pas : il protège le fichier de base de données, alors que `COPY` peut toujours écrire partout où vous pouvez écrire et que `FROM 'https://...'` peut toujours envoyer une requête.

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

| Ce que le SQL tente de faire | Résultat |
| --- | --- |
| Lire un fichier sous `--allow-read` | Autorisé |
| Lire tout autre fichier, par chemin, glob ou `..` | Refusé |
| Écrire un fichier, même sous `--allow-read` | Refusé |
| `ATTACH` une base de données, ou en créer une | Refusé |
| Atteindre `http`, `https`, `s3` ou toute autre URL | Refusé |
| `INSTALL` ou `LOAD` une extension | Refusé |
| Modifier un paramètre, y compris ces limites | Refusé |
| S'exécuter plus longtemps que `--timeout` (60 secondes par défaut) | Interrompu, kind `timeout` |
| Utiliser plus que `--memory-limit` (`2GB` par défaut) | Échec, kind `resource_limit` |

Sans `--allow-read`, aucun fichier n'est lisible, y compris le dossier du tableau de bord lui-même. Une instruction refusée se termine avec le code 1 et le kind `policy_denied`, et ne retombe jamais sur une exécution sans restriction. `EXPLAIN`, `PRAGMA` et un `PIVOT` de premier niveau sont eux aussi refusés, car l'instruction doit être un seul SELECT.

**Ce n'est pas un bac à sable.** Les limites sont celles de DuckDB, et DuckLocal n'applique aucune isolation du système d'exploitation, sur aucune plateforme. Elles lient le SQL, pas celui qui choisit les options : un agent disposant d'un shell peut retirer `--restricted`. Pour contenir un agent auquel vous ne faites pas confiance, exécutez l'agent lui-même dans un conteneur ou une VM. `schema`, `profile`, `project check` et `open --run` ne s'exécutent pas en mode restreint, et la fenêtre non plus lorsqu'elle ouvre un tableau de bord.

[Ce qui limite le SQL exécuté par un agent](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md) contient le modèle de menace complet et ce qui a été testé sur chaque plateforme.

## Rester synchronisé avec la fenêtre {#handoff}

`ducklocal open` ne signalait auparavant que la remise, rien de plus. Deux options indiquent désormais comment une requête s'est terminée et protègent contre une action sur une fenêtre qui a changé.

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

- `--wait` attend jusqu'à 5 minutes et ajoute `status`, `tab_id`, `result_status`, `error` et `revision` à la sortie.
- `--if-revision REV` n'ouvre rien si la fenêtre n'affiche plus cette révision, et se termine avec le code 1 et le kind `stale`. Relisez l'état avant de réessayer. Une personne qui tape dans un autre onglet rend aussi l'état périmé, volontairement.

`--state` indique désormais aussi :

| Champ | Signification |
| --- | --- |
| `schema_version`, `revision` | La version du contrat, et un jeton pour ce que la fenêtre affiche |
| `actions` | Ce qu'il est advenu des requêtes récentes : `stale`, `queued`, `running`, `opened`, `succeeded` ou `failed` |
| `limits` | Les bornes des aperçus. Une lecture ne renvoie jamais un résultat entier |
| `connections` | Le point de terminaison et la région de S3, ainsi que le nom, le type, l'emplacement et l'adresse de chaque base de données attachée. **Jamais une clé** |
| `result.reach` | `local`, `remote` ou `unknown`, déduit du SQL seul, et s'il a utilisé votre clé S3 |
| `sql_withheld` | `true` quand le SQL d'un onglet peut contenir un identifiant, et le texte est remplacé |
| `scope`, sur chaque graphique | La part de sa requête que le graphique dessine |

`reach` ne voit que ce que le SQL nomme : une vue locale sur des données distantes est donc lue comme `local`. La lecture de toutes ces informations n'effectue aucune requête réseau ; `location: "remote"` indique où se trouve une base de données, pas qu'elle répond encore.

Un agent peut constater que S3 est configuré sans voir la clé, mais le SQL qu'il exécute avec `open --run` peut encore utiliser cette clé.

Le [contrat de passation](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md) liste chaque champ et chaque kind d'erreur, et le [schéma JSON](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json) décrit l'état.

## Proposer une modification de tableau de bord {#propose}

Quand vous voulez approuver une modification, un agent peut la proposer au lieu de modifier le fichier :

```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 spécification reste telle quelle, et l'onglet du tableau de bord montre qu'une modification est en attente. Cliquez sur **Review** pour exécuter le SQL proposé et voir le diff et les contrôles, puis cliquez sur **Apply** ou **Reject**.

- Vous seul pouvez appliquer une proposition, dans la fenêtre. Il n'existe aucune commande pour cela.
- L'appliquer conserve l'ancienne version sous `sales.dash.bak`, et est refusé si la spécification a changé depuis la proposition.
- Un refus laisse la spécification intacte.
- Cliquer sur **Review** exécute le SQL proposé : une proposition à laquelle vous ne faites pas confiance peut donc atteindre tout ce que le SQL du tableau de bord peut atteindre. Lancez d'abord `check --restricted` dessus.

## Enregistrer comment une analyse a été menée {#session}

Définissez `DUCKLOCAL_SESSION`, et `query`, `check`, `propose` et `open` enregistrent chacun ce qu'ils ont fait :

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

Rien n'est enregistré sans cette variable. Le fichier contient le SQL et le texte des spécifications, la taille et la date de modification de chaque source, et la forme de chaque résultat, jamais ses lignes. Les erreurs sont conservées jusqu'à 500 caractères et peuvent citer des valeurs : gardez donc le fichier hors des dossiers partagés, sauf si vous voulez les partager.

Chaque étape et chaque conclusion a ses `doubts`, calculés quand vous lisez le fichier : ce qui a échoué, a été tronqué ou a changé depuis. Une liste vide signifie que rien de connu ne s'y oppose, pas qu'elle est juste.

Le SQL susceptible de contenir un identifiant est omis. Ce contrôle repose sur des mots comme `secret`, `token` et `access_key`, si bien qu'une colonne portant l'un de ces noms masque aussi sa requête.

## Garder une analyse déplaçable {#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 fichier `ducklocal-project.json` est facultatif. Il liste les tableaux de bord d'un dossier et ce dont ils ont besoin ; les données sont référencées, jamais copiées. L'ouvrir dans la fenêtre ouvre ces tableaux de bord.

`project check` rapporte `ok`, `portable`, `problems` (chacun avec un `hint`) et `limitations`, et se termine avec le code 0 quoi qu'il trouve : lisez donc la sortie. Il ne contacte jamais le réseau et n'installe rien. Réussir ne prouve pas que les données sont identiques. `project relink` modifie vos tableaux de bord et conserve chaque ancien sous `NAME.dash.bak`.

## Un exemple concret {#worked-example}

[Une clé divulguée, examinée par un agent et par une personne](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation) parcourt une semaine fictive de CloudTrail, de la première requête à un tableau de bord relu. Un test exécute la moitié de l'agent à chaque modification. Personne n'a encore parcouru dans la fenêtre la moitié de cet exemple qui la concerne, et son README indique de quelles étapes il s'agit.
