# エージェントワークフロー

> DuckLocal 0.4.0 で AI エージェント向けに追加された機能：制限付き SQL、ウィンドウへの検証付きハンドオフ、ダッシュボードの提案、分析記録、可搬なプロジェクト。

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

::: info 0.4.0 の新機能
このページの内容はすべて [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0) で追加されました。`ducklocal check --help` に `--restricted` が表示されない場合、お使いのバージョンは古いです。[更新](getting-started.md)してから利用してください。
:::

エージェントはすでに [CLI](cli.md) を使ってファイルをクエリし、ダッシュボードを作成し、あなたのコメントを読むことができます。ここで紹介する追加機能は、その作業の周辺で起きることを扱います。つまり、自分が書いていない SQL を制限すること、リクエストに対してウィンドウが何を行ったかを知ること、変更をあなたが承認できるようにすること、そして答えにどうたどり着いたかを記録することです。

## 自分が書いていない SQL を制限する {#restricted}

`--restricted` は、データからコピーしてきた SQL や、他の誰かが書いたダッシュボードのためのものです。読み取り専用モードだけでは足りません。読み取り専用モードはデータベースファイルを守りますが、`COPY` はあなたが書き込める場所ならどこへでも書き込め、`FROM 'https://...'` は依然としてリクエストを送信できます。

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

| SQL が試みること | 結果 |
| --- | --- |
| `--allow-read` 配下のファイルを読む | 許可 |
| パス、glob、`..` を使って他のファイルを読む | 拒否 |
| ファイルに書き込む（`--allow-read` 配下でも） | 拒否 |
| データベースを `ATTACH` する、または作成する | 拒否 |
| `http`、`https`、`s3`、その他の URL に到達する | 拒否 |
| 拡張機能を `INSTALL` または `LOAD` する | 拒否 |
| 設定を変更する（これらの制限自体を含む） | 拒否 |
| `--timeout`（デフォルト 60 秒）より長く実行する | 中断、kind は `timeout` |
| `--memory-limit`（デフォルト `2GB`）を超えて使う | 失敗、kind は `resource_limit` |

`--allow-read` を指定しない場合、どのファイルも読めません。これにはダッシュボード自身のフォルダーも含まれます。拒否されたステートメントは kind `policy_denied` で終了コード 1 を返し、制限なしの実行にフォールバックすることは決してありません。ステートメントは 1 つの SELECT でなければならないため、`EXPLAIN`、`PRAGMA`、トップレベルの `PIVOT` も拒否されます。

**これはサンドボックスではありません。** 制限は DuckDB 自身のものであり、DuckLocal はどのプラットフォームでもオペレーティングシステムによる分離を行いません。制限が縛るのは SQL であって、フラグを選ぶ者ではありません。シェルを持つエージェントは `--restricted` を外せます。信頼できないエージェントを封じ込めたい場合は、エージェント自体をコンテナーや VM で実行してください。`schema`、`profile`、`project check`、`open --run` は制限付きでは実行されず、ウィンドウがダッシュボードを開くときも同様です。

[エージェントが実行する SQL を制限するもの](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md) には、完全な脅威モデルと各プラットフォームでテストした内容が記載されています。

## ウィンドウと歩調を合わせる {#handoff}

`ducklocal open` は以前、配信を報告するだけでした。2 つのフラグが、リクエストがどう終わったかを報告し、変化したウィンドウに対して操作してしまうのを防ぎます。

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

- `--wait` は最大 5 分待機し、出力に `status`、`tab_id`、`result_status`、`error`、`revision` を追加します。
- `--if-revision REV` は、ウィンドウがそのリビジョンを表示していなければ何も開かず、kind `stale` で終了コード 1 を返します。再試行する前に状態を読み直してください。別のタブで人が入力した場合も、意図的に stale になります。

`--state` は次の情報も報告するようになりました。

