nestjs-agentic

The NestJS-native runtime for governed AI agents
Define agents and tools with NestJS, enforce policy before side effects, and keep model integrations replaceable.

Why nestjs-agentic?

Most agent frameworks introduce a separate runtime and application boundary. nestjs-agentic keeps agent-facing capabilities inside the NestJS module and dependency-injection system:

NestJS service
    -> @ToolSet and @Tool
    -> context-bound ResolvedTool
    -> allow / deny / require_approval policy decision
    -> RuntimeAdapter

Application services remain ordinary NestJS providers. The model runtime receives governed tool closures rather than direct access to services or application-owned security context.

Current Capabilities

The current release line is 0.6.x. Core primitives, persistence adapters, and durable execution checkpoints are production-intent; higher-order orchestration packages remain experimental while their contracts stabilize.

See the product roadmap for milestones and production-readiness criteria.

Packages

Installation

npm install nestjs-agentic

Connect a model provider:

npm install @nestjs-agentic/openai openai

Optional packages:

npm install @nestjs-agentic/mcp
npm install @nestjs-agentic/memory
npm install @nestjs-agentic/rag @nestjs-agentic/memory
npm install @nestjs-agentic/orchestration
npm install @nestjs-agentic/evaluation

Quick Start

The example uses MockModelAdapter, so the full tool-calling loop runs deterministically without an API key. Swap in your own ModelAdapter to talk to a real provider.

1. Define a policy and tool set

import { Injectable } from '@nestjs/common';
import {
  AgentContext,
  Context,
  Param,
  PolicyResult,
  Tool,
  ToolPolicy,
  ToolSet,
  UsePolicies,
} from 'nestjs-agentic';

@Injectable()
export class RefundLimitPolicy implements ToolPolicy {
  async evaluate(
    _ctx: AgentContext,
    _toolName: string,
    args: Record<string, unknown>,
  ): Promise<PolicyResult> {
    return Number(args.amount) > 500
      ? { decision: 'require_approval', reason: 'Refund exceeds $500.' }
      : { decision: 'allow' };
  }
}

@ToolSet({ name: 'orders' })
export class OrderTools {
  @Tool({ name: 'refundOrder', description: 'Refund an order' })
  @UsePolicies(RefundLimitPolicy)
  async refundOrder(
    @Param('orderId') orderId: string,
    @Param('amount', { type: 'number' }) amount: number,
    @Context() ctx: AgentContext,
  ) {
    return { orderId, amount, requestedBy: ctx.security.userId };
  }
}

2. Define an agent and module

import { Module } from '@nestjs/common';
import {
  Agent,
  AgentConfig,
  AgenticModule,
  AgentProvider,
  MockModelAdapter,
} from 'nestjs-agentic';

@Agent({ name: 'support', description: 'Handles support requests' })
export class SupportAgent implements AgentProvider {
  constructor(private readonly orderTools: OrderTools) {}

  define(): AgentConfig {
    return {
      instructions: 'Help the user while respecting tool policies.',
      tools: [this.orderTools],
    };
  }
}

const model = new MockModelAdapter();
model
  .whenAsked('Refund $600 for order #42')
  .callTool('refundOrder', { orderId: '42', amount: 600 })
  .reply('That refund needs approval before I can complete it.');

@Module({
  imports: [
    AgenticModule.forRoot({
      defaultModel: { provider: 'mock', model: 'deterministic' },
      modelAdapter: model,
      limits: { maxIterations: 6 },
    }),
    AgenticModule.forFeature({
      agents: [SupportAgent],
      toolSets: [OrderTools],
      policies: [RefundLimitPolicy],
    }),
  ],
})
export class AppModule {}

AgenticModule.forFeature() registers these classes inside AgenticModule. Keep an agent, its tool sets, and its policies in a single forFeature() call, and export any application services they inject from a @Global() module.

3. Run the agent and handle approval

import { Body, Controller, Param, Post } from '@nestjs/common';
import { AgentRunner, ApprovalService } from 'nestjs-agentic';

@Controller('support')
export class SupportController {
  constructor(
    private readonly runner: AgentRunner,
    private readonly approvals: ApprovalService,
  ) {}

  @Post('chat')
  chat(@Body() body: { sessionId: string; message: string }) {
    return this.runner.run('support', {
      sessionId: body.sessionId,
      message: body.message,
      context: {
        userId: 'user_123',
        tenantId: 'acme',
      },
    });
  }

  @Post('approve/:id')
  approve(@Param('id') id: string) {
    return this.approvals.approve(id);
  }

  @Post('reject/:id')
  reject(@Param('id') id: string) {
    return this.approvals.reject(id);
  }
}

runner.runStream() exposes structured token, tool_start, tool_result, approval_required, and complete events.

Each run is bounded. Pass limits and a signal to cap iterations, tool calls, tokens, and wall-clock time, or to cancel work in flight:

await runner.run('support', {
  sessionId,
  message,
  limits: { maxIterations: 4, maxToolCalls: 8, timeoutMs: 30_000 },
  signal: abortController.signal,
});

Built-in Policies

• RateLimitPolicy — process-local sliding-window limits by tenant, user, and tool.
• CostLimitPolicy — numeric allow, approval, and deny thresholds.
• LoggingPolicy — configurable tool-attempt logging with field masking.

These are framework primitives, not replacements for distributed rate limiting, durable audit storage, or application authorization.

Connecting a Model

For OpenAI and any Chat Completions compatible endpoint, use the published adapter:

import { AgenticModule } from 'nestjs-agentic';
import { OpenAiModelAdapter } from '@nestjs-agentic/openai';

AgenticModule.forRoot({
  defaultModel: { provider: 'openai', model: 'gpt-4o-mini' },
  modelAdapter: new OpenAiModelAdapter({ apiKey: process.env.OPENAI_API_KEY }),
});

The same adapter targets local and third-party servers by pointing baseUrl at them, for example http://localhost:11434/v1 for Ollama. See @nestjs-agentic/openai for Azure, reasoning models, and compatibility notes.

For any other provider, implement ModelAdapter directly. It handles only provider communication; the framework owns the loop, validation, policies, budgets, and streaming.

import type { ModelAdapter, ModelRequest, ModelResponse } from 'nestjs-agentic';

export class MyModelAdapter implements ModelAdapter {
  async generate(request: ModelRequest): Promise<ModelResponse> {
    const completion = await callProvider({
      model: request.model.model,
      messages: request.messages,
      tools: request.tools,
      signal: request.signal,
    });

    return {
      content: completion.text,
      toolCalls: completion.toolCalls,
      usage: completion.usage,
      finishReason: completion.toolCalls.length ? 'tool_calls' : 'stop',
    };
  }
}

The core package does not import external model SDKs. Custom model adapters implement ModelAdapter directly, while the framework manages loop execution, policy enforcement, budgets, and streaming.

Documentation

• Product Roadmap
• Architecture Guide
• Core API Reference
• Contributing Guide
• Community Discussions

Runnable examples are available in examples.

Sponsorship & Support

nestjs-agentic is an open-source framework dedicated to production-grade, governed AI agent systems in NestJS. If you or your organization find value in the project, consider supporting ongoing development:

• 💖 Sponsor on GitHub
• ⭐ Star the repository on GitHub
• 🤝 Contribute features, adapters, and improvements

License

MIT © irzix