DEV Community: Martin-Bruel

LangChain Structured Output in NestJS: Typed with Zod

Martin-Bruel — Thu, 29 Oct 2026 15:32:18 +0000

To get an object instead of text from a LangChain agent in NestJS, pass a Zod schema as output to run(). This tutorial turns a customer message into an order your code can use, in a dozen lines.

This is part 3 of AI agents with NestJS. Part 2 gives the agent the catalog tools used here.

Tested with NestJS 12, LangChain 1.x, Zod 4, nestjs-langchain 2.1 and Node 22.

What does structured output change?

Same message, same model. Without a schema, the agent answers in text, and your code has to dig the SKU out of a sentence. With one, it answers an object, checked against the schema and typed by it.

The model is still not deterministic: it decides what goes in each field. But the shape of its answer is fixed, and that is what your backend relies on.

How do I describe the answer?

With a Zod object, in orders/order-draft.schema.ts:

import { z } from 'zod';

export const OrderDraft = z.object({
  sku: z.string().describe('The SKU of the product in the catalog.'),
  quantity: z.number().int().positive(),
});

export type OrderDraft = z.infer<typeof OrderDraft>;

The model receives this schema, descriptions included, and fills in each field from them. .transform() and .refine() work too: see docs/structured-output.md.

How do I get it from `run()`?

Pass the schema as output, in a new orders/orders.controller.ts:

import { Body, Controller, Post } from '@nestjs/common';
import { Agent } from 'nestjs-langchain';
import { OrderDraft } from './order-draft.schema.js';

@Controller('orders')
export class OrdersController {
  constructor(private readonly agent: Agent) {}

  @Post('draft')
  async draft(@Body('message') message: string): Promise<OrderDraft> {
    const { output } = await this.agent.run(
      `Find the product of this customer message in the catalog, then draft the order.\n\n${message}`,
      { output: OrderDraft },
    );
    return output;
  }
}

Then add OrdersController to the controllers of AppModule.

output is an OrderDraft: output.sku compiles, a typo does not.
The input asks for the catalog search of part 2: otherwise the model may write a SKU from memory.
POST /ask still answers in text: the schema belongs to the run, not to the agent.

Try it

npm run start:dev

curl -X POST http://localhost:3000/orders/draft \
  -H 'Content-Type: application/json' \
  -d '{"message": "Two K2 keyboards, please."}'

{ "sku": "KB-101", "quantity": 2 }

The model found the SKU with the searchProducts tool of part 2, then answered through the schema.

Next: test it without an API key

The agent now answers in a shape your code can trust. Part 4 tests all of it with LangChain's fakeModel(), which replays the tool calls and answers you queue: the catalog tools, this endpoint, the retry and the 422, with no provider and no network. The tests are already in the repo, in orders/orders.controller.spec.ts.

The code of this article: nestjs-ai-agent-example, tag part-3
Structured output in detail, and its limits: docs/structured-output.md
Package: nestjs-langchain on npm
Source, issues and stars: GitHub

Gouvernez votre agent IA : NestJS et Mistral en 30 lignes

Martin-Bruel — Mon, 26 Oct 2026 16:05:39 +0000

Gouverner un agent IA, c'est maîtriser deux choses : le modèle qu'il utilise, et ce qu'il fait dans votre application. Ce tutoriel couvre les deux en une trentaine de lignes de TypeScript, de nest new à un endpoint POST /ask : un modèle Mistral, européen et open source, et un agent déclaré comme un module NestJS avec nestjs-langchain.

Le modèle n'est pas déterministe, mais tout ce qui l'entoure peut l'être : l'agent est configuré en un seul endroit, vérifié au démarrage, et chaque exécution dit ce qu'il a fait.

Testé avec NestJS 12, LangChain 1.x, nestjs-langchain 2.0, @langchain/mistralai 1.2 et Node 22.

Comment ajouter LangChain et Mistral à un projet NestJS ?

Créez l'application, puis installez la bibliothèque et l'intégration Mistral de LangChain :

npx @nestjs/cli new my-app --package-manager npm
cd my-app
npm install nestjs-langchain @langchain/mistralai

npm installe aussi langchain, @langchain/core et zod, les dépendances pairs de la bibliothèque. @langchain/mistralai est le fournisseur : @langchain/openai, @langchain/anthropic ou toute autre intégration de chat LangChain s'utilise de la même façon.

Le fournisseur lit sa clé dans l'environnement. Créez-la dans la console de Mistral AI, puis :

export MISTRAL_API_KEY=...

Comment déclarer l'agent avec un modèle Mistral ?

