简介
Assistant Agent 是一个基于 Spring AI Alibaba 构建的企业级智能助手框架，采用代码即行动（Code-as-Action）范式，通过生成和执行代码来编排工具、完成任务。它是一个能理解、能行动、能学习的智能助手解决方案，可帮助企业快速构建智能答疑客服、系统诊断、运维助手、业务助理、AIOps 等智能体。
仓库地址：spring-ai-alibaba/AssistantAgent
https://github.com/spring-ai-alibaba/AssistantAgent
技术特性
代码即行动（Code-as-Action）：Agent 通过生成并执行代码来完成任务，而非仅仅调用预定义工具，可以在代码中灵活编排、组合多个工具，实现复杂流程； 安全沙箱：AI 生成的代码在 GraalVM 多语言沙箱中安全运行，具备资源隔离能力； 多维评估：通过评估图（Graph）进行多层次意图识别，精准指导 Agent 行为； Prompt 动态组装：根据场景及前置评估结果动态注入上下文（经验、知识等）到 Prompt 中，灵活处理不同任务； 经验学习：自动积累成功经验，持续提升后续任务的表现； 快速响应：熟悉场景下，跳过 LLM 推理过程，基于经验快速响应；
Assistant Agent 能帮你做什么？
Assistant Agent 是一个功能完整的智能助手，具备以下核心能力：
智能问答：支持多数据源统一检索架构（通过 SPI 可扩展知识库、Web 等数据源），提供准确、可溯源的答案； 工具调用：支持 MCP、HTTP API（OpenAPI）等协议，灵活接入海量工具，可组合调用实现复杂业务流程； 主动服务：支持定时任务、延迟执行、事件回调，让助手主动为你服务； 多渠道触达：内置 IDE 回复，允许通过 SPI 可扩展钉钉、飞书、企微、Webhook 等渠道；
为什么选择 Assistant Agent？
适用场景
智能客服：接入企业知识库，智能解答用户咨询； 运维助手：对接监控、工单系统，自动处理告警、查询状态、执行操作； 业务助理：连接 CRM、ERP 等业务系统，辅助员工完成日常工作；
以上仅为典型场景示例。通过配置知识库和接入工具，Assistant Agent 可适配更多业务场景，欢迎探索。
整体工作原理
以下是 Assistant Agent 处理一个完整请求的端到端流程示例：
项目结构
assistant-agent/├── assistant-agent-common # 通用工具、枚举、常量├── assistant-agent-core # 核心引擎：GraalVM 执行器、工具注册表├── assistant-agent-extensions # 扩展模块：│ ├── dynamic/ # - 动态工具（MCP、HTTP API）│ ├── experience/ # - 经验管理与快速意图配置│ ├── learning/ # - 学习提取与存储│ ├── search/ # - 统一搜索能力│ ├── reply/ # - 多渠道回复│ ├── trigger/ # - 触发器机制│ └── evaluation/ # - 评估集成├── assistant-agent-prompt-builder # Prompt 动态组装├── assistant-agent-evaluation # 评估引擎├── assistant-agent-autoconfigure # Spring Boot 自动配置└── assistant-agent-start # 启动模块
快速启动
前置要求
Java 17+ Maven 3.8+ DashScope API Key
1. 克隆并构建
git clone https://github.com/spring-ai-alibaba/AssistantAgentcd assistant-agentmvn clean install -DskipTests
2. 配置 API Key
export DASHSCOPE_API_KEY=your-api-key-here
3. 最小配置
项目已内置默认配置，只需确保 API Key 正确即可。如需自定义，可编辑 assistant-agent-start/src/main/resources/application.yml：
spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-max4. 启动应用
cd assistant-agent-startmvn spring-boot:run
所有扩展模块默认开启并采用合理的配置，无需额外配置即可快速启动。
5. 配置知识库（接入业务知识）
💡 框架默认提供 Mock 知识库实现用于演示测试。生产环境需要接入真实知识源（如向量数据库、Elasticsearch、企业知识库 API 等），以便 Agent 能够检索并回答业务相关问题。
方式一：快速体验（使用内置 Mock 实现）
默认配置已启用知识库搜索，可直接体验：
spring: ai: alibaba: codeact: extension: search: enabled: true knowledge-search-enabled: true # 默认开启
方式二：接入真实知识库（推荐）
实现 SearchProvider SPI 接口，接入你的业务知识源：
package com.example.knowledge;import com.alibaba.assistant.agent.extension.search.spi.SearchProvider;import com.alibaba.assistant.agent.extension.search.model.*;import org.springframework.stereotype.Component;import java.util.*;@Component // 添加此注解，Provider 会自动注册publicclassMyKnowledgeSearchProviderimplementsSearchProvider {@Overridepublic boolean supports(SearchSourceType type){return SearchSourceType.KNOWLEDGE == type;}@Overridepublic List<SearchResultItem> search(SearchRequest request){List<SearchResultItem> results = new ArrayList<>();// 1. 从你的知识源查询（向量数据库、ES、API 等）// 示例：List<Doc> docs = vectorStore.similaritySearch(request.getQuery());// 2. 转换为 SearchResultItem// for (Doc doc : docs) {// SearchResultItem item = new SearchResultItem();// item.setId(doc.getId());// item.setSourceType(SearchSourceType.KNOWLEDGE);// item.setTitle(doc.getTitle());// item.setSnippet(doc.getSummary());// item.setContent(doc.getContent());// item.setScore(doc.getScore());// results.add(item);// }return results;}@Overridepublic String getName(){return"MyKnowledgeSearchProvider";}}
常见知识源接入示例
核心模块介绍
评估模块（Evaluation）
作用：多维度意图识别框架，通过评估图（Graph）对信息进行多层次特质识别。
┌──────────────────────────────────────────────────────────────────┐│ 评估图 (Evaluation Graph) 示例 │├──────────────────────────────────────────────────────────────────┤│ ││ 用户输入: "查询今日订单" ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Layer 1 （并行执行） │ ││ │ ┌────────────┐ ┌────────────┐ │ ││ │ │ 是否模糊? │ │ 输入改写 │ │ ││ │ │ 清晰/模糊 │ │（增强） │ │ ││ │ └─────┬──────┘ └─────┬──────┘ │ ││ └─────────┼──────────────────────┼────────────────────────┘ ││ │ │ ││ └──────────┬───────────┘ ││ ▼ ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Layer 2 (基于改写内容，并行执行) │ ││ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ││ │ │ 检索经验 │ │ 匹配工具 │ │ 搜索知识 │ │ ││ │ │ 有/无 │ │ 有/无 │ │ 有/无 │ │ ││ │ └──────────┘ └──────────┘ └──────────┘ │ ││ └─────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ 整合不同维度评估结果 │ ││ │ → 传递给后续模块 │ ││ └────────────────────┘ ││ │└──────────────────────────────────────────────────────────────────┘
核心能力：
双评估引擎：
LLM 评估：通过大模型进行复杂语义判断，用户可完全自定义评估 Prompt（ customPrompt），也可使用默认 Prompt 组装（支持description、workingMechanism、fewShots等配置）；Rule-based 评估：通过 Java 函数实现规则逻辑，用户自定义 Function<CriterionExecutionContext, CriterionResult>执行任意规则判断，适合阈值检测、格式校验、精确匹配等场景；
依赖关系自定义：评估项可通过 dependsOn声明前置依赖，系统自动构建评估图按拓扑执行，无依赖项并行、有依赖项顺序执行，后续评估项可访问前置评估项的结果；
评估结果：支持 BOOLEAN、ENUM、SCORE、JSON、TEXT等类型，传递给 Prompt Builder 驱动动态组装；
Prompt Builder 模块
作用：根据评估结果和运行时上下文，动态组装发送给模型的 Prompt。示例：
┌─────────────────────────────────────────────────────────────────────────┐│ Prompt Builder - 条件化动态生成 │├─────────────────────────────────────────────────────────────────────────┤│ ││ 评估结果输入: ││ ┌────────────────────────────────────────────────────────┐ ││ │ 模糊: 是 │ 经验: 有 │ 工具: 有 │ 知识: 无 │ ││ └────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────────────────────────────────────────────────────┐ ││ │ 自定义 PromptBuilder 条件匹配 │ ││ │ │ ││ │ 模糊=是 ──────▶ 注入 [澄清引导 Prompt] │ ││ │ 模糊=否 ──────▶ 注入 [直接执行 Prompt] │ ││ │ │ ││ │ 经验=有 ──────▶ 注入 [历史经验参考] │ ││ │ 工具=有 ──────▶ 注入 [工具使用说明] │ ││ │ 知识=有 ──────▶ 注入 [相关知识片段] │ ││ │ │ ││ │ 组合示例1: 模糊+无工具+无知识 ──▶ [追问用户 Prompt] │ ││ │ 组合示例2: 清晰+有工具+有经验 ──▶ [快速执行 Prompt] │ ││ └────────────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────────────────────────────────────────────────────┐ ││ │ 最终动态 Prompt: │ ││ │ [系统提示] + [澄清引导] + [历史经验] + [工具说明] + [用户问题] │ ││ └────────────────────────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌──────────┐ ││ │ 模型 │ ││ └──────────┘ ││ │└─────────────────────────────────────────────────────────────────────────┘
核心能力：
多个 PromptBuilder 按优先级顺序执行 每个 Builder 根据评估结果决定是否贡献、贡献什么内容 支持自定义 Builder，根据业务需求定制 Prompt 逻辑 非侵入式，在模型调用层拦截
对比传统方案：
学习模块（Learning）
作用：从 Agent 执行历史中自动提取并保存有价值的经验。
┌─────────────────────────────────────────────────────────────────────────┐│ 学习模块工作流程 │├─────────────────────────────────────────────────────────────────────────┤│ ││ ┌────────────────────────────────────────────────────────────────────┐ ││ │ Agent 执行过程 │ ││ │ │ ││ │ 输入 ──▶ 推理 ──▶ 代码生成 ──▶ 执行 ──▶ 输出 │ ││ │ │ │ │ │ │ │ ││ │ └────────┴──────────┴─────────┴────────┘ │ ││ │ │ │ ││ └────────────────────────┼───────────────────────────────────────────┘ ││ ▼ ││ ┌────────────────────────┐ ││ │ 学习上下文捕获 │ ││ │ - 用户输入 │ ││ │ - 中间推理步骤 │ ││ │ - 生成的代码 │ ││ │ - 执行结果 │ ││ └───────────┬────────────┘ ││ │ ││ ▼ ││ ┌──────────────────────────────────────────────────────────────┐ ││ │ 学习提取器分析 │ ││ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ ││ │ │ 经验提取器 │ │ 模式提取器 │ │ 错误提取器 │ │ ││ │ │ 成功模式 │ │ 通用模式 │ │ 失败教训 │ │ ││ │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ ││ └────────┼───────────────┼───────────────┼─────────────────────┘ ││ │ │ │ ││ └───────────────┼───────────────┘ ││ ▼ ││ ┌────────────────┐ ││ │ 持久化存储 │ ──▶ 供后续任务参考使用 ││ └────────────────┘ ││ │└────────────────────────────────────────────────────────────────────────┘
核心能力：
After-Agent 学习：每次 Agent 运行完成后提取经验； After-Model 学习：每次模型调用后提取经验； Tool Interceptor：从工具调用中提取经验； 离线学习：批量分析历史数据提取模式； 学习过程：捕获执行上下文 → 提取器分析识别 → 生成经验记录 → 持久化存储供后续复用；
经验模块（Experience）
作用：积累和复用历史成功执行经验。
┌─────────────────────────────────────────────────────────────────────────┐│ 经验模块工作示意 │├─────────────────────────────────────────────────────────────────────────┤│ ││ 【场景1: 经验积累】 ││ ││ 用户: "查询订单状态" ──▶ Agent 成功执行 ──▶ ┌────────────────┐ ││ │ 保存经验: │ ││ │ - React决策经验 │ ││ │ - Code经验 │ ││ │ - 常识经验 │ ││ └────────────────┘ ││ │ ││ ▼ ││ ┌────────────────┐ ││ │ 经验库 │ ││ └────────────────┘ ││ ││ 【场景2: 经验复用】 ｜ ││ │ ││ 用户: "查询我的订单状态" ◀──── 匹配相似经验 ◀────────────┘ ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────┐ ││ │ Agent 参考历史经验，更快决策+生成正确代码 │ ││ └─────────────────────────────────────────────────┘ ││ ││ 【场景3: 快速意图响应】 ││ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ 经验库 │ ││ │ ┌─────────────────────┐ ┌────────────────────────────┐ │ ││ │ │ 经验A (普通) │ │ 经验B (✓ 已配置快速意图) │ │ ││ │ │ 无快速意图配置 │ │ 条件: 前缀匹配"查看*销量" │ │ ││ │ │ → 注入prompt供llm参考│ │ 动作: 调用销量查询API │ │ ││ │ └─────────────────────┘ └───────────┬────────────────┘ │ ││ └─────────────────────────────────────────────┼───────────────────┘ ││ │ 条件命中 ││ ▼ ││ 用户: "查看今日销量" ──▶ 匹配经验B快速意图 ──▶ 跳过LLM，直接执行 ││ ││ │└─────────────────────────────────────────────────────────────────────────┘
核心能力：
多类型经验：代码生成经验、ReAct 决策经验、常识经验，为类似任务提供历史参考；
灵活复用：经验可注入 Prompt 或用于快速意图匹配；
生命周期管理：支持经验的创建、更新、删除；
快速意图响应：
经验需显式配置 fastIntentConfig才能启用；匹配已配置条件时，跳过 LLM 完整推理，直接执行预记录的工具调用或代码； 支持多条件匹配：消息前缀、正则、元数据、状态等；
触发器模块（Trigger）
作用：创建和管理定时任务或事件触发的 Agent 执行。
┌─────────────────────────────────────────────────────────────────────────┐│ 触发器模块能力示意 │├─────────────────────────────────────────────────────────────────────────┤│ ││ 【定时触发】 ││ ││ 用户: "每天早上9点给我发送销售日报" ││ │ ││ ▼ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ Agent 创建 │ │ 调度器 │ │ 自动执行 │ ││ │ Cron 触发器 │────▶│ 09 * * * │────▶│ 生成日报 │ ││ │ (自我调度) │ │ │ │ 发送通知 │ ││ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││ ││ 【延迟触发】 ││ ││ 用户: "30分钟后提醒我开会" ││ │ ││ ▼ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ Agent 创建 │ │ 30分钟后 │ │ 发送提醒 │ ││ │ 一次性触发器 │────▶│ 触发 │────▶│ "该开会了" │ ││ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││ ││ 【回调触发】 ││ ││ 用户: "满足xx条件时帮我xx" ││ ││ 外部系统: 发送事件到 Webhook ││ │ ││ ▼ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ 接收回调 │ │ 触发 Agent │ │ 处理事件 │ ││ │ Webhook 事件 │────▶│ 执行任务 │────▶│ 返回响应 │ ││ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────────┘
核心能力：
TIME_CRON触发器：支持 Cron 表达式定时触发任务；TIME_ONCE触发器：支持一次性延迟触发；CALLBACK触发器：支持回调事件触发；Agent 可通过工具自主创建触发器，实现"自我调度"；
回复渠道模块（Reply Channel）
作用：提供灵活的消息回复能力，支持多种输出渠道。
┌─────────────────────────────────────────────────────────────────────────┐│ 回复渠道模块能力示意 │├─────────────────────────────────────────────────────────────────────────┤│ ││ Agent 需要向用户回复消息 ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ 回复渠道路由 │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │ ││ ├──────────────┬──────────────┬──────────────┐ ││ ▼ ▼ ▼ ▼ ││ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ││ │ DEFAULT │ │ IDE_CARD │ │ IM_NOTIFY │ │ WEBHOOK │ ││ │ 文本回复 │ │ 卡片展示 │ │ 消息推送 │ │ JSON推送 │ ││ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ ││ │ │ │ │ ││ ▼ ▼ ▼ ▼ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ 控制台 │ │ IDE │ │ IM │ │ 第三方 │ ││ │ 终端回复 │ │ 富文本卡片 │ │ (可扩展) │ │ 系统 │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││ ││ 【使用示例】 ││ ││ 用户: "分析完成后发送结果" ││ │ ││ ▼ ││ Agent: send_message(text="分析结果...") ││ │ ││ ▼ ││ 用户收到消息: "📊 分析结果: ..." ││ │└─────────────────────────────────────────────────────────────────────────┘
核心能力：
多渠道路由：Agent 可根据场景选择不同渠道回复； 配置驱动：动态生成回复工具，无需编码； 同步异步支持：支持同步和异步回复模式； 统一接口：屏蔽底层实现差异； 内置示例渠道： IDE_TEXT（演示用）；可扩展渠道（通过实现 ReplyChannelDefinitionSPI）：如IDE_CARD、IM_NOTIFICATION（钉钉/飞书/企微）、 WEBHOOK_JSON等，需用户自行实现
工具扩展模块（Dynamic Tools）
作用：提供高度可扩展的工具体系，让 Agent 能够调用各类外部工具完成任务。
┌─────────────────────────────────────────────────────────────────────────┐│ 工具扩展架构 │├─────────────────────────────────────────────────────────────────────────┤│ ││ Agent 需要执行操作 ││ │ ││ ▼ ││ ┌──────────────────────────────────────────────────────────────────┐ ││ │ CodeactTool 工具体系 │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │ ││ ├─────────────┬─────────────┬─────────────┬──────────────┐ ││ ▼ ▼ ▼ ▼ ▼ ││ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌───────┐ ││ │ MCP │ │ HTTP │ │ Search │ │ Trigger │ │ 自定义 │ ││ │ Tools │ │ API │ │ Tools │ │ Tools │ │ Tools │ ││ │ │ │ Tools │ │ │ │ │ │ │ ││ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └───┬───┘ ││ │ │ │ │ │ ││ ▼ ▼ ▼ ▼ ▼ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ ││ │ 任意 MCP │ │ REST API │ │ 知识检索 │ │ 定时任务 │ │ ... │ ││ │ Server │ │ OpenAPI │ │ 项目搜索 │ │ 事件回调 │ │ │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────┘ ││ │└─────────────────────────────────────────────────────────────────────────┘
核心能力：
MCP 工具支持：一键接入任意 MCP Server，复用 MCP 工具生态； HTTP API 支持：通过 OpenAPI 规范接入 REST API，调用企业现有接口； 内置工具类型：搜索（Search）、回复（Reply）、触发器（Trigger）、学习（Learning）等； 自定义工具 SPI：实现 CodeactTool接口，轻松扩展新工具；
知识检索模块（Knowledge Search）
作用：多数据源统一检索引擎，为 Agent 的问答和决策提供知识支撑。
┌─────────────────────────────────────────────────────────────────────────┐│ 多数据源检索架构 │├─────────────────────────────────────────────────────────────────────────┤│ ││ 用户问题: "如何配置数据库连接池？" ││ │ ││ ▼ ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ 统一检索接口 │ ││ └─────────────────────────────────────────────────────────────────┘ ││ │ ││ ├────────────────┬────────────────┬────────────────┐ ││ ▼ ▼ ▼ ▼ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────┐ ││ │ 知识库 │ │ 项目 │ │ Web │ │ 自定义 │ ││ │ Provider │ │ Provider │ │ Provider │ │Provider │ ││ │ (主要) │ │ (可选) │ │ (可选) │ │ (SPI) │ ││ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └───┬─────┘ ││ │ │ │ │ ││ ▼ ▼ ▼ ▼ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────┐ ││ │ FAQ / 文档 │ │ 源代码 │ │ 网络文章 │ │ ... │ ││ │ 历史问答 │ │ 配置文件 │ │ 技术论坛 │ │ │ ││ │ 团队笔记 │ │ 日志 │ │ │ │ │ ││ └──────────────┘ └─────────────┘ └───────────────┘ └────────┘ ││ │ │ │ │ ││ └─────────────────┴─────────────────┴──────────────┘ ││ │ ││ ▼ ││ ┌────────────────────────┐ ││ │ 聚合排序 │ ││ │ → 注入 Prompt │ ││ └────────────────────────┘ ││ │└────────────────────────────────────────────────────────────────────────┘
核心能力：
统一检索接口： SearchProviderSPI，支持可插拔数据源；演示 Provider：内置知识库、项目、Web 的 Mock 实现（仅供演示和测试）； 自定义扩展：通过实现 SearchProvider接口，接入任意数据源（数据库、向量库、API）；结果聚合：支持可配置的排序策略； 业务价值：接入企业知识库提供准确答案、支持答案溯源、降低人工客服压力；
配置示例：
spring: ai: alibaba: codeact: extension: search: enabled: true knowledge-search-enabled: true # 知识库（默认 Mock 实现） project-search-enabled: false # 项目代码（默认 Mock 实现） web-search-enabled: false # Web 搜索（默认 Mock 实现） default-top-k: 5 search-timeout-ms: 5000
💡 以上搜索功能默认提供 Mock 实现供演示测试。生产环境需实现 SearchProvider SPI 接入实际数据源。
