如何通过ADK.js扩展机制打造定制化AI代理

2026-03-17 06:04:43作者：虞亚竹Luna

核心概念解析：ADK.js扩展架构的底层逻辑

在构建企业级AI代理时，通用解决方案往往难以满足特定业务场景需求。ADK.js作为代码优先的TypeScript工具包，通过处理器（Processors）和钩子（Callbacks）机制提供了深度定制能力。这种设计允许开发者在不修改核心源码的情况下，介入AI代理的完整生命周期。

扩展机制的核心价值

业务适配：针对垂直领域需求定制LLM交互逻辑
流程管控：精细控制代理决策流程和工具调用行为
系统集成：与企业现有系统无缝对接
性能优化：根据实际场景调整资源占用和响应速度

LlmAgent扩展点解析

ADK.js的扩展能力集中体现在LlmAgent组件中，主要包含两大扩展维度：

处理器系统：通过实现特定接口对LLM请求进行完整生命周期处理
钩子系统：在关键节点插入自定义逻辑，轻量化干预代理行为

核心处理器定义：core/src/agents/base_llm_processor.ts

功能实现路径：从接口到应用的完整流程

构建自定义处理器：从接口实现到功能注册

1. 理解处理器接口规范

所有请求处理器需实现BaseLlmRequestProcessor接口，核心方法为runAsync，该方法接收调用上下文和LLM请求对象，返回事件生成器：

import { BaseLlmRequestProcessor, InvocationContext, LlmRequest } from '../core/src/agents/base_llm_processor.ts';

class SupportRequestProcessor extends BaseLlmRequestProcessor {
  async *runAsync(
    invocationContext: InvocationContext,
    llmRequest: LlmRequest
  ): AsyncGenerator<Event, void, void> {
    // 处理器核心逻辑
  }
}

2. 实现智能客服场景处理器

以下示例实现一个客服请求预处理处理器，自动识别用户情绪并调整LLM指令：

class SupportSentimentProcessor extends BaseLlmRequestProcessor {
  async *runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest) {
    // 提取用户最新查询
    const userQuery = llmRequest.contents
      .filter(c => c.role === 'user')
      .slice(-1)[0]?.parts[0].text;
      
    if (userQuery) {
      // 简单情绪分析
      const sentiment = this.analyzeSentiment(userQuery);
      
      // 根据情绪添加系统指令
      if (sentiment === 'negative') {
        llmRequest.contents.push({
          role: 'system',
          parts: [{ 
            text: '用户当前情绪负面，请优先表达理解并提供解决方案，避免使用技术术语' 
          }]
        });
        
        yield createEvent({
          invocationId: invocationContext.invocationId,
          author: 'SupportSentimentProcessor',
          content: { parts: [{ text: '检测到负面情绪，已调整响应策略' }] }
        });
      }
    }
    
    // 将控制权传递给下一个处理器
    yield* this.nextProcessor?.runAsync(invocationContext, llmRequest) ?? [];
  }
  
  private analyzeSentiment(text: string): 'positive' | 'negative' | 'neutral' {
    // 实现情绪分析逻辑
    const negativeKeywords = ['问题', '错误', '不行', '失败', '糟糕'];
    return negativeKeywords.some(keyword => text.includes(keyword)) ? 'negative' : 'neutral';
  }
}

3. 注册自定义处理器

创建处理器实例后，需在LlmAgent配置中按执行顺序注册：

const supportAgent = new LlmAgent({
  name: 'customer-support-agent',
  model: 'gemini-pro',
  instruction: '你是一名专业的客户支持助手，负责解答产品使用问题',
  requestProcessors: [
    BASIC_LLM_REQUEST_PROCESSOR,       // 基础配置处理器
    IDENTITY_LLM_REQUEST_PROCESSOR,    // 身份信息处理器
    new SupportSentimentProcessor(),    // 自定义情绪处理处理器
    INSTRUCTIONS_LLM_REQUEST_PROCESSOR, // 指令处理器
    CONTENT_REQUEST_PROCESSOR           // 内容处理处理器
  ]
});

应用场景：在电商客服系统中，通过情绪分析处理器动态调整回复策略，提升用户满意度。

