TAgent

🚀 面向生产实践的 AI Agent 工程框架

英文版 | 中文版

不只是简单的模型封装，而是覆盖 Agent 请求的完整生命周期：接入、路由、运行时装配、规划执行、RAG、记忆、MCP 工具治理、人工审批、交互通知、执行中干预，到 SSE 流式输出和全链路观测。

📖 项目简介

TAgent 是一个基于 Java 17、Spring Boot、Spring AI 和 DDD 分层架构 构建的企业级 AI Agent 工程实践项目。

它覆盖了一次 Agent 请求从接入、路由、运行时装配、规划执行、RAG、记忆、MCP 工具治理、人工审批、交互通知、执行中干预，到 SSE 流式输出和全链路观测的完整过程。

本仓库是脱敏后的公开版本，不包含真实密钥、运行日志、历史对话、临时报告、数据库备份和个人文件。

🌐 在线体验：https://tagentapp.cn

注册后既可以体验预配置的各类 Agent，也可以进入“我的 Agent”自行搭建 Fixed、Auto、Flow 三种模式的 Agent，按节点配置 System Prompt、MCP 连接和 Advisor，并关联自己的 RAG 知识库。个人 Agent 配置、知识检索和使用观测按用户隔离。

目前处于试用阶段，平台提供的模型主要为 mimo-v2.6-flash 和 deepseek-v4-flash，受平台试用额度限制。v2.0.0 已支持个人 OpenAI 兼容模型连接：配置自己的接口、模型和 API Key，密钥加密保存。路由、记忆摘要、向量检索等平台辅助服务需要单独授权，不会借用个人主模型密钥。个人模型与 MCP 连接均受部署方允许域名限制。Agent 工作区 · 模型连接与加密配置，项目提供了图片理解能力，但是这与模型的能力有关，如果想要体验图片理解功能可以使用测试Agent运行，其搭配的是mimo-v2.6-flash具有图片理解能力。

🧰 个人工作区与运行结果

• 自己的 Agent 与模型：从公共 Agent 开始，按模式配置节点；草稿、启用版本和运行绑定分开，支持版本比较、恢复到草稿及节点调试。个人模型密钥按用户隔离并加密保存。
• 可维护的知识库：上传后可查看入库阶段、失败原因、片段预览，支持重试、取消、删除和检索测试；只有发布成功的知识才参与正常检索。
• 可追溯的执行：运行历史持久保存问题、结果、配置版本、状态和有限诊断；刷新恢复步骤依赖与工具卡片，离开任务页面也能收到完成/失败通知，收件箱支持全部已读。
• 真正可下载的产物：内置 create_artifact 生成 Markdown、表格 CSV 和单个代码文件，支持预览、下载、不可变修订及指定版本复用；代码仅保存，不执行。
• 反馈进入评测：将本人反馈主动转为 EvalOps 草稿，审核启用后用规则评分、LLM Judge 和逐例对比验证改进；不会自动把模型原答案当成标准答案。
• 运行与用量治理：运行预算、上下文压缩、工具结果按需回读、MCP 连接容量/空闲回收，以及按用户保存的平台额度与请求用量。金额未接入真实定价时显示未知，不作为实际账单。

工作台通过统一导航连接模型、Agent、知识库、历史、产物与反馈、用量和 MCP 观测。查看升级与功能指南。

适合谁

• 想系统学习 Java / Spring AI Agent 工程化落地的开发者。
• 正在研究 MCP 工具治理、动态工具补挂、Agentic RAG、多层记忆的同学。
• 需要参考 流式 SSE、人工审批、执行中干预、主动追问 ask_user、可观测性完整链路的团队。

🎯 系统总览

查看高清图 · 可编辑 SVG

🎬 功能演示

2026 年 10 月重新录制并从 Codex / Muse 两批择优，加入最新补录，共 34 段：32 段功能演示 + 2 段工程实测。覆盖个人 Agent、版本、追问与干预、知识库、附件、产物、沙箱、个人模型、运行轨迹与评测改进。视频已上传 GitHub Release，替代早期录屏作为当前演示入口。

推荐先看： 创建个人 Agent · 版本比较与恢复 · 主动追问 · 运行中引导 · 产物修订 · Python 图表与下载

完整演示目录、时长与范围说明 · Release 视频与字幕下载。全部为真实 UI 字幕录屏；24/25 是工程实测，运行完成不等于答案全部正确。19 仅展示服务器本地文件监视，20 仅展示只读搜索审批。

