TAgent

📖 项目简介

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

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

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

适合谁

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

🎯 系统总览

🎬 功能演示

三种策略、动态工具补充、主动追问、计划确认、人工审批、通知收件箱、运行编号重做、长期记忆管理、断线续作、图片理解、后台任务与观测页面均提供了独立录屏，便于按功能查看或替换：查看功能演示录屏。

主链路

用户请求
  -> 过滤器 / 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 模式

适合直接问答或单轮工具任务：

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

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

Auto 模式

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

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

Flow 模式

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

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 和前置步骤，并从目标步骤继续生成新回答。
• 历史记录：对话记忆和事件日志记录运行编号，刷新页面后仍能复制运行编号；但真正能否重做以 Redis 快照是否仍有效为准。

🔌 断线续作与 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：用于语义检索的工具向量

request_tool 属于元工具，不算业务执行工具；它可以在 Flow 的工具分析/规划阶段提前为后续 DAG 执行步补齐能力。路由预推断则适合在请求开始前补齐较明确的能力缺口。当前工具匹配采用 embedding-only，不回退 BM25 或 LLM rerank。向量服务不可用时宁可跳过动态补挂，也不盲目匹配无关工具。

🔧 MCP 工具治理与自动重连

MCP 调用不是直接执行裸 callback，而是经过 MeteredToolCallback、RobustToolCallingManager 和 McpClientRegistry 三层治理。

McpClientRegistry

Registry 维护 MCP Client、工具与 MCP 的映射、重建工厂、最近成功时间、连续失败次数和熔断状态。

自愈路径包括：

1. 工具调用前按需进行懒探活
2. 首次调用失败后执行有限重试
3. 超时后再次探活，判断连接仍存活还是已经死亡
4. dead-client 或发送失败时重建 MCP Client
5. 重建成功后刷新旧 MeteredToolCallback 内部 delegate
6. 同一 MCP 设置 10 秒重连冷却，避免连续抖动和重连风暴
7. 连续失败进入熔断状态时跳过无意义重连

重连后对模型暴露的 ToolDefinition 保持稳定，因此工具参数提示不会因 callback 切换而丢失。

📚 Advisor 链

Advisor 由数据库配置，并按 order 参与请求：

🧠 Agentic RAG

RAG Router 会先判断是否需要检索，再从四种策略中选择：

检索链路：

Query Planning
  -> PgVector 语义召回
  -> Elasticsearch BM25
  -> RRF 融合
  -> Cross Encoder / LLM Rerank
  -> Child 命中替换为 Parent Document
  -> 注入编号引用
  -> rag_evidence SSE

💾 四层记忆

长期记忆包含：

• 固定画像槽位
• 情景记忆语义召回
• exact match 与语义去重
• 单值覆盖、累加记忆合并
• 冲突判断
• 访问热度继承与冷记忆归档
• 同一轮多步骤共享召回快照

🎮 执行中干预

Auto、Flow、Fixed 三种模式均支持 steer、answer_now 和 cancel。

引导 steer

POST /api/v1/agent/steer
Content-Type: application/json

{
  "sessionId": "session_demo_001",
  "idea": "请重点从工程落地和风险控制角度分析"
}

行为：

• 中断当前正在生成的流，而不是等待步骤自然结束
• 保留当前 reasoning、半截输出和已有步骤结果
• 将新想法合并到有效用户问题
• 重做当前步骤，并将引导继续传递到后续步骤

🤔 主动追问 ask_user

当模型缺少完成任务所必需的信息，或用户意图存在多种合理理解需要拍板时，可以调用 ask_user 主动向用户追问。

流程：

Advisor + LLM
  -> ask_user tool_call
  -> user_input_required SSE
  -> 用户补充回填
  -> ask_user tool result
  -> 继续下一轮推理

设计边界：

• agent.user-input.enabled=false 时完全不广播 ask_user，默认不影响原链路
• UserInputGate 按 sessionId 限制追问次数，并支持超时自动放行
• ask_user 与人工审批互不复用 ID：审批管工具授权，ask_user 管需求澄清

👨‍💼 人工审批

高风险工具可配置为执行前审批：

1. 后端发送 human_approval_required SSE 事件
2. 前端显示工具名、参数和审批原因
3. 用户调用审批接口
4. 批准后执行，拒绝或超时则向模型返回结构化错误

POST /api/v1/agent/approval
Content-Type: application/json

{
  "approvalId": "approval-id-from-sse",
  "approved": true
}

📡 SSE 事件

📊 可观测性

TAgent 同时记录模型、工具和 Agent 步骤：

