---
title: "Custom Agents"
framework: angular
version: "2.1.2"
---

# Custom Agents

The [Default Agents](https://www.ag-grid.com/studio/angular/ai-ax/) 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](https://www.ag-grid.com/studio/angular/ai-adapter/).

## Supplying Agents

`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.

```ts
import { agStudioDefaultAgents } from 'ag-studio';
```

```ts
<ag-studio
    [ai]="ai"
    /* other studio properties ... */ />

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

`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

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.

```ts
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

`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](https://www.ag-grid.com/studio/angular/ai-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

`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](https://www.ag-grid.com/studio/angular/ai-ax#tool-reference).

### Delegation

`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

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.

#### Custom Agents

```ts
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()],
});
```

[Live example: Custom Agents](https://www.ag-grid.com/studio/examples/ai-custom-agents/ai-custom-agents-example/angular/)

## Interface Reference

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  | Unique identifier for this agent type. |
| `description` | `string` |  | Short description of what this agent does, shown to a delegating agent so it can decide when to hand off. Falls back to type when omitted. |
| `schema` | `Function` |  | Builds the shape that validates this agent's parameters, given the shape builder. Return `s.undefined()` for a param-less agent, or e.g. `s.object({ region: s.string() })` to require parameters. |
| `config` | `Function` |  | Agent configuration. The factory function receives parameters and returns the configuration, allowing dynamic agent behaviour based on input. |

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Display name for the agent, shown in UI. |
| `icon` | `string` |  | SVG icon string for the agent, rendered in delegate cards. Uses `currentColor` for theme adaptability. |
| `instructions` | `Function` |  | System instructions that guide the AI's behaviour for this agent. |
| `delegateAgents` | `string[]` |  | Agent types this agent can delegate tasks to. Enables hierarchical task decomposition across specialised agents. |
| `tools` | `AgToolRef[]` |  | Tool names available to this agent for performing actions. |
| `defaultToolCalls` | `{ tool: string; args?: Record<string, unknown> }[]` |  | Tools to call automatically before the agent's first turn, their results prepended to the agent's instructions. Each named tool must be in tools. |

## Next Steps

- [Context](https://www.ag-grid.com/studio/angular/ai-context/) - Build agent instructions from live dashboard and data state.
- [Default Agents](https://www.ag-grid.com/studio/angular/ai-ax/) - The built-in agents you are extending or replacing.