DuckDBのCLIが、AIエージェントには出力を自動で圧縮する

Claude CodeやCursorに「このテーブル、データを確認して」と頼んで、SQLを実行させた。下の方には小さく「5000 rows (40 shown)」と出ていた。もしAIがその一行を読み飛ばして、見えている40行だけで答えていたら。DuckDBチームは2026年10月9日、公式ブログでCLIに「エージェントモード」という新機能を発表した。公式記事によれば、相手がAIエージェントだと分かると、出力の形式を自動で切り替える。設定は要らない。トークンを6割近く減らせたという実測値まで、DuckDBチーム自身が公開している。

罫線表示はAIには読みにくい

DuckDBのCLIは、もともと人間がターミナルに向かって使うことを前提に作られている。結果は列の幅を揃えた罫線付きの表で出て、行数が多いときは先頭と末尾の20行だけを表示し、間に点を並べる。

├───────────────┴───────┴────────┴───────────────┤
│ 5000 rows (40 shown)                4 columns  │
└────────────────────────────────────────────────┘

人間なら、この点の並びと「(40 shown)」という注記を見て、省略されたと気づく。しかし公式記事が指摘するとおり、Claude CodeやCodex、Cursorのようなコーディングエージェントは違う。ターミナルの画面ではなく、パイプ越しにテキストを受け取るだけの存在だ。スクロールもページ送りもできず、与えられたテキストがすべてになる。読んだ分だけ課金されるので、罫線を揃える余白の文字にまでトークンを払っている。そして「(40 shown)」の一行は、他の行と同じ重みのテキストとして流れてくる。読み飛ばされれば、AIは一部のデータだけを見て、全体を見たつもりで答えを返しかねない。

人間向けの表示は、読み手がAIエージェントに変わった瞬間、情報を伝え損ねる道具になる。ここに手を入れたのが、今回のエージェントモードだ。

3つの条件で相手を自動的に見分ける

公式記事によると、エージェントモードは次の3条件がすべて揃ったときに自動で有効になる。

• CLAUDECODEやCURSOR_AGENTなど、エージェントが自分で設定する環境変数が立っている
• 標準出力の先がターミナルではない(パイプなどに流れている)
• -csvや-jsonのような出力形式を、コマンドの実行者が明示的に指定していない

Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilotは、いずれもこの環境変数のどれかを自分で設定している。出力もパイプ越しに受け取る。つまり、これらのエージェントからDuckDBのCLIを呼ぶだけで、使う側は何も設定しなくてもエージェントモードが働く。逆に-csvなどで出力形式を自分で指定した場合は、「人間が意図して選んだ形式」とみなされ、エージェントモードは手を出さない。

有効になると、出力は罫線付きの表ではなく、型名を見出しに含めたコンパクトなMarkdown表に変わる。

| name:VARCHAR | n:BIGINT | total:HUGEINT | avg_amount:DECIMAL(10,2) |
|---|---|---|---|
| customer_0 | 3 | 777 | 259.00 |
| customer_1 | 3 | 888 | 296.00 |

これは公式記事に載っている説明用の例だ。列の幅を揃える空白が無くなり、|の区切りだけでAIは列を読み取れる。公式記事は、この形式だけで出力が通常より25〜65%小さくなるとしている。

省略の扱いも変わる。1,000行・10,000バイトまでは全部そのまま出す。それを超えると先頭と末尾の各20行を残し、「何行省略したか」をフッターに明記したうえで、結果全体を表すハッシュ値も添える。ハッシュを比べれば、クエリを書き直す前後で結果が変わったかどうかを、全件を読み直さずに確認できる。さらに10万行を超えて返ってきそうなクエリは、その時点で打ち切り、件数を「少なくともこれだけ」という下限として報告する。公式記事が挙げる例では、10億行を返すはずのクエリが30ミリ秒で打ち切られ、「少なくとも102,400行」という報告に変わる。

ここまでで、出力の省略をAIが読み飛ばしにくくする工夫は分かった。では、実際にどれだけ効果があったのだろうか。

