# NestJS Agent

> A governed, durable-backed AI agent library for NestJS with chat, tool-calling, RBAC, quotas, cost tracking and human-in-the-loop approval.

@dudousxd/nestjs-agent is an open-source NestJS library from the Aviary ecosystem, published by Davide Carvalho under the MIT license. It adds an in-app AI assistant to a NestJS backend: the agent loop, a tool registry, per-tool authorization, token quotas, cost tracking and human approval for destructive actions. The documentation marks it as early development (0.x), with package surface and SPIs still stabilizing.

## What It Is

The library packages the machinery every in-app copilot needs, such as model-to-tool looping, tool discovery, governance and resumable streaming. Developers declare tools with `@AiTool` classes (read or action kind), register `AgentModule.forRoot` with a model (for example through the Vercel AI SDK adapter), and get SSE and REST endpoints under `/agent`. The application's domain (tables, tenant columns, roles) remains policy the developer supplies.

## Governance and Approval

Action tools never auto-execute; the run pauses for approve or reject, or can become an independent proposal decided later. Tools can be gated by roles or by abilities through an authz integration, switched off per deployment or per user, and made idempotent through a per-call idempotency key. Quotas can be set per day or month in tokens or USD, and every tool call is audited. Cost is taken from provider-reported spend when available, otherwise from a cache-aware estimate against a pricing table.

## Inline or Durable Turns

By default a turn runs in-process. With `@dudousxd/nestjs-durable` and `durable: true`, model and tool calls become checkpointed steps dispatched across workers, so crashes replay from cache and approvals become durable signals. The wire protocol stays the same, and a cross-process token sink such as Redis or a database-backed sink is needed for multi-replica streaming.

## Ecosystem Packages

The family includes MikroORM and Drizzle persistence, governed read-only SQL, MCP client and server packages, WhatsApp and Telegram channels, a React frontend with `useAgentChat`, a governance dashboard, a Telescope tab, codegen, evals scorers and testing utilities. Additional features include multi-agent delegation via `ask_<name>` tools, personas, scoped skills, memory, structured output, input and output processors, history windows, and an AG-UI adapter.

## Features
- AiTool framework with read and action kinds and auto-discovery
- Per-tool RBAC and ability-based authorization
- Token and USD quotas per day and month
- Usage ledger with reported-cost and cache-aware cost estimates
- Human-in-the-loop approval and independent action proposals
- Inline or durable replay-safe turn runners
- SSE streaming with resume
- Multi-agent delegation to sub-agents
- Personas, skills and memory
- Structured output with bounded repair
- Input and output processors
- Governed read-only SQL tool
- MCP client and MCP server packages
- React hooks and chat components
- Governance dashboard and Telescope tab
- Diagnostics channel events and tracing spans
- Evals scorers over stored runs
- AG-UI protocol adapter

## Integrations
NestJS, Vercel AI SDK, MikroORM, Drizzle, Redis, Model Context Protocol, WhatsApp, Telegram, React, Telescope, @dudousxd/nestjs-durable, @dudousxd/nestjs-authz, OpenAI, AG-UI

## Platforms
WINDOWS, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.4.1

## Links
- Website: https://davidecarvalho.github.io/aviary/docs/agent
- Documentation: https://davidecarvalho.github.io/aviary/docs/agent
- Repository: https://github.com/DavideCarvalho/nestjs-agent
- EveryDev.ai: https://www.everydev.ai/tools/nestjs-agent