Charts in answers — what you get for free, and what you must not do
Your agent draws a chart when an answer carries comparable numbers. Nothing to switch on. What you do control is whether the figures are in the knowledge base, and whether derived numbers go through a tool.
list_toolsupdate_agentsearch_knowledge_basePrinciple — the agent may copy numbers, never compute them. Copying out of retrieved text is reliable; arithmetic is not. Everything on this page follows from that one measurement. More in Design principles.
When an answer already contains a set of comparable numbers, the agent draws them — unprompted, in the middle of an ordinary conversation. There is nothing to enable: any agent with a knowledge base or tools does this. Charts render in the widget, the console, the test panel and the Inbox, and degrade to a compact table on Telegram, WhatsApp and screen readers.
So the useful question is not "how do I turn charts on". It is what makes the difference between a chart that appears and one that gets thrown away.
Every figure must be in the material
Before a chart renders, a deterministic check runs over it: each label-and-value pair must appear in the passages the agent actually retrieved that turn. A pair that cannot be found means the whole block is dropped — the visitor keeps the words and loses the picture, and nothing in the reply says why.
That check is why the practical work is in your knowledge base, not in any setting:
- Short, specific documents win. A long page about a product that never states its price will be retrieved for a pricing question and answer nothing. Give each thing its own short document that states its numbers.
- Write numbers the way people ask about them.
25M,25,000,000and2500万are all matched, as are$49,49 USDand49 美元. Units are not checked, so keep them in the text next to the figure. - Verify with
search_knowledge_basebefore you rely on it. If the passage that comes back has no number in it, no chart is coming either.
Derived numbers go through compute_chart
Shares, growth rates, running totals and bills are exactly what a model gets wrong, and exactly what
makes a chart worth looking at. So the agent does not calculate them: it hands the verbatim figures
to compute_chart, the platform computes the series in code, and the numbers are filled into the
chart without passing back through the model.
derive | For | Give it |
|---|---|---|
share | percent of total | labels + series |
growth | percent change vs the previous period | labels + series |
cumulative | running total | labels + series |
project | "grows X% per period for N periods" | base, rate_pct, periods |
tier | "at that usage, what does it cost" | included, rate_per_unit, base_fee — plus base/rate_pct/periods to project and bill in one call |
The tool is attached automatically to any agent that already has tools, so there is usually nothing
to add. Confirm with list_tools() on your tenant.
Two guards worth knowing, because they explain charts that "should have appeared":
- The inputs are checked too. A price handed to
tierhas to exist in the material as money — next to a currency mark. A model that invents a monthly fee produces an exactly-computed bill built on a figure nobody published, and the chart is dropped for it. - Units must agree.
included,rate_per_unitand the usage values are all in the same unit. Give usage in raw tokens and an allowance in millions and the call is refused rather than billed at a million times the rate.
What you cannot style, and why
Chart colours are derived from your theme colour — the whole palette, both light and dark, the hover state and the tooltip. One setting, every chart type.
Do not try to reach charts from custom_css: they are drawn on a canvas, and CSS cannot reach inside
one. A rule targeting a chart is not overridden, it simply does nothing, which is worse than being
refused. If a chart looks wrong for your brand, change the theme colour.
When it stays quiet
Three numbers is the floor — "up from 120k to 150k" is a sentence, not a bar chart. Yes/no questions and single-value lookups get an answer, not a picture. At most two charts per reply, and a second only when the two measures are in different units.
And if nothing was retrieved that turn, there is nothing to draw. The agent says what it knows and what it does not, which is what it does with words too.