Class Agent<S>

Allow to create a new Forest Admin agent from scratch. Builds the application by composing and configuring all the collection decorators.

Minimal code to add a datasource

Example

new AgentBuilder(options)
 .addDataSource(new SomeDataSource())
 .start();

Type Parameters

S extends TSchema = TSchema

Hierarchy

default
- Agent

Constructors

constructor

new Agent<S extends TSchema = TSchema>(options: AgentOptions): Agent<S>
Create a new Agent Builder. If any options are missing, the default will be applied:
```
 forestServerUrl: 'https://api.forestadmin.com',
 logger: (level, data) => console.error(level, data),
 prefix: 'api/v1',
 schemaPath: '.forestadmin-schema.json',
 permissionsCacheDurationInSeconds: 15 * 60,
```
Type Parameters
- S extends TSchema = TSchema
Parameters
- options: AgentOptions
  options
Returns Agent<S>
Example
```
new AgentBuilder(options)
 .addDataSource(new DataSource())
 .start();
```
Overrides FrameworkMounter.constructor
- Defined in agent/src/agent.ts:82

Properties

`Protected`aiProvider

aiProvider: AiProviderDefinition = null

`Protected`customizationService

customizationService: CustomizationPluginService

`Protected`customizer

customizer: DataSourceCustomizer<S>

`Protected`nocodeCustomizer

nocodeCustomizer: DataSourceCustomizer<S>

`Protected`options

options: AgentOptionsWithDefaults

`Protected` `Readonly`prefix

prefix: string

`Protected`schemaGenerator

schemaGenerator: SchemaGenerator

`Optional`standaloneServerHost

standaloneServerHost?: string

standaloneServerPort

standaloneServerPort: number

Methods

addAi

addAi(provider: AiProviderDefinition): this
Enable AI features for your Forest Admin panel.

All AI requests from Forest Admin are forwarded to your agent and processed locally. Your data and API keys never transit through Forest Admin servers, ensuring full privacy.

Requires the @forestadmin/ai-proxy package to be installed:
```
npm install @forestadmin/ai-proxy
```
Parameters
- provider: AiProviderDefinition
  An AI provider definition created via createAiProvider from @forestadmin/ai-proxy
Returns this
The agent instance for chaining
See
https://docs.forestadmin.com/developer-guide-agents-nodejs/agent-customization/ai/self-hosted-ai

Throws
Error if addAi is called more than once
Example
```
import { createAiProvider } from '@forestadmin/ai-proxy';

agent.addAi(createAiProvider({
  name: 'assistant',
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o',
}));
```
- Defined in agent/src/agent.ts:291

addChart

addChart(name: string, definition: DataSourceChartDefinition<S>): this
Create a new API chart
Parameters
- name: string
  name of the chart
- definition: DataSourceChartDefinition<S>
  definition of the chart
Returns this
See
Documentation Link
Example
```
.addChart('numCustomers', (context, resultBuilder) => {
  return resultBuilder.distribution({
    tomatoes: 10,
    potatoes: 20,
    carrots: 30,
  });
})
```
- Defined in agent/src/agent.ts:192

addDataSource

addDataSource(factory: DataSourceFactory, options?: DataSourceOptions): this
Add a datasource
Parameters
- factory: DataSourceFactory
  the datasource to add
- Optionaloptions: DataSourceOptions
  the options
Returns this
See
Documentation Link
- Defined in agent/src/agent.ts:160

addWorkflowExecutor

