flowchart TB
    subgraph "Agent智能体系统架构"
        subgraph "输入层"
            Query[用户查询]
            History[对话历史]
            Config[Agent配置]
        end
        
        subgraph "AgentRunner层"
            Factory{AgentRunner<br/>Factory}
            CoT[CoT Agent<br/>ReAct框架]
            FC[Function Call Agent]
            Base[BaseAgentRunner]
        end
        
        subgraph "推理循环"
            Iterator[迭代控制器]
            Prompt[提示词构建]
            LLM[LLM调用]
            Parser[输出解析]
        end
        
        subgraph "工具管理"
            ToolMgr[ToolManager]
            Builtin[内置工具]
            Dataset[知识库工具]
            API[API工具]
            Plugin[插件工具]
        end
        
        subgraph "工具执行"
            Engine[ToolEngine]
            Validate[参数校验]
            Invoke[工具调用]
            Format[结果格式化]
        end
        
        subgraph "记忆管理"
            Memory[TokenBufferMemory]
            MsgHistory[消息历史]
            Scratchpad[推理记录]
        end
        
        subgraph "输出层"
            Stream[流式管理]
            Thought[推理步骤]
            Answer[最终答案]
        end
    end
    
    Query --> Factory
    History --> Factory
    Config --> Factory
    
    Factory --> CoT
    Factory --> FC
    CoT --> Base
    FC --> Base
    
    Base --> Iterator
    Iterator --> Prompt
    Prompt --> LLM
    LLM --> Parser
    
    Parser -->|需要工具| ToolMgr
    Parser -->|最终答案| Answer
    
    ToolMgr --> Builtin
    ToolMgr --> Dataset
    ToolMgr --> API
    ToolMgr --> Plugin
    
    Builtin --> Engine
    Dataset --> Engine
    API --> Engine
    Plugin --> Engine
    
    Engine --> Validate
    Validate --> Invoke
    Invoke --> Format
    Format -->|结果| Iterator
    
    Iterator --> Memory
    Memory --> MsgHistory
    Memory --> Scratchpad
    
    Iterator --> Stream
    Stream --> Thought
    Stream --> Answer

iteration = 0
while iteration < max_iteration:
    # 构建提示词
    prompt = self._build_prompt(query, history, scratchpad)
    
    # 调用LLM
    response = self.llm.invoke(prompt)
    
    # 解析输出
    parsed = self.parser.parse(response)
    
    # 执行工具或返回答案
    if parsed.has_tool_call:
        result = self.tool_engine.invoke(parsed.tool_call)
        scratchpad.add_observation(result)
        iteration += 1
    else:
        return parsed.answer

classDiagram
    class AgentEntity {
        +str provider
        +str model
        +AgentStrategy strategy
        +int max_iteration
        +list~AgentToolEntity~ tools
        +PromptTemplate prompt_template
    }
    
    class AgentStrategy {
        <<enumeration>>
        FUNCTION_CALL
        REACT
    }
    
    class AgentToolEntity {
        +str provider_type
        +str provider_id
        +str tool_name
        +dict tool_parameters
    }
    
    AgentEntity --> AgentStrategy
    AgentEntity "1" *-- "*" AgentToolEntity

classDiagram
    class AgentScratchpadUnit {
        <<abstract>>
        +str id
        +int position
    }
    
    class AgentThought {
        +str thought
        +str action
        +dict action_input
    }
    
    class AgentObservation {
        +str tool_name
        +str tool_input
        +str tool_output
    }
    
    class AgentAnswer {
        +str answer
    }
    
    AgentScratchpadUnit <|-- AgentThought
    AgentScratchpadUnit <|-- AgentObservation
    AgentScratchpadUnit <|-- AgentAnswer

def run(
    self,
    query: str,
    inputs: dict = None,
) -> Generator[AgentThought | AgentAnswer, None, None]:
    """执行CoT Agent推理"""

