A progressive Node.js framework for building efficient and scalable server-side applications.

Description

Language models for Nest: named models through dependency injection, model calls with timeouts, retries and fallback models (run on @nestjs/resilience policies, or your own), budgets and usage events, structured output validated by a schema, the application's own provider methods as agent functions its agents call (through Nest's guards, interceptors, pipes and exception filters, as the user the agent acts for), answers streamed to the browser on Express, Fastify and the Node adapter, and durable agent runs on @nestjs/workflows (@nestjs/ai/workflows) that survive restarts and wait for a person's approval. You write an agent function with @AgentFunction(), and the model is offered it as a tool; a method can be an MCP tool too, served by @nestjs/mcp, with its @Tool() stacked on it. Embedding models have their own named registry, dependency injection, resilient single and batch calls, and usage events. Comes with fake language and embedding models for tests. Built on the AI SDK (ai) and its provider packages.

Installation

$ npm i --save @nestjs/ai @nestjs/resilience ai @ai-sdk/anthropic zod

Any @ai-sdk/* provider package works (@ai-sdk/openai, @ai-sdk/google, ...). Zod 4.2 or later for the schemas; any other Standard Schema library that produces JSON Schema works too. Node.js 22 or later.

Each major version of @nestjs/ai supports one major version of the AI SDK: this one, ai 7.

Quick Start

Register the models, and call them:

import { anthropic } from '@ai-sdk/anthropic';
import { Injectable, Module } from '@nestjs/common';
import { AgentFunction, AiModule, AiService, type AgentFunctionContext } from '@nestjs/ai';
import * as z from 'zod';

@Injectable()
export class OrdersTools {
  constructor(private readonly orders: OrdersService) {}

  @AgentFunction({
    name: 'find-order',
    description: 'Find an order by its id',
    inputSchema: z.object({ orderId: z.string() }),
  })
  find({ orderId }: { orderId: string }, ctx: AgentFunctionContext) {
    return this.orders.findFor(ctx.request?.user, orderId);
  }
}

@Injectable()
export class SupportService {
  constructor(private readonly ai: AiService) {}

  async answer(question: string, request: unknown) {
    const { text } = await this.ai.generateText({
      prompt: question,
      tools: ['find-order'],
      caller: { request },
    });
    return text;
  }
}

@Module({
  imports: [
    AiModule.forRoot({
      models: {
        default: anthropic('claude-opus-5-5'),
        fast: anthropic('claude-haiku-5-5'),
      },
      defaults: { timeout: '30s', retry: { attempts: 3 } },
    }),
  ],
  providers: [OrdersService, OrdersTools, SupportService],
})
export class AppModule {}

A method that MCP clients call too also carries @nestjs/mcp's @Tool(), with options of its own: the two decorators don't read each other's, and one schema constant serves both. generateObject({ schema }) answers a typed object, and streamText() an answer a controller sends to the browser with pipeUIMessageStreamToResponse(res), as the AI SDK's useChat() reads it. Agent function calls run through the guards, interceptors, pipes and filters of the class and the method, with the context type 'ai', so AiExecutionContext reads them in enhancers (on a method with both decorators, they see 'mcp' for MCP clients' calls), and @nestjs/authentication (0.1.4 or later) and @nestjs/authorization (0.1.2 or later) authenticate and authorize them. @nestjs/ai/testing has FakeModel, which answers with text, tool calls, objects or errors, without a network.

The sample is a cat store: it triages support emails, and runs a chat assistant that calls the same find-order method its MCP server serves. npm run build && npx tsc -p sample/tsconfig.json, then node sample/dist/main.js (with ANTHROPIC_API_KEY set, Claude answers; without it, fake models do).

Read Overview to get started and for the module's options, Models for retries, timeouts, fallback models and budgets, Tools for agent functions, the call context, guards and authorization, Agents for the agent loop, streaming to the browser and durable runs, Embeddings for embedding models and batches, and Testing for the fake models.

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

• Author - Kamil Myśliwiec
• Website - https://nestjs.com
• Twitter - @nestframework

License

Nest is MIT licensed.