Work with an AI agent

Work with your AI agent

You connected your own agent under your account. In this guide, you see how a dashboard looks to the agent, and learn the habits that get good results.

What to know first

• A dashboard is one JSON document. Every chart, table, note and filter is in that document. Your agent reads and edits the same document that the app edits, and its changes appear in the app while it works.
• Charts read saved data. A datasource is a named set of saved rows, the snapshot, plus where the rows come from: a query, a sheet, a file at an address, or a file you imported. Charts read the snapshot and never the source itself, such as a BigQuery table or a Google Sheet. Opening the dashboard runs no query. New numbers come from a refresh.
• The agent acts as you. The agent sees the dashboards you can see and edits the ones you can edit. Every change is recorded under your account.

What an agent can do

• Create dashboards, and edit everything in a dashboard: blocks, queries, layout, field formats, the theme.
• Refresh a datasource that the server can run: a derived view, or a query over a file that you brought in. On an org install, a file or a sheet at an address that the server reads, and a query as a registered service account, too. A datasource that runs in your browser, and the rows of a dashboard made before every import was a file, are the exceptions. See What an agent cannot do.
• Explore before it changes anything: read snapshot rows, test a join, try the SQL of a derived view.
• Answer one question from several dashboards you can view, in one query. The agent sees when each dashboard's data was refreshed, and tells you when the refreshes differ.
• Copy a dashboard you can view, with its data, as you do with Duplicate in the app. The copy is private and yours, and the agent then changes the copy. If an admin limits who may download or export data and you are not on that list, the copy carries no data.
• Copy a shared datasource from the datasource library into a dashboard: a prepared query with its data. The library can be empty. The agent can give you the link to a shared datasource's page, where its owner changes it.
• On an org install, build charts in your sandbox on a dashboard you can view. Only you and the dashboard's editors see them. When you can edit a dashboard, the agent sees its sandboxes, your own included, and adds a chart from one when you ask it to.
• Browse the warehouse catalog: dataset and table names, descriptions and columns. The agent sees the data once you refresh a datasource that reads it. On an org install, the agent browses as a service account that the org install registered and that you may use: you hold the Service Account User role on it, or an admin put you on the list of an account with a key file. Everywhere, the agent reads the tables you saved for it with your own Google: tick a dataset in Browse tables in a datasource editor, or pick datasets in Tables for agents on your Settings page. Without either, the agent asks you which table to read.
• Check its own work: validate the dashboard, and render any chart as the same picture that a viewer sees.
• Write up a finding in an article: text beside the dashboard, with charts that keep the filters the finding needs. See Write up a finding in an article.
• Answer comments. A comment needs view access only, so the agent can reply on a dashboard that you can view but not edit.

Your rights carry over to the agent. On arkush.app, a BigQuery query runs as you, in your browser, so the agent writes the query and you select Refresh in the app. The agent continues from the rows that the refresh saves.

You can read the checks yourself in the Findings panel. Switch the dashboard to Edit, then select the warning icon in the icon rail at the right edge. The panel shows what is broken, what will read badly, and how much the charts cost to draw. Each finding is a problem or advice. A problem means the dashboard is broken or reads wrong now. Advice means the dashboard works, but something will cause trouble later. The badge on the rail counts problems only, and a block with a problem shows the same mark in its header.

Some advice describes a choice you made on purpose, such as a note laid over a chart. Select Mark as understood on that advice, write why it stays, and select Mark as understood again. The advice moves to the Understood group with your reason, and your agent no longer gets it after each change. Your agent can mark advice the same way. To see it as advice again, select Show as advice again.

The cost of the charts shows as meters in the panel's Weight section. One meter compares the rows of the fullest datasource with the row cap. Another compares the marks that the charts draw with the limit for a fast dashboard. Point at a meter to read the datasource or the chart that fills it, and its count. A dashboard with no findings shows a green check and Nothing to fix. The (i) beside it says what the checks look for.

The panel shows the checks that run in the browser, and what Vega-Lite said when the canvas drew each chart. Some checks need the server, and only agents get them: the checks for an unregistered service account, an unregistered database and an unknown delivery destination. Each one is about an org-install feature. So your agent can report a finding that the panel does not show. The panel is for editors, so a person who can only view the dashboard does not see it. After an agent finishes, read the panel to check its work.

What an agent cannot do

• Refresh a datasource that runs in your browser: a query under your own Google sign-in, or a Google Sheet that Read with sends to your browser. Such a datasource runs only when a person selects Refresh in the app. On arkush.app, refresh it yourself, and the agent continues from the saved rows. On an org install, the agent can keep the data fresh with a datasource that runs on the server: a sheet or a file at an address that the server reads, or a query as a registered service account.
• Import a file from your computer, or replace the file under a datasource. Import the file in the app: drop it on the canvas, or use the Data workspace. Then the agent works with the imported data like any other datasource. On an org install whose server reads web addresses, give the agent the file's address instead. The agent can then add the file and refresh it itself.
• See or change a dashboard outside your access.
• Change who can see a dashboard. You publish a dashboard to the internet in the app: open the dashboard, then select Share in the header. If you ask the agent to publish a dashboard, it tells you these steps. See Share a dashboard.
• Stamp a maturity level, promote a datasource into the datasource library, save a theme to the theme library, send a delivery, register a service account or a destination, or upload a file. Each of these records a person who stands behind the result, so a person does it in the app.

When arkush refuses the agent

A refusal names its situation with a short code, for example not-shared, and a link to its entry in Error messages. The agent acts on the code. When somebody other than the agent can fix the situation, the agent gives you the message and the link. Read the entry to learn who can fix it and what to do.

Habits that get good results

• Name the dashboard. "On the dashboard 'Course feedback', …" beats "on my dashboard".
• Point at data. Name the datasource you imported, and the dashboard that holds it. Or ask the agent to look in the datasource library first, which holds shared datasources ready to copy into a dashboard. Or name the warehouse table.
• Ask the agent to look at its work. "Render the chart and check that the labels read well." The agent sees the same picture that a viewer sees, theme included.
• Leave comments as requests. A comment you write on a block is a task that your agent can pick up. Write "split this by month" on a chart, then ask your agent to resolve the open comments. Your agent acts on a comment that someone else wrote only after you approve it: your agent tells you what the comment asks and changes nothing until you answer.
• Go back to an earlier version. Each change to the dashboard is kept as a version, with a version number and the name of who saved it: you or an agent. A refresh or a comment makes no version. Older versions thin out: every save for 15 minutes, every change for 2 days, then the last state of each day for 90 days. The list groups versions by day. Switch the dashboard to Edit, then select Version history on the icon rail at the right edge. Select a version to view it read-only, then restore it or go back to the current dashboard. With version history, you review an agent's changes before you keep or undo them.
• Keep the dashboard open while the agent works. The header shows Agent editing, and the blocks the agent changed have a dashed outline. When the agent stops, one notice names all of its changes, for example "Your agent added a table." To take back the whole change, select Undo in the notice. Undo takes back only what the agent changed, and your own edits stay. For more, see When someone else changes the dashboard.

Example asks

• "Create a dashboard 'Enrollment overview' from the shared datasource 'Enrollment by program'. One bar chart of students per year."
• "On 'Course feedback', add a scorecard with the average rating, one decimal."
• "On 'Household budget', I imported a CSV as the datasource 'expenses'. Add a line chart of spending per month."
• "Resolve the open comments on 'Weekly KPIs'."