def run(self, query: str, inputs: dict = None):
    # 1. 初始化
    iteration = 0
    scratchpad = AgentScratchpad()
    
    # 2. 推理循环
    while iteration < self.max_iteration:
        # 构建提示词
        prompt = self._build_prompt(query, scratchpad)
        
        # 调用LLM
        response = self.llm_client.invoke(prompt)
        
        # 解析输出
        parsed = self.output_parser.parse(response)
        
        # 输出推理步骤
        yield AgentThought(
            thought=parsed.thought,
            action=parsed.action,
            action_input=parsed.action_input,
        )
        
        # 判断是否需要工具调用
        if parsed.action == "Final Answer":
            yield AgentAnswer(answer=parsed.action_input)
            break
        
        # 执行工具调用
        tool_result = self.tool_engine.invoke(
            tool_name=parsed.action,
            tool_input=parsed.action_input,
        )
        
        # 记录观察结果
        observation = AgentObservation(
            tool_name=parsed.action,
            tool_input=str(parsed.action_input),
            tool_output=tool_result,
        )
        scratchpad.add(observation)
        yield observation
        
        iteration += 1
    
    # 达到最大迭代次数
    if iteration >= self.max_iteration:
        yield AgentAnswer(answer="抱歉，我无法在规定步骤内完成任务。")

AgentChatApp.run()
  └─> AgentRunnerFactory.create()
       └─> CotAgentRunner().__init__()
            ├─> _init_tools()
            ├─> _init_memory()
            └─> run()
                 ├─> _build_prompt()
                 ├─> llm_client.invoke()
                 ├─> output_parser.parse()
                 └─> tool_engine.invoke()

class AgentChatApp:
    def run(self, query: str, conversation_id: str = None):
        # 创建Agent Runner
        agent_runner = AgentRunnerFactory.create(
            tenant_id=self.tenant_id,
            app_config=self.app_config,
            model_config=self.model_config,
            agent_config=self.agent_config,
            conversation=conversation,
        )
        
        # 执行Agent
        for event in agent_runner.run(query=query):
            # 转换为App事件
            app_event = self._convert_to_app_event(event)
            yield app_event

def run(self, query: str, inputs: dict = None):
    # 1. 初始化
    iteration = 0
    messages = self._build_messages(query)
    
    # 2. 推理循环
    while iteration < self.max_iteration:
        # 调用LLM（带工具定义）
        response = self.llm_client.invoke(
            messages=messages,
            tools=self._get_tool_schemas(),
            tool_choice="auto",
        )
        
        # 判断是否有工具调用
        if response.tool_calls:
            # 并行执行工具调用
            tool_results = []
            for tool_call in response.tool_calls:
                result = self.tool_engine.invoke(
                    tool_name=tool_call.function.name,
                    tool_input=json.loads(tool_call.function.arguments),
                )
                tool_results.append({
                    "tool_call_id": tool_call.id,
                    "role": "tool",
                    "content": result,
                })
                
                # 输出工具调用
                yield AgentThought(
                    action=tool_call.function.name,
                    action_input=tool_call.function.arguments,
                )
            
            # 将结果添加到消息列表
            messages.extend(tool_results)
            iteration += 1
        else:
            # 返回最终答案
            yield AgentAnswer(answer=response.content)
            break

sequenceDiagram
    autonumber
    participant U as 用户
    participant App as AgentChatApp
    participant CoT as CotAgentRunner
    participant LLM as LLM Client
    participant Parser as OutputParser
    participant TE as ToolEngine
    participant Tool as 工具
    
    U->>App: 发送查询
    App->>CoT: run(query)
    
    loop 推理循环 (max_iteration)
        CoT->>CoT: _build_prompt()
        CoT->>LLM: invoke(prompt)
        LLM-->>CoT: 响应文本
        
        CoT->>Parser: parse(response)
        Parser-->>CoT: {thought, action, action_input}
        
        CoT-->>App: yield AgentThought
        
        alt 最终答案
            CoT-->>App: yield AgentAnswer
        else 工具调用
            CoT->>TE: invoke(tool_name, tool_input)
            TE->>Tool: 执行工具
            Tool-->>TE: 工具结果
            TE-->>CoT: formatted_result
            
            CoT->>CoT: 记录Observation
            CoT-->>App: yield AgentObservation
        end
    end
    
    App-->>U: 返回结果

sequenceDiagram
    autonumber
    participant App as AgentChatApp
    participant FC as FunctionCallRunner
    participant LLM as LLM Client
    participant TE as ToolEngine
    
    App->>FC: run(query)
    FC->>FC: _build_messages()
    
    loop 推理循环
        FC->>LLM: invoke(messages, tools)
        LLM-->>FC: response with tool_calls
        
        alt 有工具调用
            par 并行执行工具
                FC->>TE: invoke(tool1)
                TE-->>FC: result1
            and
                FC->>TE: invoke(tool2)
                TE-->>FC: result2
            end
            
            FC->>FC: 添加tool结果到messages
            FC-->>App: yield AgentThought
        else 无工具调用
            FC-->>App: yield AgentAnswer
        end
    end

[系统提示]
You are a helpful assistant with access to tools.