実測ではトークンが59%減った

公式記事は、Claude Codeを使った実験の結果を公開している。TPC-Hという標準的なベンチマーク問題集から22問を選び、SQLを使わない平易な英語の指示だけで答えさせた。エージェントモードありと無しをそれぞれ3回ずつ、計132回実行し、全回で正解にたどり着いた。そのうえで、AIが読み込んだDuckDBの出力トークン数は次のように変わった。

123.6千トークンから50.8千トークンへ、59%の削減になる。同じ22問を3回ずつ、132回すべて正解というのは地味に見えて重い実測で、公式記事の数字を見るまで、自分はここまできれいに削れるとは思っていなかった。

トークンは減ってもコストは変わらない

ここで読者と同じように、自分も「じゃあ実行は安く、速くなったはずだ」と考えた。ところが公式記事は、総コストと実行時間には、ほとんど差が出なかったと明記している。エージェントのターン数はむしろ、エージェントモード無しの224回に対し、ありのほうが237回と増えている。

理由は、AIエージェントの動き方にある。エージェントはターンごとに、それまでの指示文(システムプロンプト)を丸ごと読み直してから応答する。このシステムプロンプトは、DuckDBが返すクエリ結果よりはるかに大きい。公式記事によれば、削減できたトークンは、入力全体のおよそ0.5%にしかならない。

つまり、エージェントモードが削っているのは「クエリ結果を読む」部分のトークンだけで、エージェントが毎ターン持ち歩く指示文の大きさはそのまま残る。コストや速度を決めているのは、こちらの大きい方だということになる。

トークン数の削減そのものには意味がないわけではない。132回全問正解という結果は、省略された結果を読み飛ばして誤答する事故を防げていることの裏付けになる。安さや速さを目的にこの機能を試すと、期待したほどの変化は見えない。

v2.0を今すぐ試すには

エージェントモードは公式記事によれば「DuckDB v2.0に搭載される」機能で、単体の拡張機能ではない。ところがDuckDBのリリースカレンダーを見ると、2026年10月11日時点でv2.0.0はまだ掲載されていない。予定表には「2026-10-21」と、暫定の注記付きで載っているだけだ。DuckDBのv2.0プレビュー記事でも、リリース時期は「この秋」としか書かれていない。今日の時点では、正式版はまだ手元に無い。

それでも、今すぐ試す方法はDuckDBの公式インストールページに用意されている。開発中のプレビュー版2.0.0-devを選べばよく、CLIなら次のコマンドでインストールできる。

curl https://install.duckdb.org | DUCKDB_VERSION=alpha bash

同ページはこのプレビュー版について「本番利用にはあまり向かない(“less suitable for production use”)」と明記している。Claude CodeやCursorから普段使いしているDuckDBを、そのままこのプレビュー版へ置き換えるのは避けたほうがいい。別の作業ディレクトリで試すか、v2.0が正式にリリースされるのを待つのが無難だろう。

まとめ

DuckDBのCLIは、AIコーディングエージェントが実行していると自動で見分ける。見分けると、人間向けの罫線表示から、省略を明記したコンパクトなMarkdown表示へ切り替わる。設定は要らず、対応エージェントから呼び出すだけで働く。DuckDBチーム自身の実測では、同じ22問を132回解かせてすべて正解しながら、AIが読むトークンは59%減った。

ただし、この削減がそのままコストや速度の改善にはつながらない。エージェントは毎ターン大きなシステムプロンプトを読み直しており、クエリ結果のトークンはその一部にすぎないからだ。エージェントモードが解決するのは、安さや速さではなく、省略された結果をAIが見落として誤った結論を出す事故の方になる。機能はDuckDB v2.0に搭載され、正式リリースは2026年10月21日を予定しているが暫定の表記にとどまる。今すぐ試したい場合は、プレビュー版2.0.0-devを本番とは別の環境で使うのが、現時点での正しい距離の取り方になる。