Build a Mini Data Agent with AVA

models:
  - name: data
    tableReference:
      table: data
    properties:
      description: Each row represents one order.
cubes:
  - name: sales
    baseObject: data
    measures:
      - name: total_sales
        expression: CAST(SUM(sales) AS DOUBLE)
        type: DOUBLE
        description: Sales after discounts, calculated by summing sales.
    dimensions:
      - name: product
        expression: product
        type: VARCHAR
    timeDimensions:
      - name: order_date
        expression: CAST(order_date AS DATE)
        type: DATE
    properties:
      description: |
        Compare both periods using the same set of products. Change is current-period sales minus prior-period sales; negative values indicate a decline.
        Change rate is change divided by prior-period sales. Return null when prior-period sales are zero, indicating that the rate is not applicable.

npm install @antv/[email protected] [email protected] [email protected]

import { AVA } from '@antv/ava';
import { ToolLoopAgent, isStepCount, tool } from 'ai';
import { z } from 'zod';
 
async function createDataAgent({ model, data, semantic }) {
  const ava = new AVA({ llm: { model } });
  await ava.source({ type: 'json', options: { data } });
  await ava.semantic(undefined, () => semantic);
 
  const messages = [];
  let analysis;
  let chart;
 
  const agent = new ToolLoopAgent({
    model,
    instructions: `Analyze the user's task step by step, using conversation history to make each query self-contained.
    Use analyze to compute and verify data.
    For visualize, select relevant rows and fields from analyze results; never invent or change values.
    Base conclusions on tool results and state what data is missing when evidence is insufficient.`,
    stopWhen: isStepCount(8),
    providerOptions: { openai: { parallelToolCalls: false } },
    tools: {
      analyze: tool({
        description: 'Query and analyze data using a self-contained question.',
        inputSchema: z.object({ query: z.string() }),
        execute: async ({ query }) => {
          analysis = chart = undefined;
          analysis = await ava.analyze(query);
          return analysis;
        },
      }),
      visualize: tool({
        description: 'Generate a chart from the visualization request and data returned by analyze.',
        inputSchema: z.object({ query: z.string(), data: z.array(z.record(z.string(), z.unknown())) }),
        execute: async ({ query, data }) => {
          chart = await ava.visualize({ query, data });
          return { chartType: chart?.chartType };
        },
      }),
    },
  });
 
  return {
    async ask(question) {
      chart = undefined;
      messages.push({ role: 'user', content: question });
      const result = await agent.generate({ messages });
      messages.push(...result.responseMessages);
      return { text: result.text, analysis, chart };
    },
    dispose: () => ava.dispose(),
  };
}

import { writeFile } from 'node:fs/promises';
 
const assistant = await createDataAgent({
  model: YOUR_MODEL,
  data: YOUR_DATA,
  semantic: YOUR_SEMANTIC,
});
 
try {
  const task = `Analyze the decline in sales from January to February 2025. List sales for each product in both months and the change,
sort by the size of the decline, reconcile the totals, and show the changes in a bar chart.`;
  const answer = await assistant.ask(task);
  console.log(answer.text);
  console.table(answer.analysis?.data);
  console.log(answer.analysis?.sql);
  if (answer.chart) await writeFile('chart.html', answer.chart.html);
 
  console.log((await assistant.ask('Did Laptop sales fall because a promotion ended?')).text);
} finally {
  await assistant.dispose();
}