DuckDB CLI 新增 Agent Mode，管線輸出改為給模型讀
DuckDB 官方部落格 · 2026-10-09
DuckDB CLI 偵測到自己被 AI coding agent 呼叫、且 stdout 不是終端機時，不再輸出給人看的方框表格，而是改成精簡的 markdown 表格與 JSON 錯誤。這個功能隨 DuckDB v2.0 發布，對應 PR #26167，該 PR 於 2026-10-01 合併。
原本的問題
預設的 box 渲染器會補空白、畫邊框，這些字元對模型只花 token、沒有資訊。結果被截斷時，只留下一行 (40 shown) 之類的頁尾，模型很容易略過，把不完整的結果當成全部。
錯誤訊息很長，agent 得靠文字比對才能判斷處理方式；官方文章舉例，一則錯誤就有 2.7 kB。長查詢開跑前也沒有任何警告，agent 只能等到逾時。
核心改動
自動啟用需同時滿足三個條件：設了 agent 環境變數、stdout 不是終端機、沒有指定輸出格式旗標。偵測的變數包含 AI_AGENT、CLAUDECODE、CODEX_CI、CURSOR_AGENT、GEMINI_CLI、COPILOT_AGENT 等。
| 項目 | 一般模式 | Agent Mode |
|---|---|---|
| 表格 | 方框、欄位補空白 | 無補白的 markdown，型別寫在欄名（name:VARCHAR） |
| 大結果 | 依終端機設定截斷 | 1,000 列或 10,000 bytes 內全印；超過則印前後各 20 列，加省略標記、總數與雜湊 |
| 錯誤 | 人類可讀文字 | stderr 輸出 JSON（沿用 errors_as_json，去掉 candidates） |
| EXPLAIN | 完整計畫 | 預設 compact 格式 |
官方說緊湊表格比方框輸出小 25% 到 65%。頁尾的結果雜湊與列順序無關，且區分 NULL 與 'NULL'，agent 可用它比對兩次查詢結果是否相同。
超過上限後，CLI 會再多數 100,000 列就停止查詢，並把總數標為下限。官方範例 FROM range(1_000_000_000); 在 30 毫秒內返回。預期讀取約 100 萬列以上時，stderr 會先印 estimate:，長查詢則每 5 秒印一行 progress:。
開關與覆寫
duckdb -agent -c "SUMMARIZE FROM 'my_data.parquet'" | cat
duckdb -agent -csv # 強制啟用，同時指定格式
duckdb -no-agent # 強制關閉
.maxrows N .maxbytes N .maxcellwidth N
.startup_text none # 寫進 ~/.duckdbrc，關掉啟動提示行單格超過 500 字元會被截斷，可用 .maxcellwidth 調整。-csv、-json、-markdown 一律讓 agent mode 讓路，.show 可看目前狀態。
實測效果
官方用 Claude Code 在 TPC-H scale factor 100 上回答 22 個英文問題，開與關各跑 3 次，共 132 次，答案全部正確。DuckDB 輸出佔用的 token 從 123.6k 降到 50.8k，減少 59%（實驗報告）。
但總成本與執行時間沒有改善：省下的 token 約佔總輸入的 0.5%，因為 system prompt 佔大宗。開啟後的輪數還略多（237 對 224）。文章也承認這是「第一次嘗試」。
影響範圍
- 在 CI 或腳本裡解析 CLI 輸出的人：如果腳本在帶有
CLAUDECODE、CODEX_CI等變數的環境下，用管線讀duckdb輸出且沒指定格式，輸出格式會變；請明確加-csv或-json，或加-no-agent。 - 讓 agent 直接下 SQL 的人：錯誤改成 stderr 的 JSON，agent 的錯誤處理與重試邏輯可直接解析。
- 用其他 agent 的人：偵測只認已知環境變數；沒設變數的 agent 要自己加
-agent，管線執行失敗時 CLI 會在 stderr 印出提示。
文章未涵蓋權限或安全面的設計。該 PR 合併後另有後續提交，加入 DUCKDB_AGENT_MODE=1/0 覆寫（PR #26416）。
原始來源：DuckDB 官方文章、PR #26167