开发钩子函数：轻量级干预代理行为

1. 钩子类型与应用场景

ADK.js提供四类核心钩子，覆盖代理运行关键节点：

钩子类型	执行时机	典型应用场景
BeforeModelCallback	LLM调用前	请求日志、敏感信息过滤、动态参数调整
AfterModelCallback	LLM响应后	响应内容审查、格式转换、结果缓存
BeforeToolCallback	工具调用前	参数验证、权限检查、调用频率限制
AfterToolCallback	工具响应后	结果处理、错误恢复、二次加工

2. 实现客服场景钩子

以下示例实现一个工单自动创建钩子，在特定条件下触发后续流程：

const supportAgent = new LlmAgent({
  // 其他配置...
  afterModelCallback: async ({ context, response }) => {
    // 检查LLM是否建议创建工单
    if (response.content.parts[0].text.includes('[需要工单]')) {
      // 提取工单信息
      const ticketInfo = this.extractTicketInfo(response.content.parts[0].text);
      
      // 调用工单系统API
      const ticketId = await createSupportTicket(ticketInfo);
      
      // 修改LLM响应，添加工单信息
      return {
        ...response,
        content: {
          parts: [{ 
            text: `${response.content.parts[0].text}\n\n已为您创建工单 #${ticketId}，客服人员将在2小时内联系您。` 
          }]
        }
      };
    }
    return response;
  },
  beforeToolCallback: async ({ tool, args, context }) => {
    // 记录敏感工具调用
    if (tool.name === 'customer_db_query') {
      logSensitiveOperation({
        userId: context.user.id,
        tool: tool.name,
        query: args.query,
        timestamp: new Date().toISOString()
      });
      
      // 检查查询权限
      if (!hasQueryPermission(context.user.role, args.query)) {
        throw new Error('您没有执行此查询的权限');
      }
    }
  }
});

应用场景：在企业客服系统中，通过钩子实现自动工单创建和敏感操作审计，提升客服效率和系统安全性。

实战场景落地：构建智能客服代理系统

场景需求分析

某电商平台需要构建智能客服代理，具备以下能力：

情绪感知与个性化响应
产品知识库查询
订单状态跟踪
自动工单创建
敏感操作审计

完整实现方案

1. 处理器链配置

const supportAgent = new LlmAgent({
  name: 'ecommerce-support-agent',
  model: 'gemini-pro',
  instruction: `你是电商平台的智能客服助手，负责：
  1. 解答产品使用问题
  2. 查询订单状态
  3. 提供售后服务
  4. 在必要时创建支持工单`,
  requestProcessors: [
    BASIC_LLM_REQUEST_PROCESSOR,
    IDENTITY_LLM_REQUEST_PROCESSOR,
    new SupportSentimentProcessor(),      // 情绪分析处理器
    new KnowledgeBaseProcessor(),         // 知识库增强处理器
    INSTRUCTIONS_LLM_REQUEST_PROCESSOR,
    CONTENT_REQUEST_PROCESSOR
  ],
  tools: [
    new ProductKnowledgeTool(),
    new OrderTrackingTool(),
    new CustomerDbQueryTool()
  ],
  // 钩子配置...
});

2. 知识库增强处理器实现

class KnowledgeBaseProcessor extends BaseLlmRequestProcessor {
  private knowledgeBase: KnowledgeBaseService;
  
  constructor() {
    super();
    this.knowledgeBase = new KnowledgeBaseService();
  }
  
  async *runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest) {
    const userQuery = llmRequest.contents
      .filter(c => c.role === 'user')
      .slice(-1)[0]?.parts[0].text;
      
    if (userQuery) {
      // 检索相关知识库文档
      const docs = await this.knowledgeBase.search(userQuery, 3);
      
      if (docs.length > 0) {
        // 将知识库内容添加到LLM请求
        llmRequest.contents.unshift({
          role: 'system',
          parts: [{ 
            text: `以下是相关产品知识，用于回答用户问题：\n${docs.map(d => d.content).join('\n\n')}` 
          }]
        });
        
        yield createEvent({
          invocationId: invocationContext.invocationId,
          author: 'KnowledgeBaseProcessor',
          content: { parts: [{ text: `添加了${docs.length}条知识库参考内容` }] }
        });
      }
    }
    
    yield* this.nextProcessor?.runAsync(invocationContext, llmRequest) ?? [];
  }
}

