The built-in agents are a starting point, not a fixed team. You can change what they say, what they can do and who they hand work to, all while keeping Studio's harness and chat panel.
To own the run loop instead, see Client Tool Runner.
Declare Your Own Team Copy Link
builtIn is a convenience. Declare agents directly and you control every part:
// Your AgLlmAdapter - see Direct LLM Runner.
const adapter = myOpenAiAdapter({ endpoint: '/api/llm' });
ai: ({ api }) =>
createAiHarness(api, ({ tools: { studio } }) => ({
agents: [
directLlmRunner({
id: 'analyst',
adapter,
instructions: () => 'You build sales dashboards. Prefer bar charts over pie charts.',
tools: () => [
studio.viewSchema(),
studio.viewPage(),
studio.executeQuery(),
studio.addWidget(),
],
}),
],
primary: 'analyst',
})),The builder hands you the Studio tools on tools.studio, so there is no need to call api.getAiTools() yourself. Each tool is a function: call it where you list it. Instructions and tools are callbacks, re-resolved every run, and primary names the agent a new thread starts from.
The example below declares one agent of its own - a chart builder with its own instructions and a narrow tool set - in place of the default team.
import { Component } from "@angular/core";
import { AgStudio } from "ag-studio-angular";
import {
AgAiAgentRunner,
AgAiHarnessSetup,
AgAiModel,
AgAiPromptStarter,
AgDataEngine,
AgDataSourcesDefinition,
AgLlmAdapter,
AgReportState,
AgStudioAiModule,
AgStudioApi,
AgStudioApiReadyEvent,
AgStudioMode,
AgStudioModuleRegistry,
AgStudioProperties,
createAiHarness,
directLlmRunner,
enableStudioDevValidations,
} from "ag-studio";
import { getGhcnCitiesData } from "./shared/ghcnCities/data.ts";
import { ghcnCitiesReportState } from "./shared/ghcnCities/state.ts";
import { openaiAdapter } from "./shared/openaiAdapter.ts";
AgStudioModuleRegistry.registerModules([AgStudioAiModule]);
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableStudioDevValidations();
}
@Component({
selector: "my-app",
standalone: true,
imports: [AgStudio],
template: `<div style="display: flex; flex-direction: column; height: 100%">
<div class="example-controls">
<div class="controls-row">
<button (click)="setPage('temperature')">Temperature</button>
<button (click)="setPage('precipitation')">Precipitation</button>
<button (click)="setPage('blank')">Blank</button>
</div>
</div>
<ag-studio
style="width: 100%; height: 100%;"
class="my-studio-container"
[data]="data"
[mode]="mode"
[initialState]="initialState"
[ai]="ai"
(apiReady)="onApiReady($event)"
/>
</div> `,
})
export class AppComponent {
private studioApi!: AgStudioApi;
data: AgDataSourcesDefinition | AgDataEngine = getGhcnCitiesData(
"https://www.ag-grid.com/studio/archive/3.0.0/example-assets",
);
mode: AgStudioMode = "edit";
initialState: AgReportState = ghcnCitiesReportState;
ai: AgAiHarnessSetup = ({ api }) =>
createAiHarness(api, () => ({
agents: [createChartBuilder(api, adapter)],
primary: "chart-builder",
promptStarters: PROMPT_STARTERS,
models: MODELS,
}));
setPage(pageId: string) {
this.studioApi.setState({
...this.studioApi.getState(),
selectedPageId: pageId,
});
}
onApiReady(params: AgStudioApiReadyEvent) {
this.studioApi = params.api;
}
}
export const AI_API_URL = "https://ai-api.ag-grid.com/api/openai/v1";
export const AI_API_TOKEN = "";
const adapter = openaiAdapter({
endpoint: AI_API_URL,
key: AI_API_TOKEN,
});
/**
* The suggestions a new conversation opens on, worded for the one agent this example declares. The
* last asks for a chart it does not build, so the reader sees a narrowed agent decline and offer the
* closest bar chart instead.
*/
const PROMPT_STARTERS: AgAiPromptStarter[] = [
{
label: "Chart average highs",
prompt: "Chart average high temperature by city.",
},
{
label: "Compare climate bands",
prompt: "Chart average high and average low temperature by climate band.",
},
{
label: "Ask for a line chart",
prompt: "Chart average temperature by year as a line chart.",
},
];
/**
* The models offered beside the send button. Each `id` reaches the adapter as declared here and is
* passed straight on to the provider, so these are real model ids. The first is the one a new
* conversation starts on.
*/
const MODELS: AgAiModel[] = [
{ id: "gpt-5.6-terra", label: "GPT-5.6 Terra" },
{ id: "gpt-5.6-sol", label: "GPT-5.6 Sol" },
{ id: "gpt-5.6-luna", label: "GPT-5.6 Luna" },
];
// The single widget this agent builds into. configure_widget's config schema is fixed to one widget
// type, so the agent adds a 'bar-chart-grouped' widget under this id and then maps data onto it.
const CHART_WIDGET_ID = "bar-chart";
/**
* A self-contained custom agent: it explores the data and builds a bar chart, running its own loop on
* the given LLM adapter. Its tools are pulled from `api.getAiTools()` and re-listed each run; `schema`
* returns `s.undefined()` because a primary agent takes no delegation parameters.
*/
function createChartBuilder(
api: AgStudioApi,
assistant: AgLlmAdapter,
): AgAiAgentRunner {
const studio = api.getAiTools();
return directLlmRunner({
adapter: assistant,
id: "chart-builder",
description: "Explores the data and builds bar charts.",
schema: (s) => s.undefined(),
tools: () => [
studio.viewSchema(),
studio.executeQuery(),
studio.viewPage(),
studio.viewWidget(),
studio.addWidget(),
studio.configureWidget({
widgetType: "bar-chart-grouped",
widgetId: CHART_WIDGET_ID,
}),
studio.positionWidget(),
studio.addPageFilter(),
studio.removePageFilter(),
studio.addWidgetFilter(),
studio.removeWidgetFilter(),
],
instructions: () => {
const { tables } = api.getAiContext().schema();
return `You are a bar-chart specialist for this dashboard. You explore the user's data and build bar charts.
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, then keep any explanation to a sentence or two.
What you do:
- Explore the data with view_schema and execute_query before building anything.
- Build a grouped bar chart in the '${CHART_WIDGET_ID}' widget: add it with add_widget (type 'bar-chart-grouped'), place it with position_widget, then map the data with configure_widget. You only build grouped bar charts; if asked for any other chart type, explain that you build bar charts only and offer the closest bar-chart alternative.
- Manage filters with add_page_filter / remove_page_filter and add_widget_filter / remove_widget_filter.
Available tables: ${tables.map((t) => t.name).join(", ")}.`;
},
});
}
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component.ts';
const app = bootstrapApplication(AppComponent, {
providers: [provideHttpClient()],
});
/**
* OpenAI Responses API adapter for AG Studio.
*
* This is example code - copy it into your project and adapt as needed.
* It maps between AG Studio's AI types and the OpenAI Responses API,
* handling encoding (AG → OpenAI), decoding (OpenAI → AG), and SSE streaming.
*/
import type {
AgAiConversationItem,
AgAiEvent,
AgAiOutputContent,
AgAiOutputItem,
AgAiOutputMessage,
AgAiReasoningItem,
AgAiToolSchema,
AgLlmAdapter,
AgLlmJsonFormat,
AgLlmRequest,
AgLlmResponse,
AgLlmResponseHandler,
AgLlmTextFormat,
} from 'ag-studio';
// =============================================================================
// OpenAI Types (hand-written, minimal)
// =============================================================================
interface OpenAiAdapterOptions {
key?: string;
endpoint?: string;
model?: string;
organization?: string;
}
interface OpenAiConfig {
endpoint: string;
key?: string;
model: string;
organization?: string;
}
// =============================================================================
// JSON Schema → OpenAI strict-mode subset
// =============================================================================
//
// The Shape library emits JSON Schema 2020-12. OpenAI's Responses API in
// `strict: true` mode accepts only a narrow subset. This transform bridges the
// two so docs examples work against OpenAI without forcing Shape authors to
// know the quirks.
//
// What OpenAI accepts: object/array/string/number/integer/boolean/enum/anyOf,
// `$ref` + `$defs` (including recursive), `additionalProperties: false`, and
// the standard string/number/array constraint keywords. Every key in
// `properties` must appear in `required`; optional fields are encoded as a
// nullable type. Open-ended `additionalProperties: <schema>` (i.e. Shape's
// `s.record(...)`) is **not** representable.
type JsonSchema = Record<string, unknown>;
const BANNED_KEYWORDS = [
'allOf',
'not',
'oneOf',
'if',
'then',
'else',
'prefixItems',
'patternProperties',
'propertyNames',
'unevaluatedProperties',
'unevaluatedItems',
'dependentSchemas',
'dependentRequired',
'contains',
] as const;
function isSchema(value: unknown): value is JsonSchema {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
// Shape encodes "undefined" (used in `union(T, undefined)` to mark optionality) as the
// sentinel `{ not: {} }`. OpenAI doesn't allow `not`, so strip these from any `anyOf`
// branches; the surrounding object handler turns the remaining schema nullable for
// optional properties.
function isUndefinedSentinel(s: unknown): boolean {
if (!isSchema(s)) return false;
return Object.keys(s).length === 1 && isSchema(s.not) && Object.keys(s.not as JsonSchema).length === 0;
}
function stripUndefinedSentinel(schema: JsonSchema): JsonSchema {
if (!Array.isArray(schema.anyOf)) return schema;
const filtered = (schema.anyOf as unknown[]).filter((b) => !isUndefinedSentinel(b));
if (filtered.length === schema.anyOf.length) return schema;
if (filtered.length === 0) {
throw new Error('toOpenAiSchema: schema reduces to `undefined`-only - nothing to express');
}
const { anyOf: _, ...rest } = schema;
if (filtered.length === 1 && isSchema(filtered[0])) {
return { ...filtered[0], ...rest } as JsonSchema;
}
return { ...rest, anyOf: filtered as JsonSchema[] };
}
function inferTypeFromValue(v: unknown): string | undefined {
if (v === null) return 'null';
if (typeof v === 'string') return 'string';
if (typeof v === 'boolean') return 'boolean';
if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
return undefined;
}
function makeNullable(schema: JsonSchema): JsonSchema {
if (typeof schema.type === 'string') {
return schema.type === 'null' ? schema : { ...schema, type: [schema.type, 'null'] };
}
if (Array.isArray(schema.type)) {
return schema.type.includes('null') ? schema : { ...schema, type: [...schema.type, 'null'] };
}
if (Array.isArray(schema.anyOf)) {
const branches = schema.anyOf as JsonSchema[];
const hasNull = branches.some((b) => isSchema(b) && b.type === 'null');
return hasNull ? schema : { ...schema, anyOf: [...branches, { type: 'null' }] };
}
return { anyOf: [schema, { type: 'null' }] };
}
function transformSchema(schema: JsonSchema): JsonSchema {
schema = stripUndefinedSentinel(schema);
// OpenAI strict mode rejects any sibling keyword on `$ref` (description, examples, etc.).
// Shape authors apply per-callsite descriptions on the outside of the def - preserve `$ref`
// itself, drop everything else; the description lives inside the referenced `$def` via the
// first emission.
if ('$ref' in schema) {
const { $ref, $defs } = schema as JsonSchema & { $ref: unknown };
return $defs !== undefined ? { $ref, $defs } : { $ref };
}
for (const kw of BANNED_KEYWORDS) {
if (kw in schema) {
throw new Error(`toOpenAiSchema: '${kw}' is not supported by OpenAI strict mode`);
}
}
if ('const' in schema) {
const { const: literalValue, ...rest } = schema as JsonSchema & { const: unknown };
const inferred = inferTypeFromValue(literalValue);
const out: JsonSchema = { ...rest, enum: [literalValue] };
if (out.type == null && inferred != null) out.type = inferred;
return transformSchema(out);
}
const out: JsonSchema = { ...schema };
if (Array.isArray(out.anyOf)) {
out.anyOf = (out.anyOf as JsonSchema[]).map((branch) => (isSchema(branch) ? transformSchema(branch) : branch));
}
if (isSchema(out.$defs)) {
const transformedDefs: JsonSchema = {};
for (const [k, v] of Object.entries(out.$defs as JsonSchema)) {
transformedDefs[k] = isSchema(v) ? transformSchema(v) : v;
}
out.$defs = transformedDefs;
}
if (out.type === 'object' || isSchema(out.properties)) {
if ('additionalProperties' in out && out.additionalProperties !== false) {
throw new Error(
'toOpenAiSchema: open-ended `additionalProperties` (e.g. s.record(...)) cannot be expressed in OpenAI strict mode'
);
}
const properties = isSchema(out.properties) ? out.properties : {};
const required = new Set(Array.isArray(out.required) ? (out.required as string[]) : []);
const newProperties: JsonSchema = {};
for (const [key, propSchema] of Object.entries(properties)) {
const transformed = isSchema(propSchema) ? transformSchema(propSchema) : propSchema;
newProperties[key] = required.has(key)
? transformed
: isSchema(transformed)
? makeNullable(transformed)
: transformed;
}
out.properties = newProperties;
out.required = Object.keys(newProperties);
out.additionalProperties = false;
}
// Array items keep their real schema: only optional PROPERTIES need the required+nullable
// rewrite. Advertising nullable items invites the model to emit `[null]` for values the
// AG-side shapes reject.
if (isSchema(out.items)) {
out.items = transformSchema(out.items);
}
return out;
}
function toOpenAiSchema(schema: JsonSchema): JsonSchema {
if (Array.isArray(schema.anyOf) && schema.type !== 'object' && !isSchema(schema.properties)) {
throw new Error(
'toOpenAiSchema: root schema cannot be `anyOf` - wrap in an object (e.g. `s.object({ value: ... })`)'
);
}
return transformSchema(schema);
}
// =============================================================================
// Encoding: AG → OpenAI
// =============================================================================
function encodeConversationItems(items: AgAiConversationItem[]): unknown[] {
return items.map((item) => {
if (item.kind === 'input' && item.type === 'message') {
return {
type: 'message',
role: item.role,
status: item.status,
content: item.content.map((c) => {
switch (c.type) {
case 'text':
return { type: 'input_text', text: c.text };
case 'image':
return {
type: 'input_image',
detail: c.detail,
file_id: c.fileId ?? null,
image_url: c.imageUrl ?? null,
};
case 'file':
return {
type: 'input_file',
file_id: c.fileId ?? null,
file_data: c.fileData,
file_url: c.fileUrl,
filename: c.filename,
};
}
}),
};
}
if (item.type === 'function_call_output') {
return {
type: 'function_call_output',
call_id: item.callId,
output: item.output,
status: item.status,
};
}
if (item.kind === 'output' && item.type === 'message') {
// No `id`: replayed history is reconstructed conversational context, not a resumed
// OpenAI response. Echoing the original `msg_…` id makes the API treat it as response
// state and demand the linked `reasoning` item (which a view-derived history lacks).
return {
type: 'message',
role: 'assistant',
status: item.status,
content: item.content.map((c) => {
if (c.type === 'text') {
return {
type: 'output_text',
text: c.text,
annotations: c.annotations.map((ann) => {
switch (ann.type) {
case 'file_path':
return { type: 'file_path', file_id: ann.fileId, index: ann.index };
case 'file_citation':
return {
type: 'file_citation',
file_id: ann.fileId,
index: ann.index,
filename: ann.filename,
};
case 'url_citation':
return {
type: 'url_citation',
url: ann.url,
start_index: ann.startIndex,
end_index: ann.endIndex,
title: ann.title,
};
case 'container_file_citation':
return {
type: 'container_file_citation',
container_id: ann.containerId,
file_id: ann.fileId,
start_index: ann.startIndex,
end_index: ann.endIndex,
filename: ann.filename,
};
}
}),
};
}
return { type: 'refusal', refusal: c.refusal };
}),
};
}
if (item.kind === 'output' && item.type === 'function_call') {
// No `id` (same reason as the assistant message above): `call_id` alone pairs the call
// with its `function_call_output`, and a reconstructed `id` isn't a valid `fc_…` anyway.
return {
type: 'function_call',
call_id: item.callId,
name: item.name,
arguments: item.arguments,
status: item.status,
};
}
if (item.kind === 'output' && item.type === 'reasoning') {
return {
id: item.id,
type: 'reasoning',
summary: item.summary.map((s) => ({ type: 'summary_text', text: s.text })),
content: item.content?.map((c) => ({ type: 'reasoning_text', text: c.text })),
};
}
throw new Error(`Unknown conversation item type: ${(item as { type: string }).type}`);
});
}
// =============================================================================
// Decoding: OpenAI → AG
// =============================================================================
// `toOpenAiSchema` rewrites optional properties as required + nullable to satisfy
// OpenAI strict mode, so the model returns `null` for unset optionals. AG-side
// validation treats those fields as optional (not nullable), so strip `null`s
// from tool-call argument payloads on the way back. Only object PROPERTIES are
// stripped: a null array item is either a genuinely nullable value that must
// survive (e.g. a rank filter's `[10, null]` bounds) or invalid input that
// AG-side validation should report rather than have silently deleted.
function stripNulls(value: unknown): unknown {
if (Array.isArray(value)) return value.map((v) => stripNulls(v));
if (value !== null && typeof value === 'object') {
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(value)) {
if (v === null) continue;
out[k] = stripNulls(v);
}
return out;
}
return value;
}
function stripNullsFromToolArgs(argsJson: string): string {
if (!argsJson) return argsJson;
let parsed: unknown;
try {
parsed = JSON.parse(argsJson);
} catch {
return argsJson;
}
return JSON.stringify(stripNulls(parsed));
}
function decodeAnnotations(annotations: any[]): any[] {
return (annotations ?? []).map((ann: any) => {
if (ann.type === 'file_path') {
return { type: 'file_path', fileId: ann.file_id, index: ann.index };
}
if (ann.type === 'file_citation') {
return { type: 'file_citation', fileId: ann.file_id, index: ann.index, filename: ann.filename };
}
if (ann.type === 'url_citation') {
return {
type: 'url_citation',
url: ann.url,
startIndex: ann.start_index,
endIndex: ann.end_index,
title: ann.title,
};
}
if (ann.type === 'container_file_citation') {
return {
type: 'container_file_citation',
containerId: ann.container_id,
fileId: ann.file_id,
startIndex: ann.start_index,
endIndex: ann.end_index,
filename: ann.filename,
};
}
return ann;
});
}
function decodeOutputContent(input: Record<string, any>): AgAiOutputContent {
if (input.type === 'output_text') {
return {
type: 'text',
text: input.text,
annotations: decodeAnnotations(input.annotations),
};
}
return input as AgAiOutputContent;
}
function decodeOutputItem(input: Record<string, any>): AgAiOutputItem {
switch (input.type) {
case 'message': {
const message: AgAiOutputMessage = {
id: input.id ?? '',
kind: 'output',
type: 'message',
role: 'assistant',
status: input.status ?? 'completed',
content: input.content.map(decodeOutputContent),
};
return message;
}
case 'function_call':
return {
id: input.id ?? '',
kind: 'output',
type: 'function_call',
callId: input.call_id,
name: input.name,
arguments: stripNullsFromToolArgs(input.arguments ?? ''),
status: input.status,
};
case 'reasoning': {
const reasoning: AgAiReasoningItem = {
id: input.id ?? '',
kind: 'output',
type: 'reasoning',
summary: input.summary.map((s: any) => ({ type: 'summary', text: s.text })),
content: input.content?.map((c: any) => ({ type: 'text', text: c.text })),
};
return reasoning;
}
default:
throw new Error(`Unknown output item type: ${input.type}`);
}
}
function decodeResponse(input: Record<string, any>): AgLlmResponse {
return {
id: input.id,
createdAt: input.created_at,
model: input.model,
incompleteDetails: input.incomplete_details ? { reason: input.incomplete_details.reason } : undefined,
output: input.output.map(decodeOutputItem),
status: input.status,
error: input.error ? { code: input.error.code, message: input.error.message } : undefined,
usage: input.usage
? {
inputTokens: input.usage.input_tokens,
outputTokens: input.usage.output_tokens,
totalTokens: input.usage.total_tokens,
reasoningTokens: input.usage.output_tokens_details?.reasoning_tokens,
cachedInputTokens: input.usage.input_tokens_details?.cached_tokens,
cacheWriteTokens: input.usage.input_tokens_details?.cache_write_tokens,
}
: undefined,
};
}
/** What a turn produced besides its events: the final response, or the failure that ended it. */
interface TurnOutcome {
response?: AgLlmResponse;
error?: Error;
}
/**
* Translates the OpenAI Responses stream into the events AG Studio reads.
*
* The provider is item-and-index shaped; AG Studio is message-shaped, keyed by id. The only state
* needed to bridge them is the item id of each open item, since argument deltas arrive against the
* item while tool events are keyed by the call.
*/
class ResponseStreamTranslator {
private readonly callIdByItemId = new Map<string, string>();
private readonly kindByItemId = new Map<string, 'message' | 'reasoning' | 'function_call'>();
/** The events one SSE payload maps to. Anything not recognised is ignored, not an error. */
translate(input: Record<string, any>, outcome: TurnOutcome): AgAiEvent[] {
switch (input.type) {
case 'response.output_item.added':
return this.open(input.item);
case 'response.output_item.done':
return this.close(input.item);
case 'response.output_text.delta':
case 'response.refusal.delta':
return [{ type: 'TEXT_MESSAGE_CONTENT', messageId: input.item_id, delta: input.delta }];
case 'response.reasoning_text.delta':
case 'response.reasoning_summary_text.delta':
return [{ type: 'REASONING_MESSAGE_CONTENT', messageId: input.item_id, delta: input.delta }];
case 'response.function_call_arguments.delta': {
const toolCallId = this.callIdByItemId.get(input.item_id);
return toolCallId ? [{ type: 'TOOL_CALL_ARGS', toolCallId, delta: input.delta }] : [];
}
case 'response.completed':
outcome.response = decodeResponse(input.response);
return [];
case 'response.failed':
case 'response.incomplete':
outcome.error ??= new Error(input.response?.error?.message ?? `Response ${input.type}.`);
return [];
case 'error':
outcome.error ??= new Error(`${input.code ?? 'api_error'}: ${input.message}`);
return [];
default:
return [];
}
}
private open(item: Record<string, any>): AgAiEvent[] {
switch (item?.type) {
case 'message':
this.kindByItemId.set(item.id, 'message');
return [{ type: 'TEXT_MESSAGE_START', messageId: item.id, role: 'assistant' }];
case 'reasoning':
this.kindByItemId.set(item.id, 'reasoning');
return [{ type: 'REASONING_MESSAGE_START', messageId: item.id, role: 'reasoning' }];
case 'function_call':
this.kindByItemId.set(item.id, 'function_call');
this.callIdByItemId.set(item.id, item.call_id);
return [{ type: 'TOOL_CALL_START', toolCallId: item.call_id, toolCallName: item.name }];
default:
return [];
}
}
private close(item: Record<string, any>): AgAiEvent[] {
switch (this.kindByItemId.get(item?.id)) {
case 'message':
return [{ type: 'TEXT_MESSAGE_END', messageId: item.id }];
case 'reasoning':
return [{ type: 'REASONING_MESSAGE_END', messageId: item.id }];
case 'function_call': {
const toolCallId = this.callIdByItemId.get(item.id);
return toolCallId ? [{ type: 'TOOL_CALL_END', toolCallId }] : [];
}
default:
return [];
}
}
}
// =============================================================================
// Stream Processor
// =============================================================================
async function* streamOpenAi(
config: OpenAiConfig,
requestBody: Record<string, unknown>,
outcome: TurnOutcome,
signal?: AbortSignal
): AsyncIterableIterator<AgAiEvent> {
const translator = new ResponseStreamTranslator();
const emit = (payload: string): AgAiEvent[] => {
if (payload === '[DONE]') {
return [];
}
try {
const parsed = JSON.parse(payload);
return parsed.type === 'keepalive' ? [] : translator.translate(parsed, outcome);
} catch (error) {
outcome.error ??= error instanceof Error ? error : new Error(String(error));
return [];
}
};
const response = await fetch(`${config.endpoint}/responses`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...(config.key && { Authorization: `Bearer ${config.key}` }),
...(config.organization && { 'OpenAI-Organization': config.organization }),
},
body: JSON.stringify(requestBody),
signal,
});
if (!response.ok) {
const body = await response.json().catch(() => ({}));
throw new Error(body.error?.message || `HTTP ${response.status}: ${response.statusText}`);
}
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) {
break;
}
buffer += decoder.decode(value, { stream: true });
const frames = buffer.split('\n\n');
buffer = frames.pop() ?? '';
for (const frame of frames) {
for (const line of frame.split('\n')) {
if (line.startsWith('data: ')) {
yield* emit(line.slice(6));
}
}
}
}
}
// =============================================================================
// Request Builder
// =============================================================================
function prepareToolChoice(
toolChoice: AgLlmRequest['toolChoice']
): 'auto' | 'none' | 'required' | { type: 'function'; name: string } | undefined {
if (!toolChoice) return undefined;
if (typeof toolChoice === 'string') return toolChoice;
return { type: 'function', name: toolChoice.name };
}
function prepareResponseFormat(format: AgLlmTextFormat | AgLlmJsonFormat): Record<string, unknown> {
if (format.type === 'text') return { type: 'text' };
return {
type: 'json_schema',
name: format.name,
description: format.description,
schema: toOpenAiSchema(format.schema as JsonSchema),
strict: true,
};
}
function runRequest(config: OpenAiConfig, request: AgLlmRequest, signal?: AbortSignal): AgLlmResponseHandler {
const { tools = [], toolChoice, responseFormat, input, model, ...rest } = request;
const requestBody: Record<string, unknown> = {
...rest,
input: encodeConversationItems(input),
// `request.model` carries whichever model the reader picked, and is absent when the chat
// offers no choice - so the adapter's own model is the fallback, not an override.
model: model?.id ?? config.model,
stream: true,
tools: tools.map((tool: AgAiToolSchema) => ({
type: 'function' as const,
name: tool.name,
description: tool.description,
parameters: toOpenAiSchema(tool.parameters as unknown as JsonSchema),
strict: true,
})),
tool_choice: prepareToolChoice(toolChoice),
text: { format: prepareResponseFormat(responseFormat!) },
// Studio's effort ids are passed straight through as OpenAI's reasoning effort. A model
// declared without efforts sends none, so the adapter's own default applies.
reasoning: { effort: model?.effort ?? 'medium' },
parallel_tool_calls: true,
};
const outcome: TurnOutcome = {};
const streamIterator = streamOpenAi(config, requestBody, outcome, signal);
let resolveComplete: (response: AgLlmResponse) => void;
let rejectComplete: (error: Error) => void;
const completePromise = new Promise<AgLlmResponse>((resolve, reject) => {
resolveComplete = resolve;
rejectComplete = reject;
});
// `complete` rejects on a failed turn: the host ends a run on a throw from here and reads
// nothing off the response's own status.
// A failed turn is reported once, through `complete`. Rethrowing as well would leave the
// rejection unobserved whenever a consumer stops reading the stream before awaiting it - which
// is exactly what happens on an HTTP error or a cancellation - and that surfaces as an unhandled
// rejection rather than as the run's own error.
async function* wrappedIterator(): AsyncIterableIterator<AgAiEvent> {
try {
yield* streamIterator;
} catch (error) {
outcome.error ??= error instanceof Error ? error : new Error(String(error));
}
if (outcome.error) {
rejectComplete(outcome.error);
} else if (outcome.response) {
resolveComplete(outcome.response);
} else {
rejectComplete(new Error('Stream completed without a final response.'));
}
}
// Marks the rejection observed for a consumer that abandons the stream and never awaits
// `complete`; anyone who does await it still sees the failure.
void completePromise.catch(() => {});
const wrapped = wrappedIterator();
return {
stream: { [Symbol.asyncIterator]: () => wrapped },
complete: completePromise,
};
}
// =============================================================================
// Factory Function
// =============================================================================
export function openaiAdapter(options: OpenAiAdapterOptions): AgLlmAdapter {
const config: OpenAiConfig = {
endpoint: options.endpoint ?? 'https://api.openai.com/v1',
key: options.key,
model: options.model ?? 'gpt-5.4-mini',
organization: options.organization,
};
return {
executeTurn: (request: AgLlmRequest, options?: { signal?: AbortSignal }) =>
runRequest(config, request, options?.signal),
};
}
import type { AgReportState } from 'ag-studio';
/**
* Starting report states for the GHCN world-cities weather data, shared by the AI docs
* examples and the eval harness so each one does not restate a dashboard it is not about.
* Pair either state with `getGhcnCitiesData` from the sibling `data` module - the widgets
* below reference that schema's fields and measures.
*/
/** An empty canvas: one page, no widgets. For examples whose point is that the assistant
* builds the dashboard from nothing. */
export const ghcnCitiesBlankState: AgReportState = {
pages: [{ id: 'main', widgets: {}, widgetLayout: {} }],
selectedPageId: 'main',
panels: {
filters: { collapsed: true },
edit: { collapsed: true },
data: { collapsed: true },
},
};
/**
* A three-page weather report: a finished temperature page, a deliberately unfinished
* precipitation page for the assistant to complete, and a blank page to build on. For
* examples that need existing widgets to read, edit or reason about.
*/
export const ghcnCitiesReportState: AgReportState = {
pages: [
// Page 1: a complete, titled temperature report.
{
id: 'temperature',
widgets: {
'temp-heading': {
type: 'text',
dataMapping: {},
format: {
style: { text: 'Global City Temperatures', typography: { fontSize: 20, fontWeight: 'bold' } },
},
},
'kpi-avg-high': {
type: 'value',
dataMapping: { value: [{ id: 'avgHigh' }] },
format: { caption: { enabled: true, text: 'Avg High' } },
},
'kpi-avg-low': {
type: 'value',
dataMapping: { value: [{ id: 'avgLow' }] },
format: { caption: { enabled: true, text: 'Avg Low' } },
},
'kpi-avg-range': {
type: 'value',
dataMapping: { value: [{ id: 'avgTempRange' }] },
format: { caption: { enabled: true, text: 'Avg Daily Range' } },
},
'temp-trend': {
type: 'line-chart',
dataMapping: {
categoryKey: [{ id: 'calendar::year' }],
valueKey: [{ id: 'avgHigh' }, { id: 'avgLow' }],
tooltipKey: [],
},
format: {
title: {
enabled: true,
text: 'Average Temperature by Year',
typography: { fontSize: 16, fontWeight: 'bold' },
},
},
},
'record-highs': {
type: 'column-chart-grouped',
dataMapping: {
categoryKey: [{ id: 'cities.city' }],
valueKey: [{ id: 'weather.tmax', aggregation: 'max' }],
tooltipKey: [{ id: 'cities.country' }],
},
format: {
title: {
enabled: true,
text: 'Record High Temperature by City',
typography: { fontSize: 16, fontWeight: 'bold' },
},
},
},
'range-by-band': {
type: 'column-chart-grouped',
dataMapping: {
categoryKey: [{ id: 'cities.latitudeBand' }],
valueKey: [{ id: 'avgTempRange' }],
tooltipKey: [],
},
format: {
title: {
enabled: true,
text: 'Average Daily Temperature Range by Climate Band',
typography: { fontSize: 16, fontWeight: 'bold' },
},
},
},
'daily-grid': {
type: 'grid',
dataMapping: {
cols: [
{ id: 'cities.city' },
{ id: 'weather.date' },
{ id: 'weather.tmax', aggregation: 'avg' },
{ id: 'weather.tmin', aggregation: 'avg' },
{ id: 'tempRange', aggregation: 'avg' },
{ id: 'weather.prcp', aggregation: 'sum' },
],
},
format: {
title: {
enabled: true,
text: 'Daily Observations',
typography: { fontSize: 16, fontWeight: 'bold' },
},
style: { theme: { rowHeight: 28 } },
},
},
},
widgetLayout: {
'temp-heading': { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 3 },
'kpi-avg-high': { xTrack: 0, yTrack: 3, xSpan: 8, ySpan: 8 },
'kpi-avg-low': { xTrack: 8, yTrack: 3, xSpan: 8, ySpan: 8 },
'kpi-avg-range': { xTrack: 16, yTrack: 3, xSpan: 8, ySpan: 8 },
'temp-trend': { xTrack: 0, yTrack: 11, xSpan: 24, ySpan: 22 },
'record-highs': { xTrack: 0, yTrack: 33, xSpan: 12, ySpan: 26 },
'range-by-band': { xTrack: 12, yTrack: 33, xSpan: 12, ySpan: 26 },
'daily-grid': { xTrack: 0, yTrack: 59, xSpan: 24, ySpan: 34 },
},
filter: { page: [] },
},
// Page 2: a deliberately unfinished precipitation report for the AI to complete.
{
id: 'precipitation',
widgets: {
'precip-heading': {
type: 'text',
dataMapping: {},
format: {
style: {
text: 'Precipitation (work in progress)',
typography: { fontSize: 20, fontWeight: 'bold' },
},
},
},
'rain-by-city': {
type: 'column-chart-grouped',
dataMapping: {
categoryKey: [{ id: 'cities.city' }],
valueKey: [{ id: 'totalRainfall' }],
tooltipKey: [{ id: 'cities.country' }],
},
format: {
title: {
enabled: true,
text: 'Total Rainfall by City',
typography: { fontSize: 16, fontWeight: 'bold' },
},
},
},
'wet-days-by-band': {
type: 'column-chart-grouped',
dataMapping: {
categoryKey: [{ id: 'cities.latitudeBand' }],
valueKey: [{ id: 'wetDays' }],
tooltipKey: [],
},
format: {
title: {
enabled: true,
text: 'Wet Days by Climate Band',
typography: { fontSize: 16, fontWeight: 'bold' },
},
},
},
},
widgetLayout: {
'precip-heading': { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 3 },
'rain-by-city': { xTrack: 0, yTrack: 3, xSpan: 12, ySpan: 26 },
'wet-days-by-band': { xTrack: 12, yTrack: 3, xSpan: 12, ySpan: 26 },
},
filter: { page: [] },
},
// Page 3: a blank canvas, ready for editing.
{
id: 'blank',
widgets: {},
widgetLayout: {},
filter: { page: [] },
},
],
selectedPageId: 'temperature',
panels: {
ai: { collapsed: false },
filters: { collapsed: false },
edit: { collapsed: true },
data: { collapsed: true },
},
};
import type {
AgDataSourceDefinition,
AgDataSourcesDefinition,
AgExpressionFieldDefinition,
AgFieldDefinition,
AgRelationDefinition,
} from 'ag-studio';
// NOAA GHCN-Daily "world cities" dataset. Weather facts are stored column-wise as
// raw GHCN integers (temperatures/precip in tenths, snow in mm) with dates as
// integer days since 1970-01-01; the scaling and date conversion below are the
// "format in the browser" step, so the shipped asset stays maximally compact.
//
// The asset base URL is supplied by the caller (a docs example passes its
// substituted asset path; the eval harness passes its own served path), so this
// canonical dataset is not bound to any one host's asset layout.
const MS_PER_DAY = 86_400_000;
// Raw column arrays keyed by field id, exactly as emitted by the generator
// (cityId/date are integer arrays; the measures may contain nulls).
type WeatherColumns = Record<string, (number | null)[]>;
// Keyed by base URL, not held once per process: the whole point of taking the URL from the caller
// is that two callers in one process can serve the asset from different roots, and a single cache
// would hand the second caller the first one's data.
const rawColumnsByBaseUrl = new Map<string, Promise<WeatherColumns>>();
const columnCache = new Map<string, (number | null)[]>();
function loadRawColumns(baseUrl: string): Promise<WeatherColumns> {
let columns = rawColumnsByBaseUrl.get(baseUrl);
if (columns == null) {
columns = fetch(`${baseUrl}/weather.columns.json`).then((r) => r.json());
rawColumnsByBaseUrl.set(baseUrl, columns);
}
return columns;
}
// Column values are transformed to display units once and memoised - repeated
// queries for the same field reuse the converted array.
async function getWeatherColumn(baseUrl: string, fieldId: string): Promise<(number | null)[]> {
const cacheKey = `${baseUrl}\u0000${fieldId}`;
const cached = columnCache.get(cacheKey);
if (cached != null) {
return cached;
}
const raw = await loadRawColumns(baseUrl);
const source = raw[fieldId] ?? [];
let column: (number | null)[];
if (fieldId === 'date') {
// Dates reach the engine as epoch milliseconds, which is the cheapest form it accepts:
// it converts them with a single division, where an ISO string costs a regex test and
// three slices per row. Two constraints on this line:
// - The multiply is required. A bare number is read as milliseconds, so passing the
// stored day integers straight through is not an error, it silently lands every
// observation in 1970.
// - Do not wrap this in a `new Date(...)`. A Date is read through local calendar
// accessors while a number is read as UTC, so a UTC-midnight Date decodes to the
// previous day anywhere west of Greenwich - the dataset would shift by a day
// depending on the reader's timezone.
column = source.map((day) => (day == null ? null : day * MS_PER_DAY));
} else if (fieldId === 'tmax' || fieldId === 'tmin' || fieldId === 'prcp') {
column = source.map((value) => (value == null ? null : value / 10));
} else {
column = source;
}
columnCache.set(cacheKey, column);
return column;
}
const weatherFields: AgFieldDefinition[] = [
{
id: 'cityId',
name: 'City ID',
description: 'Foreign key to the cities table (cities.id) identifying which city this reading belongs to.',
format: 'integerFormat',
cardinality: 'low',
hide: true,
},
{
id: 'date',
name: 'Date',
description: 'Calendar date of the observation. The data is daily - one row per city per day.',
format: 'dateFormat',
cardinality: 'high',
notBlank: true,
},
{
id: 'tmax',
name: 'Max Temp (°C)',
description: 'Highest air temperature recorded during the day, in degrees Celsius.',
format: 'decimalFormat',
cardinality: 'medium',
},
{
id: 'tmin',
name: 'Min Temp (°C)',
description: 'Lowest air temperature recorded during the day, in degrees Celsius.',
format: 'decimalFormat',
cardinality: 'medium',
},
{
id: 'prcp',
name: 'Precipitation (mm)',
description:
'Total precipitation for the day (rain plus melted snow), in millimetres. 0 is a dry day; a blank means it was not recorded.',
format: 'decimalFormat',
cardinality: 'medium',
},
{
id: 'snow',
name: 'Snowfall (mm)',
description:
'Fresh snow that fell during the day, in millimetres. Usually 0 or blank outside cold-climate cities. Distinct from snow depth.',
format: 'integerFormat',
cardinality: 'medium',
},
{
id: 'snwd',
name: 'Snow Depth (mm)',
description:
'Depth of snow lying on the ground at observation time, in millimetres. Distinct from snowfall, which is only the fresh fall that day.',
format: 'integerFormat',
cardinality: 'medium',
},
];
const cityFields: AgFieldDefinition[] = [
{
id: 'id',
name: 'City ID',
description: 'Primary key; the join target for weather.cityId.',
format: 'integerFormat',
cardinality: 'low',
hide: true,
},
{
id: 'city',
name: 'City',
description: 'City name. This is the label most reports group by.',
format: 'textFormat',
cardinality: 'low',
},
{
id: 'country',
name: 'Country',
description: 'Country the city is located in.',
format: 'textFormat',
cardinality: 'low',
},
{
id: 'region',
name: 'Region',
description: 'Continent-level grouping, such as Europe, Asia or North America.',
format: 'textFormat',
cardinality: 'low',
},
{
id: 'latitudeBand',
name: 'Climate Band',
description: 'Climate band derived from latitude: Tropical, Subtropical, Temperate, Subpolar or Polar.',
format: 'textFormat',
cardinality: 'low',
},
{
id: 'latitude',
name: 'Latitude',
description: 'City-centre latitude in decimal degrees (positive north). Suitable for plotting on a map.',
format: 'decimalFormat',
cardinality: 'low',
},
{
id: 'longitude',
name: 'Longitude',
description: 'City-centre longitude in decimal degrees (positive east).',
format: 'decimalFormat',
cardinality: 'low',
},
{
id: 'elevation',
name: 'Elevation (m)',
description: 'Elevation of the backing weather station, in metres above sea level.',
format: 'decimalFormat',
cardinality: 'low',
},
{
id: 'stationName',
name: 'Station',
description: 'Name of the NOAA GHCN weather station whose readings back this city.',
format: 'textFormat',
cardinality: 'low',
},
];
function getWeatherSource(baseUrl: string): AgDataSourceDefinition<'column'> {
return {
id: 'weather',
name: 'Daily Weather',
dataShape: 'column',
tables: [
{
id: 'weather',
name: 'Daily Weather',
description:
'Daily weather observations, one row per city per day. Temperatures are in degrees Celsius and precipitation and snow in millimetres; a blank means the value was not recorded that day. Join cityId to the cities table for city attributes.',
fields: weatherFields,
},
],
getData: async (_tableId, fieldIds) => ({
data: await Promise.all(fieldIds.map((fieldId) => getWeatherColumn(baseUrl, fieldId))),
}),
};
}
const citiesByBaseUrl = new Map<string, Promise<Record<string, unknown>[]>>();
function loadCities(baseUrl: string): Promise<Record<string, unknown>[]> {
let cities = citiesByBaseUrl.get(baseUrl);
if (cities == null) {
cities = fetch(`${baseUrl}/cities.json`).then((r) => r.json());
citiesByBaseUrl.set(baseUrl, cities);
}
return cities;
}
function getCitiesSource(baseUrl: string): AgDataSourceDefinition<'row'> {
return {
id: 'cities',
name: 'Cities',
dataShape: 'row',
tables: [
{
id: 'cities',
name: 'Cities',
description:
'One row per city: the dimension describing each city and the weather station backing it. Join cities.id to weather.cityId.',
fields: cityFields,
},
],
getData: async () => ({ data: await loadCities(baseUrl) }),
};
}
const relationships: AgRelationDefinition[] = [
{
id: 'weather-cities',
source: { tableId: 'weather', fieldId: 'cityId' },
target: { tableId: 'cities', fieldId: 'id' },
type: 'many-to-one',
},
// Bind the observation date to a generated calendar (no date table needed) so
// charts can group by `calendar::year`, `calendar::monthOfYear`, etc.
{
id: 'weather-calendar',
source: { tableId: 'weather', fieldId: 'date' },
target: { calendarId: 'calendar' },
},
];
// A day counts as "frost"/"hot"/"wet" via a 0/1 calculated column; the matching
// measures below sum those flags. Comparing a null reading yields no count.
function dayFlag(fieldId: string, operator: 'lessThan' | 'greaterThanOrEqual', threshold: number) {
return {
operator: 'if' as const,
inputs: [
{ operator, inputs: [{ id: fieldId }, { type: 'number' as const, value: threshold }] },
{ type: 'number' as const, value: 1 },
{ type: 'number' as const, value: 0 },
],
};
}
const expressions: AgExpressionFieldDefinition[] = [
// --- Calculated columns (row-level) ---
{
id: 'tempRange',
name: 'Temp Range (°C)',
description:
'Daily temperature range (max temp minus min temp), in degrees Celsius. A large range suggests a continental or dry climate; a small range suggests a maritime one.',
isMeasure: false,
format: 'decimalFormat',
expression: { operator: 'subtract', inputs: [{ id: 'weather.tmax' }, { id: 'weather.tmin' }] },
},
{
id: 'isFrost',
isMeasure: false,
format: 'integerFormat',
hide: true,
expression: dayFlag('weather.tmin', 'lessThan', 0),
},
{
id: 'isHot',
isMeasure: false,
format: 'integerFormat',
hide: true,
expression: dayFlag('weather.tmax', 'greaterThanOrEqual', 30),
},
{
id: 'isWet',
isMeasure: false,
format: 'integerFormat',
hide: true,
expression: dayFlag('weather.prcp', 'greaterThanOrEqual', 1),
},
// --- Measures (aggregates over the grouped period) ---
{
id: 'avgHigh',
name: 'Avg High (°C)',
description: 'Average of the daily maximum temperatures over the grouped period, in degrees Celsius.',
isMeasure: true,
format: 'decimalFormat',
expression: { id: 'weather.tmax', aggregation: 'avg' },
},
{
id: 'avgLow',
name: 'Avg Low (°C)',
description: 'Average of the daily minimum temperatures over the grouped period, in degrees Celsius.',
isMeasure: true,
format: 'decimalFormat',
expression: { id: 'weather.tmin', aggregation: 'avg' },
},
{
id: 'avgTempRange',
name: 'Avg Temp Range (°C)',
description: 'Average daily temperature range (max minus min) over the grouped period, in degrees Celsius.',
isMeasure: true,
format: 'decimalFormat',
expression: { id: 'tempRange', aggregation: 'avg' },
},
{
id: 'totalRainfall',
name: 'Total Rainfall (mm)',
description: 'Total precipitation over the grouped period, in millimetres.',
isMeasure: true,
format: 'decimalFormat',
expression: { id: 'weather.prcp', aggregation: 'sum' },
},
{
id: 'totalSnowfall',
name: 'Total Snowfall (mm)',
description: 'Total fresh snowfall over the grouped period, in millimetres.',
isMeasure: true,
format: 'integerFormat',
expression: { id: 'weather.snow', aggregation: 'sum' },
},
{
id: 'frostDays',
name: 'Frost Days',
description: 'Number of days in the grouped period with a minimum temperature below 0°C.',
isMeasure: true,
format: 'integerFormat',
expression: { id: 'isFrost', aggregation: 'sum' },
},
{
id: 'hotDays',
name: 'Hot Days (≥30°C)',
description: 'Number of days in the grouped period with a maximum temperature of at least 30°C.',
isMeasure: true,
format: 'integerFormat',
expression: { id: 'isHot', aggregation: 'sum' },
},
{
id: 'wetDays',
name: 'Wet Days (≥1mm)',
description: 'Number of days in the grouped period with at least 1 mm of precipitation.',
isMeasure: true,
format: 'integerFormat',
expression: { id: 'isWet', aggregation: 'sum' },
},
];
export function getGhcnCitiesData(assetsBaseUrl: string): AgDataSourcesDefinition {
const baseUrl = `${assetsBaseUrl}/ghcn-cities`;
return {
description:
'Daily weather for 39 major world cities over roughly the last 100 years, from NOAA ' +
'GHCN-Daily. The weather table has one row per city per day (max/min temperature in degrees ' +
'Celsius, precipitation and snow in millimetres); a blank reading means it was not recorded. ' +
'Each row joins via cityId to the cities dimension (city, country, region, climate band, ' +
'coordinates and the backing station). The observation date is bound to a calendar, so results ' +
'can be grouped or trended by year, quarter, month or month-of-year. Calculated fields add the ' +
'daily temperature range; measures provide average high/low, average range, total ' +
'rainfall/snowfall, and counts of frost days (min below 0°C), hot days (max at least 30°C) and ' +
'wet days (at least 1 mm). Typical questions: compare cities or climate bands, show long-term ' +
'temperature trends, or find the wettest or snowiest places.',
sources: [getWeatherSource(baseUrl), getCitiesSource(baseUrl)],
relationships,
expressions,
// Generated spine covering the ~100-year data window (see the generator's
// --start-year). Keep `from`/`to` aligned with the data on each release refresh.
calendars: [
{
id: 'calendar',
label: 'Calendar',
range: { from: { type: 'date', value: '1926-01-01' }, to: { type: 'date', value: '2026-12-31' } },
fragments: ['year', 'quarter', 'month', 'monthOfYear', 'dayOfWeek'],
},
],
};
}
Change Instructions Copy Link
Instructions are a function, so build them from live context rather than hardcoding what the data looks like:
// Your AgLlmAdapter - see Direct LLM Runner.
const adapter = myOpenAiAdapter({ endpoint: '/api/llm' });
const studio = api.getAiTools();
directLlmRunner({
id: 'analyst',
adapter,
instructions: () => {
const { tables } = api.getAiContext().schema();
const names = tables.map((table) => table.name).join(', ');
return [
'You build dashboards for the finance team.',
`Available data: ${names}.`,
'Currency is GBP. Never mix currencies in one chart.',
'When asked for a trend, prefer a line chart over a bar chart.',
].join('\n');
},
tools: () => [studio.viewSchema(), studio.executeQuery()],
});See Agent Context for everything available to build instructions from.
Change the Tool Set Copy Link
The simplest control over what an agent can do is which tools you list. An agent with no mutating tools cannot change the dashboard, whatever the model decides:
// A read-only analyst: it can look and answer, but not touch the page.
tools: () => [studio.viewSchema(), studio.viewPage(), studio.executeQuery()],Every Studio tool takes the same optional overrides, applied to that listing only:
Advertise the tool under a different name.
|
Advertise a different description to this agent.
|
tools: () => [
studio.addWidget({ description: 'Add a widget. Prefer charts; only use a grid when asked for a table.' }),
// Renamed to avoid a clash with a tool of your own
studio.executeQuery({ name: 'query_dashboard_data' }),
],A description here applies to one agent's listing. To change a description everywhere, use the aiText property instead, which is keyed by the name the tool advertises:
aiText: {
'tools.add_widget.description': 'Add a widget to the grid. Position is 0-indexed.',
}, Binding a Widget Tool Copy Link
configureWidget is the one tool that takes parameters rather than only overrides. Its schema is narrowed to a single widget type's options, so it has to be told which widget it configures:
tools: () => [studio.configureWidget({ widgetType: 'grid', widgetId: 'main' })],The built-in widget agent resolves those two values from its delegation parameters, which is how one agent configures whichever widget the lead hands it.
Add Tools of Your Own Copy Link
Anything from api.defineAiTool sits alongside the built-ins in the same array:
tools: () => [studio.viewSchema(), studio.executeQuery(), setThemeTool, notifyTeamTool], Change Delegation Copy Link
tools.delegateTo builds the delegation tool for a set of target ids. Give an agent a narrower set and it can only hand off to those:
// Your AgLlmAdapter - see Direct LLM Runner.
const adapter = myOpenAiAdapter({ endpoint: '/api/llm' });
createAiHarness(api, ({ tools }) => ({
agents: [
directLlmRunner({
id: 'lead',
adapter,
instructions: () => 'Coordinate. Delegate data questions; never answer them yourself.',
tools: () => [tools.studio.viewSchema(), tools.delegateTo(['data'])],
}),
directLlmRunner({
id: 'data',
adapter,
description: 'Answers questions about the data by running queries.',
instructions: () => 'You are a data analyst. Answer with numbers, not adjectives.',
tools: () => [tools.studio.executeQuery(), tools.studio.viewSchema()],
}),
],
primary: 'lead',
}));A delegate target needs a description, which is what the delegating model reads to decide whether to hand off. Give it delegation parameters with schema, and the delegating agent must supply them:
directLlmRunner<{ region: string }>({
id: 'regional-analyst',
adapter,
description: 'Answers questions about one region.',
schema: (s) => s.object({ region: s.string() }),
instructions: ({ region }) => `You only discuss the ${region} region.`,
tools: () => [studio.executeQuery()],
});delegate_to's schema advertises those parameters, resolved per turn.
An agent that takes no delegation parameters must declare schema: (s) => s.undefined(), not an empty object. A primary agent is run with undefined parameters, and an object schema rejects that, so the agent fails to start.
Mix Built-ins With Your Own Copy Link
Spread the defaults and add to them. Keep primary pointing at whichever agent should front the conversation:
// Your AgLlmAdapter - see Direct LLM Runner.
const adapter = myOpenAiAdapter({ endpoint: '/api/llm' });
const studio = api.getAiTools();
// An agent of your own, built as in Declare Your Own Team above.
const auditAgent = directLlmRunner({
id: 'audit',
adapter,
description: 'Reviews a page for missing or misleading widgets.',
instructions: () => 'You review dashboards and report what is missing.',
tools: () => [studio.viewPage(), studio.viewWidget()],
});
createAiHarness(api, ({ builtIn }) => ({
agents: [...Object.values(builtIn).map((definition) => directLlmRunner({ ...definition, adapter })), auditAgent],
primary: 'lead',
}));The built-in lead delegates to a fixed set of ids, so it will not discover auditAgent on its own. To have work delegated to it, declare your own lead with a wider delegateTo.
Next Copy Link
- Custom Tools - adding actions of your own
- Client Tool Runner - owning the loop
- Built-in Agents - what you are starting from