flowchart TB
    subgraph Clients["客户端层"]
        WebUI["Web 界面<br/>WebSocket 实时通信"]
        APIClient["REST API 客户端<br/>HTTP/SSE"]
        Orchestrator["AI Orchestrator<br/>上游服务"]
        AdminPanel["管理面板<br/>任务监控"]
    end

    subgraph EntryLayer["接入层"]
        HTTPServer["HTTP Server<br/>FastAPI + Uvicorn<br/>4 workers / 100 concurrency"]
        WSServer["WebSocket Server<br/>实时双向通信"]
        Middleware["中间件栈<br/>CORS / Metrics / Auth"]
    end

    subgraph CoreEngine["核心引擎层"]
        AgentCore["Agent Engine Core<br/>任务调度 / 执行器管理"]
        TaskManager["Task Manager<br/>Redis 持久化 / 状态跟踪"]
        ExecutorFactory["Executor Factory<br/>策略模式 / 执行器选择"]
    end

    subgraph Executors["执行器层"]
        ReActExec["ReAct Executor<br/>Reasoning + Acting<br/>最大 50 步"]
        PlanExec["Plan-Execute Executor<br/>两阶段计划-执行<br/>失败重试"]
        ReflexionExec["Reflexion Executor<br/>自我反思 / 迭代优化<br/>最多 3 次迭代"]
        SimpleExec["Simple Executor<br/>单次调用 / 快速响应"]
    end

    subgraph Components["核心组件层"]
        ToolRegistry["Dynamic Tool Registry<br/>5+ 内置工具<br/>动态注册 / 沙箱执行"]
        UnifiedMemory["Unified Memory Manager<br/>短期 Redis + 长期 Milvus<br/>重要性评估 / 自动存储"]
        LLMAdapter["Multi-LLM Adapter<br/>统一接口 / 4+ 提供商<br/>超时 60s / 重试 3 次"]
    end

    subgraph MemoryLayer["记忆层"]
        ShortMem["短期记忆<br/>Redis List<br/>TTL 1h / 最多 20 条"]
        LongMem["长期记忆<br/>Milvus 向量库<br/>时间衰减 / 语义检索"]
        TaskCache["任务缓存<br/>Redis Hash<br/>状态持久化 7 天"]
    end

    subgraph LLMProviders["LLM 提供商"]
        OpenAI["OpenAI<br/>GPT-4 / GPT-3.5<br/>延迟 1-3s"]
        Claude["Claude<br/>Claude-3-opus/sonnet<br/>延迟 2-4s"]
        Qwen["通义千问<br/>Qwen-turbo/plus<br/>延迟 1-2s"]
        Ollama["Ollama<br/>本地模型<br/>延迟 0.5-1s"]
    end

    subgraph Tools["工具生态"]
        SearchTool["搜索工具<br/>Google Search API<br/>延迟 1-2s"]
        CalcTool["计算器工具<br/>Python Sandbox<br/>延迟 <100ms"]
        KBTool["知识库工具<br/>RAG 检索<br/>延迟 200-500ms"]
        WeatherTool["天气工具<br/>外部 API<br/>延迟 500ms-1s"]
        TimeTool["时间工具<br/>本地计算<br/>延迟 <10ms"]
    end

    subgraph Infrastructure["基础设施"]
        Redis["Redis<br/>短期存储 / 任务状态<br/>内存模式 / 持久化可选"]
        Milvus["Milvus<br/>向量数据库<br/>HNSW 索引 / 余弦相似度"]
        Nacos["Nacos<br/>配置中心 / 服务发现<br/>动态配置更新"]
        Prometheus["Prometheus<br/>指标采集 / 监控告警<br/>/metrics 端点"]
    end

    subgraph Monitoring["可观测性"]
        Logs["结构化日志<br/>JSON 格式 / 分级输出"]
        Metrics["业务指标<br/>任务成功率 / 执行时间<br/>工具调用统计"]
        Tracing["调用追踪<br/>分布式追踪 / 链路分析"]
    end

    %% 客户端 -> 接入层
    Clients --> EntryLayer
    WebUI --> WSServer
    APIClient --> HTTPServer
    Orchestrator --> HTTPServer
    AdminPanel --> HTTPServer

    %% 接入层 -> 核心引擎
    HTTPServer --> Middleware
    WSServer --> Middleware
    Middleware --> AgentCore
    Middleware --> TaskManager

    %% 核心引擎 -> 执行器
    AgentCore --> ExecutorFactory
    ExecutorFactory --> ReActExec
    ExecutorFactory --> PlanExec
    ExecutorFactory --> ReflexionExec
    ExecutorFactory --> SimpleExec

    %% 执行器 -> 核心组件
    ReActExec --> ToolRegistry
    ReActExec --> UnifiedMemory
    ReActExec --> LLMAdapter

    PlanExec --> ToolRegistry
    PlanExec --> LLMAdapter

    ReflexionExec --> ToolRegistry
    ReflexionExec --> UnifiedMemory
    ReflexionExec --> LLMAdapter

    SimpleExec --> LLMAdapter

    %% 核心组件 -> 下游
    ToolRegistry --> Tools
    UnifiedMemory --> MemoryLayer
    LLMAdapter --> LLMProviders

    %% 记忆层 -> 基础设施
    ShortMem --> Redis
    LongMem --> Milvus
    TaskCache --> Redis
    TaskManager --> Redis

    %% 核心组件 -> 基础设施
    AgentCore --> Nacos
    AgentCore --> Prometheus

    %% 监控
    Middleware --> Monitoring
    AgentCore --> Monitoring
    Executors --> Monitoring

    style Clients fill:#e3f2fd
    style EntryLayer fill:#fff3e0
    style CoreEngine fill:#ffebee
    style Executors fill:#f3e5f5
    style Components fill:#e8f5e9
    style MemoryLayer fill:#e0f7fa
    style LLMProviders fill:#fff9c4
    style Tools fill:#fce4ec
    style Infrastructure fill:#e0f2f1
    style Monitoring fill:#f3e5f5

