Java 手写 AI Agent：ZenoAgent 实战笔记

防御式编程：四重保障解决'大模型不听话'

• 剔除 json 和 包裹。
• 自动补全截断的 JSON：利用堆栈检测括号平衡，自动补齐末尾缺失的 }。
• 自愈式重试循环：当解析失败时，将错误堆栈作为 Prompt 反馈给模型。
• 原生 Response Format：对于支持 JSON Mode 的模型，调用时直接注入约束。

2. ReAct 模式设计与工程实现

ZenoAgent 的核心是手写了一个基于状态机的 ReAct 循环引擎。

2.1 Action 的抽象设计

将 Agent 的所有能力抽象为 4 种原子 Action：

• TOOL_CALL：调用外部工具（通过 MCP 协议）。
• RAG_RETRIEVE：检索知识库。
• LLM_GENERATE：让子模型处理纯文本生成任务。
• DIRECT_RESPONSE：直接向用户输出结果。

2.2 性能优化：DIRECT_RESPONSE

对于简单场景，将'回复用户'设计为一种 Action。当模型判断无需使用工具时，直接生成 DIRECT_RESPONSE 动作，使'思考'和'回复'在一次 LLM 调用中完成，延迟降低 50% 以上。

2.3 并发执行机制

允许 LLM 在一次 Thinking 过程中输出多个 Action，后端利用 Java 的 CompletableFuture 并行分发请求。

// ActionExecutor.java 核心逻辑
public List<ActionResult> executeParallel(List<AgentAction> actions) {
    List<CompletableFuture<ActionResult>> futures = actions.stream()
        .map(action -> CompletableFuture.supplyAsync(() -> execute(action), executor))
        .toList();
    return futures.stream().map(CompletableFuture::join).toList();
}

2.4 isComplete 的语义陷阱

重构了 Prompt 中对 isComplete 的语义定义：

• isComplete=true：移交控制权（任务彻底完成或需要提问等待用户回复）。
• isComplete=false：保持控制权（发送进度提示，流程自动继续）。

3. 分布式环境下的 Human-in-the-loop

企业级应用中敏感操作需人工确认。利用 Redisson 实现了跨实例的线程挂起与唤醒。

// ToolConfirmationManager.java
public ToolExecutionDecision waitForDecision(String executionId) {
    RBlockingQueue<ToolExecutionDecision> queue = redissonClient.getBlockingQueue(KEY_PREFIX + executionId);
    return queue.poll(60, TimeUnit.SECONDS);
}

4. 流式思考：从 Prompt 模拟到原生 API 适配

• 方案一：Prompt 引导的模拟思考。将'思考'作为 JSON 结构的一部分，后端实时解析流式响应提取 thinking 字段推送到前端。
• 方案二：原生 Reasoning 字段适配。监听特定 API 字段（如 reasoning_content）获取独立传输的思维链数据。

Lookahead Buffer 机制：在后端增加前缀缓冲，防止流未结束时残缺标签泄露。

5. RAG 知识库：从摄入到召回的全链路优化

• 文档摄入：使用 Apache Tika 进行全格式解析，配合 Recursive Character Splitter 进行语义分块。
• 动态召回策略：基于 knowledgeId 进行物理/逻辑隔离，支持多租户数据安全。

// RAGEnhancer.java 核心逻辑
embeddingStore.search(EmbeddingSearchRequest.builder()
    .queryEmbedding(queryVector)
    .filter(metadataKey("knowledgeId").isEqualTo(currentKnowledgeId))
    .maxResults(5)
    .minScore(0.75)
    .build());

7. 自愈式错误处理

当工具调用失败时，Agent 不会直接崩溃，而是进入自愈循环。错误信息被记录到 AgentContext 中并在下一轮 Thinking 阶段注入 Prompt，促使 LLM 智能修正参数或选择替代工具。

8. 动态工具发现与热加载

基于 MCP (Model Context Protocol)，实现了工具的动态管理。McpConfigLoader 监听配置文件变更，一旦修改 mcp.json，系统会自动重新连接 MCP Server 并刷新工具列表，无需重启服务。

📸 系统预览

🚀 总结

通过 Spring Boot 的工程化能力，可以构建出比 Python 原型更稳定、更易于扩展的 Agent 系统。ZenoAgent 展示了 ReAct 引擎、RAG 知识库、MCP 工具协议、分布式协同及流式思考的实现细节。