1. 项目概述为什么 Java 还能做 AI Agent这不是“复古”而是“务实”最近在几个技术社区里看到不少人在问“Java 做 AI Agent 是不是过时了Python 不香吗”——这问题我听了不下十次。但去年底我接手一个需要嵌入某工业边缘网关的智能调度模块客户明确要求必须跑在 JDK 11 的轻量级容器里不能装 Python不能拉 Docker 镜像所有依赖要打成单 Jar同时要对接已运行 8 年的老系统基于 Spring Boot 2.3 Dubbo 2.7还要支持热插拔式任务编排、异步流式响应、以及与本地知识库SQLite 自建向量索引低延迟交互。这时候Python 的 asyncio LangChain 组合直接被排除——不是能力不行是部署链路太长、环境不可控、运维同学一看到 requirements.txt 就摇头。“JavaManus”就是在这个背景下诞生的。它不是为了挑战 LangChain 或 LlamaIndex也不是要做个“Java 版 AutoGen”而是一个面向中大型企业后端场景的、可嵌入、可审计、可灰度、可监控的 AI Agent 轻量框架。名字里的 “Manus” 取自拉丁语“手”寓意“亲手掌控每一步执行”强调可控性而非黑盒调用。它不封装大模型 API不内置 Prompt 工程器不强制使用特定向量库——它只提供四个核心契约接口TaskRouter路由决策、ToolExecutor工具调用、MemoryManager状态快照、ResponseComposer结果组装。其余全部交由业务方按需实现。关键词里反复出现的“从零构建”不是指“从字节码开始写 JVM”而是指不依赖任何现成 Agent 框架 SDK仅基于 JDK 17 标准库 Spring Boot 3.2 Lombok SLF4J 构建完整生命周期管理。我们用CompletableFuture做非阻塞编排用ThreadLocalCopyOnWriteArrayList实现线程安全的上下文透传用ServiceLoader实现插件化工具注册——所有设计都服务于一个目标让一个有 5 年 Spring 开发经验的工程师花半天看懂源码一天就能替换掉自己系统里的旧版规则引擎。它适合谁不是刚学 Java 的学生也不是想快速跑通一个 ChatUI 的前端同学。它适合三类人一是正在把传统 ERP/MES/SCM 系统升级为“带思考能力”的智能中枢的后端架构师二是需要将 LLM 能力深度集成进高可用金融交易链路比如信贷审批辅助、反欺诈策略增强的中间件团队三是受信创合规约束、必须使用国产 JDK 和可控开源组件的政企项目组。如果你的系统已经重度依赖 Spring Cloud Alibaba那 JavaManus 的AgentTask注解和AgentTemplate模板类能让你在不改一行 FeignClient 的前提下把某个PostMapping(/v1/apply)接口升级为多步骤自主推理服务。我试过用它在一个真实物流调度系统里替换原有 Drools 规则链原来 17 条硬编码 if-else 判断“是否启用夜间加急”现在变成一个DeliveryOptimizationAgent自动调用运力池查询、天气 API、历史履约率统计工具在 320ms 内返回带置信度的三套方案。最关键是——所有决策路径可回溯、所有工具调用可熔断、所有中间状态可审计。这才是企业级 AI Agent 的起点而不是 Demo 展示页上那个会讲笑话的聊天机器人。2. 整体架构设计放弃“大而全”坚持“小而韧”2.1 四层职责分离为什么不用“Agent 类继承抽象基类”很多初学者一上来就想定义一个BaseAgent然后让CustomerServiceAgent、ReportGeneratorAgent去继承它。这在教学 Demo 里没问题但在真实系统里会迅速失控。我们做过一次代码扫描某客户项目里 12 个 Agent 子类平均重写了 67% 的父类方法其中 4 个子类甚至覆盖了execute()主流程——这意味着父类抽象完全失效维护成本指数级上升。JavaManus 的解法是彻底解耦不提供 Agent 类只提供 Agent 执行协议。整个框架只有四个核心接口每个接口对应一个明确的、可独立演进的领域职责TaskRouter输入当前上下文Context输出下一步要执行的ToolSpec含工具 ID、参数 Schema、超时阈值。它不关心工具怎么执行只负责“判题”。ToolExecutor输入ToolSpec和上下文返回ToolResult含原始响应、结构化解析结果、耗时、错误码。它不关心结果怎么用只负责“答题”。MemoryManager提供saveSnapshot()/loadLatest()方法用于保存/加载 Agent 执行过程中的关键状态如用户原始提问、已调用工具列表、临时变量。它不存储业务数据只存“推理痕迹”。ResponseComposer输入最终所有ToolResult列表和初始 Context输出标准化的AgentResponse含文本回复、结构化数据、引用溯源、置信度分数。它不生成内容只“排版”。这四层之间通过AgentContext对象传递数据该对象是不可变Immutable的每次流转都生成新实例避免共享状态引发的并发问题。我们刻意没用 MapString, Object 做上下文容器而是定义了强类型的AgentContext.Builder强制声明哪些字段是必填如sessionId,requestId哪些是可选如userProfile,geoLocation。这样做的好处是IDE 能自动提示字段单元测试能精准 mock日志打印时不会漏掉关键 trace 信息。提示AgentContext的序列化格式默认为 JSON但预留了ContextSerializerSPI 接口。某银行客户就用它替换成国密 SM4 加密后的二进制格式确保敏感字段不出 JVM 堆。这种设计牺牲了“开箱即用”的便利性换来了三个关键收益第一各层可独立压测——你能单独对TaskRouter做百万 QPS 的规则匹配性能测试而不必启动整个 Agent 流程第二故障隔离性强——如果ToolExecutor里某个 HTTP 工具超时ResponseComposer依然能用缓存结果生成降级回复第三演进自由度高——今年用 Redis 做MemoryManager明年换成 TiKV只要接口不变上层逻辑零修改。2.2 执行模型为什么选择“显式编排”而非“隐式循环”主流 Python Agent 框架普遍采用while not done: action router() → result executor(action) → memory.save(result)的隐式循环模型。这很优雅但对企业系统是隐患无法预估最大迭代次数无法设置全局超时无法在第 3 次循环时强制注入人工审核节点。JavaManus 采用显式有限状态机FSM驱动。每个 Agent 实例绑定一个AgentPlan它是一个 JSON 文件描述了最多允许几步执行、每步的条件分支、失败后的 fallback 路径。例如一个信贷审批 Agent 的 plan 可能是{ maxSteps: 5, steps: [ {id: check_identity, tool: idVerificationTool, timeoutMs: 2000}, {id: fetch_credit_report, tool: creditReportTool, timeoutMs: 3000, onFailure: fallback_to_manual}, {id: calculate_risk_score, tool: riskScoringTool, timeoutMs: 800} ], finalStep: compose_approval_response }框架在启动时解析此 plan生成一个ExecutionGraph对象内部用DirectedAcyclicGraphDAG结构存储节点依赖。执行时AgentRunner按拓扑序遍历节点每个节点执行前校验前置条件如fetch_credit_report要求check_identity.status SUCCESS失败则跳转到onFailure指定节点。整个过程可被 Prometheus 的agent_step_duration_seconds指标精确观测。这个设计让运维同学第一次真正“看懂”了 Agent 在做什么。他们不再需要翻日志猜“现在卡在哪一步”而是直接查 Grafana 看agent_step_status{stepfetch_credit_report}这个指标的失败率。某证券公司就基于此做了自动化巡检当calculate_risk_score步骤连续 5 分钟失败率 5%自动触发告警并推送至风控值班群。2.3 插件机制如何让“工具”真正热插拔很多框架说支持插件实际是把工具类打包进主 Jar改一行代码就得重启。JavaManus 的ToolExecutor实现了真正的运行时热加载工具实现类必须标注Tool(name weatherApi, version 1.2)框架启动时扫描META-INF/services/com.javamanus.tool.ToolProvider文件读取所有工具提供者类名每个ToolProvider返回一个ToolDefinition含名称、版本、参数类型、是否幂等当TaskRouter返回ToolSpec(weatherApi, ...)时ToolExecutor从注册中心按 nameversion 查找对应 provider并调用其execute()方法关键在于ToolProvider的execute()方法接收一个ToolInvocation对象它封装了参数、超时、重试策略。而 provider 本身可以是任意实现——它可以是本地 Spring Bean也可以是通过 gRPC 调用远端服务甚至可以是用 GraalVM 编译的 Native Image 微服务。我们有个客户就把核心风控模型封装成 Native Tool启动时间从 2.3 秒降到 180ms内存占用减少 65%。注意热加载不等于无损更新。我们要求所有ToolProvider必须实现LifecycleAware接口提供preDestroy()方法。当管理员通过 Actuator 端点/actuator/tools/unload?nameweatherApi卸载工具时框架会先调用preDestroy()让工具释放连接池、关闭线程池再从注册中心移除。实测下来单次卸载耗时稳定在 12ms 内不影响其他工具调用。3. 核心细节解析那些文档里不会写的“手感”3.1 上下文透传为什么 ThreadLocal 不够用我们怎么补初版设计确实只用了ThreadLocalAgentContext。但很快在压测中暴雷Spring WebFlux 的Mono链式调用会跨线程切换ThreadLocal值在publishOn(Schedulers.boundedElastic())后就丢失了。有人提议改用 Reactor 的ContextView但我们发现它只能存 String-Key 的简单值而AgentContext是复杂对象且需要在日志、Metrics、Tracing 中全局可见。最终方案是“双 Context 机制”逻辑 Context仍用ThreadLocal但只在同步执行路径如TaskRouter.route()中使用保证单线程内高效访问物理 Context所有异步操作HTTP 调用、DB 查询、消息发送都显式携带AgentContext参数并在回调中重建ThreadLocal值。具体实现是在ToolExecutor的模板方法里public T MonoToolResultT executeAsync(ToolSpec spec, AgentContext context) { // 1. 将 context 序列化为字符串注入 HTTP Header String ctxHeader contextSerializer.serialize(context); // 2. 发起异步请求 return webClient.post() .uri(spec.getEndpoint()) .header(X-Agent-Context, ctxHeader) .bodyValue(spec.getParams()) .retrieve() .bodyToMono(String.class) .map(response - { // 3. 回调中反序列化 context并绑定到当前线程 AgentContext restored contextSerializer.deserialize(ctxHeader); agentContextHolder.set(restored); // 自定义 holder支持 Mono return parseResponse(response, spec); }); }agentContextHolder是我们封装的Mono.subscriberContext()适配器它能在Mono链的每个阶段自动提取并设置ThreadLocal。这样既保留了ThreadLocal的零拷贝优势又解决了异步穿透问题。实测在 5000 QPS 下额外序列化开销低于 0.8ms/次。3.2 内存管理为什么不用 Redis我们怎么用 SQLite 做毫秒级快照很多团队一想到“记忆”立刻上 Redis。但 Redis 是远程调用P99 延迟至少 3ms而我们的 SLA 要求单次 Agent 执行总耗时 500ms。更麻烦的是Redis 的 key 设计容易引发热点——所有请求都往agent:session:${id}这个 key 写QPS 上去就打满单节点带宽。JavaManus 默认采用嵌入式 SQLite WAL 模式。别笑SQLite 在单机场景下是王者启动零依赖Class.forName(org.sqlite.JDBC)后直接DriverManager.getConnection(jdbc:sqlite:agent_memory.db)WAL 模式下写操作不阻塞读多个 Agent 实例可并发访问同一 DB我们把MemoryManager的saveSnapshot()实现为单条INSERT INTO snapshots (session_id, step_id, data, created_at) VALUES (?, ?, ?, ?)用PRAGMA journal_modeWAL和PRAGMA synchronousNORMAL调优后P99 写入延迟稳定在 0.3ms更绝的是我们用 SQLite 的FTS5全文检索模块给data字段建虚拟表支持按“用户问了什么”快速回溯历史会话——某客服系统就靠这个功能把“上次用户投诉物流慢这次推荐了什么方案”的复盘时间从 2 小时缩短到 17 秒。当然我们也提供了RedisMemoryManager实现但明确标注为Deprecated并在 Javadoc 里写清适用场景“仅当 Agent 部署在无状态 Pod 中且容忍 5ms 延迟时使用”。3.3 响应组装如何让 LLM 输出“可解析”而非“可阅读”这是最容易被忽略的坑。很多团队直接把 LLM 的自然语言回复如“根据分析建议您选择方案 A因为它的成本更低”当最终结果返回给前端。但下游系统如订单创建服务需要的是结构化数据{selectedPlan: A, estimatedCost: 299.0, reason: cost_lower}。JavaManus 的ResponseComposer强制要求所有 Agent 必须配置一个OutputSchema它是一个 JSON Schema 片段描述期望的输出结构。框架在调用 LLM 前会把这个 schema 注入 system prompt你是一个严谨的AI助手必须严格按以下JSON Schema输出不要任何额外文字 { type: object, properties: { selectedPlan: {type: string}, estimatedCost: {type: number}, reason: {type: string} }, required: [selectedPlan, estimatedCost, reason] }然后ResponseComposer用 Jackson 的JsonNode解析响应若解析失败如 LLM 返回了 Markdown 表格则触发FallbackStrategy要么重试加更严格的 temperature0.1要么调用备用规则引擎兜底。我们还内置了SchemaValidator能检测 schema 是否存在循环引用、是否过度嵌套超过 5 层会警告避免前端解析崩溃。某保险公司的核保 Agent 就因此受益原来人工核保员要从 LLM 的长篇回复里手动摘录 7 个字段现在前端直接response.selectedPlan就拿到值错误率从 12% 降到 0.3%。4. 实操过程从空 Maven 项目到可运行 Agent 的 7 个关键步骤4.1 初始化工程为什么用 JDK 17 而不是 21新建 Maven 项目时pom.xml的maven.compiler.source和maven.compiler.target必须设为17。不是因为 JDK 21 不行而是因为 JDK 21 的虚拟线程Virtual Threads在 Agent 场景下反而有害。我们做过对比测试在 2000 并发下JDK 17 的ThreadPoolExecutor处理ToolExecutor调用平均延迟 42ms而 JDK 21 启用-XX:UseVirtualThreads后由于大量短生命周期的虚拟线程频繁创建销毁GC 压力激增P95 延迟飙升到 187ms。更糟的是某些老版本 JDBC 驱动如 MySQL Connector/J 8.0.28不兼容虚拟线程会抛出UnsupportedOperationException。所以 JavaManus 明确要求运行时JDK 17.0.1OpenJDK 或 Alibaba Dragonwell构建时Maven 3.8.6禁用--enable-preview依赖管理用spring-boot-starter-parent3.2.0 作为 parent它已内置 Jakarta EE 9 兼容性pom.xml关键片段如下properties java.version17/java.version spring-boot.version3.2.0/spring-boot.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency !-- SQLite 驱动 -- dependency groupIdorg.xerial/groupId artifactIdsqlite-jdbc/artifactId version3.42.0.0/version /dependency /dependencies注意h2仅用于单元测试生产环境用 SQLite所以h2的 scope 是runtime避免打入主 Jar。4.2 定义第一个 Agent从AgentTask注解开始JavaManus 不要求你写 XML 或 YAML 配置。Agent 的元信息全部通过注解声明。创建一个CreditAssessmentAgentComponent AgentTask( id credit-assessment-v2, description 基于用户征信报告和收入证明评估贷款申请可行性, inputSchema {type:object,properties:{userId:{type:string}},required:[userId]} , outputSchema {type:object,properties:{approved:{type:boolean},reason:{type:string}},required:[approved,reason]} ) public class CreditAssessmentAgent implements AgentHandler { Override public MonoAgentResponse handle(AgentContext context) { // 1. 从 context 提取 userId String userId context.getInput().get(userId).asText(); // 2. 构建执行计划这里简化为固定三步 AgentPlan plan AgentPlan.builder() .maxSteps(3) .addStep(Step.builder() .id(fetch_report) .tool(creditReportTool) .param(userId, userId) .timeoutMs(3000) .build()) .addStep(Step.builder() .id(verify_income) .tool(incomeVerificationTool) .param(userId, userId) .timeoutMs(2000) .build()) .finalStep(compose_result) .build(); // 3. 启动执行引擎 return agentRunner.execute(plan, context); } }关键点解析AgentTask的id是全局唯一标识会被注册到AgentRegistry供 API 网关路由inputSchema和outputSchema是纯字符串但框架会在启动时用JsonSchemaFactory验证其合法性非法 schema 直接抛BeanCreationException避免运行时才发现AgentHandler.handle()方法返回MonoAgentResponse天然支持 WebFlux无需额外适配agentRunner.execute()是框架提供的模板方法它会自动处理 plan 解析、上下文透传、异常熔断。4.3 实现首个工具creditReportTool的完整代码工具类必须实现ToolProvider接口并标注ToolTool(name creditReportTool, version 1.0) Component public class CreditReportTool implements ToolProvider { private final WebClient webClient; // 注入 Spring 的 WebClient public CreditReportTool(WebClient.Builder builder) { this.webClient builder.baseUrl(https://api.credit-data.com/v1).build(); } Override public MonoToolResultCreditReport execute(ToolInvocation invocation) { // 1. 解析参数 String userId invocation.getParam(userId, String.class); if (userId null || userId.isBlank()) { return Mono.error(new IllegalArgumentException(userId is required)); } // 2. 构建请求 HttpRequest request HttpRequest.newBuilder() .uri(URI.create(/report?userId userId)) .header(Authorization, Bearer getApiKey()) .GET() .build(); // 3. 发起 HTTP 调用这里用 JDK 11 HttpClient避免 Spring WebFlux 依赖 return Mono.fromFuture(HttpClient.newHttpClient() .sendAsync(request, HttpResponse.BodyHandlers.ofString()) .thenApply(response - { if (response.statusCode() ! 200) { throw new RuntimeException(Credit API returned response.statusCode()); } try { CreditReport report new ObjectMapper().readValue(response.body(), CreditReport.class); return ToolResult.success(report) .withMetadata(api_latency_ms, response.elapsed().toMillis()); } catch (Exception e) { throw new RuntimeException(Failed to parse credit report, e); } })); } private String getApiKey() { // 从 Spring Config Server 或 Vault 获取此处简化 return sk-xxx; } }这里有几个硬核细节用 JDK 原生HttpClient而非 SpringWebClient是为了避免工具层和框架层的 Reactive 链路耦合保证工具可独立测试ToolResult.success(report)会自动记录调用耗时、状态码等元数据这些数据最终会进入ResponseComposer的决策依据getApiKey()方法看似简单实则我们预留了SecretResolverSPI支持从 HashiCorp Vault、阿里云 KMS、甚至本地加密文件读取密钥密钥变更无需重启应用。4.4 配置执行引擎application.yml的 5 个必配项application.yml不是可选的以下 5 项必须显式配置否则启动失败javamanus: # 1. Agent 执行超时全局兜底 global-timeout-ms: 45000 # 2. 工具调用重试策略指数退避 tool-retry: max-attempts: 3 base-delay-ms: 100 # 3. 内存管理器类型可选 memory-manager-type: sqlite | redis | in-memory memory-manager-type: sqlite # 4. SQLite 数据库路径绝对路径或 classpath: sqlite-db-path: /var/lib/javamanus/memory.db # 5. 日志级别DEBUG 可看到每步执行详情 log-level: INFO # Spring Boot Actuator 端点暴露 management: endpoints: web: exposure: include: health,metrics,prometheus,tools特别说明sqlite-db-path如果是容器化部署必须用宿主机绝对路径如/data/javamanus/memory.db避免容器重启后数据丢失如果是开发环境可设为classpath:memory.db框架会自动从src/main/resources加载预置的空 DB 文件我们禁止使用相对路径如./memory.db因为不同启动方式IDE、Jar、Docker的工作目录不同极易导致“找不到 DB”错误。4.5 启动与验证curl 一条命令跑通全流程启动应用后用 curl 发送请求curl -X POST http://localhost:8080/agent/execute \ -H Content-Type: application/json \ -d { agentId: credit-assessment-v2, input: {userId: U123456789} }预期返回已格式化{ status: SUCCESS, output: { approved: true, reason: credit_score_high }, executionTrace: [ { stepId: fetch_report, tool: creditReportTool, status: SUCCESS, durationMs: 284, metadata: {api_latency_ms: 271} }, { stepId: verify_income, tool: incomeVerificationTool, status: SUCCESS, durationMs: 192 } ], requestId: req_abc123 }关键验证点executionTrace数组必须包含所有执行步骤且顺序与AgentPlan一致durationMs是框架层统计的端到端耗时metadata.api_latency_ms是工具层上报的子耗时两者差值即为框架调度开销本例中 284-27113ms符合预期requestId会自动注入到所有日志行中方便全链路追踪。4.6 监控埋点如何用 Micrometer 暴露 12 个关键指标JavaManus 内置 Micrometer 支持无需额外配置。启动后访问http://localhost:8080/actuator/metrics你会看到这些指标指标名类型说明标签示例agent.execution.durationTimerAgent 总执行耗时agentIdcredit-assessment-v2,statusSUCCESSagent.step.durationTimer单步执行耗时stepIdfetch_report,toolcreditReportToolagent.tool.invocationCounter工具调用次数toolcreditReportTool,resultSUCCESSagent.memory.writeTimer内存写入耗时dbsqlite,operationINSERTagent.router.decisionCounter路由决策次数routerdefault,outcomefetch_report我们特意把agent.step.duration的标签设计为stepIdtool而不是agentIdstepId是因为同一个工具如creditReportTool可能被多个 Agent 复用这样能聚合分析工具本身的性能瓶颈。某客户就靠agent.tool.invocation{toolcreditReportTool,resultTIMEOUT}这个指标发现了第三方征信 API 在每日 10:00-10:15 的固定超时及时联系对方优化避免了批量贷款审批失败。4.7 灰度发布如何让新 Agent 版本只对 5% 用户生效JavaManus 的AgentRouter支持动态权重路由。在application.yml中添加javamanus: agent-router: strategy: weighted weights: credit-assessment-v1: 95 credit-assessment-v2: 5然后在AgentHandler实现中用ConditionalOnProperty控制 Bean 加载Configuration public class AgentConfig { Bean ConditionalOnProperty(name javamanus.agent-router.weights.credit-assessment-v2, havingValue 5) public AgentHandler creditAssessmentV2() { return new CreditAssessmentAgent(); // v2 版本 } Bean ConditionalOnProperty(name javamanus.agent-router.weights.credit-assessment-v1, havingValue 95) public AgentHandler creditAssessmentV1() { return new LegacyCreditAssessmentAgent(); // v1 版本 } }当运维同学把weights.credit-assessment-v2从5改成100时Spring Boot 的RefreshScope会自动刷新 Bean无需重启。我们实测从修改配置到新版本生效平均耗时 2.3 秒。5. 常见问题与排查技巧实录那些踩过的坑比文档还管用5.1 问题速查表高频报错与根因定位报错信息根本原因排查命令解决方案AgentExecutionException: No TaskRouter found for contextTaskRouter实现类未加Component或未被 Spring 扫描到curl http://localhost:8080/actuator/beans | grep taskRouter检查类路径是否在ComponentScan范围内或显式ImportToolExecutionException: Failed to resolve tool xxxTool注解的name与ToolSpec中的工具 ID 不一致大小写敏感curl http://localhost:8080/actuator/tools查看返回的工具列表确认 name 和 version 完全匹配MemoryManagerException: Database is lockedSQLite WAL 模式未启用或多个进程同时写同一 DB 文件ls -l /var/lib/javamanus/memory.db*确认application.yml中sqlite-db-path是绝对路径且PRAGMA journal_modeWAL已执行AgentResponseException: Output schema validation failedLLM 返回了非 JSON 格式内容如带 json 代码块查看agent.execution.duration指标中statusVALIDATION_ERROR的数量在ResponseComposer中启用strictSchemaValidationfalse或调整 LLM 的 system promptNullPointerException at AgentContext.getInput()AgentContext构造时未传入inputMap或input为 nullcurl -v http://localhost:8080/agent/execute -d {input:null}在AgentHandler.handle()开头加Objects.requireNonNull(context.getInput())断言5.2 独家避坑技巧来自 3 个真实项目的血泪总结技巧一永远不要在ToolProvider.execute()里做日志打印某物流客户在deliveryRouteTool的execute()方法里写了log.info(Routing for {}, orderId)结果在 1000 QPS 下日志 I/O 成为瓶颈CPU 使用率飙到 98%。正确做法是框架层统一在ToolExecutor模板方法中记录INFO级日志含工具名、参数摘要、耗时工具实现只在ERROR级打印异常堆栈。我们为此专门写了ToolLogger工具类它会自动脱敏敏感参数如手机号、身份证号避免日志泄露。技巧二AgentPlan的maxSteps不是“最多执行几步”而是“最多创建几个执行节点”初版文档写错了导致某银行客户把maxSteps设为 1结果所有 Agent 都只执行第一步就结束。实际上maxSteps限制的是ExecutionGraph的节点总数包括fallback节点。比如 plan 里定义了 3 步但每步都有onFailure那实际最多可能创建 6 个节点。我们在 2.1.3 版本中把参数名改为maxExecutionNodes并加了 Javadoc 强调“This counts all nodes in the execution graph, including fallback and retry nodes.”技巧三AgentTask的id必须符合 DNS 子域名规范某客户用了id my-agent_v2结果在 Kubernetes Ingress 路由时被截断因为-和_在 DNS 中含义不同。我们强制校验id只能包含小写字母、数字、-且不能以-开头或结尾。启动时若校验失败抛出IllegalAgentIdException并提示“Agent ID must match regex a-z0-9 ?”。这个正则来自 RFC 1123是 Kubernetes Service 名称的规范。5.3 性能调优清单从 200 QPS 到 5000 QPS 的 6 个关键参数参数默认值生产建议值调优效果风险提示javamanus.global-timeout-ms3000045