33 - Agent矩阵与领域设计模式

100+ Agent 分6大领域、零配置注册、AgentCapability驱动UI、Pipeline流水线

一、Agent 接口设计

Agent接口是整个框架的核心契约，所有Agent必须实现此接口：

public interface Agent {

    /** 唯一标识 (如 "photo-agent", "code-review-agent") */
    String getId();

    /** 显示名称 (如 "智能修图助手") */
    String getName();

    /** 功能描述 */
    String getDescription();

    /** 能力集合 - 驱动前端UI动态渲染 */
    Set<AgentCapability> getCapabilities();

    /** 核心方法 - 处理用户消息并返回流式响应 */
    Flux<ChatResponse> chat(ChatRequest request);

    /** 超时时间 (默认120秒) */
    default Duration getTimeout() { return Duration.ofSeconds(120); }

    /** 最大重试次数 (默认3次) */
    default int getMaxRetries() { return 3; }

    /** 优���级 (数值越小优先级越高，用于路由决策) */
    default int getPriority() { return 100; }

    /** 最大并发数 (0=不限) */
    default int getMaxConcurrency() { return 0; }

    /** Agent所属领域 */
    default AgentDomain getDomain() { return AgentDomain.GENERAL; }
}

二、AgentRegistry 零配置注册

零配置注册原理 (Spring DI自动发现):

  Spring容器启动
  │
  ├── 扫描所有 @Component 类
  │   ├── PhotoAgent         implements Agent ✓
  │   ├── CodeReviewAgent    implements Agent ✓
  │   ├── TranslationAgent   implements Agent ✓
  │   ├── ... (100+ Agent)
  │   └── NetDiskAgent       implements Agent ✓
  │
  ▼
  ┌─────────────────────────────────────────────────────────┐
  │ @Component                                              │
  │ public class AgentRegistry {                            │
  │                                                         │
  │   private final Map<String, Agent> agentMap;            │
  │                                                         │
  │   // Spring自动注入所有Agent实现到List中                │
  │   public AgentRegistry(List<Agent> agents) {            │
  │     this.agentMap = agents.stream()                     │
  │       .collect(Collectors.toMap(Agent::getId, a -> a)); │
  │   }                                                     │
  │                                                         │
  │   public Agent getAgent(String id) { ... }              │
  │   public List<Agent> listAll() { ... }                  │
  │   public List<Agent> listByDomain(AgentDomain d) { }   │
  │   public List<Agent> listByCapability(AgentCapability c)│
  │ }                                                       │
  └─────────────────────────────────────────────────────────┘

  新增Agent的全部工作:
  ┌──────────────────────────────────────────┐
  │ 1. 创建Java类                           │
  │ 2. 加 @Component 注解                   │
  │ 3. 实现 Agent 接口                      │
  │ 4. 完毕! (无需任何配置文件)             │
  │                                          │
  │ ✅ 自动出现在API列表                    │
  │ ✅ 自动出现在前端选择器                 │
  │ ✅ 自动获得限流/熔断/重试保护           │
  │ ✅ 自动获得SSE流式通信                  │
  │ ✅ 自动获得对话历史管理                 │
  │ ✅ 自动获得Prompt安全校验               │
  └──────────────────────────────────────────┘

三、AgentCapability 枚举 (23个能力)

每个Agent声明自己支持的能力，前端根据能力集动态渲染UI组件：