客户端 HTTP 请求
  ↓
FastAPI Router (main.py:execute_task)
  ├─ 请求参数提取：task, mode, max_steps, tools, conversation_id, tenant_id
  ├─ 参数验证：task 非空，mode 有效值，max_steps 范围检查
  └─ 错误处理：HTTPException(400/503/500)
  ↓
AgentEngine.execute() (app/core/agent_engine.py:70)
  ├─ 统计计数：stats["total_tasks"] += 1
  ├─ 记录开始时间：start_time = time.time()
  │
  ├─ 【步骤 1】获取执行器
  │   ↓ executors.get(mode)
  │   └─ 返回：ReActExecutor / PlanExecuteExecutor / ReflexionExecutor
  │
  ├─ 【步骤 2】加载记忆（如果有 conversation_id）
  │   ↓ memory_manager.get_memory(conversation_id)
  │   └─ UnifiedMemoryManager.recall_memories()
  │       ├─ 短期记忆：Redis LRANGE memory:short:{conversation_id}
  │       │   └─ 返回：最近 20 条消息（FIFO）
  │       ├─ 长期记忆：Milvus.search(query_embedding, top_k=5)
  │       │   ├─ 向量化查询：EmbeddingService.embed(query)
  │       │   ├─ 向量检索：Milvus HNSW 索引检索
  │       │   └─ 返回：Top-5 相似记忆（score, content, days_ago）
  │       └─ 融合记忆：按 score 排序，返回综合结果
  │
  ├─ 【步骤 3】过滤工具
  │   ↓ _filter_tools(tools)
  │   ├─ 获取所有工具：tool_registry.list_tools()
  │   ├─ 过滤逻辑：
  │   │   └─ tools=None → 返回全部工具
  │   │   └─ tools=[...] → 返回指定工具子集
  │   └─ 返回：List[ToolDefinition]
  │
  ├─ 【步骤 4】执行任务
  │   ↓ executor.execute(task, max_steps, available_tools, memory)
  │   │
  │   ├─ 【ReAct 模式详细流程】
  │   │   ↓ ReActExecutor.execute()
  │   │   ├─ 构建初始 Prompt
  │   │   │   ├─ 任务描述：task
  │   │   │   ├─ 工具列表：_format_tools(available_tools)
  │   │   │   ├─ 历史记忆：_format_memory(memory)
  │   │   │   └─ ReAct 指令：思考→动作→观察循环模板
  │   │   │
  │   │   └─ ReAct 循环（while current_step < max_steps）
  │   │       ├─ current_step += 1
  │   │       │
  │   │       ├─ 【子步骤 4.1】LLM 推理
  │   │       │   ↓ llm_client.generate(prompt, temperature=0.2, max_tokens=1000)
  │   │       │   ├─ OpenAIClient.complete()
  │   │       │   │   ├─ 格式化消息：List[Message]
  │   │       │   │   ├─ API 调用：client.chat.completions.create()
  │   │       │   │   │   └─ 超时：60s，重试：3 次
  │   │       │   │   ├─ 解析响应：choice.message.content
  │   │       │   │   └─ 统计 Token：prompt_tokens, completion_tokens
  │   │       │   │
  │   │       │   └─ 返回：react_output（包含思考、动作、动作输入）
  │   │       │
  │   │       ├─ 【子步骤 4.2】解析输出
  │   │       │   ↓ _parse_react_output(react_output)
  │   │       │   ├─ 正则提取思考：r"思考[:：]\s*(.*?)(?=\n|动作|最终答案|$)"
  │   │       │   ├─ 正则提取最终答案：r"最终答案[:：]\s*(.*?)$"
  │   │       │   ├─ 正则提取动作：r"动作[:：]\s*(\w+)"
  │   │       │   ├─ 正则提取动作输入：r"动作输入[:：]\s*(.*?)(?=\n|$)"
  │   │       │   └─ 返回：(thought, action, action_input, final_answer)
  │   │       │
  │   │       ├─ 【子步骤 4.3】判断终止条件
  │   │       │   ├─ 如果 final_answer 存在
  │   │       │   │   └─ 记录步骤，退出循环（break）
  │   │       │   │
  │   │       │   └─ 如果 action 存在
  │   │       │       ↓ 继续执行工具
  │   │       │
  │   │       ├─ 【子步骤 4.4】执行工具
  │   │       │   ↓ _execute_tool(action, action_input, available_tools)
  │   │       │   ├─ tool_registry.execute_tool(tool_name, tool_input)
  │   │       │   │   ├─ 查找工具：tools[tool_name]
  │   │       │   │   ├─ 参数校验：JSON Schema 验证
  │   │       │   │   ├─ 执行工具：tool_instance.execute(**parameters)
  │   │       │   │   │   │
  │   │       │   │   │   ├─ 【SearchTool 示例】
  │   │       │   │   │   │   ├─ API 调用：Google Search API
  │   │       │   │   │   │   ├─ 超时：30s
  │   │       │   │   │   │   └─ 返回：搜索结果摘要（前 3 条）
  │   │       │   │   │   │
  │   │       │   │   │   ├─ 【CalculatorTool 示例】
  │   │       │   │   │   │   ├─ 表达式安全检查：禁止 import、eval 等
  │   │       │   │   │   │   ├─ Python eval()：沙箱环境
  │   │       │   │   │   │   └─ 返回：计算结果
  │   │       │   │   │   │
  │   │       │   │   │   └─ 【KnowledgeBaseTool 示例】
  │   │       │   │   │       ├─ 向量化查询：EmbeddingService.embed(query)
  │   │       │   │   │       ├─ Milvus 检索：search(collection="kb", top_k=3)
  │   │       │   │   │       └─ 返回：相关文档片段
  │   │       │   │   │
  │   │       │   │   └─ 返回：tool_result（字符串）或异常信息
  │   │       │   │
  │   │       │   └─ observation = tool_result
  │   │       │
  │   │       ├─ 【子步骤 4.5】更新 Prompt
  │   │       │   └─ prompt += f"\n{react_output}\n观察: {observation}\n\n继续思考："
  │   │       │
  │   │       └─ 【子步骤 4.6】记录步骤
  │   │           └─ steps.append({step, thought, action, action_input, observation})
  │   │
  │   └─ 返回：ExecutionResult
  │       ├─ status: "success" / "max_steps_reached" / "failed"
  │       ├─ steps: List[StepInfo]（完整步骤列表）
  │       ├─ step_count: len(steps)
  │       ├─ tool_call_count: sum(1 for s in steps if "action" in s)
  │       └─ final_answer: str
  │
  ├─ 【步骤 5】保存记忆
  │   ↓ memory_manager.add_to_memory(conversation_id, task, result)
  │   ├─ 构造记忆条目：
  │   │   └─ {task, result, steps, timestamp}
  │   │
  │   ├─ 存储到短期记忆
  │   │   ├─ Redis LPUSH memory:short:{conversation_id}
  │   │   └─ Redis EXPIRE memory:short:{conversation_id} 3600
  │   │
  │   └─ 评估重要性（如果 auto_save_to_long_term=true）
  │       ├─ _evaluate_importance(memory_item)
  │       │   └─ LLM 评分机制：importance_score (0.0-1.0)
  │       │
  │       └─ 如果 importance_score > 0.6
  │           ├─ 向量化：_generate_embedding(memory_item)
  │           │   └─ EmbeddingService.embed(content)
  │           │
  │           └─ 存储到 Milvus
  │               └─ insert(collection="agent_memory", embedding, metadata)
  │
  ├─ 【步骤 6】更新统计信息
  │   ├─ execution_time = time.time() - start_time
  │   ├─ stats["successful_tasks"] += 1
  │   ├─ stats["total_steps"] += step_count
  │   ├─ stats["total_tool_calls"] += tool_call_count
  │   ├─ stats["total_execution_time"] += execution_time
  │   └─ stats["avg_execution_time"] = total_execution_time / successful_tasks
  │
  ├─ 【步骤 7】持久化任务状态
  │   ↓ task_manager.save_task(result)
  │   ├─ 序列化：_serialize_result(result) → JSON
  │   ├─ Redis SETEX agent:task:{task_id} 604800 {json_data}（7 天 TTL）
  │   └─ Redis ZADD agent:tasks:list {task_id} {timestamp}
  │
  └─ 返回：ExecuteResponse
      ├─ task: str
      ├─ mode: str
      ├─ status: str
      ├─ steps: List[StepInfo]
      ├─ step_count: int
      ├─ tool_call_count: int
      ├─ final_answer: str
      ├─ execution_time: float
      └─ conversation_id: str
  ↓