主链路

用户请求
  -> 过滤器 / SSE 控制器
  -> 统一 Agent 路由
  -> Fixed / Auto / Flow 三种策略
  -> Advisor 顾问链 + LLM
  -> MCP 工具执行
  -> SSE 流式响应

主链之外的关键控制链

• 动态工具补充：路由可预推断缺失能力，也可由执行期 request_tool 主动描述能力缺口 → PgVector 匹配真实 MCP 工具 → 与 Agent 常驻工具合并
• Flow 计划确认：仅 Flow 策略在生成并解析计划后可暂停，用户确认或编辑计划后再进入 DAG 执行
• 运行编号快照重做：Fixed、Auto、Flow 每次运行都会生成运行编号；前端可通过 /run 查看近期快照，并用 /runId-stepN 从指定步骤修正重跑
• 断线续作与重连：浏览器连接只是 run 的订阅者；刷新、网络抖动或切换会话不取消后端执行，重连后恢复完整 Timeline 并继续接收实时事件
• 后台任务中心：独立命令路由识别定时、Cron 和文件变化稳定监视任务，确认后由调度器在目标会话触发普通 Agent run
• 执行中干预：用户可发送 steer 重做当前步骤、answer_now 跳过剩余步骤、cancel 中止执行
• 主动追问：模型缺少关键信息时可调用 ask_user，通过 SSE 向用户收集补充信息，再回填继续执行
• 交互通知收件箱：统一保存主动追问、工具审批、计划确认和后台任务结果；当前会话内隐藏待交互铃铛提醒，切走后仍待处理时自动显示
• 按需证据地图：用户可从最终回答主动生成 Evidence Map，把成块结论关联到本次 Run 的 RAG、工具、记忆与用户输入来源，并可查看全部运行来源

✨ 项目亮点

🔄 端到端请求流程

1. 接入与 SSE 建连

请求进入 POST /api/v1/agent/auto_agent 后依次经过：

1. MdcTraceFilter：写入 request、trace、user、tenant、session 等上下文
2. RateLimitFilter：按用户、会话或 IP 进行限流
3. IdempotencyFilter：同步请求支持幂等，SSE 长连接端点直接放行
4. AiAgentController：创建 ResponseBodyEmitter、注册审批通道并立即发送 ack
5. Controller 组装 ExecuteCommandEntity，交给 Dispatch 异步执行

ack 会携带干预能力是否开启，前端据此决定是否显示执行中的操作栏。

2. 统一路由与懒装配

AgentDispatchService 负责：

• 用户未指定 Agent 时，调用 UnifiedAgentRouter 选择最合适的 agent_id
• 用户已经指定 Agent 时，跳过 Agent 选择，直接使用该 Agent 的策略和装配配置；可按 agent.dynamic-tools.infer-on-selected-agent 决定是否继续推断缺失工具能力
• 路由结果可携带 missing_tool_descs，由 agent.dynamic-tools 配置决定是否在本次请求中预补工具
• 执行阶段如果模型发现当前工具不足，可在 agent.request-tool.enabled=true 时调用 request_tool 动态装载真实 MCP 工具
• 首次使用 Agent 时通过 Armory 懒加载 ChatClient、Model、Advisor 和 MCP callback
• 从数据库读取 Agent 的 strategy，分派到 Fixed、Auto 或 Flow

🏃 三种执行模式

Fixed 模式

按配置的 Client 链顺序执行；单节点时适合直接问答或工具任务：

准备上下文 -> 注入 Advisor -> 合并工具 -> LLM 流式生成 -> 保存记忆 -> 输出

也支持 MCP 工具调用、RAG、长期记忆、steer 重做、answer_now 提前结束。

Auto 模式

适合目标明确但需要自主分析、执行和检查的任务：

Auto 会循环执行，直到任务完成或达到 maxStep。Step3 判断失败时，可携带结构化 critique 返回 Step2 修正。

Flow 模式

适合可拆解、存在依赖关系的复杂任务：

分析/规划可读取执行节点所绑定 MCP 的工具名称和说明，无需先连接或装载全部工具；实际调用与 request_tool 留到执行阶段。ask_user 按阶段规则开放，Auto 最终总结与 Flow 最终合成可以使用内置 create_artifact，不因此开放业务 MCP。

DAG 中依赖已经满足的步骤可以并行，不同 MCP Server 的工具可以并行，同一个 MCP Server 复用同一连接时保持串行。