#	Capability	含义	前端UI效果
1	TEXT_CHAT	文本对话	基础聊天输入框
2	IMAGE_UPLOAD	图片上传	显示图片上传按钮
3	FILE_UPLOAD	文件上传	显示文件拖拽区
4	VOICE_INPUT	语音输入	显示录音按钮
5	VOICE_OUTPUT	语音输出	显示播放按钮
6	MODEL_SELECTION	模型选择	模型下拉选择器
7	PLAN_MODE	规划模式	Plan/Act切换开关
8	WEB_SEARCH	联网搜索	搜索开关
9	CODE_EXECUTION	代码执行	代码编辑器+运行按钮
10	MARKDOWN_RENDER	Markdown渲染	富文本渲染区
11	STREAMING	流式输出	逐字显示效果
12	MULTI_TURN	多轮对话	对话历史保持
13	SYSTEM_PROMPT	自定义系统提示	系统提示编辑框
14	TEMPERATURE_CONTROL	温度调节	温度滑动条
15	CONTEXT_WINDOW	上下文窗口设置	窗口大小选择器
16	TOOL_CALLING	工具调用	工具状态指示器
17	RAG_RETRIEVAL	RAG检索	知识库选择器
18	IMAGE_GENERATION	图片生成	图片预览区
19	BATCH_PROCESSING	批量处理	批量输入表单
20	EXPORT	导出功能	导出格式按钮组
21	COLLABORATION	协作模式	协作者面板
22	SCHEDULE	定时任务	Cron表达式配置
23	WEBHOOK	Webhook回调	Webhook URL配置

能力驱动UI的工作原理:

  后端返回:
  {
    "agentId": "photo-agent",
    "capabilities": ["IMAGE_UPLOAD", "MODEL_SELECTION", "STREAMING"]
  }

  前端动态渲染:
  ┌───────────────────────────────────────┐
  │ ChatPanel                             │
  │ ┌─────────────────────────────────┐   │
  │ │ [图片上传区] ← IMAGE_UPLOAD     │   │
  │ └─────────────────────────────────┘   │
  │ ┌─────────────────────────────────┐   │
  │ │ 模型: [GPT-4V ▼] ← MODEL_SEL  │   │
  │ └─────────────────────────────────┘   │
  │ ┌─────────────────────────────────┐   │
  │ │ 输入框... [发送]                │   │
  │ │ 流式输出中... ← STREAMING       │   │
  │ └─────────────────────────────────┘   │
  └───────────────────────────────────────┘

四、6大领域分类

领域	Domain枚举	Agent数量	代表Agent
创意内容	CREATIVE	18+	PhotoAgent、VideoScriptAgent、CopywritingAgent、LogoDesignAgent
企业办公	ENTERPRISE	22+	ContractReviewAgent、MeetingSummaryAgent、OKRAgent、HRAssistant
教育培训	EDUCATION	15+	TutorAgent、QuizGeneratorAgent、PaperReviewAgent、LanguageCoach
生活服务	LIFESTYLE	12+	TravelPlannerAgent、RecipeAgent、HealthAdvisor、FitnessCoach
效率工具	PRODUCTIVITY	20+	CodeReviewAgent、TranslationAgent、DataAnalysisAgent、EmailDraft
专业领域	SPECIALIZED	15+	LegalConsultAgent、FinanceAnalystAgent、MedicalQAAgent

Agent矩阵概览:

  ┌────────────────── 6大领域 × 100+ Agent ──────────────────┐
  │                                                           │
  │  CREATIVE (创意)        ENTERPRISE (企业)                 │
  │  ├── PhotoAgent         ├── ContractReviewAgent           │
  │  ├── VideoScriptAgent   ├── MeetingSummaryAgent           │
  │  ├── CopywritingAgent   ├── OKRAgent                     │
  │  ├── MusicComposeAgent  ├── DataReportAgent              │
  │  └── ...18个            └── ...22个                      │
  │                                                           │
  │  EDUCATION (教育)       LIFESTYLE (生活)                  │
  │  ├── TutorAgent         ├── TravelPlannerAgent           │
  │  ├── QuizGenerator      ├── RecipeAgent                  │
  │  ├── PaperReview        ├── HealthAdvisor                │
  │  └── ...15个            └── ...12个                      │
  │                                                           │
  │  PRODUCTIVITY (效率)    SPECIALIZED (专业)                │
  │  ├── CodeReviewAgent    ├── LegalConsultAgent            │
  │  ├── TranslationAgent   ├── FinanceAnalystAgent          │
  │  ├── DataAnalysis       ├── MedicalQAAgent               │
  │  └── ...20个            └── ...15个                      │
  │                                                           │
  └───────────────────────────────────────────────────────────┘