Importez LangChainModule dans app.module.ts :

import { Module } from '@nestjs/common';
import { LangChainModule } from 'nestjs-langchain';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';
import { AskController } from './ask.controller.js';

@Module({
  imports: [
    LangChainModule.register({
      // `fournisseur:modèle` ; le fournisseur lit MISTRAL_API_KEY.
      model: { model: 'mistralai:mistral-small-latest' },
      systemPrompt: 'Tu es un assistant utile. Réponds en un paragraphe.',
    }),
  ],
  controllers: [AppController, AskController],
  providers: [AppService],
})
export class AppModule {}

model nomme le fournisseur et le modèle. mistral-small-latest suffit pour commencer et sait appeler des outils, ce qui servira plus loin ; mistralai:mistral-large-latest donne le plus grand modèle de Mistral. Passer à OpenAI, c'est openai:gpt-5-mini avec @langchain/openai installé.

Pourquoi Mistral pour gouverner le modèle ?

Parce que vous choisissez où il tourne, et sous quelle licence :

Un éditeur européen. Mistral AI est une société française, et par défaut les données envoyées à son API sont hébergées dans l'Union européenne.
Des poids ouverts. Mistral Small est publié sous licence Apache 2.0 : vous pouvez l'exécuter sur vos propres serveurs.

Avec Ollama, seule la ligne model change : plus de clé d'API, et vos données restent sur votre infrastructure.

npm install @langchain/ollama
ollama pull mistral-small3.2

model: { model: 'ollama:mistral-small3.2' },

Le reste de la chaîne est open source aussi : NestJS, LangChain et nestjs-langchain sont sous licence MIT.

Comment appeler l'agent depuis un contrôleur ?

Injectez Agent comme n'importe quel provider, dans un nouveau ask.controller.ts :

import { Body, Controller, Post } from '@nestjs/common';
import { Agent } from 'nestjs-langchain';

@Controller('ask')
export class AskController {
  constructor(private readonly agent: Agent) {}

  @Post()
  async ask(@Body('question') question: string): Promise<string> {
    const { output } = await this.agent.run(question);
    return output;
  }
}

En plus de output, la réponse, run() renvoie les outils appelés par le modèle, les tokens utilisés et la durée de l'exécution.

Démarrez l'application et posez une question :

npm run start:dev

curl -X POST http://localhost:3000/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "À quoi sert un module NestJS ?"}'

La réponse est celle de Mistral, en texte brut.

Comment gouverner ce que fait l'agent ?

En le traitant comme le reste du backend : nestjs-langchain le range dans un module Nest, avec les mêmes règles.

Une configuration, vérifiée au démarrage. Fournisseur, modèle et prompt sont dans le module, et registerAsync les lit dans ConfigService. Une clé manquante bloque le démarrage, comme plus haut.
Un agent par usage. Chaque agent a son nom, son prompt et ses outils, et s'injecte avec @InjectAgent() : le chatbot public et l'agent du back-office restent séparés.
Seulement les outils que vous déclarez. L'agent n'appelle que les méthodes @Tool() des modules listés dans tools, et vérifie leurs arguments avant chaque appel.
Chaque exécution se lit. run() renvoie les outils appelés, les tokens et la durée ; un observer les envoie dans vos logs.
Des tests sans clé Mistral. Le fakeModel() de LangChain remplace le modèle en CI.

Pour un simple appel à un modèle, LangChain seul suffit. Le module sert dès que l'agent touche votre application et que vous devez savoir ce qu'il fait.

Ensuite : donner des outils à l'agent

Un agent devient utile quand il agit sur votre application. Avec @Tool(), une méthode de service devient un outil que Mistral peut appeler :

@Injectable()
export class MathService {
  @Tool({ description: 'Additionne deux nombres.' })
  add(
    @ToolParam({ name: 'a' }) a: number,
    @ToolParam({ name: 'b' }) b: number,
  ): number {
    return a + b;
  }
}

Puis tools: [MathModule] dans register() le donne à l'agent. Les détails se trouvent dans la série complète : AI agents with NestJS.

Le code de cet article : nestjs-ai-agent-example, tag part-1, avec OpenAI ; pour Mistral, installez @langchain/mistralai et changez la ligne model
Paquet : nestjs-langchain sur npm
Code source, issues et étoiles : GitHub

NestJS Tool Calling: Turn Services into LLM Tools

Martin-Bruel — Wed, 21 Oct 2026 13:00:48 +0000