FastAPI 响应：200 OK (application/json)
  ↓
客户端接收完整结果

@app.post("/execute")
async def execute_task(request: dict):
    global agent_engine

    if not agent_engine:
        raise HTTPException(status_code=503, detail="Service not initialized")

    task = request.get("task")
    if not task:
        raise HTTPException(status_code=400, detail="Task is required")

    try:
        result = await agent_engine.execute(
            task=task,
            mode=request.get("mode", "react"),
            max_steps=request.get("max_steps", 10),
            tools=request.get("tools"),
            conversation_id=request.get("conversation_id"),
            tenant_id=request.get("tenant_id"),
        )
        return result
    except Exception as e:
        logger.error(f"Error executing task: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))

async def execute(
    self,
    task: str,
    mode: str = "react",
    max_steps: int = 10,
    tools: List[str] = None,
    conversation_id: str = None,
    tenant_id: str = None,
) -> Dict:
    start_time = time.time()
    self.stats["total_tasks"] += 1

    try:
        # 1. 获取执行器
        executor = self.executors.get(mode)
        if not executor:
            raise ValueError(f"Unknown execution mode: {mode}")

        # 2. 获取记忆
        memory = None
        if conversation_id:
            memory = await self.memory_manager.get_memory(conversation_id)

        # 3. 过滤工具
        available_tools = self._filter_tools(tools)

        # 4. 执行任务
        result = await executor.execute(
            task=task,
            max_steps=max_steps,
            available_tools=available_tools,
            memory=memory,
        )

        # 5. 更新记忆
        if conversation_id:
            await self.memory_manager.add_to_memory(
                conversation_id, task=task, result=result
            )

        # 6. 更新统计
        execution_time = time.time() - start_time
        self.stats["successful_tasks"] += 1
        self.stats["total_steps"] += result.get("step_count", 0)
        self.stats["total_tool_calls"] += result.get("tool_call_count", 0)
        self.stats["total_execution_time"] += execution_time
        self.stats["avg_execution_time"] = (
            self.stats["total_execution_time"] / self.stats["successful_tasks"]
        )

        return {
            **result,
            "task": task,
            "mode": mode,
            "execution_time": execution_time,
            "conversation_id": conversation_id,
        }

    except Exception as e:
        self.stats["failed_tasks"] += 1
        logger.error(f"Error executing task: {e}", exc_info=True)
        raise

async def execute(
    self,
    task: str,
    max_steps: int = 10,
    available_tools: List[Dict] = None,
    memory: Dict = None,
) -> Dict:
    steps = []
    current_step = 0

    # 构建初始 Prompt
    prompt = self._build_initial_prompt(task, available_tools, memory)

    while current_step < max_steps:
        current_step += 1

        # 1. 生成 ReAct 步骤
        react_output = await self.llm_client.generate(
            prompt=prompt, temperature=0.2, max_tokens=1000
        )

        # 2. 解析输出
        thought, action, action_input, final_answer = self._parse_react_output(react_output)

        step_info = {"step": current_step, "thought": thought}

        # 3. 检查是否完成
        if final_answer:
            step_info["final_answer"] = final_answer
            steps.append(step_info)
            break

        # 4. 执行工具调用
        if action:
            step_info["action"] = action
            step_info["action_input"] = action_input

            observation = await self._execute_tool(action, action_input, available_tools)
            step_info["observation"] = observation

            steps.append(step_info)

            # 更新 Prompt
            prompt += f"\n{react_output}\n观察: {observation}\n\n继续思考："
        else:
            step_info["error"] = "Failed to parse action"
            steps.append(step_info)
            break

    return {
        "status": "success" if final_answer else "max_steps_reached",
        "steps": steps,
        "step_count": len(steps),
        "tool_call_count": sum(1 for s in steps if "action" in s),
        "final_answer": final_answer if final_answer else "任务未完成",
    }

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant HTTP as FastAPI<br/>Router
    participant Engine as Agent<br/>Engine
    participant Executor as ReAct<br/>Executor
    participant LLM as LLM<br/>Client
    participant ToolReg as Tool<br/>Registry
    participant Tool as Tool<br/>Instance
    participant Memory as Memory<br/>Manager
    participant Redis as Redis
    participant Milvus as Milvus

    Note over Client,Milvus: 场景：执行"查询北京天气并总结"任务

    Client->>HTTP: POST /execute<br/>{task, mode:react, conversation_id}
    HTTP->>HTTP: 验证参数<br/>检查服务状态

    HTTP->>Engine: execute(task, mode, max_steps, ...)
    Note over Engine: stats["total_tasks"]++<br/>start_time=now()

    Engine->>Engine: 获取执行器<br/>executors.get("react")
    Note over Engine: 返回 ReActExecutor 实例

    alt 有 conversation_id
        Engine->>Memory: get_memory(conversation_id)

        par 并行查询短期和长期记忆
            Memory->>Redis: LRANGE memory:short:{id}<br/>获取最近 20 条
            Redis-->>Memory: [msg1, msg2, ...]
        and
            Memory->>Memory: embed(query)<br/>向量化查询
            Memory->>Milvus: search(embedding, top_k=5)
            Milvus-->>Memory: [相似记忆 Top-5]
        end

        Memory->>Memory: 融合排序<br/>score 降序
        Memory-->>Engine: {short_term, long_term, combined}
    end

    Engine->>Engine: _filter_tools(tools)<br/>获取可用工具列表
    Note over Engine: 返回 [SearchTool, WeatherTool, ...]

    Engine->>Executor: execute(task, max_steps=10, tools, memory)

    Note over Executor: 构建初始 Prompt<br/>任务+工具+记忆+ReAct模板

    rect rgb(255, 245, 230)
        Note over Executor,Tool: ReAct 循环：第 1 步

        Executor->>LLM: generate(prompt, temp=0.2, max_tokens=1000)
        Note over LLM: OpenAI API 调用<br/>GPT-4 推理

        LLM->>LLM: 超时 60s<br/>重试 3 次
        LLM-->>Executor: react_output<br/>"思考:需要查天气 动作:weather_query ..."

        Executor->>Executor: _parse_react_output()<br/>正则提取 thought/action/input
        Note over Executor: thought="需要查天气"<br/>action="weather_query"<br/>action_input='{"city":"北京"}'

        alt 提取到 final_answer
            Note over Executor: 任务完成，退出循环
        else 提取到 action
            Executor->>ToolReg: execute_tool(action, action_input)
            ToolReg->>ToolReg: 查找工具实例<br/>tools["weather_query"]
            ToolReg->>ToolReg: 参数校验<br/>JSON Schema验证

            ToolReg->>Tool: execute(**parameters)
            Note over Tool: WeatherTool 实例
            Tool->>Tool: 调用外部天气 API<br/>超时 30s
            Tool-->>ToolReg: "北京今天晴天，25度"

            ToolReg-->>Executor: observation<br/>"北京今天晴天，25度"

            Executor->>Executor: 更新 Prompt<br/>追加 observation
            Executor->>Executor: steps.append({step:1, thought, action, observation})
        end
    end

    rect rgb(230, 245, 255)
        Note over Executor,Tool: ReAct 循环：第 2 步

        Executor->>LLM: generate(updated_prompt, ...)
        LLM-->>Executor: react_output<br/>"思考:已获取天气 最终答案:..."

        Executor->>Executor: _parse_react_output()
        Note over Executor: final_answer="北京今天晴天..."

        Executor->>Executor: steps.append({step:2, final_answer})
        Note over Executor: 检测到 final_answer<br/>break 循环
    end

    Executor-->>Engine: ExecutionResult<br/>{status:"success", steps:[], step_count:2, ...}

    alt auto_save_to_long_term = true
        Engine->>Memory: add_to_memory(conversation_id, task, result)

        Memory->>Redis: LPUSH memory:short:{id}<br/>EXPIRE 3600
        Redis-->>Memory: OK

        Memory->>LLM: evaluate_importance(memory_item)
        LLM-->>Memory: importance_score=0.75

        alt importance_score > 0.6
            Memory->>Memory: embed(memory_item)
            Memory->>Milvus: insert(embedding, metadata)
            Milvus-->>Memory: OK
        end
    end

    Engine->>Engine: 更新统计信息<br/>stats["successful_tasks"]++<br/>stats["total_steps"]+=2

    opt 任务持久化
        Engine->>Redis: SETEX agent:task:{id} 604800 {json}<br/>ZADD agent:tasks:list {id} {timestamp}
        Redis-->>Engine: OK
    end

    Engine-->>HTTP: ExecuteResponse<br/>{task, mode, status, steps, execution_time, ...}
    HTTP-->>Client: 200 OK<br/>JSON Response

    Note over Client: 客户端接收完整结果<br/>展示任务执行步骤

你是一个智能助手，可以使用以下工具完成任务：
[工具列表]

任务：{task}

请按照以下格式回答：
思考：[你的推理过程]
行动：[工具名称]
行动输入：[工具输入JSON]
观察：[工具执行结果]
... (重复思考-行动-观察循环)
思考：我已经得到最终答案
最终答案：[你的答案]

开始！

任务：{task}

请将任务分解为多个子任务，按执行顺序列出：
1. [子任务1]
2. [子任务2]
3. [子任务3]
...

执行子任务：{subtask}
可用工具：[工具列表]

请选择合适的工具完成子任务。

任务：{task}
执行过程：{steps}
执行结果：{result}

请评估执行结果：
1. 是否完全达成任务目标？
2. 哪些步骤执行得好？
3. 哪些步骤需要改进？
4. 下次执行时应该如何调整策略？

反思：[你的分析]
改进建议：[具体建议]

class Tool:
    name: str              # 工具名称
    description: str       # 工具描述
    parameters: Dict       # 参数schema (JSON Schema格式)

    async def run(self, input: str) -> str:
        """执行工具，返回结果"""
        pass

async def add_to_memory(conversation_id, task, result):
    # 1. 构造记忆条目
    memory_item = {
        "task": task,
        "result": result,
        "steps": result.get("steps"),
        "timestamp": time.time(),
    }

    # 2. 存储到短期记忆（Redis）
    await redis.lpush(f"memory:short:{conversation_id}", json.dumps(memory_item))
    await redis.expire(f"memory:short:{conversation_id}", 3600)

    # 3. 评估重要性，决定是否存储到长期记忆
    importance_score = await self._evaluate_importance(memory_item)
    if importance_score > 0.6:
        # 向量化
        embedding = await self._generate_embedding(memory_item)
        # 存储到Milvus
        await milvus.insert(collection="agent_memory", data={
            "embedding": embedding,
            "metadata": memory_item,
        })

async def get_memory(conversation_id, query=None):
    # 1. 获取短期记忆
    short_term = await redis.lrange(f"memory:short:{conversation_id}", 0, -1)

    # 2. 如果有query，检索相关长期记忆
    long_term = []
    if query:
        query_embedding = await self._generate_embedding(query)
        long_term = await milvus.search(
            collection="agent_memory",
            query_vector=query_embedding,
            limit=5,
        )

    return {
        "short_term": short_term,
        "long_term": long_term,
    }

async def generate(
    prompt: str,
    temperature: float = 0.7,
    max_tokens: int = 2000,
    stop_sequences: List[str] = None,
) -> str:
    """生成文本"""
    pass

async def generate_stream(
    prompt: str,
    temperature: float = 0.7,
    max_tokens: int = 2000,
) -> AsyncIterator[str]:
    """流式生成文本"""
    pass

classDiagram
    class AgentEngine {
        +LLMClient llm_client
        +ToolRegistry tool_registry
        +MemoryManager memory_manager
        +Dict executors
        +Dict stats
        +initialize()
        +execute(task, mode, max_steps, tools) Dict
        +execute_stream(task, mode, max_steps, tools) AsyncIterator
        +_filter_tools(tools) List
    }

    class Executor {
        <<interface>>
        +execute(task, max_steps, tools, memory) Dict
        +execute_stream(task, max_steps, tools, memory) AsyncIterator
    }

    class ReActExecutor {
        +LLMClient llm_client
        +ToolRegistry tool_registry
        +execute(task, max_steps, tools, memory) Dict
        +execute_stream(...) AsyncIterator
        -_build_initial_prompt(task, tools, memory) str
        -_parse_react_output(output) Tuple
        -_execute_tool(tool, input, tools) str
    }

    class PlanExecuteExecutor {
        +LLMClient llm_client
        +ToolRegistry tool_registry
        +execute(task, max_steps, tools, memory) Dict
        +execute_stream(...) AsyncIterator
        -_generate_plan(task) List
        -_execute_step(step, tools) Dict
    }

    class ReflexionExecutor {
        +LLMClient llm_client
        +ToolRegistry tool_registry
        +MemoryManager memory_manager
        +int max_iterations
        +execute(task, max_steps, tools, memory) Dict
        -_evaluate_result(result) float
        -_generate_reflection(task, result) str
    }

    class ToolRegistry {
        +Dict tools
        +initialize()
        +register_tool(tool)
        +list_tools() List
        +execute_tool(tool_name, input) str
    }

    class Tool {
        <<interface>>
        +str name
        +str description
        +Dict parameters
        +run(input) str
    }

    class SearchTool {
        +str name = "search"
        +str description
        +Dict parameters
        +run(query) str
    }

    class CalculatorTool {
        +str name = "calculator"
        +str description
        +Dict parameters
        +run(expression) str
    }

    class MemoryManager {
        +RedisClient redis
        +MilvusClient milvus
        +initialize()
        +get_memory(conversation_id, query) Dict
        +add_to_memory(conversation_id, task, result)
        -_evaluate_importance(item) float
        -_generate_embedding(content) List
    }

    class Memory {
        +str conversation_id
        +List short_term
        +List long_term
        +time.Time updated_at
    }

    class ExecutionResult {
        +str status
        +List steps
        +int step_count
        +int tool_call_count
        +str final_answer
        +float execution_time
    }

    class Step {
        +int step_number
        +str thought
        +str action
        +str action_input
        +str observation
        +str error
    }

    AgentEngine --> Executor
    AgentEngine --> ToolRegistry
    AgentEngine --> MemoryManager

    Executor <|.. ReActExecutor
    Executor <|.. PlanExecuteExecutor
    Executor <|.. ReflexionExecutor

    ReActExecutor --> ToolRegistry
    ReActExecutor --> Memory

    PlanExecuteExecutor --> ToolRegistry

    ReflexionExecutor --> ToolRegistry
    ReflexionExecutor --> MemoryManager
    ReflexionExecutor --> Memory

    ToolRegistry --> Tool
    Tool <|.. SearchTool
    Tool <|.. CalculatorTool

    MemoryManager --> Memory

    Executor ..> ExecutionResult
    ExecutionResult --> Step

class ExecuteRequest(BaseModel):
    task: str                         # 任务描述
    mode: str = "react"               # 执行模式
    max_steps: int = 10               # 最大步骤数
    tools: Optional[List[str]] = None # 可用工具列表
    conversation_id: Optional[str] = None  # 会话ID
    tenant_id: Optional[str] = None   # 租户ID

class ExecuteResponse(BaseModel):
    task: str                         # 任务描述
    mode: str                         # 使用的执行模式
    status: str                       # 执行状态
    steps: List[StepInfo]             # 执行步骤列表
    step_count: int                   # 总步骤数
    tool_call_count: int              # 工具调用次数
    final_answer: str                 # 最终答案
    execution_time: float             # 执行耗时(秒)
    conversation_id: Optional[str]    # 会话ID

class StepInfo(BaseModel):
    step: int                         # 步骤编号
    thought: Optional[str]            # 思考内容
    action: Optional[str]             # 行动(工具名称)
    action_input: Optional[str]       # 行动输入
    observation: Optional[str]        # 观察(工具结果)
    error: Optional[str]              # 错误信息
    final_answer: Optional[str]       # 最终答案(如果有)

# AgentEngine核心执行逻辑
async def execute(
    self,
    task: str,
    mode: str = "react",
    max_steps: int = 10,
    tools: List[str] = None,
    conversation_id: str = None,
    tenant_id: str = None,
) -> Dict:
    start_time = time.time()
    self.stats["total_tasks"] += 1

    try:
        # 1. 获取执行器
        executor = self.executors.get(mode)
        if not executor:
            raise ValueError(f"Unknown execution mode: {mode}")

        # 2. 获取记忆（如果有conversation_id）
        memory = None
        if conversation_id:
            memory = await self.memory_manager.get_memory(conversation_id)

        # 3. 过滤工具
        available_tools = self._filter_tools(tools)

        # 4. 执行任务
        result = await executor.execute(
            task=task,
            max_steps=max_steps,
            available_tools=available_tools,
            memory=memory,
        )

        # 5. 更新记忆
        if conversation_id:
            await self.memory_manager.add_to_memory(
                conversation_id,
                task=task,
                result=result,
            )

        # 6. 更新统计
        execution_time = time.time() - start_time
        self.stats["successful_tasks"] += 1
        self.stats["total_steps"] += result.get("step_count", 0)
        self.stats["total_tool_calls"] += result.get("tool_call_count", 0)
        # （省略平均时间计算）

        # （省略日志记录）

        return {
            **result,
            "task": task,
            "mode": mode,
            "execution_time": execution_time,
            "conversation_id": conversation_id,
        }

    except Exception as e:
        self.stats["failed_tasks"] += 1
        # （省略错误日志）
        raise

# ReActExecutor执行逻辑
async def execute(
    self,
    task: str,
    max_steps: int = 10,
    available_tools: List[Dict] = None,
    memory: Dict = None,
) -> Dict:
    steps = []
    current_step = 0

    # 构建初始Prompt
    prompt = self._build_initial_prompt(task, available_tools, memory)

    while current_step < max_steps:
        current_step += 1
        # （省略日志）

        # 1. 生成ReAct步骤
        react_output = await self.llm_client.generate(
            prompt=prompt,
            temperature=0.2,
            max_tokens=1000,
        )

        # 2. 解析输出
        thought, action, action_input, final_answer = self._parse_react_output(react_output)

        step_info = {
            "step": current_step,
            "thought": thought,
        }

        # 3. 检查是否完成
        if final_answer:
            step_info["final_answer"] = final_answer
            steps.append(step_info)
            # （省略日志）
            break

        # 4. 执行工具调用
        if action:
            step_info["action"] = action
            step_info["action_input"] = action_input

            observation = await self._execute_tool(action, action_input, available_tools)
            step_info["observation"] = observation

            steps.append(step_info)

            # 更新Prompt（添加观察结果）
            prompt += f"\n{react_output}\n观察: {observation}\n\n继续思考："
        else:
            # 无法解析出有效动作
            step_info["error"] = "Failed to parse action"
            steps.append(step_info)
            break

    return {
        "status": "success" if final_answer else "max_steps_reached",
        "steps": steps,
        "step_count": len(steps),
        "tool_call_count": sum(1 for s in steps if "action" in s),
        "final_answer": final_answer if final_answer else "任务未完成",
    }

HTTP Handler (routers/agent.py)
  ↓ 参数验证
execute_task_endpoint
  ↓
AgentEngine.execute
  ↓
  ├─ executors.get(mode) → 获取执行器
  ├─ memory_manager.get_memory(conversation_id) → 加载记忆
  ├─ _filter_tools(tools) → 过滤工具
  │
  ├─ executor.execute(task, max_steps, available_tools, memory)
  │   ↓
  │   ReActExecutor.execute
  │     ↓
  │     ├─ _build_initial_prompt → 构建Prompt
  │     │
  │     └─ Loop (max_steps次)
  │         ├─ llm_client.generate → 调用LLM
  │         ├─ _parse_react_output → 解析输出
  │         ├─ _execute_tool → 执行工具
  │         │   ↓
  │         │   tool_registry.execute_tool(tool_name, tool_input)
  │         │     ↓
  │         │     tool.run(tool_input) → 工具具体执行
  │         │
  │         └─ 判断是否完成 (final_answer存在)
  │
  ├─ memory_manager.add_to_memory → 保存记忆
  │
  └─ 更新统计信息

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant HTTP as FastAPI Server
    participant Engine as AgentEngine
    participant Executor as ReActExecutor
    participant LLM as LLM Client
    participant Tools as Tool Registry
    participant Memory as Memory Manager
    participant Redis as Redis
    participant Milvus as Milvus

    Client->>HTTP: POST /api/v1/agent/execute
    Note over Client,HTTP: {task: "查询北京天气并发送邮件",<br/>mode: "react", max_steps: 10}

    HTTP->>Engine: execute(task, mode, max_steps, ...)

    Engine->>Memory: get_memory(conversation_id)
    Memory->>Redis: LRANGE memory:short:{id}
    Redis-->>Memory: [历史记忆]
    Memory->>Milvus: search(query_embedding) [可选]
    Milvus-->>Memory: [相关长期记忆]
    Memory-->>Engine: {short_term, long_term}

    Engine->>Executor: execute(task, max_steps, tools, memory)

    Note over Executor: 构建初始Prompt<br/>包含任务、工具列表、记忆

    loop ReAct循环 (最多max_steps次)
        Executor->>LLM: generate(prompt)
        Note over LLM: GPT-4推理<br/>生成thought/action/action_input
        LLM-->>Executor: react_output

        Note over Executor: 解析输出<br/>_parse_react_output()

        alt 找到final_answer
            Note over Executor: 任务完成，退出循环
        else 需要执行工具
            Executor->>Tools: execute_tool(tool_name, tool_input)
            Tools->>Tools: 调用具体工具<br/>(SearchTool/CalculatorTool/...)
            Note over Tools: 工具执行<br/>可能调用外部API
            Tools-->>Executor: observation (工具结果)

            Note over Executor: 更新Prompt<br/>添加observation到上下文
        end
    end

    Executor-->>Engine: ExecutionResult<br/>{status, steps, final_answer}

    Engine->>Memory: add_to_memory(conversation_id, task, result)

    Note over Memory: 评估重要性<br/>_evaluate_importance()

    Memory->>Redis: LPUSH memory:short:{id}
    Redis-->>Memory: OK

    alt 重要性 > 0.6
        Memory->>Memory: _generate_embedding(memory_item)
        Memory->>Milvus: insert(embedding, metadata)
        Milvus-->>Memory: OK
    end

    Memory-->>Engine: OK

    Note over Engine: 更新统计信息

    Engine-->>HTTP: ExecuteResponse
    HTTP-->>Client: 200 OK<br/>{status, steps, final_answer, execution_time}

data: {"type": "step_start", "step": 1}

data: {"type": "thought", "content": "我需要查询天气信息"}

data: {"type": "action", "tool": "search", "input": "北京天气"}

data: {"type": "observation", "content": "北京今天晴天，25度"}

data: {"type": "final_answer", "content": "已完成任务"}

data: [DONE]

class ToolListResponse(BaseModel):
    tools: List[ToolInfo]
    total: int

class ToolInfo(BaseModel):
    name: str                    # 工具名称
    description: str             # 工具描述
    parameters: Dict             # 参数schema

class MemoryResponse(BaseModel):
    conversation_id: str
    short_term: List[Dict]       # 短期记忆列表
    long_term: List[Dict]        # 长期记忆列表（如果有query）
    updated_at: str

# app/core/executor/react_executor.py
class ReActExecutor:
    async def execute(self, task, max_steps, available_tools, memory):
        steps = []
        current_step = 0
        prompt = self._build_initial_prompt(task, available_tools, memory)

        while current_step < max_steps:
            current_step += 1

            # 1. LLM 推理生成 ReAct 步骤
            react_output = await self.llm_client.generate(
                prompt=prompt, temperature=0.2, max_tokens=1000
            )

            # 2. 解析输出（thought, action, action_input, final_answer）
            thought, action, action_input, final_answer = \
                self._parse_react_output(react_output)

            # 3. 检查是否完成
            if final_answer:
                step_info["final_answer"] = final_answer
                steps.append(step_info)
                break

            # 4. 执行工具调用
            if action:
                observation = await self._execute_tool(
                    action, action_input, available_tools
                )
                # 5. 更新 Prompt，继续循环
                prompt += f"\n{react_output}\n观察: {observation}\n\n继续思考："

        return {"status": "success" if final_answer else "max_steps_reached",
                "steps": steps, "step_count": len(steps)}