• LlmObservationRecorder：模型、耗时、Token、缓存 Token、billing scope
• ai_event_log：步骤输入输出、路由、工具、干预和最终结果
• Prometheus：LLM 与 MCP 指标
• ELK：结构化日志与 MDC 上下文
• Jaeger：跨 Controller、Step、LLM 和工具调用 Trace
• WireTraceRecorder：在不消费下游响应体的前提下记录流式 wire 信息

页面：

• 系统观测：http://localhost:8099/observe.html
• MCP 观测：http://localhost:8099/observe-mcp.html

📋 技术栈

• Java 17
• Spring Boot 3.4.3
• Spring AI 1.1.7
• MCP SDK 0.18.2
• MyBatis、MySQL
• PostgreSQL + pgvector
• Redis
• Elasticsearch
• Resilience4j
• Reactor、SSE
• Micrometer、Prometheus、Grafana、Jaeger、ELK

🏗️ 项目模块

🚀 本地运行

外部依赖

默认地址：

环境变量

# LLM 配置
LLM_BASE_URL=https://your-openai-compatible-endpoint
LLM_API_KEY=your-llm-key
LLM_MODEL=your-model

# 向量模型配置
EMBEDDING_BASE_URL=https://your-embedding-endpoint
EMBEDDING_API_KEY=your-embedding-key
EMBEDDING_MODEL=BAAI/bge-m3

# 可选：远程图片下载代理
TAGENT_IMAGE_PROXY_URL=http://127.0.0.1:7897

# 可选：私有 OSS 图片存储
TAGENT_OSS_ENABLED=false
TAGENT_OSS_BUCKET=your-private-bucket

# 数据库凭据
MYSQL_USERNAME=root
MYSQL_PASSWORD=your-mysql-password
PGVECTOR_USERNAME=postgres
PGVECTOR_PASSWORD=your-postgres-password

按需设置 MCP 和观测凭据：

GITHUB_PERSONAL_ACCESS_TOKEN=your-github-token
GRAFANA_API_KEY=your-grafana-key
CSDN_API_COOKIE=your-csdn-cookie
WEIXIN_API_APP_SECRET=your-weixin-secret

数据库迁移

增量脚本位于：

docs/dev-ops/sql-migrations

新环境应按版本顺序执行。动态工具功能至少需要 V041、V046、V047；后台任务中心需要执行 V058__create_background_task_center.sql。

构建

mvn "-Dmaven.test.skip=true" package

项目包含依赖外部服务和账号环境的集成测试。普通本地构建可跳过测试，验收时再运行指定测试类。

启动

java -jar ai-agent-station-study-app/target/ai-agent-station-study-app.jar

默认端口：8099

• 对话页：http://localhost:8099/index.html
• Agent 配置：http://localhost:8099/agent-config.html
• 健康检查：http://localhost:8099/actuator/health

📤 流式请求示例

POST /api/v1/agent/auto_agent
Content-Type: application/json
Accept: text/event-stream

{
  "aiAgentId": "3",
  "message": "总结当前系统的 Agent、RAG、记忆和 MCP 能力",
  "sessionId": "session_demo_001",
  "userId": "user_demo",
  "maxStep": 5
}

⚙️ 关键配置

agent:
  intervention:
    enabled: true
  steer:
    enabled: true
    max-rounds: 3
  answer-now:
    finalize-tools: true
  user-input:
    enabled: false
    max-asks: 2
    timeout-seconds: 120
  request-tool:
    enabled: false
    max-calls: 3

  mcp:
    disable-tools-on-nonexec-steps: true
    tool-call:
      max-attempts: 2
      retry-delay-ms: 1000
      parallel-enabled: true
      max-serial-rounds-per-client: 3

  dynamic-tools:
    # 路由阶段缺失能力预推断；与执行期 request_tool 可并存
    infer-on-selected-agent: true
    per-need-top-k: 2
    max-extra-tools-per-request: 6
    match-cache-ttl-ms: 600000
  flow:
    plan-review:
      enabled: false
      store-enabled: true
      ttl-seconds: 7200
  run-snapshot:
    enabled: true
    ttl-seconds: 21600
    session-index-size: 30
  run-events:
    enabled: true
    ttl-seconds: 21600
  evidence-map:
    ttl-seconds: 604800

🔒 安全说明

公开仓库中不应提交：

• API Key、Access Token、Cookie、私钥
• .local-config、浏览器状态和本地凭据
• 运行日志、压测报告和临时调试文件
• 个人对话、简历和面试资料
• 数据库备份和生产数据

📝 更新记录

详见 CHANGELOG.md。

📄 许可证

本项目采用 MIT License 许可证。

🤝 贡献指南

欢迎 Issue、Pull Request 和讨论！我们非常期待你的建议和贡献。

问题或建议？ 创建 Issue 或 发起讨论 🙌