Agentic Data Plane

Show Visualizations in a Conversation

A managed agent can answer with a visualization: a titled card holding HTML or SVG that Agentic Data Plane renders in the conversation itself, with optional controls you can interact with. Use it when a number, a comparison, or a layout reads better as a picture than as a paragraph, and when a chart is too fixed a shape for what you want to see.

Unlike charts, visualizations need nothing in the agent’s system prompt. When the client it is talking to supports visualizations, the agent receives the drawing instructions automatically for that conversation.

After reading this page, you will be able to:

  • Ask an agent for a visualization of verified data

  • Read and interact with a rendered visualization

  • Troubleshoot a visualization that doesn’t render

Prerequisites

Ask for a visualization

Open the agent’s Playground tab and ask for the view you want, naming the data to draw from. For example, ask the agent to chart last month’s ticket volume by team from the rows it just read, or to lay out the totals in a card grid.

The agent answers with a fenced code block tagged visualization, followed by a short written takeaway. The block’s body is a JSON object with version set to 1, a title, a description, and the html of the fragment to draw. Agentic Data Plane replaces the block with the rendered card.

The agent uses the environment’s own colors, fonts, and corner radius, so a visualization matches light and dark mode without being told which one is in use. It draws metric cards, charts, heatmaps, diagrams, tables, treemaps, and dashboard layouts, and it embeds the values it needs in the fragment.

Two limits shape what you get back:

  • The agent draws only data you supplied or a tool returned, and labels anything synthetic or estimated. Ask it to show the underlying values if you want to check them.

  • The whole view has to fit the response, so ask for an aggregate with drill-down rather than thousands of individual marks. See Limits.

Instructions that pin the response to another format win. An agent told to answer only with structured JSON returns that instead of a visualization.

Read a visualization

A rendered visualization is a card with its title in the header, its description under it, and the drawing in a frame below. A status line above the frame says whether the drawing is Static visualization or Interactive visualization.

From the header:

  • Select Source to read the JSON the agent sent, and Preview to go back to the drawing.

  • Select the copy control to copy that JSON, for example to paste it into an issue.

  • Select Expand to fill the screen, and press Esc to come back.

An interactive visualization carries a small script, so its buttons, inputs, and keyboard controls redraw the view as you use it. While it runs, Stop ends the interaction and leaves the current drawing in place, which reads as Interactions stopped.

Restart loads the visualization again from the agent’s original block, which discards anything you clicked or typed. It appears on every interactive visualization, and on any visualization that failed to draw.

Visualizations render in the Playground and in the Transcripts tab of both managed and self-managed agents, through the same renderer as charts. Interaction state isn’t recorded, so reopening a session or a transcript shows the view the agent first produced.

An application that calls the agent over A2A gets a visualization only if it asks for one: the agent advertises the capability on its agent card, sends the drawing instructions to a client that requests it, and that client renders the block itself. See Connect Agents with A2A.

What a visualization can’t do

A visualization is drawn in an isolated frame, and its script runs in a worker rather than in the page. That boundary is what makes it safe to render a drawing the model wrote:

  • The script can’t reach the page around it, the network, your browser storage, or any Agentic Data Plane data. It works only with the values the agent embedded in the block.

  • Links, images, media, frames, forms, inline event handlers, and animation elements are removed before the drawing appears, so a visualization can’t navigate anywhere, load anything, or send what you type to anyone.

  • A visualization can’t fetch more data. To chart something it doesn’t have, ask the agent to call a tool and draw the result.

Limits

Agentic Data Plane refuses a block that exceeds any of these limits and shows the reason in place of the drawing.

Item Limit Details

Whole block

256 KiB of UTF-8

Covers the JSON object the agent sends, and the HTML it draws after each redraw.

Title

1 to 120 characters

Shown in the card header.

Description

1 to 1,000 characters

A text summary of the drawing, including where its data came from. Screen readers use it.

Drawing

1 to 180,000 characters, at most 2,000 elements

The element count applies to the drawing after the forbidden markup is removed. A denser view has to be aggregated instead.

Script

Up to 64,000 characters

Optional. A visualization without one is static.

Troubleshooting

Symptom What to do

A Building visualization… placeholder stays in place

The block is still arriving, or the response is still streaming. A complete block renders once the whole response finishes, not as soon as the block closes. If the response has finished and the placeholder is still there, ask the agent for the whole block again, with valid JSON and a closing fence.

Could not render visualization, with a reason

The JSON didn’t match the contract, for example a missing title or a field over its limit. The error names the field. Select Copy source to keep the block, then ask the agent to send it again within the limits.

Visualization exceeds the 256 KiB limit or exceeds 2,000 elements

The view is too large to draw. Ask the agent to aggregate the data, show fewer rows, or split the view.

This browser blocked the visualization runtime

The browser didn’t load the isolated frame, usually because an extension or a strict privacy setting blocks it. Try another browser or profile.

Visualization stopped

The script failed, or a redraw broke the contract. Select Restart to load the original drawing again.

The agent answers with plain HTML, a json block, or a table

The fence has to be tagged exactly visualization. Ask for that. If the agent’s instructions require another response format, that format wins, so relax the instruction or ask for the view in a separate message.

The drawing is empty until you interact with it

The agent built the view in its script instead of in the block. Ask it to send a populated drawing and use the script only for changes.

Nothing renders in your own application

The client has to request the visualization capability and draw the block itself. See Connect Agents with A2A.

Next steps