Available tools:
- google_search: Search Google for information
  Parameters: {"query": "string"}
- calculator: Perform calculations
  Parameters: {"expression": "string"}

[推理格式]
Use the following format:

Thought: your reasoning about what to do
Action: tool name to use
Action Input: tool parameters in JSON
Observation: tool result

[历史对话]
User: ...
Assistant: ...

[当前Scratchpad]
Thought: ...
Action: ...
Observation: ...

[当前查询]
User: {query}

def _build_prompt(self, query: str, scratchpad: AgentScratchpad):
    # 1. 系统提示
    system_prompt = self._get_system_prompt()
    
    # 2. 工具描述
    tools_desc = self._format_tools_description()
    
    # 3. 推理格式说明
    format_instruction = self._get_format_instruction()
    
    # 4. 历史对话
    history = self.memory.get_history()
    
    # 5. 当前Scratchpad
    scratchpad_text = self._format_scratchpad(scratchpad)
    
    # 6. 组合提示词
    prompt = f"{system_prompt}\n\n{tools_desc}\n\n{format_instruction}\n\n{history}\n\n{scratchpad_text}\n\nUser: {query}"
    
    return prompt

class CotOutputParser:
    def parse(self, text: str) -> ParsedOutput:
        # 使用正则提取各个部分
        thought_match = re.search(r"Thought:\s*(.+?)(?=\nAction:|$)", text, re.DOTALL)
        action_match = re.search(r"Action:\s*(.+?)(?=\nAction Input:|$)", text)
        action_input_match = re.search(r"Action Input:\s*(.+?)(?=\n|$)", text, re.DOTALL)
        
        # 提取内容
        thought = thought_match.group(1).strip() if thought_match else ""
        action = action_match.group(1).strip() if action_match else ""
        action_input_str = action_input_match.group(1).strip() if action_input_match else "{}"
        
        # 解析JSON参数
        try:
            action_input = json.loads(action_input_str)
        except:
            action_input = {"input": action_input_str}
        
        return ParsedOutput(
            thought=thought,
            action=action,
            action_input=action_input,
        )

class TokenBufferMemory:
    def __init__(self, model_context_window: int):
        self.messages = []
        self.max_tokens = model_context_window - 1000  # 预留空间
    
    def add_message(self, role: str, content: str):
        self.messages.append({"role": role, "content": content})
        self._trim_if_needed()
    
    def _trim_if_needed(self):
        # 计算当前token数
        total_tokens = sum(self._count_tokens(m["content"]) for m in self.messages)
        
        # 如果超出限制，删除最老的消息（保留系统消息）
        while total_tokens > self.max_tokens and len(self.messages) > 2:
            # 跳过第一条（系统消息）
            removed = self.messages.pop(1)
            total_tokens -= self._count_tokens(removed["content"])

agent_config:
  provider: "openai"
  model: "gpt-4"
  strategy: "function_call"
  max_iteration: 5
  tools:
    - provider_type: "builtin"
      provider_id: "google"
      tool_name: "google_search"
    - provider_type: "builtin"
      provider_id: "calculator"
      tool_name: "calculate"
    - provider_type: "builtin"
      provider_id: "weather"
      tool_name: "get_weather"
  prompt_template: |
    You are a helpful assistant with access to tools.
    Use tools when necessary to answer user questions.

# 创建Agent应用
app = AgentChatApp(app_config, model_config, agent_config)

# 执行查询
query = "What's the weather in San Francisco and calculate 25% tip on $80?"

for event in app.run(query):
    if isinstance(event, AgentThought):
        print(f"Thought: {event.thought}")
        print(f"Action: {event.action}({event.action_input})")
    elif isinstance(event, AgentObservation):
        print(f"Observation: {event.tool_output}")
    elif isinstance(event, AgentAnswer):
        print(f"Answer: {event.answer}")

agent_config:
  strategy: "react"
  max_iteration: 3
  tools:
    - provider_type: "dataset_retrieval"
      dataset_ids: ["kb-001", "kb-002"]
      retrieval_config:
        top_k: 3
        score_threshold: 0.7

User: 公司的年假政策是什么？

Thought: 需要查询公司知识库获取年假政策
Action: dataset_retrieval
Action Input: {"query": "年假政策"}
Observation: 找到3个相关文档：
1. 员工享有15天带薪年假...
2. 年假需要提前申请...
3. 未使用年假可转至下年...

Thought: 已获取相关信息，可以回答
Action: Final Answer
Answer: 根据公司政策，员工享有15天带薪年假...