应用场景：在产品支持场景中，通过知识库处理器自动为LLM提供产品信息，提高回答准确性和一致性。

进阶优化技巧：提升扩展机制性能与可靠性

处理器优先级与执行顺序优化

1. 处理器排序原则

基础配置优先：BASIC_LLM_REQUEST_PROCESSOR应始终作为第一个处理器
数据增强居中：如知识库、情绪分析等内容增强处理器放在中间
内容格式化最后： CONTENT_REQUEST_PROCESSOR等格式处理放在最后

2. 条件执行处理器

通过在处理器中添加条件判断，避免不必要的处理逻辑：

class ConditionalProcessor extends BaseLlmRequestProcessor {
  async *runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest) {
    // 仅处理特定类型的请求
    if (invocationContext.requestType === 'order_inquiry') {
      // 执行订单查询增强逻辑
      // ...
    }
    
    // 继续执行后续处理器
    yield* this.nextProcessor?.runAsync(invocationContext, llmRequest) ?? [];
  }
}

钩子执行顺序与调试

1. 钩子链配置与执行顺序

钩子可以配置为函数数组，按顺序执行：

const agent = new LlmAgent({
  beforeModelCallback: [
    logRequestHook,      // 第一个执行：日志记录
    validateRequestHook, // 第二个执行：请求验证
    enhanceRequestHook   // 第三个执行：请求增强
  ]
});

2. 钩子调试技巧

使用ADK.js提供的调试工具记录钩子执行过程：

function createDebugHook(name: string, hook: Function) {
  return async (...args: any[]) => {
    console.log(`[Hook Debug] ${name} - 开始执行`);
    const startTime = Date.now();
    
    try {
      const result = await hook(...args);
      console.log(`[Hook Debug] ${name} - 执行成功，耗时${Date.now() - startTime}ms`);
      return result;
    } catch (error) {
      console.error(`[Hook Debug] ${name} - 执行失败:`, error);
      throw error;
    }
  };
}

// 使用调试钩子
const agent = new LlmAgent({
  beforeModelCallback: createDebugHook('logRequest', logRequestHook)
});

性能优化策略

1. 处理器缓存机制

对频繁使用且计算密集的处理器结果进行缓存：

class CachedKnowledgeProcessor extends KnowledgeBaseProcessor {
  private cache = new Map<string, any>();
  private ttl = 5 * 60 * 1000; // 5分钟缓存
  
  async *runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest) {
    const userQuery = llmRequest.contents
      .filter(c => c.role === 'user')
      .slice(-1)[0]?.parts[0].text;
      
    if (userQuery) {
      const cacheKey = hash(userQuery);
      const cached = this.cache.get(cacheKey);
      
      if (cached && Date.now() - cached.timestamp < this.ttl) {
        // 使用缓存数据
        llmRequest.contents.unshift(cached.data);
        yield createEvent({
          invocationId: invocationContext.invocationId,
          author: 'CachedKnowledgeProcessor',
          content: { parts: [{ text: '使用缓存的知识库内容' }] }
        });
      } else {
        // 执行正常查询并缓存结果
        // ...原有逻辑...
        this.cache.set(cacheKey, {
          timestamp: Date.now(),
          data: knowledgeContent
        });
      }
    }
    
    yield* this.nextProcessor?.runAsync(invocationContext, llmRequest) ?? [];
  }
}

2. 异步处理器优化

对于包含异步操作的处理器，使用并行处理提高效率：

class ParallelDataProcessor extends BaseLlmRequestProcessor {
  async *runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest) {
    // 并行获取多个数据源
    const [productInfo, userHistory] = await Promise.all([
      this.getProductInfo(llmRequest),
      this.getUserHistory(invocationContext.userId)
    ]);
    
    // 合并结果并添加到请求
    // ...
    
    yield* this.nextProcessor?.runAsync(invocationContext, llmRequest) ?? [];
  }
}