NestJS智能体开发进阶：结构化输出与工具调用实践

2025年12月16日 互联网

一、结构化输出的核心价值与设计原则

在智能体开发中，结构化输出是连接后端逻辑与前端交互的桥梁。相较于自由文本，结构化数据（如JSON Schema）能显著提升信息解析效率，尤其在多模态交互场景下，清晰的字段定义可避免语义歧义。

1.1 DTO设计规范

NestJS推荐使用数据传输对象（DTO）定义输出结构，例如：

  1. // src/agent/dto/output.dto.ts
  2. export class AgentOutputDto {
  3.   @ApiProperty({ description: '智能体唯一标识' })
  4.   agentId: string;
  6.   @ApiProperty({ 
  7.     type: 'object',
  8.     description: '结构化响应内容',
  9.     example: {
  10.       text: '查询成功',
  11.       data: { temperature: 25, humidity: 60 }
  12.     }
  13.   })
  14.   response: {
  15.     text: string;
  16.     data?: Record<string, any>;
  17.   };
  19.   @ApiProperty({ description: '工具调用状态' })
  20.   status: 'success' | 'pending' | 'failed';
  21. }

设计要点：

  • 字段分级：基础信息（如agentId）与业务数据分离
  • 类型安全：通过Zod或class-validator进行运行时校验
  • 扩展性：预留data字段支持动态业务数据

1.2 中间件处理链

通过NestJS中间件实现输出标准化：

  1. // src/common/middleware/output-formatter.middleware.ts
  2. export class OutputFormatterMiddleware implements NestMiddleware {
  3.   use(req: Request, res: Response, next: NextFunction) {
  4.     const originalJson = res.json;
  5.     res.json = (body: any) => {
  6.       const formatted = {
  7.         timestamp: new Date().toISOString(),
  8.         ...(this.isAgentResponse(body) ? 
  9.           { agentOutput: this.normalizeAgentOutput(body) } : 
  10.           body)
  11.       };
  12.       return originalJson.call(res, formatted);
  13.     };
  14.     next();
  15.   }
  17.   private isAgentResponse(body: any): boolean {
  18.     return body?.hasOwnProperty('agentId');
  19.   }
  20. }

