第 23 章：Java / Spring Boot Agent Framework 设计

本章导读

  • 核心问题：如何用 Java / Spring Boot 抽象企业 Agent Framework。
  • 关键词：agent-api、agent-core、agent-runtime、agent-context、agent-tool、agent-skill、agent-memory
  • 学习产出：用 CI 失败分析应用验证 Java Agent Framework 的模块与接口设计。

1. 本章要解决什么问题

这是全书最后一章。

前面我们从 Anthropic Engineering 出发，系统讨论了：

Agent
Workflow
Claude Code
Context Engineering
Tool Engineering
Skill Engineering
Harness
Memory
MCP
Multi-Agent
Managed Agents
Enterprise Agent Platform

这一章要把这些思想落到一个 Java / Spring Boot Agent Framework 的设计中。

目标不是一次性写出完整框架，而是给出一套清晰、可扩展、可演进的模块边界和核心接口。

本章核心观点是：

Java Agent Framework 的目标不是重新发明模型，而是为企业 Agent 提供标准抽象、运行时、扩展点和治理能力。

2. 设计目标

这个框架应满足：

2.1 模型无关

不绑定某个模型供应商。

应支持：

  • Claude；
  • OpenAI；
  • Gemini；
  • 本地模型；
  • 企业代理模型服务。

2.2 模块化

Context、Tool、Skill、Memory、Harness、MCP 应独立模块化。

业务方可以按需引入。

2.3 接口优先

核心模块定义接口和事件协议。

具体实现可以替换。

2.4 可治理

内置：

  • 权限；
  • 审计；
  • 观测；
  • 成本；
  • 策略；
  • Memory 治理。

2.5 面向企业集成

要方便接入：

  • Spring Security；
  • PostgreSQL；
  • Redis；
  • Kafka；
  • Kubernetes；
  • GitLab / GitHub；
  • Jira；
  • Confluence；
  • CI/CD。

3. Maven 多模块结构

建议结构：

java-agent-framework/
  pom.xml
  agent-api/
  agent-core/
  agent-runtime/
  agent-context/
  agent-tool/
  agent-skill/
  agent-memory/
  agent-harness/
  agent-mcp/
  agent-security/
  agent-observability/
  agent-evaluation/
  agent-spring-boot-starter/
  examples/
    ci-failure-agent/
    pr-review-agent/

4. 模块职责

4.1 agent-api

定义对外 API DTO：

  • SubmitTaskRequest；
  • AgentTaskResponse；
  • SessionResponse；
  • ToolCallView；
  • TraceView。

4.2 agent-core

定义核心领域对象：

  • AgentTask；
  • AgentSession；
  • AgentEvent；
  • AgentResult；
  • AgentStatus；
  • AgentPolicy。

4.3 agent-runtime

负责运行时：

  • AgentRuntime；
  • TaskManager；
  • SessionManager；
  • Scheduler；
  • EventStore；
  • ResumeManager。

4.4 agent-context

负责上下文：

  • ContextChunk；
  • ContextProvider；
  • ContextSelector；
  • ContextCompressor；
  • ContextRenderer；
  • ContextBudget。

4.5 agent-tool

负责工具：

  • AgentTool；
  • ToolDefinition；
  • ToolRegistry；
  • ToolExecutor；
  • ToolOrchestrator；
  • ToolAuditLog。

4.6 agent-skill

负责 Skill：

  • Skill；
  • SkillMetadata；
  • SkillRegistry；
  • SkillSelector；
  • SkillLoader；
  • SkillContextInjector。

4.7 agent-memory

负责记忆：

  • MemoryRecord；
  • MemoryService；
  • MemoryRetriever；
  • MemoryPolicy；
  • MemoryAuditLog。

4.8 agent-harness

负责执行循环：

  • AgentHarness；
  • Planner；
  • VerificationRunner；
  • RecoveryStrategy；
  • CheckpointStore；
  • StopCondition。

