What is nestjs-agentic?

nestjs-agentic keeps agent-facing capabilities inside the NestJS module and dependency-injection system. Application services remain ordinary providers; runtimes receive context-bound tool closures that evaluate policy before invoking side effects.

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

Current Status

The current release line is 0.8.x.

| Area | Status | Scope | | --- | --- | --- | | Agents, tools, NestJS DI, policies, mock runtime | Available | Core decorators, discovery, context-bound execution, governance decisions, and deterministic tests. | | Built-in agent runtime & Cascading | Available | Governed model-to-tool loop with argument validation, execution budgets, cancellation, streaming, and FrugalGPT model cascading. | | Model Context Protocol (MCP) | Available | @nestjs-agentic/mcp for Stdio and SSE remote tool discovery and authorization. | | Human approval & Durable HITL | Available | The runtime suspends a turn on require_approval; resumes durably via ApprovalStore and execution checkpoints. | | OpenAI model adapter | Available | @nestjs-agentic/openai for OpenAI and Chat Completions compatible endpoints. | | Cognitive Memory & SOP Playbooks | Available | @nestjs-agentic/memory for Stanford Tri-Factor scoring, procedural SOPs, and trajectory reflection. | | Context Attention & RAG | Available | @nestjs-agentic/rag for U-Shaped context assembly, AST codebase splitting, and GraphRAG. | | Debiased Evaluation & Trajectory Metrics | Available | @nestjs-agentic/evaluation for MT-Bench position-debiased judge and AgentBench metrics. | | Sub-Agent Orchestration | Available | @nestjs-agentic/orchestration for parallel delegation, bounded concurrency, and refinement. | | Persistence & Stores | Available | In-memory, Redis, and PostgreSQL drivers for Session, State, Approval, and Idempotency. |

Installation

npm install nestjs-agentic

Use MockRuntimeAdapter for deterministic governance tests without a model API.

Minimal Governed Tool

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 };
  }
}

Documentation

• Product Roadmap
• Architecture Guide
• API Reference

License

MIT © irzix