最佳实践：

  • 在全局中间件中注入时间戳、请求ID等元数据
  • 对特定路由（如/api/agent/*）应用差异化格式化
  • 避免过度嵌套，保持三级以内结构

二、工具调用的异步处理模式

智能体的核心能力往往依赖外部工具（如数据库查询、API调用），需建立可靠的异步处理机制。

2.1 工具注册与发现

采用依赖注入方式管理工具：

  1. // src/tools/tool-registry.service.ts
  2. @Injectable()
  3. export class ToolRegistryService {
  4.   private readonly tools = new Map<string, ToolInterface>();
  6.   registerTool(name: string, tool: ToolInterface) {
  7.     this.tools.set(name, tool);
  8.   }
  10.   getTool(name: string): ToolInterface {
  11.     const tool = this.tools.get(name);
  12.     if (!tool) throw new NotFoundException(`Tool ${name} not found`);
  13.     return tool;
  14.   }
  15. }
  17. // src/tools/database.tool.ts
  18. @Injectable()
  19. export class DatabaseTool implements ToolInterface {
  20.   constructor(private prisma: PrismaService) {}
  22.   async execute(query: string): Promise<any> {
  23.     return this.prisma.$queryRawUnsafe(query);
  24.   }
  25. }

架构优势：

  • 集中式管理避免工具重复实例化
  • 通过接口抽象实现工具热插拔
  • 结合AOP实现调用日志、权限校验等横切关注点

2.2 异步调用编排

使用RxJS处理工具链调用：

  1. // src/agent/services/agent.service.ts
  2. executeToolChain(tools: string[], input: any): Observable<any> {
  3.   return from(tools).pipe(
  4.     concatMap(toolName => {
  5.       const tool = this.toolRegistry.getTool(toolName);
  6.       return tool.execute(input).pipe(
  7.         tap(result => this.logger.log(`Tool ${toolName} executed`)),
  8.         catchError(err => {
  9.           this.logger.error(`Tool ${toolName} failed`, err.stack);
  10.           return throwError(err);
  11.         })
  12.       );
  13.     }),
  14.     reduce((acc, curr) => ({ ...acc, ...curr }), {})
  15.   );
  16. }

性能优化：

  • 对无依赖的工具采用mergeMap并行执行
  • 设置并发限制避免资源耗尽
  • 通过retry策略处理瞬时故障

三、典型场景实现方案

3.1 多轮对话状态管理

结合Redis实现跨请求状态持久化：

  1. // src/agent/services/dialog-manager.service.ts
  2. @Injectable()
  3. export class DialogManagerService {
  4.   constructor(
  5.     @InjectRedis() private readonly redis: Redis,
  6.     private readonly agentService: AgentService
  7.   ) {}
  9.   async handleDialog(sessionId: string, input: DialogInputDto) {
  10.     const dialogState = await this.getDialogState(sessionId);
  11.     const context = { ...dialogState, ...input };
  13.     const result = await this.agentService.process(context);
  15.     await this.updateDialogState(sessionId, {
  16.       lastInput: input,
  17.       lastOutput: result,
  18.       step: dialogState.step + 1
  19.     });
  21.     return result;
  22.   }
  24.   private async getDialogState(sessionId: string) {
  25.     const cached = await this.redis.get(`dialog:${sessionId}`);
  26.     return cached ? JSON.parse(cached) : { step: 0 };
  27.   }
  28. }

关键考虑：

  • 设置合理的TTL避免状态堆积
  • 对敏感数据加密存储
  • 实现状态迁移验证逻辑

3.2 工具调用超时控制

通过AbortController实现：

  1. // src/tools/http-client.tool.ts
  2. @Injectable()
  3. export class HttpClientTool implements ToolInterface {
  4.   async execute(config: HttpRequestConfig): Promise<any> {
  5.     const controller = new AbortController();
  6.     const timeoutId = setTimeout(() => controller.abort(), 5000);
  8.     try {
  9.       const response = await fetch(config.url, {
  10.         signal: controller.signal,
  11.         ...config
  12.       });
  13.       clearTimeout(timeoutId);
  14.       return response.json();
  15.     } catch (err) {
  16.       if (err.name === 'AbortError') {
  17.         throw new RequestTimeoutException('Tool execution timed out');
  18.       }
  19.       throw err;
  20.     }
  21.   }
  22. }

容错设计：

  • 熔断机制：连续超时后自动降级
  • 备份工具：主工具失败时切换备用方案
  • 监控告警：记录超时率异常波动

四、测试与质量保障

4.1 结构化输出验证

使用Fastify的JSON Schema验证：

  1. // src/agent/agent.controller.ts
  2. @Post()
  3. @UsePipes(new ValidationPipe({ transform: true }))
  4. @UseInterceptors(new SchemaValidatorInterceptor({
  5.   schema: {
  6.     type: 'object',
  7.     properties: {
  8.       agentOutput: {
  9.         type: 'object',
  10.         required: ['text', 'status'],
  11.         properties: {
  12.           text: { type: 'string' },
  13.           status: { enum: ['success', 'pending', 'failed'] }
  14.         }
  15.       }
  16.     }
  17.   }
  18. }))
  19. async handleRequest(@Body() input: AgentInputDto) {
  20.   // ...
  21. }

4.2 工具调用模拟测试

创建工具存根（Stub）进行隔离测试：

  1. // test/tools/database.tool.stub.ts
  2. export class DatabaseToolStub implements ToolInterface {
  3.   private mockData: Record<string, any> = {};
  5.   setMockData(key: string, value: any) {
  6.     this.mockData[key] = value;
  7.   }
  9.   async execute(query: string): Promise<any> {
  10.     const match = query.match(/SELECT\s+\*\s+FROM\s+(\w+)/i);
  11.     if (match) return this.mockData[match[1]] || [];
  12.     throw new Error('Query not mocked');
  13.   }
  14. }
  16. // 在测试中替换真实工具
  17. beforeEach(() => {
  18.   const mock = new DatabaseToolStub();
  19.   mock.setMockData('users', [{ id: 1, name: 'Test' }]);
  21.   const module = await Test.createTestingModule({
  22.     providers: [
  23.       AgentService,
  24.       { provide: ToolRegistryService, useValue: {
  25.         getTool: () => mock
  26.       }}
  27.     ]
  28.   }).compile();
  30.   // ...
  31. });

五、性能优化实践

5.1 输出缓存策略

对稳定输出实施缓存：

  1. // src/agent/services/output-cache.service.ts
  2. @Injectable()
  3. export class OutputCacheService {
  4.   constructor(
  5.     @InjectRedis() private readonly redis: Redis,
  6.     private readonly agentService: AgentService
  7.   ) {}
  9.   async getCachedOutput(inputHash: string): Promise<any> {
  10.     const cached = await this.redis.get(`output:${inputHash}`);
  11.     return cached ? JSON.parse(cached) : null;
  12.   }
  14.   async processWithCache(input: AgentInputDto): Promise<any> {
  15.     const inputHash = createHash('md5').update(JSON.stringify(input)).digest('hex');
  16.     const cached = await this.getCachedOutput(inputHash);
  18.     if (cached) return cached;
  20.     const result = await this.agentService.process(input);
  21.     await this.redis.setex(`output:${inputHash}`, 3600, JSON.stringify(result));
  23.     return result;
  24.   }
  25. }

缓存策略选择：

  • 参数化查询：对相同输入返回相同输出的情况适用
  • 版本控制：当工具集变更时清空相关缓存
  • 梯度失效：重要数据设置较短TTL，静态数据设置长TTL

5.2 工具池复用

对耗时工具实现连接池：

  1. // src/tools/pool/tool-pool.service.ts
  2. @Injectable()
  3. export class ToolPoolService {
  4.   private pool = new Map<string, Pool<ToolInterface>>();
  6.   acquireTool(name: string): Promise<ToolInterface> {
  7.     if (!this.pool.has(name)) {
  8.       const factory = () => this.createToolInstance(name);
  9.       this.pool.set(name, new Pool({ factory, max: 5 }));
  10.     }
  11.     return this.pool.get(name)!.acquire();
  12.   }
  14.   releaseTool(name: string, tool: ToolInterface): Promise<void> {
  15.     const pool = this.pool.get(name);
  16.     if (pool) return pool.release(tool);
  17.     return Promise.resolve();
  18.   }
  19. }

六、安全与合规考量

6.1 输出脱敏处理

实现敏感数据过滤中间件：

  1. // src/common/middleware/output-sanitizer.middleware.ts
  2. export class OutputSanitizerMiddleware implements NestMiddleware {
  3.   private readonly sensitivePatterns = [
  4.     /(\d{3})-\d{2}-\d{4}/g, // SSN
  5.     /(\d{3})[\s-]?\d{3}[\s-]?\d{4}/g // 信用卡
  6.   ];
  8.   use(req: Request, res: Response, next: NextFunction) {
  9.     const originalJson = res.json;
  10.     res.json = (body: any) => {
  11.       const sanitized = this.sanitize(body);
  12.       return originalJson.call(res, sanitized);
  13.     };
  14.     next();
  15.   }
  17.   private sanitize(data: any): any {
  18.     if (typeof data !== 'object' || data === null) return data;
  20.     return Object.fromEntries(
  21.       Object.entries(data).map(([key, value]) => {
  22.         if (typeof value === 'string') {
  23.           return [key, this.applyPatterns(value)];
  24.         } else if (typeof value === 'object') {
  25.           return [key, this.sanitize(value)];
  26.         }
  27.         return [key, value];
  28.       })
  29.     );
  30.   }
  31. }

6.2 工具调用鉴权

基于角色的工具访问控制：

  1. // src/tools/auth/tool-auth.guard.ts
  2. @Injectable()
  3. export class ToolAuthGuard implements CanActivate {
  4.   constructor(
  5.     private readonly reflector: Reflector,
  6.     private readonly toolAuthService: ToolAuthService
  7.   ) {}
  9.   async canActivate(context: ExecutionContext): Promise<boolean> {
  10.     const requiredTools = this.reflector.get<string[]>(
  11.       'requiredTools', 
  12.       context.getHandler()
  13.     );
  15.     if (!requiredTools) return true;
  17.     const request = context.switchToHttp().getRequest();
  18.     const user = request.user;
  20.     return this.toolAuthService.checkAccess(
  21.       user.id, 
  22.       requiredTools
  23.     );
  24.   }
  25. }
  27. // 在控制器方法上使用装饰器
  28. export const RequiredTools = (tools: string[]) => 
  29.   SetMetadata('requiredTools', tools);
  31. @UseGuards(ToolAuthGuard)
  32. @RequiredTools(['database', 'file-system'])
  33. @Post('/sensitive-operation')
  34. async sensitiveOperation() {
  35.   // ...
  36. }

通过系统化的结构化输出设计和工具调用管理，NestJS智能体可实现高可维护性、强安全性的业务逻辑处理。开发者应重点关注DTO设计的合理性、异步调用的错误处理以及性能瓶颈的提前识别，结合具体业务场景选择合适的缓存策略和安全控制方案。

最新文章