4.9 agent-mcp

负责 MCP 集成：

  • McpConnector；
  • McpServerRegistry；
  • McpContextProvider；
  • McpToolAdapter；
  • McpSecurityPolicy。

4.10 agent-security

负责：

  • PolicyEngine；
  • PermissionService；
  • ApprovalService；
  • DataMaskingService；
  • SecretGuard。

4.11 agent-observability

负责：

  • Trace；
  • Metrics；
  • Event Viewer；
  • Cost Recorder；
  • Audit Logger。

5. 核心接口设计

5.1 LlmClient

public interface LlmClient {
    LlmResponse complete(LlmRequest request);
}

请求：

public record LlmRequest(
    String model,
    List<LlmMessage> messages,
    List<ToolDefinition> tools,
    LlmOptions options
) {}

5.2 AgentRuntime

public interface AgentRuntime {
    AgentTaskResult submit(AgentTask task);
    AgentTaskResult resume(String sessionId);
    void pause(String sessionId);
    void cancel(String sessionId);
}

5.3 ContextProvider

public interface ContextProvider {
    boolean supports(ContextRequest request);
    List<ContextChunk> provide(ContextRequest request);
}

5.4 AgentTool

public interface AgentTool<I, O> {
    ToolDefinition definition();
    O execute(I input, ToolExecutionContext context);
}

5.5 SkillRegistry

public interface SkillRegistry {
    List<SkillMetadata> listMetadata(SkillSelectionRequest request);
    Optional<Skill> load(String skillName, SkillLoadOptions options);
}

5.6 MemoryService

public interface MemoryService {
    MemoryRecord write(MemoryWriteRequest request);
    List<MemoryRecord> retrieve(MemoryQuery query);
    void delete(String memoryId, DeleteReason reason);
}

5.7 AgentHarness

public interface AgentHarness {
    AgentResult run(AgentTask task, HarnessPolicy policy);
    AgentResult resume(String sessionId);
}

6. Spring Boot Starter 设计

agent-spring-boot-starter 应提供自动配置。

例如：

@Configuration
@EnableConfigurationProperties(AgentProperties.class)
public class AgentAutoConfiguration {

    @Bean
    public AgentRuntime agentRuntime(...) {
        return new DefaultAgentRuntime(...);
    }
}

配置：

agent:
  model:
    provider: anthropic
    default-model: claude-sonnet
  runtime:
    max-iterations: 20
    timeout: 30m
  tools:
    require-approval-for-write: true
  memory:
    enabled: true
  observability:
    tracing-enabled: true

7. 贯穿案例：CI 失败分析 Agent

作为框架第一个示例，建议实现只读型 CI 失败分析 Agent。

它可以使用以下模块验证框架抽象：

agent-core：AgentTask、AgentSession、AgentEvent
agent-runtime：任务提交、Session 管理、EventStore
agent-context：CI、Git、AGENTS.md、Memory 的 ContextProvider
agent-tool：summarize_ci_failure、get_git_diff、search_code、read_file_range
agent-skill：ci-failure-analysis Skill
agent-harness：只读分析 Harness 和 VerificationRunner
agent-memory：历史类似失败和项目经验
agent-mcp：CI MCP、Git MCP、Jira MCP
agent-security：只读 Policy 和工具权限
agent-observability：Trace、工具调用日志、报告质量评估

这个应用不需要一开始实现自动修复，但足以验证框架的核心抽象是否成立。等书稿定稿后，完整 Java 示例工程可以围绕这个场景独立开发。

7.1 输入

{
  "buildId": "4312",
  "repositoryId": "order-service",
  "pullRequestId": "882"
}

7.2 可用工具

summarize_ci_failure
get_git_diff
get_recent_commits
search_code
read_file_range

7.3 可用上下文

AGENTS.md
CI 失败摘要
Git Diff
最近提交
历史类似失败 Memory

7.4 输出

