AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Search
Getting started
OverviewQuick StartBuilding a Dashboard
Configuring Data
Data OverviewSync Data SourcesAsync Data SourcesData TypesExpressionsSharing Data
UI Customisation
Modes & LayoutStateThemingLocalisation
AI Assistant
OverviewBuilding an AdapterConfigurationAgentic Experience
User guide
User InterfacePage SettingsData SetupWidgetsFiltersWorking with AI

React Embedded AnalyticsBuilding an Adapter

AG Studio is provider-agnostic and does not bundle a connection to any LLM. To use the AI assistant, you must implement the AgAiAssistant interface, which translates between AG Studio's request format and your chosen AI provider.

The AgAiAssistant Interface Copy Link

The adapter is a plain object with one required method - executeTurn.

executeTurnCopy Link
Function
Execute a single turn of conversation with the AI. A turn consists of sending input and receiving a streamed response.

executeTurn Copy Link

executeTurn is called every time Studio needs an AI response. It receives an AgAiRequest and must return an AgAiResponseHandler synchronously. The handler provides both a real-time stream and a completion promise.

The Assistant Request Copy Link

Each call to executeTurn receives a request containing everything the AI needs.

inputCopy Link
AgAiConversationItem[]
Conversation history to send to the AI, providing context.
instructionsCopy Link
string
System instructions for this specific turn, overriding defaults.
toolsCopy Link
AgToolSchema[]
Tools available for the AI to use during this turn.
toolChoiceCopy Link
'auto' | 'none' | 'required' | AgAiToolChoice
Strategy for how the AI should choose tools.
  • 'auto': AI decides whether to use tools
  • 'none': AI must not use tools
  • 'required': AI must use at least one tool
  • AgAiToolChoice: AI must use the specified tool
    • responseFormatCopy Link
    AgAiTextFormat | AgAiJsonFormat
    Output format configuration controlling response structure.

    The LLM Response Copy Link

    executeTurn must return an AgAiResponseHandler - an object with a stream and a complete promise.

    streamCopy Link
    { [Symbol.asyncIterator](): AsyncIterator<AgAiStreamEvent>; }
    Async iterable of stream events for real-time updates. Events are yielded as they arrive from the AI provider.
    completeCopy Link
    Promise<AgAiResponse>
    Promise that resolves when the response is fully complete. Contains the final, consolidated response data.

    Stream Event Types Copy Link

    The stream yields AgAiStreamEvent values. Each event has a type and event discriminator:

    TypeEventDescription
    statuscreatedResponse object has been created by the provider.
    statusin_progressThe AI is actively generating.
    statuscompletedGeneration finished. The event includes the final AgAiResponse.
    statusfailedGeneration failed.
    errorapi, network, timeout, etc.An error occurred. Includes code and message.
    itemaddedA new output item (message, tool call, reasoning) started.
    itemdoneAn output item finished.
    partaddedA content part within an item started (e.g. a text segment).
    partdoneA content part finished.
    deltaupdateIncremental content - a text or argument chunk to append.
    deltadoneFinal content for a part.

    Tool Call Handling Copy Link

    The adapter does not execute tools. Its only responsibility is to:

    1. Pass AgToolSchema[] definitions to the LLM (via request.tools).
    2. Relay tool call output items from the LLM response back through the stream.
    3. Studio intercepts tool calls, executes them internally, and feeds results back as function_call_output items in subsequent turns.

    This means your adapter never needs to know what view_schema or configure_widget actually do - Studio handles all of that.

    Interface Reference Copy Link

    idCopy Link
    string
    Unique identifier for this response.
    createdAtCopy Link
    number
    Timestamp when the response was created (milliseconds since epoch).
    errorCopy Link
    { /** Error code identifying the type of error. */ code: string; /** Human-readable error message. */ message: string; } | null
    Error details if the response failed, null otherwise.
    incompleteDetailsCopy Link
    { /** The reason for incomplete response. */ reason?: 'max_output_tokens' | 'content_filter'; } | null
    Details about why the response was incomplete. Present when the AI couldn't fully complete its response.
    outputCopy Link
    AgAiOutputItem[]
    Output items produced by the AI (messages, tool calls, reasoning).
    statusCopy Link
    'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete'
    Current status of the response.
    nameCopy Link
    string
    Tool name.
    descriptionCopy Link
    string
    Human-readable description for the LLM.
    parametersCopy Link
    AgJSONSchema
    JSON Schema describing the tool's parameters.

    Next Steps Copy Link