DuckDB 2.0 : le CLI compacte sa sortie pour les agents

Ce qui se passe

Quand un agent de code lance duckdb -c "…", il récupère par un tube un texte dessiné pour un humain : bordures, colonnes alignées, types sous les noms. Chaque caractère de décor coûte des jetons. Pire, un gros résultat est coupé avec un pied de page « (40 shown) » qu'un modèle peut survoler, avant de conclure sur des données qu'il n'a jamais vues.

DuckDB 2.0 ajoute un mode agent au CLI.

Le mécanisme

Le mode s'active seul quand trois conditions sont réunies : une variable d'environnement d'agent est définie (AI_AGENT, AGENT, CLAUDECODE, CODEX_CI, CODEX_SANDBOX, CODEX_THREAD_ID, CURSOR_AGENT, GEMINI_CLI, COPILOT_AGENT, COPILOT_CLI, COPILOT_AGENT_SESSION_ID), la sortie n'est pas un terminal, et aucun format n'a été demandé (-csv, -json, -markdown).

Ce qui change, par défaut :

Tableaux Markdown compacts, type dans l'en-tête de colonne : de 25 à 65 % plus petits que les boîtes.
Troncature explicite : jusqu'à 1 000 lignes et 10 000 octets en entier ; au-delà, les 20 premières et les 20 dernières autour d'une ligne « … N rows omitted … », et un pied de page avec un hash du résultat entier, comparable d'un run à l'autre.
Arrêt anticipé : après 100 000 lignes de plus, la requête est stoppée et le compte donné comme minimum.
Erreurs en JSON sur stderr.
Coût annoncé avant exécution quand le plan lit un million de lignes ou plus, et une ligne de progression toutes les 5 secondes.
EXPLAIN au format compact, .tables avec colonnes et nombre de lignes.

Ce que la mesure dit, et ne dit pas

Sur les 22 questions TPC-H en facteur d'échelle 100, posées en français courant sans SQL, avec Claude Code (trois runs avec le mode, trois sans) : 132 runs, 132 réponses justes. Le texte lu venant de DuckDB passe de 123,6 k à 50,8 k jetons, soit −59 %.

L'équipe précise elle-même la limite : le coût total ne bouge pas. Le prompt système, relu à chaque tour, pèse bien plus que les résultats, si bien que les jetons économisés font environ 0,5 % de l'entrée totale. Les runs avec le mode ont même demandé un peu plus de tours (237 contre 224). Le gain est dans la fiabilité de lecture, pas dans la facture.

Comment s'y prendre

Terminal

# voir ce que voit l'agent
duckdb -agent -c "SUMMARIZE FROM 'my_data.parquet'" | cat

# comparer avec le rendu classique
duckdb -no-agent -c "SUMMARIZE FROM 'my_data.parquet'"

Les réglages .maxrows N et .maxbytes N (-1 ou 0 : sans limite) ajustent les seuils ; .startup_text none dans ~/.duckdbrc supprime la ligne d'annonce. Il faut que le binaire duckdb du chemin de l'agent soit en 2.0 ou plus, et que l'agent ne demande pas lui-même un format.

Source : Agent Mode in the DuckDB CLI, DuckDB, 9 octobre 2026. Rapport d'expérience : hannes/agent-mode-experiment.