{
  "rootCause": "...",
  "evidence": ["..."],
  "suspectedFiles": ["..."],
  "suggestedFix": "...",
  "confidence": 0.82,
  "commandsOrToolsUsed": ["..."]
}

8. 框架架构图

Java Agent Framework 模块关系
图 23-1 Java Agent Framework 模块关系 这张图展示 Java / Spring Boot Agent Framework 的多模块拆分与核心接口。 Mermaid 源文件

8.1 Maven 模块依赖总览

下图进一步抽象模块级依赖关系，突出 agent-runtime 与 Spring Boot Starter 的装配位置。

Maven 模块依赖总览
图 23-2 Maven 模块依赖总览 Mermaid 源文件

9. 开发路线

9.1 第一阶段：核心运行时

实现：

  • agent-core；
  • agent-runtime；
  • LlmClient；
  • EventStore；
  • 简单 AgentHarness。

9.2 第二阶段：Context 与 Tool

实现：

  • ContextProvider；
  • ContextSelector；
  • ToolRegistry；
  • ToolExecutor；
  • 只读工具。

9.3 第三阶段：Skill 与 Project Knowledge

实现：

  • SkillRegistry；
  • AGENTS.md Loader；
  • Spring Boot Test Skill。

9.4 第四阶段：Memory 与 Harness

实现：

  • MemoryService；
  • CheckpointStore；
  • VerificationRunner；
  • ResumeManager。

9.5 第五阶段：MCP 与平台化

实现：

  • McpConnector；
  • Security；
  • Observability；
  • Admin UI；
  • Evaluation。

10. 常见误区

10.1 只封装模型 API

这不是 Agent Framework，只是 SDK Wrapper。

10.2 过早抽象

框架设计应从真实场景开始，例如 CI 失败分析。

10.3 把业务逻辑写进 core

agent-core 应保持通用，业务能力通过 Tool、Skill、Provider 扩展。

10.4 忽略安全和观测

企业框架必须内置治理能力。

10.5 一开始就做 Multi-Agent

先做好单 Agent Runtime，再扩展 Multi-Agent。

11. 本章小结

本章把全书内容落地为 Java / Spring Boot Agent Framework 设计。

核心结论：

  1. Java Agent Framework 应以 Runtime、Context、Tool、Skill、Memory、Harness 为核心模块。
  2. 框架应模型无关、接口优先、模块化、可治理。
  3. Spring Boot Starter 可以降低业务接入成本。
  4. 第一个实践案例建议选择只读型 CI 失败分析 Agent。
  5. 框架演进应从真实业务场景出发，逐步抽象。

一句话总结：

企业级 Java Agent Framework 的价值，不是让模型更聪明，而是让模型能力以标准、安全、可观测、可扩展的方式进入企业软件系统。

12. 实践任务

任务 1：初始化 Maven 多模块工程

在 examples/java-agent-runtime 下创建：

agent-core
agent-runtime
agent-context
agent-tool
agent-spring-boot-starter

任务 2：实现 agent-core

定义：

  • AgentTask；
  • AgentSession；
  • AgentEvent；
  • AgentResult。

任务 3：实现只读 CI Agent

支持读取 CI 摘要、Git Diff、代码片段，并输出失败分析报告。

任务 4：补充评估集

准备 20 个 CI 失败样例，用于评估 Agent 输出质量。

13. 结语

如果用一句话概括整本书：

现代 AI Agent 工程的核心，不是写一个神奇 Prompt，而是围绕模型构建 Context、Tool、Skill、Memory、Harness、Runtime 与治理体系。

Anthropic Engineering 的价值就在于，它把这些实践逐步公开出来，让我们看到 Agent 正在从“提示词技巧”演进为真正的软件工程体系。

对于企业开发者来说，下一步不是盲目追逐某个 Agent 框架，而是理解这些底层工程问题，并在自己的技术栈中建立可持续演进的平台能力。

results matching ""

    No results matching ""