| フィールド | 意味 |
| --- | --- |
| `schema_version`、`revision` | 契約のバージョンと、ウィンドウが表示している内容を表すトークン |
| `actions` | 最近のリクエストがどうなったか：`stale`、`queued`、`running`、`opened`、`succeeded`、`failed` |
| `limits` | プレビューの上限。読み取りが結果全体を返すことはありません |
| `connections` | S3 のエンドポイントとリージョン、およびアタッチされた各データベースの名前、種類、場所、アドレス。**キーは決して含まれません** |
| `result.reach` | `local`、`remote`、`unknown` のいずれかで、SQL だけから判定され、あわせてあなたの S3 キーを使ったかどうかを示します |
| `sql_withheld` | タブの SQL が認証情報を含む可能性があるときに `true` となり、テキストが置き換えられます |
| `scope`（各プロット上） | そのプロットがクエリのどこまでを描画するか |

`reach` は SQL が名指ししているものしか見えないため、リモートデータに対するローカルビューは `local` と表示されます。これらの情報を読んでもネットワークリクエストは発生しないので、`location: "remote"` はデータベースがどこにあるかを示すものであり、まだ応答するかどうかを示すものではありません。

エージェントはキーを見ずに S3 が設定されていることを確認できますが、`open --run` で実行する SQL は依然としてそのキーを使えます。

[ハンドオフ契約](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md) にはすべてのフィールドとエラー kind が一覧になっており、[JSON スキーマ](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json) が状態を記述しています。

## ダッシュボードの変更を提案する {#propose}

変更を承認したいとき、エージェントはファイルを編集する代わりに変更を提案できます。

```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
```

仕様はそのまま残り、ダッシュボードのタブに変更が待機中であることが表示されます。**Review** をクリックすると提案された SQL が実行され、差分とチェックが表示されます。その後 **Apply** または **Reject** をクリックします。

- 提案を適用できるのは、ウィンドウ上であなただけです。そのためのコマンドはありません。
- 適用すると旧バージョンは `sales.dash.bak` として保持され、提案後に仕様が変更されていた場合は拒否されます。
- 拒否しても仕様は変更されません。
- **Review** をクリックすると提案された SQL が実行されるため、信頼できない提案はダッシュボードの SQL が到達できる範囲にまで到達できます。まず `check --restricted` を実行してください。

## 分析の経緯を記録する {#session}

`DUCKLOCAL_SESSION` を設定すると、`query`、`check`、`propose`、`open` がそれぞれ行ったことを記録します。

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

この変数がなければ何も記録されません。ファイルには SQL と仕様のテキスト、各ソースのサイズと更新時刻、各結果の形状が保存されますが、行は決して保存されません。エラーは 500 文字まで保持され、値を引用することがあるため、共有するつもりがない限りファイルを共有フォルダーに置かないでください。

各ステップと結論には `doubts` があり、ファイルを読むときに計算されます。何が失敗したか、打ち切られたか、それ以降に変更されたか、という内容です。空のリストは、それに反する既知の事実がないという意味であり、正しいという意味ではありません。

認証情報を含む可能性のある SQL は除外されます。このチェックは `secret`、`token`、`access_key` といった単語に基づいて行われるため、そうした名前の列があるとそのクエリも隠されます。

## 分析を可搬なまま保つ {#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
```

`ducklocal-project.json` は省略可能です。フォルダーのダッシュボードと、それらが必要とするものを一覧にし、データは参照されるだけでコピーされません。ウィンドウでこれを開くと、それらのダッシュボードが開きます。

`project check` は `ok`、`portable`、`problems`（それぞれに `hint` があります）、`limitations` を報告し、見つけた内容にかかわらず終了コード 0 で終了するので、出力を読んでください。ネットワークに接続したり、何かをインストールしたりすることは決してありません。合格してもデータが同じであることを証明するわけではありません。`project relink` はダッシュボードを変更し、変更前のものをそれぞれ `NAME.dash.bak` として保持します。

## 実例 {#worked-example}

[漏洩したキーをエージェントと人が調査する](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation) では、架空の 1 週間分の CloudTrail を最初のクエリからレビュー済みのダッシュボードまでたどります。テストは変更のたびにエージェント側の半分を実行します。この例のウィンドウ側の半分をクリックして確認した人はまだおらず、どのステップのことかは README に書かれています。
