Work with an AI agent

Work with your AI agent

You connected your own agent under your account. This guide shows how a dashboard looks to the agent, and 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 file in your uploaded files. 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. Imported rows and a datasource that runs in your browser are the exceptions. See What an agent cannot do.
• Explore before it changes anything: read snapshot rows, test a join, try a transform.
• Copy a shared datasource from the datasource library into a dashboard: a prepared query with its data. The library can be empty.
• On an org install, build charts in your sandbox on a dashboard you can view but not edit. Only you and the dashboard's editors see them. When you can edit a dashboard, the agent sees its sandboxes and adds a chart from one when you ask it to.
• On an org install, browse the warehouse catalog: dataset and table names, descriptions and columns, never rows. The agent browses as a service account that the org install registered and that Google lets you use, because you hold the Service Account User role on it. On arkush.app, no service account exists, so 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.

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. It is the fastest way to judge the 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 imported rows. Import the file in the app: drop it on the canvas, or use the Data panel. 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. The entry says 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. A comment that someone else wrote needs your word first: 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, open Dashboard settings (the gear at the top of the right-hand rail), and use Version history. Select a version to view it read-only, then restore it or go back to the current dashboard. This is how 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'."