企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习

com.openjiuwen.core.application.schema是 openJiuwen agent-core-java 应用层 Agent 的配置模型集合，它统一承载 ReAct Agent、工作流 Agent 的身份信息、模型配置、提示模板、插件与工作流引用、记忆配置与运行约束。本文以该包及其 8 个 Schema 类型为主体，结合仓库源码逐字段讲解配置含义、JSON 序列化命名规则与运行时校验行为，帮助读者正确编写 Agent 配置、理解配置到运行时行为的映射关系，并可直接套用文中的 JSON 配置示例。

一、包定位与设计思路

在源码树 core/src/main/java/com/openjiuwen/core/application/schema 中，该包定义了应用层 Agent 使用的全部配置对象。它承担三重职责：

1. 配置聚合：把 Agent 运行所需的模型、提示词、工具、插件、工作流、记忆、约束等分散要素聚合为单个配置对象；
2. 兼容别名：部分类型（如ConstrainConfig、ReActAgentConfig、AgentMemoryConfig）是对既有 legacy 类型或共享 memory 模块类型的兼容别名，避免应用层 API 直接依赖底层实现类，同时保持运行时模型一致；
3. 序列化契约：通过 Jackson 的@JsonProperty与@JsonAlias建立"下划线为主、驼峰为辅"的双命名 JSON 入口，兼容不同风格的外部配置。

文档同时强调：这批类型大量使用 Lombok（@Data、@Builder、@SuperBuilder、@NoArgsConstructor、@AllArgsConstructor）生成 getter、setter 与 builder，因此文档只列出源码显式声明的字段与方法。

二、类型总览

三、约束配置 ConstrainConfig：会话窗口与迭代上限

ConstrainConfig描述应用层 Agent 的会话窗口与最大迭代约束，同时提供下划线和驼峰两套 JSON 字段入口。

3.1 常量与字段

3.2 校验行为

• 两个字段都必须大于0，非法值抛出IllegalArgumentException；
• 异常消息中包含当前输入值。从父类源码 ConstrainConfig.java 可见其消息格式为：Input should be greater than 0 [type=greater_than, input_value=%d, input_type=int]，与 Python 侧 pydantic 的校验提示保持一致；
• Builder 构造器会把null恢复为默认值，再对非空整数执行大于0的校验——也就是说，reservedMaxChatRounds(null)不会报错，而是回落为10。

3.3 窗口推导示例

reservedMaxChatRounds = 3时，LlmAgent会将上下文窗口上限推导为6条消息（3 * 2）。这一点与LlmAgentConfig.getContextWindowLimit()的语义衔接：上下文窗口上限直接取自reservedMaxChatRounds。

四、默认响应 DefaultResponse：意图未命中时的兜底

DefaultResponse描述工作流意图未命中时的兜底回复，仅两个字段：

源码使用@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor生成常规访问器与构造器（见 DefaultResponse.java）。在WorkflowAgentConfig中，defaultResponse默认通过DefaultResponse.builder().build()构造一个空实例；当用户输入未能匹配任何工作流时，Agent 便以此作为回复。文档记载ApplicationTranslationRegressionTest验证了 JSONdefault_response结构可以正确映射到本类。

五、引用型 Schema：PluginSchema 与 WorkflowSchema

5.1 PluginSchema：插件/工具引用

PluginSchema描述应用层 Agent 配置中的一个工具/插件引用：

从源码（PluginSchema.java）看，inputs使用LinkedHashMap保持输入参数的声明顺序，pluginId通过@JsonProperty("plugin_id")+@JsonAlias("pluginId")实现双命名映射。ApplicationTranslationRegressionTest验证了plugin_id与inputs能正确映射到本类。

5.2 WorkflowSchema：工作流引用

WorkflowSchema描述应用层配置中的单个工作流引用：

需要注意本类型的一个"内外有别"设计（见 WorkflowSchema.java）：

• 对外序列化字段名是inputs（@JsonProperty("inputs")），内部属性名是inputParams；
• 额外提供了getInputs()与setInputs()作为和inputParams等价的访问入口（两者均标注@JsonIgnore，避免与@JsonProperty("inputs")产生序列化冲突）；
• setInputs对null做了防御，统一回落为新的空LinkedHashMap。

六、主配置对象一：LlmAgentConfig 与 ReActAgentConfig

LlmAgentConfig聚合了 ReAct Agent 运行所需的身份信息、模型配置、提示模板、工作流或插件引用、记忆配置与约束参数，是应用层最核心的配置对象。

6.1 完整字段表

6.2 上下文窗口上限的计算入口

LlmAgentConfig显式声明了getContextWindowLimit()方法，且该方法上标注了@JsonProperty("context_window_limit")，说明它同时也是一个可序列化导出的计算属性：

• 当constrain非空时，返回constrain.getReservedMaxChatRounds()；
• 否则返回硬编码默认值10（对应ConstrainConfig.DEFAULT_RESERVED_MAX_CHAT_ROUNDS）。

6.3 ReActAgentConfig：语义化派生类型

ReActAgentConfig extends LlmAgentConfig，本身没有新增字段或方法，只是把"这是一个 ReAct Agent 配置"的语义显式化（源码见 ReActAgentConfig.java）：

• 使用@SuperBuilder（支持父类字段的链式构建）、@NoArgsConstructor、@EqualsAndHashCode(callSuper = true)；
• 通过ReActAgentConfig.builder()创建实例时，默认控制器类型仍为ControllerType.REACT_CONTROLLER，并继承getContextWindowLimit()的行为。

七、主配置对象二：WorkflowAgentConfig

WorkflowAgentConfig聚合了工作流 Agent 的模型、工作流集合、默认响应与全局变量配置。

7.1 完整字段表