To let an LLM call your NestJS code, decorate a service method with @Tool() and its parameters with @ToolParam(), then list the service's module in the agent's tools. This tutorial turns a product catalog service into two tools, types their arguments with Zod, and shows what happens when the model, or your code, gets something wrong.

This is part 2 of AI agents with NestJS. Part 1 sets up the agent used here.

Tested with NestJS 12, LangChain 1.x, Zod 4, nestjs-langchain 2.0 and Node 22.

What is tool calling?

Tool calling, also called function calling, lets a model ask your code to run a function and read its result before it answers. The model never runs anything itself:

With nestjs-langchain, the agent's part comes from two decorators on a method you already have.

How do I turn a NestJS service method into a tool?

Decorate the method with @Tool() and each argument the model fills in with @ToolParam(). Here, in catalog/catalog.service.ts:

import { Injectable } from '@nestjs/common';
import { Tool, ToolParam } from 'nestjs-langchain';
import { ProductsRepository } from './products.repository.js';

@Injectable()
export class CatalogService {
  constructor(private readonly products: ProductsRepository) {}

  @Tool({ description: 'Returns how many units of a product are in stock.' })
  async checkStock(
    @ToolParam({
      name: 'sku',
      description: 'The product reference, such as KB-101.',
    })
    sku: string,
  ): Promise<number> {
    const stock = await this.products.stockOf(sku);
    if (stock === undefined) {
      throw new Error(`No product with SKU ${sku}.`);
    }
    return stock;
  }
}

ProductsRepository stands for whatever your app already uses: TypeORM, Prisma, an HTTP client. The tool is a plain service method, so it keeps its dependencies, and your controllers can still call it.

The name is the method's, checkStock, unless @Tool() takes a name.
The descriptions are written for the model: it reads the tool's to decide when to call it, and each parameter's to fill it in.
sku needs no schema: for a string, number or boolean parameter, the library reads the type TypeScript records with emitDecoratorMetadata, on in every Nest project.
The return value reaches the model as text: a string as is, a number as its digits, an object as JSON.

How do I give the tools to the agent?

Declare the service in a module, catalog/catalog.module.ts:

import { Module } from '@nestjs/common';
import { CatalogService } from './catalog.service.js';
import { ProductsRepository } from './products.repository.js';

@Module({
  providers: [CatalogService, ProductsRepository],
})
export class CatalogModule {}

Then import that module and list it in the agent's tools, in app.module.ts:

import { Module } from '@nestjs/common';
import { LangChainModule } from 'nestjs-langchain';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';
import { AskController } from './ask.controller.js';
import { CatalogModule } from './catalog/catalog.module.js';

@Module({
  imports: [
    CatalogModule,
    LangChainModule.register({
      // `provider:model`; the provider reads OPENAI_API_KEY.
      model: { model: 'openai:gpt-5-mini' },
      systemPrompt: 'You sell computer accessories. Answer from the catalog.',
      tools: [CatalogModule],
    }),
  ],
  controllers: [AppController, AskController],
  providers: [AppService],
})
export class AppModule {}

The agent gets every @Tool() method of the providers CatalogModule declares, not those of the modules it imports. At startup, the agent logs how many it got: ready with 1 tool.

How do I type tool arguments with Zod?

Pass a Zod schema to @ToolParam(). Add a second tool to CatalogService, which searches by category and price:

import { z } from 'zod';

const Category = z.enum(['keyboard', 'mouse', 'headset']);

// In CatalogService:
@Tool({ description: 'Searches the catalog by name, cheapest first.' })
searchProducts(
  @ToolParam({ name: 'query', description: 'Words of the product name.' })
  query: string,
  @ToolParam({ name: 'category', schema: Category, optional: true })
  category?: z.infer<typeof Category>,
  @ToolParam({
    name: 'maxPrice',
    description: 'The highest price, in euros.',
    schema: z.number().positive(),
    optional: true,
  })
  maxPrice?: number,
): Promise<Product[]> {
  return this.products.search({ query, category, maxPrice });
}

category needs a schema. At runtime, TypeScript erases 'keyboard' | 'mouse' | 'headset' to String, so without z.enum() the model could send any string. An object or an array needs one too.
optional: true lets the model leave the argument out. Declare the parameter with ?.
The schema is your validation boundary. Bound numbers, enumerate what you can: the model writes these arguments from what the user typed.

How do I see which tools the model called?

Return them next to the answer, from the controller of part 1:

@Post()
async ask(
  @Body('question') question: string,
): Promise<{ output: string; tools: string[] }> {
  const { output, tools } = await this.agent.run(question);
  return { output, tools };
}

