---
title: "Context"
framework: react
version: "2.1.1"
---

# Context

`getAiContext()` returns a structured snapshot of the current Studio state - the data schema, the widget catalogue, the type vocabulary, and dashboard health. It is the raw material for grounding a model: the built-in agents build their instructions from it, and you use the same data when writing [Custom Agents](https://www.ag-grid.com/studio/react/ai-custom-agents/) or your own [Tools](https://www.ag-grid.com/studio/react/ai-toolkit/).

```ts
const ctx = studioApi.getAiContext();

const { tables, relationships } = ctx.schema();
const widgets = ctx.catalogue();
const { aggregations, filterOperators } = ctx.vocabulary;
const pageHealth = await ctx.health.page();
```

## What It Provides

- **`schema()`** - data sources, fields (with types, roles, and descriptions), and relationships. Reflects the current `DataModel`; re-evaluated on every call.
- **`catalogue()`** - the available widget types with descriptions, usage guidance, and default sizing. Re-evaluated on every call.
- **`vocabulary`** - the static enumerations Studio understands: aggregations, filter operators, data types, and field roles.
- **`fragments`** - resolved prose fragments, such as the `@table[id]` / `@field[id]` reference syntax for prompts.
- **`health`** - `health.page()` and `health.widget(id)` return layout, filter, and configuration issues for the active page or a single widget.

`schema()` and `catalogue()` are functions, not fixed values, because the dashboard changes as the user works - call them again to get the current state.

## Grounding a Model

Feed the parts a request needs into your instructions or prompt. For a data question, the schema and vocabulary are usually enough:

```ts
function buildInstructions(api: AgStudioApi): string {
    const { tables } = api.getAiContext().schema();
    const { aggregations } = api.getAiContext().vocabulary;

    return `Answer questions about the loaded data.
Tables: ${tables.map((t) => t.name).join(', ')}.
Available aggregations: ${aggregations.join(', ')}.`;
}
```

In a [Custom Agent](https://www.ag-grid.com/studio/react/ai-custom-agents/), the `instructions` factory receives the `api`, so you build instructions the same way. In your own [Tools](https://www.ag-grid.com/studio/react/ai-toolkit/), call `getAiContext()` to describe the data to the model or to validate arguments before applying a command.

## Interface Reference

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `schema` | `Function` |  | Reflects current DataModel state. Re-evaluated on every access. |
| `catalogue` | `Function` |  | Widget catalogue. Re-evaluated on every access. |
| `vocabulary` | `VocabularyMeta` |  | Static type enumerations available in Studio. |
| `fragments` | `FragmentsMeta` |  | Resolved static prose fragments from AgAiStrings. |
| `health` | `{ page: () => Promise<AgHealthReport>; widget: (widgetId: string) => Promise<AgHealthReport> }` |  | { page: () => Promise; widget: (widgetId: string) => Promise } |

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `string` |  | Optional description of the overall data model. |
| `tables` | `readonly TableMeta[]` |  | Tables available in the data model. |
| `relationships` | `readonly RelationshipMeta[]` |  | Relationships between tables in the data model. |

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  | Widget type identifier. |
| `name` | `string` |  | Human-readable display name. |
| `description` | `string` |  | What the widget does and when to use it. |
| `usage` | `string` |  | Optional guidance on how to configure the widget. |
| `configuration` | `string` |  | Optional summary of the widget's configuration options. |
| `sizing` | `WidgetSizing` |  | Recommended minimum and default sizing. |

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aggregations` | `readonly string[]` |  | Aggregation functions available across the data model. |
| `filterOperators` | `readonly string[]` |  | Filter operators available across the data model. |
| `dataTypes` | `readonly string[]` |  | Data types recognised by Studio. |
| `fieldRoles` | `readonly string[]` |  | Roles a field can take in a widget. |

## Next Steps

- [Custom Agents](https://www.ag-grid.com/studio/react/ai-custom-agents/) - Build agent instructions from context.
- [Toolkit](https://www.ag-grid.com/studio/react/ai-toolkit/) - Use context when building your own tools.