五、特色Agent介绍

PhotoAgent (智能修图)

PhotoAgent 工作流:

  用户上传图片 + 指令("去除背景", "美化人像", "风格迁移")
  │
  ├── 1. 图片分析 (Vision Model识别内容)
  ├── 2. 指令解析 (NLU理解用户意图)
  ├── 3. 工具选择 (背景移除/美颜/滤镜/裁剪)
  ├── 4. 图片处理 (调用对应图像处理API)
  └── 5. 结果返回 (处理后图片 + 操作说明)

  能力集: [IMAGE_UPLOAD, MODEL_SELECTION, STREAMING, EXPORT]

NetDiskAgent (智能网盘助手)

NetDiskAgent 工作流:

  用户指令("帮我整理下载文件夹", "找到上周的合同文档")
  │
  ├── 1. 意图识别 (搜索/整理/分类/清理)
  ├── 2. 文件扫描 (遍历目标目录)
  ├── 3. 智能分类 (按类型/日期/项目自动归类)
  ├── 4. 执行操作 (移动/重命名/压缩/删除)
  └── 5. 生成报告 (操作摘要 + 目录树变化)

  能力集: [FILE_UPLOAD, BATCH_PROCESSING, EXPORT, TOOL_CALLING]

WechatAgent (微信运营助手)

WechatAgent 工作流:

  运营需求("写一篇关于AI的公众号文章", "生成朋友圈文案")
  │
  ├── 1. 平台适配 (公众号/朋友圈/视频号/小程序)
  ├── 2. 内容生成 (标题/正文/摘要/配图建议)
  ├── 3. SEO优化 (关键词/标签/发布时间建议)
  ├── 4. 排版美化 (Markdown → 微信富文本)
  └── 5. 数据预测 (预估阅读量/互动率)

  能力集: [TEXT_CHAT, IMAGE_GENERATION, MARKDOWN_RENDER, EXPORT]

六、Pipeline 流水线

复杂任务通过Pipeline将多个Agent串联为流水线，支持PROCESSOR(处理)和REVIEWER(审核)两种角色：

Pipeline流水线模式:

  ┌─────────────────────────────────────────────────────────────┐
  │  PipelineDefinition                                         │
  │                                                             │
  │  Stage 1 (PROCESSOR)    Stage 2 (PROCESSOR)                │
  │  ┌──────────────────┐   ┌──────────────────┐              │
  │  │ ResearchAgent    │──→│ WritingAgent     │──┐           │
  │  │ 搜集资料/调研   │   │ 撰写初稿         │  │           │
  │  └──────────────────┘   └──────────────────┘  │           │
  │                                                │           │
  │  Stage 3 (REVIEWER)     Stage 4 (PROCESSOR)   │           │
  │  ┌──────────────────┐   ┌──────────────────┐  │           │
  │  │ ReviewAgent      │←──│ 审核通过?        │←─┘           │
  │  │ 质量审核/打分   │   │ YES → 下一步     │              │
  │  │                  │──→│ NO  → 返回修改   │              │
  │  └──────────────────┘   └──────────────────┘              │
  │                                                │           │
  │  Stage 5 (PROCESSOR)                           │           │
  │  ┌──────────────────┐                          │           │
  │  │ PublishAgent     │←─────────────────────────┘           │
  │  │ 格式化/发布     │                                      │
  │  └──────────────────┘                                      │
  └─────────────────────────────────────────────────────────────┘

public class PipelineDefinition {

    private final List<PipelineStage> stages;

    @Data
    public static class PipelineStage {
        private String agentId;           // 执行的Agent
        private StageRole role;           // PROCESSOR / REVIEWER
        private Map<String, Object> config; // 阶段配置
        private String onRejectGoTo;      // 审核不通过跳转到哪个Stage
        private int maxIterations;        // 最大循环次数(防无限loop)
    }

    public enum StageRole {
        PROCESSOR,  // 处理者：执行具体任务
        REVIEWER    // 审核者：评估上一步输出质量
    }
}

