Tools

A tool is how the model reaches into your app. You declare one as an ordinary NestJS injectable decorated with @AiTool; at boot the agent discovers it, registers its schema, and offers it to the model. The decorator is the contract — name, input shape, who may call it, and whether it runs on its own; the class body is your domain.

Declaring a tool

@AiTool marks a provider class as a tool. The class implements ToolHandler — a single execute(input, ctx) method. The input schema is validated before execute runs, so input is already parsed and typed by the time you touch it.

// src/tools/get-weather.tool.ts
import { AiTool, type ToolHandler, type AiToolCtx } from '@dudousxd/nestjs-agent';
import { z } from 'zod';

@AiTool({
  name: 'getWeather',
  kind: 'read', // auto-executes; see read vs action below
  description: 'Current weather for a city.',
  input: z.object({ city: z.string() }),
})
export class GetWeatherTool implements ToolHandler<{ city: string }> {
  async execute(input: { city: string }, ctx: AiToolCtx) {
    return { tempC: 21, summary: 'partly cloudy' };
  }
}

Then list it in the module that imports AgentModule — the same place you'd list any provider:

@Module({
  imports: [AgentModule.forRoot({ /* … */ })],
  providers: [GetWeatherTool],
})
export class AppModule {}

That's the whole registration story. AiToolDiscoveryService walks every provider at boot, reads the @AiTool metadata, and registers each into the shared ToolRegistry. There is no separate tools: [...] array to keep in sync — if it's a provider and it's decorated, it's a tool.

Tools are ordinary injectables

Because a tool is a normal provider, it can inject anything else in your app — a repository, an HTTP client, a queue, another service. Constructor DI works exactly as it does anywhere in NestJS.

@AiTool({
  name: 'countOpenOrders',
  kind: 'read',
  description: 'How many orders are currently open for a customer.',
  input: z.object({ customerId: z.string() }),
})
export class CountOpenOrdersTool implements ToolHandler<{ customerId: string }> {
  constructor(private readonly orders: OrdersService) {}

  async execute(input: { customerId: string }, ctx: AiToolCtx) {
    return { count: await this.orders.countOpen(input.customerId) };
  }
}

The decorator surface

Every option lives on the @AiTool({ … }) object.

There's a third kind, agent, but you never author it. The library synthesizes an agent-kind delegate tool for each handoff edge in a multi-agent setup; the loop handles it directly and your handler is never called. See Multi-agent.

read vs action — the crucial distinction

kind decides whether a tool runs on its own or waits for a human. This is the single most important field on the decorator.

@AiTool({
  name: 'purgeCache',
  kind: 'action', // the run pauses here — execute() does not fire until approval
  description: 'Purge a cache key.',
  input: z.object({ key: z.string() }),
})
export class PurgeCacheTool implements ToolHandler<{ key: string }> {
  constructor(private readonly cache: CacheService) {}

  async execute(input: { key: string }, ctx: AiToolCtx) {
    await this.cache.purge(input.key);
    return { purged: input.key };
  }
}

When the model calls an action tool, the run pauses and surfaces a pending tool-call over the wire; a human hits POST /agent/tool-call/approve (or /reject) to continue. Under durable: true that pause is a real durable suspend — checkpointed to the state store and resumable across restarts. Either way, execute runs only after approval.

The ToolHandler interface

The contract is one method:

export interface ToolHandler<I = unknown> {
  execute(input: I, ctx: AiToolCtx): Promise<unknown>;
}

• input — the parsed, schema-validated input (the I generic).
• ctx — the per-invocation AiToolCtx (below).
• return — anything JSON-serializable; it's fed back to the model as the tool result.

Throwing from execute surfaces the error to the loop rather than crashing the turn — return a structured error shape if you want the model to reason about the failure.

Per-tool timeout

By default a tool call runs until it resolves — nothing bounds it. Set AgentModule.forRoot({ toolTimeoutMs }) to cap every tool call's wall-clock time: a call that runs longer is aborted and recorded as a failed tool call, with the timeout fed back to the model as the result, so it can adapt (retry narrower input, try a different tool, or tell the user) instead of the turn hanging indefinitely.

AgentModule.forRoot({
  model: myModelProvider,
  actorResolver: new HeaderActorResolver(),
  toolTimeoutMs: 30_000, // no tool call may run longer than 30s
});

See Configuration for the full option reference.

The tool context (AiToolCtx)

The second argument gives you everything about the invocation without reaching for request-scoped globals. It's the same context whether the turn runs inline or as a durable workflow.

The actor is the load-bearing field, and the only source of identity: read ctx.actor.id and ctx.actor.tenantRef rather than any top-level shorthand. Never derive scope from tool input — derive it from ctx.actor.

async execute(input: { customerId: string }, ctx: AiToolCtx) {
  // Scope to the caller's tenant — from the context, not the input.
  return this.orders.findOpen({
    customerId: input.customerId,
    tenantRef: ctx.actor.tenantRef,
  });
}

Authorization gates

A tool declares one of two gates. Both are enforced by the loop before execute runs, so an unauthorized call never reaches your code.

@AiTool({
  name: 'listUsers',
  kind: 'read',
  description: 'List users in the org.',
  input: z.object({}),
  roles: ['ADMIN', 'SUPPORT'],
})
export class ListUsersTool implements ToolHandler { /* … */ }

@AiTool({
  name: 'purgeCache',
  kind: 'action',
  description: 'Purge a cache key.',
  input: z.object({ key: z.string() }),
  ability: 'cache.purge',
})
export class PurgeCacheTool implements ToolHandler { /* … */ }

The full model — the ActorResolver, why there's no insecure default, and roles vs abilities — is in Identity & Authorization.

Related

• Identity & Authorization — ActorResolver, the actor, roles vs abilities
• Human-in-the-loop & Durability — how an action tool suspends and resumes
• Multi-agent — the synthesized agent-kind delegate tools
• Governed SQL — a prebuilt read-only SQL tool
• Getting Started — install, first tool, first turn