Then start the app and ask a question that needs both tools:

npm run start:dev

curl -X POST http://localhost:3000/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "Is there a keyboard under 100 euros in stock?"}'

{
  "output": "Yes: the K2 mechanical keyboard, at 89 euros, has 12 units in stock. The Silent office keyboard, at 39 euros, is sold out.",
  "tools": ["searchProducts", "checkStock", "checkStock"]
}

The model searched the catalog, then checked the stock of each keyboard it found. tools lists every call it made, in order, failed ones included.

What does the model see when a tool fails?

The error's message, and the run goes on: the model can correct itself or tell the user. When checkStock throws for an unknown SKU, the model receives:

Error: No product with SKU XX-000.
 Please fix your mistakes.

Arguments that break the schema never reach your method. Asked for a laptop, a model may send category: 'laptop': it then receives Zod's error, expected one of "keyboard"|"mouse"|"headset", and can retry or tell the user the shop sells none.

How do I keep tools safe?

Treat a tool like a public endpoint: the model calls it with arguments written from what the user typed.

Keep tools narrow. Read-only where you can, and a specific action rather than a generic one: findOrder(id), not runQuery(sql).
Never let the model say who it acts for. A userId argument lets a prompt injection read another user's data.

Next: get a typed answer

Part 3 turns the agent's answer into an object your code can save, typed with Zod:
LangChain Structured Output in NestJS: Typed with Zod.

The code of this article: nestjs-ai-agent-example, tag part-2
Naming, parameter types and every startup check: docs/tools.md
Package: nestjs-langchain on npm
Source, issues and stars: GitHub

NestJS + LangChain: Build an AI Agent in 5 Minutes

Martin-Bruel — Tue, 13 Oct 2026 14:49:07 +0000

To add an AI agent to a NestJS app, register it as a module with nestjs-langchain, inject it like any provider, and call run(). This tutorial goes from nest new to a working POST /ask endpoint in about 30 lines of TypeScript.
Tested with NestJS 12, LangChain 1.x, nestjs-langchain 2.0 and Node 22.12.

How do I add LangChain to a NestJS project?

Create the app, then install the library and a model provider:

npx @nestjs/cli new my-app --package-manager npm
cd my-app
npm install nestjs-langchain @langchain/openai

@langchain/openai is the provider: @langchain/anthropic, @langchain/ollama, @langchain/mistralai or any other LangChain chat integration works the same way.

The provider reads its key from the environment:
export OPENAI_API_KEY=sk-...

How do I register the agent?

Import LangChainModule in app.module.ts:

import { Module } from '@nestjs/common';
import { LangChainModule } from 'nestjs-langchain';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';
import { AskController } from './ask.controller.js';

@Module({
  imports: [
    LangChainModule.register({
      // `provider:model`; the provider reads OPENAI_API_KEY.
      model: { model: 'openai:gpt-5-mini' },
      systemPrompt: 'You are a helpful assistant. Answer in one paragraph.',
    }),
  ],
  controllers: [AppController, AskController],
  providers: [AppService],
})
export class AppModule {}

ts
model names the provider and the model: switching to Claude is anthropic:claude-sonnet-5-5, with @langchain/anthropic installed. The agent is built when the app starts, so a wrong configuration shows up there, not on the first request.

How do I call the agent from a controller?

Inject Agent like any provider, in a new ask.controller.ts:

import { Body, Controller, Post } from '@nestjs/common';
import { Agent } from 'nestjs-langchain';

@Controller('ask')
export class AskController {
  constructor(private readonly agent: Agent) {}

  @Post()
  async ask(@Body('question') question: string): Promise<string> {
    const { output } = await this.agent.run(question);
    return output;
  }
}

Besides output, the answer, run() returns the tools the model called, the tokens it used and how long the run took.
Start the app and ask it something:

npm run start:dev

curl -X POST http://localhost:3000/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "What is dependency injection?"}'

The response is the model's answer, as plain text.

Next: give the agent tools

An agent becomes useful when it can act on your app. With @tool(), a service method becomes a tool the model can call:

@Injectable()
export class MathService {
  @Tool({ description: 'Adds two numbers.' })
  add(
    @ToolParam({ name: 'a' }) a: number,
    @ToolParam({ name: 'b' }) b: number,
  ): number {
    return a + b;
  }
}

Then tools: [MathModule] in register() hands it to the agent. The next article in this series covers tools in detail.

• The code of this article: nestjs-ai-agent-example, tag part-1
• Package: nestjs-langchain on npm
• Source, issues and stars: GitHub