// Pipeline执行引擎
@Service
public class PipelineExecutor {

    public Flux<PipelineEvent> execute(PipelineDefinition pipeline, String input) {
        return Flux.create(sink -> {
            PipelineContext ctx = new PipelineContext(input);

            for (PipelineStage stage : pipeline.getStages()) {
                Agent agent = agentRegistry.getAgent(stage.getAgentId());

                if (stage.getRole() == REVIEWER) {
                    ReviewResult result = executeReview(agent, ctx);
                    if (!result.approved()) {
                        // 跳转回指定Stage重新处理
                        ctx.jumpTo(stage.getOnRejectGoTo());
                        sink.next(PipelineEvent.rejected(stage, result.feedback()));
                        continue;
                    }
                }

                String output = executeProcessor(agent, ctx);
                ctx.addStageOutput(stage.getAgentId(), output);
                sink.next(PipelineEvent.completed(stage, output));
            }
            sink.complete();
        });
    }
}

七、AgentSpec 声明式配置

对于简单Agent，无需编写Java代码，通过YAML声明式配置即可创建：

# agents/translation-agent.yml
agent:
  id: "translation-agent"
  name: "多语言翻译助手"
  domain: PRODUCTIVITY
  description: "支持100+语言的智能翻译，保持原文风格和语境"

  capabilities:
    - TEXT_CHAT
    - MODEL_SELECTION
    - STREAMING
    - EXPORT

  spec:
    model: "gpt-4o"
    temperature: 0.3
    maxTokens: 4096
    systemPrompt: |
      你是一位专业的多语言翻译专家。
      规则：
      1. 准确传达原文含义，保持语境和风格
      2. 专业术语使用目标语言的通用翻译
      3. 如有歧义，提供多种翻译选项
      4. 保留原文格式（列表、段落等）

  runtime:
    timeout: 60s
    maxRetries: 2
    priority: 50
    maxConcurrency: 20

  tools:
    - web-search      # 查询术语翻译
    - dictionary      # 词典查询

AgentSpec 加载流程:

  应用启动
  │
  ├── AgentSpecLoader 扫描 agents/*.yml
  │   ├── translation-agent.yml
  │   ├── recipe-agent.yml
  │   └── ...
  │
  ├── 解析YAML → AgentSpec对象
  │
  ├── AgentSpecFactory.create(spec)
  │   └── 生成 SpecBasedAgent 实例
  │       (实现Agent接口,从spec读取配置)
  │
  └── AgentRegistry.register(specAgent)
      └── 与Java编写的Agent完全等价!

  优势:
  ┌──────────────────────────────────────────────┐
  │ · 非开发人员也能创建Agent (只写YAML)        │
  │ · 热更新: 修改YAML后无需重启               │
  │ · 版本管理: YAML文件纳入Git                │
  │ · 批量管理: 100+个简单Agent用YAML维护     │
  │ · 复杂Agent: 仍用Java实现，两种方式共存   │
  └──────────────────────────────────────────────┘

八、面试话术

面试话术："我们设计了一个可扩展的Agent框架，核心是Agent接口定义了getId、getName、getCapabilities、chat等方法。新增Agent只需实现接口加@Component注解，利用Spring DI自动发现注入到AgentRegistry中——真正的零配置注册。目前已有100多个Agent分布在6大领域：创意、企业、教育、生活、效率、专业。每个Agent声明自己支持的Capability枚举，前端根据能力集动态渲染UI组件，比如Agent声明了IMAGE_UPLOAD能力，前端就自动显示图片上传区。"

面试话术："对于复杂任务场景，我们设计了Pipeline流水线模式。多个Agent可以串联为处理链，支持PROCESSOR和REVIEWER两种角色。REVIEWER Agent负责质量把关，审核不通过可以驳回到之前的Stage重做，同时有maxIterations限制防止无限循环。此外，简单Agent支持YAML声明式配置，运营人员不写代码也能创建新Agent，修改后热加载不需要重启应用。Java编写的复杂Agent和YAML声明的简单Agent在Registry中完全等价。"