addWorkflowExecutor(options?: WorkflowExecutorEmbedOptions): this
Run a workflow executor in-process, alongside the agent. The agent boots it on start(), stops it on stop(), and proxies /_internal/executor/* to it — no separate deployment.

Requires the @forestadmin/workflow-executor package to be installed:
```
npm install @forestadmin/workflow-executor
```
The executor persists run state in a database: provide database, or set the DATABASE_URL environment variable. Mutually exclusive with the workflowExecutorUrl option, which targets a separately-deployed executor instead.
Parameters
- options: WorkflowExecutorEmbedOptions = {}
  embedded executor options
Returns this
the agent instance for chaining
Throws
Error if called more than once, or if workflowExecutorUrl is also set
Example
```
createAgent(options)
  .addDataSource(...)
  .addWorkflowExecutor({ database: { uri: process.env.DATABASE_URL } })
  .start();
```
- Defined in agent/src/agent.ts:334

customizeCollection

customizeCollection<N extends string>(
name: N,
handle: (collection: CollectionCustomizer<S, N>) => unknown,
): this
Allow to interact with a decorated collection
Type Parameters
- N extends string
Parameters
- name: N
  the name of the collection to manipulate
- handle: (collection: CollectionCustomizer<S, N>) => unknown
  a function that provide a collection builder on the given collection name
Returns this
See
Documentation Link
Example
```
.customizeCollection('books', books => books.renameField('xx', 'yy'))
```
- Defined in agent/src/agent.ts:206

generateSchemaOnly

generateSchemaOnly(): Promise<void>
Generate the schema (and typings, when typingsPath is set) and write them to disk without starting the agent or sending the schema to Forest Admin servers.

Useful in a CI/CD pipeline to produce .forestadmin-schema.json at build time, so it can be shipped with the deployed code instead of committed.

Note: when experimental no-code customizations are enabled, this still fetches their configuration from the Forest API so the generated schema includes them, which requires connectivity to Forest.

Unlike start(), this always rebuilds the schema — even when isProduction is true — and writes the typings whenever typingsPath is set, regardless of isProduction.

Like the rest of the agent, this does not own the data source connection lifecycle: a data source that opens a connection pool stays open after this resolves. In a one-shot script, close your data source (or call process.exit()) once it returns so the process can exit.

Returns Promise<void>
- Defined in agent/src/agent.ts:538

`Protected`getRoutes

getRoutes(
dataSource: DataSource,
services: ForestAdminHttpDriverServices,
): BaseRoute[]
Parameters
- dataSource: DataSource
- services: ForestAdminHttpDriverServices
Returns BaseRoute[]
- Defined in agent/src/agent.ts:349

`Protected`mount

mount(router: Router): Promise<void>
Parameters
- router: Router
Returns Promise<void>
Inherited from FrameworkMounter.mount
- Defined in agent/src/framework-mounter.ts:47

mountAiMcpServer

mountAiMcpServer(
options?: { basePath?: string; enabledTools?: ToolName[] },
): this

Enable MCP (Model Context Protocol) server support. This allows AI assistants to interact with your Forest Admin data.

Parameters

Optionaloptions: { basePath?: string; enabledTools?: ToolName[] }

Returns this

See

https://docs.forestadmin.com/developer-guide-agents-nodejs/agent-customization/ai/mcp-server

Example

agent.mountAiMcpServer();
// Example: read-only mode (only browse data, no create/update/delete/actions)
agent.mountAiMcpServer({ enabledTools: ['describeCollection', 'list', 'listRelated'] });
// Example: scope MCP routes under a prefix to avoid colliding with your app's own OAuth routes.
// OAuth discovery metadata stays at the origin root (prefix-suffixed), so root `.well-known`
// traffic must still reach the agent.
agent.mountAiMcpServer({ basePath: '/ai' });

mountOnExpress

mountOnExpress(express: any): this
Mount the agent on an express app.
Parameters
- express: any
  instance of the express app or router.
Returns this
Inherited from FrameworkMounter.mountOnExpress
- Defined in agent/src/framework-mounter.ts:110

mountOnFastify

mountOnFastify(fastify: any): this
Mount the agent on a fastify app
Parameters
- fastify: any
  instance of the fastify app, or of a fastify context
Returns this
Inherited from FrameworkMounter.mountOnFastify
- Defined in agent/src/framework-mounter.ts:126

mountOnKoa

mountOnKoa(koa: any): this
Mount the agent on a koa app
Parameters
- koa: any
  instance of a koa app or a koa Router.
Returns this
Inherited from FrameworkMounter.mountOnKoa
- Defined in agent/src/framework-mounter.ts:143

mountOnNestJs

mountOnNestJs(nestJs: any): this
Mount the agent on a NestJS app
Parameters
- nestJs: any
  instance of a NestJS application
Returns this
Inherited from FrameworkMounter.mountOnNestJs
- Defined in agent/src/framework-mounter.ts:171

mountOnStandaloneServer

mountOnStandaloneServer(port?: number, host?: string): this
Expose the agent on a given port and host
Parameters
- Optionalport: number
  port that should be used, defaults to 3351 or to the PORT environment variable. O will be set a random available port and the port will be available in the standaloneServerPort property.
- Optionalhost: string
  host that should be used, default to the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise.
Returns this
Inherited from FrameworkMounter.mountOnStandaloneServer
- Defined in agent/src/framework-mounter.ts:68

`Protected`remount

remount(router: Router): Promise<void>
Parameters
- router: Router
Returns Promise<void>
Inherited from FrameworkMounter.remount
- Defined in agent/src/framework-mounter.ts:53

removeCollection

removeCollection(...names: Extract<keyof S, string>[]): this
Remove collections from the exported schema (they will still be usable within the agent).
Parameters
- ...names: Extract<keyof S, string>[]
  the collections to remove
Returns this
Example
```
.removeField('aCollectionToRemove', 'anotherCollectionToRemove');
```
- Defined in agent/src/agent.ts:221

restart

restart(): Promise<void>
Restart the agent at runtime (remount routes).

Returns Promise<void>
- Defined in agent/src/agent.ts:132

`Protected`sendSchema

sendSchema(dataSource: DataSource): Promise<void>
Send the apimap to forest admin server
Parameters
- dataSource: DataSource
Returns Promise<void>
- Defined in agent/src/agent.ts:483

`Protected`setMcpCallback

setMcpCallback(callback: HttpCallback, routeMatcher?: McpRouteMatcher): void
Set the MCP HTTP callback. Call this before mount() or remount().
Parameters
- callback: HttpCallback
- OptionalrouteMatcher: McpRouteMatcher
Returns void
Inherited from FrameworkMounter.setMcpCallback
- Defined in agent/src/framework-mounter.ts:43

start

start(): Promise<void>
Start the agent.

Returns Promise<void>
- Defined in agent/src/agent.ts:97

stop

stop(): Promise<void>
Stop the agent.

Returns Promise<void>
Overrides FrameworkMounter.stop
- Defined in agent/src/agent.ts:120

updateTypesOnFileSystem

updateTypesOnFileSystem(
typingsPath: string,
typingsMaxDepth: number,
): Promise<void>
Update the typings files generated from your datasources
Parameters
- typingsPath: string
  the path at which to write the new file
- typingsMaxDepth: number
  the max depth of relation typings
Returns Promise<void>
See
Documentation Link
- Defined in agent/src/agent.ts:172

use

use<Options>(plugin: Plugin<Options>, options?: Options): this
Load a plugin across all collections
Type Parameters
- Options
Parameters
- plugin: Plugin<Options>
  instance of the plugin
- Optionaloptions: Options
  options which need to be passed to the plugin
Returns this
See
Documentation Link
Example
```
import advancedExportPlugin from '@forestadmin/plugin-advanced-export';

agent.use(advancedExportPlugin, { format: 'xlsx' });
```
- Defined in agent/src/agent.ts:237

Class Agent<S>

Example

Type Parameters

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns Agent<S>

Example

Properties

ProtectedaiProvider

ProtectedcustomizationService

Protectedcustomizer

ProtectednocodeCustomizer

Protectedoptions

Protected Readonlyprefix

ProtectedschemaGenerator

OptionalstandaloneServerHost

standaloneServerPort

Methods

addAi

Parameters

Returns this

See

Throws

Example

addChart

Parameters

Returns this

See

Example

addDataSource

Parameters

Returns this

See

addWorkflowExecutor

Parameters

Returns this

Throws

Example

customizeCollection

Type Parameters

Parameters

Returns this

See

Example

generateSchemaOnly

Returns Promise<void>

ProtectedgetRoutes

Parameters

Returns BaseRoute[]

Protectedmount

Parameters

Returns Promise<void>

mountAiMcpServer

Parameters

Returns this

See

Example

mountOnExpress

Parameters

Returns this

mountOnFastify

Parameters

Returns this

mountOnKoa

Parameters

Returns this

mountOnNestJs

Parameters

Returns this

mountOnStandaloneServer

Parameters

Returns this

Protectedremount

`Protected`aiProvider

`Protected`customizationService

`Protected`customizer

`Protected`nocodeCustomizer

`Protected`options

`Protected` `Readonly`prefix

`Protected`schemaGenerator

`Optional`standaloneServerHost

`Protected`getRoutes

`Protected`mount

`Protected`remount

`Protected`sendSchema

`Protected`setMcpCallback