React Embedded AnalyticsCustom Agents

The Default Agents cover most dashboard-building tasks, but you can change how the built-in runtime's agents behave: rewrite an agent's instructions, change the tools it can use, or add an agent of your own. You supply agents through the agents field on your Adapter.

Supplying Agents Copy Link

agents is the set of agents the runtime runs. Omit it and you get the defaults. Provide it and you control the set - so include agStudioDefaultAgents when you want to keep the built-in agents alongside your own.

import { agStudioDefaultAgents } from 'ag-studio';

const ai = {
    executeTurn,
    agents: [chartBuilder],
    primaryAgent: 'chart-builder',
};

<AgStudio ai={ai} />

primaryAgent is the agent a conversation starts from - it defaults to 'lead'. Set it to one of your own to start there instead. The array above runs a single custom agent; to keep the built-in agents alongside yours, spread agStudioDefaultAgents into it (agents: [...agStudioDefaultAgents, chartBuilder]).

Defining an Agent Copy Link

An agent has a type, a schema for its parameters, and a config factory that returns its behaviour. The factory receives the parameters and returns the agent's name, instructions, tools, and delegation permissions - so an agent's behaviour can vary by input.

import type { AgAiAgent } from 'ag-studio';

const chartBuilder: AgAiAgent = {
    type: 'chart-builder',
    description: 'Explores the data and builds bar charts.',
    schema: (s) => s.undefined(),
    config: () => ({
        name: 'Chart Builder',
        instructions: (api) => {
            const { tables } = api.getAiContext().schema();
            return `You are a bar-chart specialist for this dashboard.

Voice: always reply in British English, in a warm and concise tone. Open each reply with a one-sentence summary of the action you are about to take.

Build charts with add_widget then configure_widget, using a bar-chart type only. Manage filters with the page and widget filter tools. Explore the data with view_schema and execute_query before building.

Available tables: ${tables.map((t) => t.name).join(', ')}.`;
        },
        tools: [
            { name: 'view_schema' },
            { name: 'execute_query' },
            { name: 'add_widget' },
            { name: 'configure_widget' },
            { name: 'position_widget' },
            { name: 'add_page_filter' },
            { name: 'remove_page_filter' },
            { name: 'add_widget_filter' },
            { name: 'remove_widget_filter' },
        ],
    }),
};

Instructions Copy Link

instructions receives the studio api, so an agent can ground itself in the live dashboard - the schema, the widget catalogue, current page state. Retrieve these through api.getAiContext(); see Context for the full surface. Instructions also shape how the agent responds - the Voice line above steers its tone and language, so you can give an agent a house style or have it reply in another language.

Tools Copy Link

tools lists the tools the agent may call, by name - and it is also how you constrain an agent. chartBuilder is given the query, widget, and filter tools but not remove_widget or the planning tools, so it stays within building bar charts and managing filters. The full set is in the Built-in Tools Reference.

Delegation Copy Link

delegateAgents lists the agent types this agent may hand work to. chartBuilder runs alone, so it needs none. The built-in Lead delegates to the planning, data, page, and widget agents; to have a coordinator delegate to an agent of your own, supply your own coordinator that lists it in delegateAgents.

Example Copy Link

The example below runs chartBuilder as the only agent. Open the AI panel and ask it to "chart net sales by region" to watch it query the data and build a bar chart - and note the British-English, summary-first voice its instructions give it. Ask for a line chart and it will decline and offer a bar chart instead.

Interface Reference Copy Link

Next Steps Copy Link

• Context - Build agent instructions from live dashboard and data state.
• Default Agents - The built-in agents you are extending or replacing.