@dudousxd/nestjs-agent

pnpm add @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, (opt-in) the durable runner under /durable, generative UI under /genui (AgentGenuiModule — see Generative UI), and chat attachments on Aviary media under /media (AgentMediaAttachmentsModule, optional peer @dudousxd/nestjs-media — see File uploads).

import { Module } from '@nestjs/common';
import { AgentModule } 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-5')) })],
})
export class AppModule {}

AgentModuleCopy Anchor Link

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 is the only required field. Everything else has a default — the in-memory store (or a store module's, found automatically), an anonymous identity per browser, every tool open to any resolved actor, 'You are a helpful assistant.' — each logged at boot where it matters for production. 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 discoveryCopy Anchor Link

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

provideAgentToolCopy Anchor Link

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: [...] }).

Independent approvalsCopy Anchor Link

actionApprovalMode: 'independent' turns a parked action call into a persisted proposal: the turn ends, the conversation takes the next message, and a decision made later — in the chat, the console, or a text reply — queues the work for a background worker that runs it as the requester.

AgentModule.forRoot({
  model,
  actionApprovalMode: 'independent', // default 'blocking'
  backgroundActorResolver: { resolve: ({ actorRef, tenantRef }) => findCurrentActor(actorRef, tenantRef) },
  actionProposalWorker: { pollIntervalMs: 1_000, leaseMs: 30_000, maxConcurrency: 1 }, // optional
  actionProposalText: ptBrActionProposalText, // optional: text decisions are English by default
});

Boot fails without a backgroundActorResolver or on a store that lacks proposal and queue support. The module starts and stops ActionProposalWorkerService with the app (not on surface: 'http'), and ActionProposalController mounts GET <path>/threads/:threadId/action-proposals and POST …/:proposalId/approve|reject. See Action proposals.

Runner and identity exportsCopy Anchor Link

Durable subpath — @dudousxd/nestjs-agent/durableCopy Anchor Link

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-redisCopy Anchor Link

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

The default TokenStreamSink (InProcessTokenStreamSink) 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) }) — or, without Redis, the SQL sinks the store packages ship (DrizzleTokenStreamSink, MikroOrmTokenStreamSink). The durable runner logs a warning at boot when it is handed the default in-process sink.

new RedisTokenStreamSink(redis, { keyPrefix?, ttlSeconds?, blockMs? }) takes an ioredis client and keeps each run in a Redis Stream. ttlSeconds (default 3600) is re-armed on every write and set when the run ends or fails, so a run whose process crashed still expires; 0 keeps the stream until close().

Run reliability recordingCopy Anchor Link

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.

RelatedCopy Anchor Link

• 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