diff --git a/liteflow-react-agent/README.md b/liteflow-react-agent/README.md
new file mode 100644
index 000000000..ca0763b9d
--- /dev/null
+++ b/liteflow-react-agent/README.md
@@ -0,0 +1,21 @@
+# liteflow-react-agent
+
+为 LiteFlow 提供基于 agentscope-java 的 ReAct Agent 组件能力。通过继承 `ReActAgentComponent` 即可在 EL 规则中作为普通 node 编排。
+
+## 子模块
+
+| 模块 | 说明 |
+|------|------|
+| `liteflow-react-agent-core` | 抽象类、Session/Workspace 管理、内置受管工具 |
+| `liteflow-react-agent-openai` | OpenAI + 兼容协议（DeepSeek/Kimi/GLM/MiniMax） |
+| `liteflow-react-agent-anthropic` | Anthropic Claude |
+| `liteflow-react-agent-gemini` | Google Gemini |
+| `liteflow-react-agent-dashscope` | 阿里云 DashScope / Qwen |
+
+## 配置
+
+见 [core 模块 README](./liteflow-react-agent-core/README.md)。
+
+## Java 版本
+
+所有 react-agent 子模块要求 **Java 21+**（agentscope-java 要求）。LiteFlow 主工程仍然保持 Java 8 兼容。
\ No newline at end of file
diff --git a/liteflow-react-agent/liteflow-react-agent-anthropic/README.md b/liteflow-react-agent/liteflow-react-agent-anthropic/README.md
new file mode 100644
index 000000000..fd547f2df
--- /dev/null
+++ b/liteflow-react-agent/liteflow-react-agent-anthropic/README.md
@@ -0,0 +1,9 @@
+# liteflow-react-agent-anthropic
+
+Anthropic Claude 模型支持。
+
+## 使用
+
+```java
+AnthropicChatModel model = AnthropicModelFactory.of(apiKey, "claude-sonnet-4-6");
+```
\ No newline at end of file
diff --git a/liteflow-react-agent/liteflow-react-agent-core/README.md b/liteflow-react-agent/liteflow-react-agent-core/README.md
new file mode 100644
index 000000000..ff311dabc
--- /dev/null
+++ b/liteflow-react-agent/liteflow-react-agent-core/README.md
@@ -0,0 +1,73 @@
+# liteflow-react-agent-core
+
+## 快速上手
+
+### 1. 添加依赖（选择至少一个平台模块）
+
+```xml
+
+ com.yomahub
+ liteflow-react-agent-openai
+ ${liteflow.version}
+
+```
+
+### 2. 配置
+
+```yaml
+liteflow:
+ agent:
+ workspace:
+ root: /var/lib/liteflow/agent-workspaces
+ shell:
+ mode: whitelist
+ whitelist: [ls, cat, grep]
+ openai-compatible:
+ deepseek:
+ api-key: ${DEEPSEEK_API_KEY}
+ base-url: https://api.deepseek.com/v1
+```
+
+### 3. 定义 Agent
+
+```java
+@LiteflowComponent("reviewAgent")
+public class ReviewAgent extends ReActAgentComponent {
+ @Override protected Model buildModel(ReActAgentContext ctx) {
+ return OpenAICompatiblePresets.deepseek(
+ agentConfig().getOpenaiCompatible().get("deepseek").getApiKey(),
+ "deepseek-chat"
+ );
+ }
+ @Override protected String systemPrompt(ReActAgentContext ctx) { return "你是审核专家"; }
+ @Override protected String userPrompt(ReActAgentContext ctx) {
+ return ctx.getSlot().getRequestData(String.class);
+ }
+}
+```
+
+### 4. EL 编排
+
+```xml
+
+ THEN(prepare, reviewAgent, notify);
+
+```
+
+## 核心概念
+
+- **Session**：由 `resolveSessionId` 决定；默认 `slot.getRequestId()`（一次性）。覆写后可复用 memory 与 workspace 实现多轮对话。
+- **Workspace**：每 session 一个目录，在 `liteflow.agent.workspace.root` 之下。内置 `WorkspaceFileTools` 强制路径围栏。
+- **Shell**：`ManagedShellCommandTool` 按 `liteflow.agent.shell.mode` 做 whitelist/blacklist/disabled 校验，首 token 不在策略内即拒绝。
+
+## 可选覆写
+
+| 方法 | 默认行为 | 说明 |
+|------|----------|------|
+| `tools(ctx)` | 空列表 | 注册自定义 agentscope @Tool 对象 |
+| `resolveSessionId(slot)` | `slot.getRequestId()` | 覆写以实现多轮对话 |
+| `maxIterations()` | 配置文件默认值 (15) | ReAct 最大推理轮数 |
+| `enableShellTool()` | true | 是否启用受管 shell 工具 |
+| `enableWorkspaceFileTools()` | true | 是否启用受管文件工具 |
+| `hooks(ctx)` | 空列表 | agentscope Hook 列表 |
+| `handleReply(reply, ctx)` | 写入 slot.responseData | 自定义回复处理 |
\ No newline at end of file
diff --git a/liteflow-react-agent/liteflow-react-agent-dashscope/README.md b/liteflow-react-agent/liteflow-react-agent-dashscope/README.md
new file mode 100644
index 000000000..477ad7690
--- /dev/null
+++ b/liteflow-react-agent/liteflow-react-agent-dashscope/README.md
@@ -0,0 +1,9 @@
+# liteflow-react-agent-dashscope
+
+阿里云 DashScope / Qwen 模型支持。
+
+## 使用
+
+```java
+DashScopeChatModel model = DashScopeModelFactory.of(apiKey, "qwen3-max");
+```
\ No newline at end of file
diff --git a/liteflow-react-agent/liteflow-react-agent-gemini/README.md b/liteflow-react-agent/liteflow-react-agent-gemini/README.md
new file mode 100644
index 000000000..fd600bb64
--- /dev/null
+++ b/liteflow-react-agent/liteflow-react-agent-gemini/README.md
@@ -0,0 +1,13 @@
+# liteflow-react-agent-gemini
+
+Google Gemini 模型支持。
+
+## 使用
+
+```java
+// 基础
+GeminiChatModel m1 = GeminiModelFactory.of(apiKey, "gemini-3-flash-preview");
+
+// 带 thinking level
+GeminiChatModel m2 = GeminiModelFactory.of(apiKey, "gemini-3-flash-preview", "high");
+```
\ No newline at end of file
diff --git a/liteflow-react-agent/liteflow-react-agent-openai/README.md b/liteflow-react-agent/liteflow-react-agent-openai/README.md
new file mode 100644
index 000000000..7f424c417
--- /dev/null
+++ b/liteflow-react-agent/liteflow-react-agent-openai/README.md
@@ -0,0 +1,25 @@
+# liteflow-react-agent-openai
+
+OpenAI 及 OpenAI 兼容协议厂商支持。
+
+## 使用
+
+```java
+// 标准 OpenAI
+OpenAIChatModel m1 = OpenAIModelFactory.openai(apiKey, "gpt-4o-mini");
+
+// DeepSeek
+OpenAIChatModel m2 = OpenAICompatiblePresets.deepseek(apiKey, "deepseek-chat");
+
+// Kimi (Moonshot)
+OpenAIChatModel m3 = OpenAICompatiblePresets.kimi(apiKey, "moonshot-v1-8k");
+
+// GLM (智谱)
+OpenAIChatModel m4 = OpenAICompatiblePresets.glm(apiKey, "glm-4");
+
+// MiniMax
+OpenAIChatModel m5 = OpenAICompatiblePresets.minimax(apiKey, "abab6.5s-chat");
+
+// 自定义 OpenAI 兼容端点
+OpenAIChatModel m6 = OpenAIModelFactory.custom(apiKey, "https://your.own/v1", "your-model");
+```
\ No newline at end of file