@dudousxd/nestjs-agent

pnpm add @dudousxd/nestjs-agent @dudousxd/nestjs-agent-core

npm install @dudousxd/nestjs-agent @dudousxd/nestjs-agent-core

@dudousxd/nestjs-agent is the package you import in a Nest app. It wires -core's loop and SPIs into NestJS DI: AgentModule, the @AiTool discovery mechanism, the /agent controllers, and (opt-in) the durable runner under /durable.

import { Module } from '@nestjs/common';
import { AgentModule, HeaderActorResolver } from '@dudousxd/nestjs-agent';
import { aiSdkModel } from '@dudousxd/nestjs-agent-ai-sdk';
import { anthropic } from '@ai-sdk/anthropic';

@Module({
  imports: [
    AgentModule.forRoot({
      model: aiSdkModel(anthropic('claude-sonnet-4-6')),
      actorResolver: new HeaderActorResolver(),
      defaultRoles: ['ADMIN'],
    }),
  ],
})
export class AppModule {}

AgentModule

There is no forFeature — named agents beyond the default are declared as @Agent-decorated providers and discovered at boot (see multi-agent), not passed as a definition array.

model and actorResolver are the two required fields — no safe default exists for either, so compile-time errors catch a forgotten one instead of a throwing placeholder at runtime. Everything else has a default. The full option-by-option reference lives in Reference → Configuration; this page covers the surface, not every field.

AgentModule also binds AGENT_APPROVAL_PORT unconditionally (@Global, no config needed) to an internal AgentApprovalPortAdapter that routes through the same decision path chat approvals use (AgentService.signalToolCall) — this is what lets @dudousxd/nestjs-agent-dashboard's approvals inbox work out of the box whenever AgentModule is imported anywhere in the app.

@AiTool and discovery

@AiTool({ name, kind, description, input, roles?, ability? }) marks an ordinary provider as a tool. AiToolDiscoveryService walks every provider at boot, reads the decorator metadata, and registers it into the shared ToolRegistry — there's no separate array to keep in sync. See Tools for the full decorator surface and the read vs action split.

provideAgentTool

For a functional tool (a plain { spec, handler } pair, like the one createExecuteSqlTool returns from -data) that needs DI-resolved dependencies:

import { provideAgentTool } from '@dudousxd/nestjs-agent';

providers: [
  provideAgentTool(
    (pool: ReadOnlyPool) => createExecuteSqlTool({ runner: { run: (sql) => pool.query(sql) }, /* … */ }),
    [ReadOnlyPool],
  ),
];

A dependency-free functional tool can also be passed straight into AgentModule.forRoot({ tools: [...] }).

InlineAgentRunner and HeaderActorResolver

Durable subpath — @dudousxd/nestjs-agent/durable

Opt into the durable runner by importing the subpath alongside a configured DurableModule and setting durable: true. Each turn then runs as the agent.run @dudousxd/nestjs-durable workflow: every model and tool call becomes a checkpointed step, and human-in-the-loop approval becomes a real durable waitForSignal suspend instead of a held connection.

import { Module } from '@nestjs/common';
import { DurableModule } from '@dudousxd/nestjs-durable';
import { AgentModule } from '@dudousxd/nestjs-agent';
import { AgentDurableModule } from '@dudousxd/nestjs-agent/durable';

@Module({
  imports: [
    DurableModule.forRoot({ /* … */ }),
    AgentModule.forRoot({ /* model, store, actorResolver, … */ durable: true }),
    AgentDurableModule,
  ],
})
export class AppModule {}

Using the helper collapses the two imports above to one line:

imports: [DurableModule.forRoot({ /* … */ }), ...agentDurable({ model, store, actorResolver })];

Cross-process token sink — /sink-redis

import { RedisTokenStreamSink } from '@dudousxd/nestjs-agent/sink-redis';

The default TokenStreamSink buffers tokens in-process. Under durable: true (dispatched steps or not), a turn's agent.run workflow — and, with dispatching on, the llm step itself — may execute on any worker in the fleet, not the pod holding the client's SSE connection. A multi-pod deployment must bind a cross-process sink such as RedisTokenStreamSink (Redis pub/sub) via AgentModule.forRoot({ sink: new RedisTokenStreamSink(redis) }); boot logs a warning when it detects the default in-process sink under an effectively-dispatched config.

Run reliability recording

AgentRunWorkflow calls AgentStore.recordRunStart/recordRunEnd (both optional on the SPI — see -core) as checkpointed steps: start is recorded with the run's promptHash, end with duration on success or an error code/message on failure. DispatchedLlmInput carries the runId so a dispatched llm step's retries can eventually be attributed back to the run via bumpRunRetries once the durable runtime exposes the attempt number to remote step handlers. This feeds the governance reads (runMetrics, runsByAgent, …) documented in -dashboard and the Telescope Agent tab's Reliability section.

Related

• Getting Started — install, declare a tool, register the module
• Tools — the @AiTool decorator surface in full
• Human-in-the-loop & Durability — what changes under durable: true
• Concepts → Runners — inline vs durable, one AgentRunner SPI
• Reference → Configuration — every AgentModuleOptions field