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/dist/agent.d.ts:50

Properties

`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

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/dist/agent.d.ts:91

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/dist/agent.d.ts:69

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
- Optionaloptions: 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/dist/agent.d.ts:169

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/dist/agent.d.ts:100

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/dist/agent.d.ts:209

`Protected`getInProcessDispatcher

getInProcessDispatcher(): InProcessDispatcher
Dispatcher that runs agent-client requests against the agent's own /forest stack in-memory. The handler is rebuilt on every (re)mount so a captured reference never goes stale.

Returns InProcessDispatcher
Inherited from FrameworkMounter.getInProcessDispatcher
- Defined in agent/dist/framework-mounter.d.ts:28

`Protected`getRoutes

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

`Protected`mount

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

mountAiMcpServer

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

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

Tool calls reach your data in-process (no socket), so they skip any host-app middleware you mounted in front of the agent (rate limiting, request logging, WAF). The agent's own JWT auth and permission checks still run on them, and the inbound MCP request itself is unaffected.

Parameters

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

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' });
// Example: shorten the OAuth token lifetimes. `accessTokenSeconds` cannot exceed the 1h Forest
// grants; `refreshTokenSeconds` bounds the time between two interactive logins, which is
// otherwise unbounded since Forest re-grants its refresh lifetime on every refresh.
agent.mountAiMcpServer({ tokenTtl: { accessTokenSeconds: 900, refreshTokenSeconds: 86400 } });

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/dist/framework-mounter.d.ts:44

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/dist/framework-mounter.d.ts:49

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/dist/framework-mounter.d.ts:54

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/dist/framework-mounter.d.ts:59

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/dist/framework-mounter.d.ts:39

`Protected`remount

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

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/dist/agent.d.ts:107

restart

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

Returns Promise<void>
- Defined in agent/dist/agent.d.ts:62

`Protected`sendSchema

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

`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/dist/framework-mounter.d.ts:23

start

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

Returns Promise<void>
- Defined in agent/dist/agent.d.ts:54

stop

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

Returns Promise<void>
Overrides FrameworkMounter.stop
- Defined in agent/dist/agent.d.ts:58

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/dist/agent.d.ts:76

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/dist/agent.d.ts:118

Class Agent<S>

Example

Type Parameters

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns Agent<S>

Example

Properties

ProtectedcustomizationService

Protectedcustomizer

ProtectednocodeCustomizer

Protectedoptions

Protected Readonlyprefix

ProtectedschemaGenerator

OptionalstandaloneServerHost

standaloneServerPort

Methods

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>

ProtectedgetInProcessDispatcher

Returns InProcessDispatcher

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

Parameters

Returns Promise<void>

removeCollection

Parameters

Returns this

`Protected`customizationService

`Protected`customizer

`Protected`nocodeCustomizer

`Protected`options

`Protected` `Readonly`prefix

`Protected`schemaGenerator

`Optional`standaloneServerHost

`Protected`getInProcessDispatcher

`Protected`getRoutes

`Protected`mount

`Protected`remount

`Protected`sendSchema

`Protected`setMcpCallback