与LlmAgentConfig相比，WorkflowAgentConfig默认控制器类型是WORKFLOW_CONTROLLER，且用startWorkflow/endWorkflow表达"起始工作流"与"结束工作流"的入口/出口定义；defaultResponse默认是空构建的DefaultResponse实例（而非null）。ApplicationTranslationRegressionTest验证了start_workflow、end_workflow、global_variables、global_params与default_response的 JSON 映射。

八、记忆配置 AgentMemoryConfig：共享 memory 模块的入口

应用层AgentMemoryConfig直接继承com.openjiuwen.core.memory.config.AgentMemoryConfig，本身不新增任何字段或方法，仅作为"应用层配置对象统一引用"的兼容入口。LlmAgentConfig会将它作为agentMemoryConfig字段暴露给应用层 Agent。

共享 memory 模块实现（AgentMemoryConfig.java）提供了以下 JSON 字段（统一为下划线命名），这些配置在编写 ReAct Agent 的记忆策略时直接生效：

此外它还提供了isEnableFragmentMemory()便捷方法（enableUserProfile || enableSemanticMemory || enableEpisodicMemory），用于判断任一碎片化记忆开关是否开启，供已迁移的 memory 调用点复用。

九、控制器类型枚举：ControllerType 的序列化取值

LlmAgentConfig与WorkflowAgentConfig中的controllerType字段类型为com.openjiuwen.core.common.constants.ControllerType（源码见 ControllerType.java），该枚举定义了三个取值：

枚举通过@JsonValue（序列化输出value）与@JsonCreator（反序列化时按 value 匹配，找不到则回落为UNDEFINED）完成双向映射。因此配置 JSON 中写"controller_type": "react"或"controller_type": "workflow"即可正确映射，而LlmAgent运行时会要求 ReAct Agent 的该字段保持为react。

十、双命名 JSON 机制：下划线为主、驼峰为辅

贯穿全部 Schema 的序列化约定是：对外统一输出下划线命名（@JsonProperty），反序列化时同时接受下划线名与驼峰别名（@JsonAlias）。受影响的字段包括：

• ConstrainConfig：reserved_max_chat_rounds、max_iteration
• LlmAgentConfig：controller_type、prompt_template_name、prompt_template、memory_scope_id、agent_memory_config、context_engine_config、default_response、context_window_limit
• PluginSchema：plugin_id
• WorkflowSchema：inputs
• WorkflowAgentConfig：controller_type、prompt_template、start_workflow、end_workflow、global_variables、global_params、default_response、context_engine_config

这意味着：编写 JSON 配置时两种风格均可被正确解析，但序列化（如导出配置）时统一呈现为下划线风格，保证配置文件的跨语言一致性（该包类型整体镜像了 Python 侧openjiuwen/core/single_agent/legacy/config.py与schema.py的配置模型）。

十一、实战：一份可落地的 JSON 配置示例

结合上述字段与默认值，一个完整的 ReAct Agent 配置（对应LlmAgentConfig/ReActAgentConfig）可以写成：

{ "id": "customer-service-agent", "version": "1.0", "description": "基于 ReAct 的客服智能体", "controller_type": "react", "model": { "name": "qwen-plus", "base_url": "https://your-endpoint/v1", "api_key": "${OPENAI_API_KEY}" }, "prompt_template_name": "react_system_prompt", "prompt_template": [], "tools": ["web_search", "order_query"], "plugins": [ { "id": "plugin-001", "name": "order-query-plugin", "plugin_id": "order_query_plugin_v1", "inputs": { "order_id": {"type": "string", "description": "订单号"} } } ], "workflows": [], "memory_scope_id": "user-scope", "agent_memory_config": { "enable_long_term_mem": true, "enable_semantic_memory": true, "enable_episodic_memory": false }, "constrain": { "reserved_max_chat_rounds": 10, "max_iteration": 5 }, "default_response": { "type": "text", "text": "抱歉，暂时无法处理该请求。" } }

对应的工作流 Agent 配置（WorkflowAgentConfig）则在controller_type上使用"workflow"，并补充start_workflow、end_workflow、global_variables、global_params等字段：

{ "id": "workflow-agent", "version": "1.0", "controller_type": "workflow", "model": {"name": "qwen-plus"}, "start_workflow": {"id": "wf-start", "name": "入口工作流", "version": "1.0", "inputs": {}}, "end_workflow": {"id": "wf-end", "name": "收尾工作流", "version": "1.0", "inputs": {}}, "workflows": [ {"id": "wf-qa", "name": "问答工作流", "version": "1.0", "inputs": {"question": {"type": "string"}}} ], "global_variables": [{"name": "session_id", "type": "string"}], "global_params": {"timezone": "Asia/Shanghai"}, "constrain": {"reserved_max_chat_rounds": 10, "max_iteration": 5}, "default_response": {"type": "text", "text": "未找到匹配的工作流。"} }

配置时需注意两条运行时约束：constrain下两个整数必须大于0（否则抛出带输入值的IllegalArgumentException）；ReAct Agent 的controller_type必须保持为"react"。

十二、小结

com.openjiuwen.core.application.schema为 openJiuwen agent-core-java 提供了完整、自洽的应用层配置模型：LlmAgentConfig（含ReActAgentConfig派生类型）与WorkflowAgentConfig是两类 Agent 的配置总入口，ConstrainConfig、DefaultResponse、AgentMemoryConfig分别负责迭代/窗口约束、兜底回复与记忆策略，PluginSchema、WorkflowSchema则统一了插件与工作流的引用描述。理解"下划线输出、双名解析"的序列化约定与"默认值 + 正数校验"的约束行为，即可稳定地编写、导入与导出 Agent 配置，并准确预判配置到运行时行为（如reservedMaxChatRounds * 2的上下文窗口推导）的映射结果。

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习