Flow 还可以开启计划确认：Step2 生成计划、Step3 解析为 DAG 后先暂停，把计划以工具卡片形式展示给用户；用户可以直接确认，也可以编辑步骤标题、内容和依赖关系后再继续执行。这个能力只属于 Flow 策略，不影响 Fixed 和 Auto 的默认直跑流程。

🔁 运行编号快照与步骤级重做

每次 Agent 运行都会生成一个运行编号，用来串联本次请求的 SSE、对话记忆、事件日志和 Redis 运行快照。

• 快照范围：Fixed 记录单次回答快照；Auto 记录 Step1-Step4；Flow 记录计划阶段和 Step4 中的 DAG 执行步骤。
• 存储方式：运行快照保存在 Redis，并设置 TTL；过期后需要重新发起任务，而不是沿用旧计划或旧工具结果。
• 前端入口：输入 /run 展示当前会话近期运行，只展开运行摘要；选择某个运行编号后再展示可重做步骤。
• 定点重做：输入 /runId-stepN 修正要求 后，系统继承源运行的 Agent 和前置步骤，并从目标步骤继续生成新回答。
• 持久历史：MySQL ai_run_history 保存本人问题、回答、Agent 版本、状态和有上限的诊断，失败/取消的评测会话也能查看。历史查看不依赖 Redis TTL；真正能否步骤重做仍以有效快照为准。进程中断后不会自动重放外部操作。

🔌 断线续作与 Timeline 重连

Agent run 的生命周期归 session 管理，不再绑定某一个浏览器 SSE 连接。刷新、网络抖动或离开当前会话时，后端继续运行；只有显式取消才会按 sessionId + runId 终止目标 run。

重连按三段恢复：先加载已聚合的 Timeline Snapshot，再读取 Redis Stream 中快照游标之后的事件，最后订阅实时流。运行完成后仍可从最终快照恢复步骤文本、工具调用、记忆/RAG 依据、审批与主动追问卡片。

⏰ 后台任务与对象监视器

聊天入口会先由独立的 BackgroundTaskCommandRouter 判断是否属于后台任务命令，不改变 Fixed、Auto、Flow 的普通意图路由职责。当前支持：

• SCHEDULE_ONCE：指定时间触发一次。
• CRON：使用六段 Spring Cron 和时区周期触发。
• FILE_CHANGE_STABLE：文件内容变化后，持续指定时间未再修改时触发。

创建结果先保存为草稿，由用户确认后启用。任务中心支持编辑、暂停、恢复、立即执行、取消、查看触发记录和进入目标会话；触发时复用普通 Agent run，同一 session 同时只允许一个 run，繁忙时任务会等待会话空闲。

🛠️ 动态 MCP 工具补充

固定给每个 Agent 挂大量工具，会增加上下文、工具幻觉和选错工具的概率。TAgent 将工具拆成"常驻工具"和"按请求动态补充工具"。动态补充支持两条互补路径：路由阶段根据 missing_tool_descs 预推断，或模型在真实执行中通过 request_tool 主动描述能力缺口。

UnifiedAgentRouter
  -> missing_tool_descs（路由预推断）
  或 Advisor / LLM
  -> request_tool(needs)（执行期补充）
  -> 优先匹配授权目录中的明确工具名
  -> 其余能力描述生成 embedding
  -> PgVector 查询 mcp_tool_vector
  -> 每类能力取 Top-K
  -> 相似度与名称/描述依据筛选，不强行补满
  -> 多类结果并集去重
  -> 懒创建或复用 MCP callback
  -> 常驻工具 + 动态工具
  -> 注入本次请求 / run

工具资产由两部分组成：

• MySQL ai_mcp_tool_catalog：真实工具名、MCP、原始描述、中文描述和中文意图
• PgVector mcp_tool_vector：用于语义检索的工具向量

用户在工作台绑定 MCP 连接，具体工具在执行时按需装载。Flow 分析/规划只阅读执行节点的授权能力目录，区分“已绑定”“已装载”和“已执行”，此时不开放 request_tool。

执行期 request_tool 优先匹配明确工具名，再结合向量相似度与名称/描述依据筛选；不会为了补满 Top-K 装配低相关工具。向量不可用时仅在授权目录内回退名称/描述匹配，找不到就明确返回无匹配。MCP 绑定和公共目录授权始终参与范围校验，工具目录可见不代表已经调用或验证连通性。

可选的免费联网搜索示例：Parallel Search MCP 配置与 smoke test。

🔧