stateDiagram-v2
    [*] --> 创建: Agent(...) 或 @agent 装饰器
    创建 --> 初始化: 配置 LLM、Tools、Memory
    初始化 --> 就绪: create_agent_executor()
    就绪 --> 执行: execute_task(task)
    执行 --> 推理循环: AgentExecutor.invoke()
    推理循环 --> 推理循环: LLM 调用 / 工具执行
    推理循环 --> 完成: 达到 Final Answer
    完成 --> 保存状态: 保存记忆、统计 Token
    保存状态 --> 就绪: 等待下一个任务
    就绪 --> [*]: Crew 执行结束

flowchart TB
    subgraph "上游调用层"
        User[用户/客户端]
        Flow[Flow 引擎<br/>事件驱动流程]
    end

    subgraph "编排层 - Crew"
        CrewKickoff[Crew.kickoff<br/>启动执行]
        CrewExec[Crew._execute_tasks<br/>任务编排]
        ProcessMgr[Process Manager<br/>Sequential/Hierarchical]
        ManagerAgent[Manager Agent<br/>分层流程专用]
    end

    subgraph "任务层 - Task"
        TaskExec[Task.execute_sync/async<br/>任务执行入口]
        TaskCore[Task._execute_core<br/>核心执行逻辑]
        TaskOutput[TaskOutput<br/>结构化输出]
        Guardrail[Guardrail<br/>输出验证]
    end

    subgraph "智能体层 - Agent"
        AgentExec[Agent.execute_task<br/>任务执行]
        AgentExecutor[CrewAgentExecutor<br/>推理循环引擎]
        PromptBuilder[Prompts<br/>提示词构建]

        subgraph "上下文管理"
            MemoryRetrieval[Memory Retrieval<br/>记忆检索]
            KnowledgeRetrieval[Knowledge Retrieval<br/>知识检索]
            ContextBuilder[Context Builder<br/>上下文拼接]
        end
    end

    subgraph "执行引擎层"
        InvokeLoop[_invoke_loop<br/>推理循环]
        LLMCall[LLM.call<br/>模型调用]
        OutputParser[OutputParser<br/>输出解析]
        ActionHandler[Action Handler<br/>动作处理]

        subgraph "工具执行子系统"
            ToolUsage[ToolUsage<br/>工具使用协调]
            ToolCache[CacheHandler<br/>缓存检查]
            ToolInvoke[Tool.invoke<br/>工具执行]
            ToolResult[Tool Result<br/>结果处理]
        end
    end

    subgraph "存储层"
        ShortTermMem[(Short Term Memory<br/>ChromaDB)]
        LongTermMem[(Long Term Memory<br/>SQLite)]
        EntityMem[(Entity Memory<br/>ChromaDB)]
        ExternalMem[(External Memory<br/>Mem0)]
        KnowledgeDB[(Knowledge Base<br/>Vector DB)]
    end

    subgraph "基础设施层"
        RPM[RPM Controller<br/>速率限制]
        TokenCounter[Token Counter<br/>使用统计]
        EventBus[Event Bus<br/>事件总线]
        Security[Security Config<br/>指纹验证]
    end

    User --> CrewKickoff
    Flow --> AgentExec
    CrewKickoff --> CrewExec
    CrewExec --> ProcessMgr
    ProcessMgr --> ManagerAgent
    ProcessMgr --> TaskExec

    TaskExec --> TaskCore
    TaskCore --> AgentExec
    TaskCore --> Guardrail
    TaskCore --> TaskOutput

    AgentExec --> MemoryRetrieval
    AgentExec --> KnowledgeRetrieval
    AgentExec --> ContextBuilder
    AgentExec --> PromptBuilder
    AgentExec --> AgentExecutor

    AgentExecutor --> InvokeLoop
    InvokeLoop --> RPM
    InvokeLoop --> LLMCall
    InvokeLoop --> OutputParser
    OutputParser --> ActionHandler

    ActionHandler --> ToolUsage
    ToolUsage --> ToolCache
    ToolCache --> ToolInvoke
    ToolInvoke --> ToolResult
    ToolResult --> InvokeLoop

    MemoryRetrieval --> ShortTermMem
    MemoryRetrieval --> LongTermMem
    MemoryRetrieval --> EntityMem
    MemoryRetrieval --> ExternalMem
    KnowledgeRetrieval --> KnowledgeDB

    AgentExecutor --> TokenCounter
    AgentExecutor --> EventBus
    ToolUsage --> EventBus
    TaskCore --> EventBus

flowchart TB
    subgraph "Agent 核心层"
        Agent[Agent 类<br/>角色、目标、背景故事]
        BaseAgent[BaseAgent 抽象类<br/>通用属性和方法]
    end

    subgraph "执行引擎层"
        Executor[CrewAgentExecutor<br/>推理循环控制]
        Parser[OutputParser<br/>解析 LLM 输出]
        PromptMgr[Prompts<br/>提示词模板管理]
    end

    subgraph "工具管理层"
        ToolsHandler[ToolsHandler<br/>工具调用协调]
        AgentTools[AgentTools<br/>委托工具]
        CustomTools[自定义工具]
        MCPTools[MCP 工具包装器]
        PlatformTools[平台工具集成]
    end

    subgraph "LLM 层"
        LLM[BaseLLM 抽象层]
        FunctionCallingLLM[Function Calling LLM<br/>工具调用专用]
    end

    subgraph "存储与上下文层"
        Memory[Memory 记忆系统<br/>短期/长期/实体/外部]
        Knowledge[Knowledge 知识库<br/>向量检索]
        CacheHandler[CacheHandler<br/>工具结果缓存]
    end

    subgraph "基础设施层"
        RPMController[RPMController<br/>请求限流]
        TokenCounter[TokenCounterCallback<br/>Token 统计]
        EventBus[EventBus<br/>事件发布]
        Security[SecurityConfig<br/>指纹验证]
    end

    Agent -.继承.-> BaseAgent
    Agent --> Executor
    Agent --> ToolsHandler
    Agent --> Memory
    Agent --> Knowledge
    Agent --> RPMController
    Agent --> Security

    Executor --> Parser
    Executor --> PromptMgr
    Executor --> LLM
    Executor --> FunctionCallingLLM
    Executor --> ToolsHandler
    Executor --> TokenCounter

    ToolsHandler --> AgentTools
    ToolsHandler --> CustomTools
    ToolsHandler --> MCPTools
    ToolsHandler --> PlatformTools
    ToolsHandler --> CacheHandler

    Memory --> EventBus
    Executor --> EventBus

sequenceDiagram
    autonumber
    participant User as 用户
    participant Crew as Crew
    participant Process as Process Manager
    participant Task as Task
    participant Agent as Agent
    participant Executor as AgentExecutor
    participant Event as EventBus

    User->>Crew: kickoff(inputs)
    activate Crew

    Crew->>Event: emit(CrewKickoffStartedEvent)
    Crew->>Crew: 初始化 Agents（设置 i18n、crew 引用）
    Crew->>Agent: set_knowledge(crew_embedder)
    Crew->>Agent: create_agent_executor()

    alt Planning 启用
        Crew->>Crew: _handle_crew_planning()
    end

    Crew->>Process: 选择执行流程

    alt Sequential Process
        Process->>Crew: _run_sequential_process()
    else Hierarchical Process
        Process->>Crew: _run_hierarchical_process()
    end

    Crew->>Crew: _execute_tasks(tasks)

    loop 遍历每个 Task
        Crew->>Crew: _get_agent_to_use(task)
        Crew->>Crew: _prepare_tools(agent, task)
        Crew->>Crew: _get_context(task, task_outputs)

        alt 异步执行
            Crew->>Task: execute_async(agent, context, tools)
        else 同步执行
            Crew->>Task: execute_sync(agent, context, tools)
            activate Task

            Task->>Event: emit(TaskStartedEvent)
            Task->>Agent: execute_task(task, context, tools)
            activate Agent

            Note over Agent: 详细执行流程见下一张图

            Agent-->>Task: return result
            deactivate Agent

            Task->>Task: _export_output(result)
            Task->>Task: 构造 TaskOutput

            alt 有 Guardrail
                loop 每个 Guardrail
                    Task->>Task: _invoke_guardrail_function()
                end
            end

            Task->>Event: emit(TaskCompletedEvent)
            Task-->>Crew: return TaskOutput
            deactivate Task
        end
    end

    Crew->>Crew: _create_crew_output(task_outputs)
    Crew->>Crew: calculate_usage_metrics()
    Crew->>Event: emit(CrewKickoffCompletedEvent)
    Crew-->>User: return CrewOutput
    deactivate Crew

sequenceDiagram
    autonumber
    participant Task as Task
    participant Agent as Agent
    participant Reasoning as Reasoning Handler
    participant Memory as Memory System
    participant Knowledge as Knowledge System
    participant Prompts as Prompts Builder
    participant Executor as AgentExecutor
    participant Event as EventBus

    Task->>Agent: execute_task(task, context, tools)
    activate Agent

    alt 启用推理规划
        Agent->>Reasoning: AgentReasoning.handle_agent_reasoning()
        activate Reasoning
        Reasoning->>Reasoning: 生成初始计划
        Reasoning->>Reasoning: 细化计划步骤
        Reasoning-->>Agent: return ReasoningOutput(plan)
        deactivate Reasoning
        Agent->>Agent: 将 plan 添加到 task.description
    end

    Agent->>Agent: _inject_date_to_task(task)
    Agent->>Agent: task.prompt() → task_prompt

    alt 使用结构化输出
        Agent->>Agent: 生成 output schema
        Agent->>Agent: 添加格式化指令到 task_prompt
    end

    alt 有前序上下文
        Agent->>Agent: 将 context 添加到 task_prompt
    end

    alt 有记忆系统
        Agent->>Event: emit(MemoryRetrievalStartedEvent)
        Agent->>Memory: ContextualMemory.build_context_for_task()
        activate Memory

        Memory->>Memory: 构建检索查询

        par 并行检索多种记忆
            Memory->>Memory: search ShortTermMemory
        and
            Memory->>Memory: search LongTermMemory
        and
            Memory->>Memory: search EntityMemory
        and
            Memory->>Memory: search ExternalMemory
        end

        Memory->>Memory: 合并检索结果
        Memory-->>Agent: return memory_context
        deactivate Memory

        Agent->>Agent: 将 memory_context 添加到 task_prompt
        Agent->>Event: emit(MemoryRetrievalCompletedEvent)
    end

    alt 有知识库
        Agent->>Event: emit(KnowledgeRetrievalStartedEvent)
        Agent->>Agent: _get_knowledge_search_query(task_prompt)
        Agent->>Knowledge: LLM 重写检索查询

        alt Agent 级知识库
            Agent->>Knowledge: agent.knowledge.query([search_query])
            Knowledge-->>Agent: return agent_knowledge_snippets
            Agent->>Agent: 提取知识上下文
            Agent->>Agent: 添加到 task_prompt
        end

        alt Crew 级知识库
            Agent->>Knowledge: crew.query_knowledge([search_query])
            Knowledge-->>Agent: return crew_knowledge_snippets
            Agent->>Agent: 提取知识上下文
            Agent->>Agent: 添加到 task_prompt
        end

        Agent->>Event: emit(KnowledgeRetrievalCompletedEvent)
    end

    Agent->>Agent: create_agent_executor(tools, task)
    Agent->>Prompts: 生成提示词模板
    activate Prompts
    Prompts->>Prompts: 构建系统提示词（角色、工具描述）
    Prompts->>Prompts: 构建用户提示词（任务描述）
    Prompts-->>Agent: return prompt_result
    deactivate Prompts

    alt 有训练数据
        Agent->>Agent: _training_handler(task_prompt)
    else 使用已训练数据
        Agent->>Agent: _use_trained_data(task_prompt)
    end

    alt 配置超时
        Agent->>Agent: _execute_with_timeout(task_prompt, task, timeout)
        Agent->>Executor: 在线程池中执行
    else 无超时
        Agent->>Executor: _execute_without_timeout(task_prompt, task)
    end

    activate Executor
    Note over Executor: 详细推理循环见下一张图
    Executor-->>Agent: return result
    deactivate Executor

    Agent->>Agent: 检查工具最终性标记
    Agent->>Event: emit(AgentExecutionCompletedEvent)
    Agent-->>Task: return result
    deactivate Agent

sequenceDiagram
    autonumber
    participant Executor as AgentExecutor
    participant RPM as RPM Controller
    participant LLM as LLM
    participant Parser as OutputParser
    participant ToolHandler as ToolsHandler
    participant Tool as Tool
    participant Cache as CacheHandler
    participant Memory as Memory
    participant Event as EventBus
    participant Callback as StepCallback

    Executor->>Executor: invoke({"input": task_prompt, ...})
    activate Executor

    Executor->>Executor: 格式化提示词（注入变量）

    alt 使用系统提示词
        Executor->>Executor: 添加 system message
        Executor->>Executor: 添加 user message
    else 单一提示词
        Executor->>Executor: 添加 user message
    end

    Executor->>Executor: _invoke_loop()

    Note over Executor: 进入推理循环

    loop 直到达到 Final Answer 或 max_iter
        Executor->>Executor: iterations += 1

        alt 达到最大迭代次数
            Executor->>Executor: handle_max_iterations_exceeded()
            Executor->>Executor: 返回当前最佳答案
        end

        alt 超过上下文长度
            Executor->>Executor: is_context_length_exceeded()
            Executor->>Executor: handle_context_length()
            Executor->>Executor: 截断历史消息
        end

        Executor->>RPM: enforce_rpm_limit()
        alt 触发限流
            RPM->>RPM: 等待至下一时间窗口
        end

        Executor->>LLM: call(messages, stop=stop_words)
        activate LLM
        Note over LLM: 调用 LLM API<br/>（OpenAI/Anthropic/...）
        LLM-->>Executor: return llm_response
        deactivate LLM

        Executor->>Parser: process_llm_response(llm_response)
        activate Parser

        alt 解析出 Action（工具调用）
            Parser->>Parser: 提取 tool_name, tool_input
            Parser-->>Executor: return AgentAction
        else 解析出 Final Answer
            Parser->>Parser: 提取最终答案
            Parser-->>Executor: return AgentFinish
        else 解析错误
            Parser-->>Executor: raise OutputParserError
        end
        deactivate Parser

        alt 解析出 AgentAction
            Executor->>Executor: execute_tool_and_check_finality()

            Executor->>Event: emit(ToolUsageStartedEvent)

            Executor->>Cache: read(tool_name, tool_input)
            activate Cache
            alt 缓存命中
                Cache-->>Executor: return cached_result
                Note over Executor: 跳过工具执行
            else 缓存未命中
                Cache-->>Executor: return None

                Executor->>Tool: invoke(tool_input)
                activate Tool

                alt 工具执行成功
                    Tool->>Tool: _run(**parsed_args)
                    Tool-->>Executor: return tool_result
                else 工具执行失败
                    Tool-->>Executor: raise ToolException
                    Executor->>Executor: 将错误信息作为 observation
                end
                deactivate Tool

                Executor->>ToolHandler: on_tool_use(calling, output)
                activate ToolHandler
                ToolHandler->>Cache: add(tool_name, tool_input, output)
                ToolHandler->>ToolHandler: last_used_tool = calling
                deactivate ToolHandler
            end
            deactivate Cache

            Executor->>Event: emit(ToolUsageCompletedEvent)

            alt 工具标记 result_as_answer=True
                Executor->>Executor: 直接返回工具结果
            else 继续推理
                Executor->>Executor: 格式化 observation
                Executor->>Executor: 添加 observation 到 messages
            end

            alt 有 step_callback
                Executor->>Callback: step_callback(formatted_answer)
            end

        else 解析出 AgentFinish
            Executor->>Executor: 推理循环结束
        else OutputParserError
            Executor->>Executor: handle_output_parser_exception()
            Executor->>Executor: 添加错误提示到 messages
            Executor->>Executor: 继续循环（重试）
        end

    end

    Note over Executor: 退出推理循环

    alt 需要人工反馈
        Executor->>Executor: _handle_human_feedback()
    end

    Executor->>Memory: _create_short_term_memory(formatted_answer)
    Executor->>Memory: _create_long_term_memory(formatted_answer)
    Executor->>Memory: _create_external_memory(formatted_answer)

    Executor-->>Executor: return {"output": formatted_answer.output}
    deactivate Executor

sequenceDiagram
    autonumber
    participant Executor as AgentExecutor
    participant ToolUsage as ToolUsage
    participant Cache as CacheHandler
    participant Tool as CrewStructuredTool
    participant ToolFunc as Tool Function
    participant Event as EventBus
    participant ToolHandler as ToolsHandler

    Executor->>ToolUsage: 执行工具调用
    activate ToolUsage

    ToolUsage->>ToolUsage: 解析 tool_name 和 tool_input

    alt 使用 Function Calling LLM
        ToolUsage->>ToolUsage: 使用 function_calling_llm 结构化解析
    else 使用标准解析
        ToolUsage->>ToolUsage: 正则表达式解析
    end

    ToolUsage->>Event: emit(ToolUsageStartedEvent)

    ToolUsage->>Cache: read(tool_name, tool_input)
    activate Cache
    alt 缓存命中
        Cache-->>ToolUsage: return cached_result
        ToolUsage->>ToolUsage: from_cache = True
    else 缓存未命中
        Cache-->>ToolUsage: return None
    end
    deactivate Cache

    alt 缓存未命中
        ToolUsage->>Tool: 查找工具实例
        alt 工具不存在
            ToolUsage-->>Executor: return "Tool not found"
        end

        ToolUsage->>Tool: 检查 max_usage_count
        alt 达到使用限制
            Tool-->>ToolUsage: raise ToolUsageLimitExceededError
            ToolUsage-->>Executor: return error message
        end

        ToolUsage->>Tool: invoke(tool_input)
        activate Tool

        Tool->>Tool: _parse_args(tool_input)
        alt 参数为字符串
            Tool->>Tool: 使用 function_calling_llm 解析
        else 参数为字典
            Tool->>Tool: 直接验证
        end

        alt 参数验证失败
            Tool-->>ToolUsage: raise ValidationError
            ToolUsage-->>Executor: return error message
        end

        Tool->>Tool: _increment_usage_count()

        Tool->>ToolFunc: func(**parsed_args)
        activate ToolFunc

        alt 工具执行成功
            ToolFunc-->>Tool: return result
        else 工具执行失败
            ToolFunc-->>Tool: raise Exception
            Tool->>Tool: 捕获异常
            Tool-->>ToolUsage: return error message
        end
        deactivate ToolFunc

        deactivate Tool
    end

    ToolUsage->>ToolUsage: 格式化工具结果

    alt 工具返回字典
        ToolUsage->>ToolUsage: json.dumps(result)
    else 工具返回字符串
        ToolUsage->>ToolUsage: 直接使用
    end

    ToolUsage->>ToolHandler: on_tool_use(calling, output, should_cache)
    activate ToolHandler

    alt should_cache=True 且非 CacheTools
        ToolHandler->>Cache: add(tool_name, tool_input, output)
    end

    ToolHandler->>ToolHandler: last_used_tool = calling
    deactivate ToolHandler

    ToolUsage->>Event: emit(ToolUsageCompletedEvent)

    alt 工具标记 result_as_answer=True
        ToolUsage->>ToolUsage: 设置最终性标记
    end

    ToolUsage-->>Executor: return tool_result
    deactivate ToolUsage

classDiagram
    class BaseAgent {
        <<abstract>>
        +UUID4 id
        +str role
        +str goal
        +str backstory
        +bool cache
        +bool verbose
        +int max_rpm
        +bool allow_delegation
        +list[BaseTool] tools
        +int max_iter
        +Any agent_executor
        +Any llm
        +Any crew
        +I18N i18n
        +CacheHandler cache_handler
        +ToolsHandler tools_handler
        +list[dict] tools_results
        +int max_tokens
        +Knowledge knowledge
        +list[BaseKnowledgeSource] knowledge_sources
        +SecurityConfig security_config
        +list[PlatformAppOrAction] apps
        +list[str] mcps
        +execute_task(task, context, tools)*
        +create_agent_executor(tools)*
        +get_delegation_tools(agents)*
        +interpolate_inputs(inputs)
        +set_cache_handler(cache_handler)
        +copy()
        +set_rpm_controller(rpm_controller)
    }

    class Agent {
        +int max_execution_time
        +Any step_callback
        +bool use_system_prompt
        +str system_template
        +str prompt_template
        +str response_template
        +bool allow_code_execution
        +bool respect_context_window
        +int max_retry_limit
        +bool multimodal
        +bool inject_date
        +str date_format
        +Literal["safe", "unsafe"] code_execution_mode
        +bool reasoning
        +int max_reasoning_attempts
        +EmbedderConfig embedder
        +str agent_knowledge_context
        +str crew_knowledge_context
        +str knowledge_search_query
        +str from_repository
        +GuardrailType guardrail
        +int guardrail_max_retries
        +execute_task(task, context, tools)
        +create_agent_executor(tools, task)
        +get_delegation_tools(agents)
        +get_platform_tools(apps)
        +get_mcp_tools(mcps)
        +get_multimodal_tools()
        +get_code_execution_tools()
        +kickoff(messages, response_format)
        +kickoff_async(messages, response_format)
        -_execute_with_timeout(task_prompt, task, timeout)
        -_execute_without_timeout(task_prompt, task)
        -_get_knowledge_search_query(task_prompt, task)
        -_inject_date_to_task(task)
        -_validate_docker_installation()
    }

    class CrewAgentExecutor {
        +BaseLLM llm
        +Task task
        +Crew crew
        +Agent agent
        +SystemPromptResult | StandardPromptResult prompt
        +int max_iter
        +list[CrewStructuredTool] tools
        +str tools_names
        +list[str] stop
        +str tools_description
        +ToolsHandler tools_handler
        +Any step_callback
        +list[BaseTool] original_tools
        +BaseLLM function_calling_llm
        +bool respect_context_window
        +Callable request_within_rpm_limit
        +list[LLMMessage] messages
        +int iterations
        +invoke(inputs)
        -_invoke_loop()
        -_format_prompt(prompt, inputs)
        -_show_start_logs()
        -_handle_human_feedback(formatted_answer)
        -_create_short_term_memory(formatted_answer)
        -_create_long_term_memory(formatted_answer)
        -_create_external_memory(formatted_answer)
    }

    class ToolsHandler {
        +BaseTool last_used_tool
        +CacheHandler cache
        +handle_tool_call(tool_call, agent, task)
        +on_tool_use(tool_usage)
    }

    class CacheHandler {
        +dict _cache
        +hit(key)
        +read(tool, input)
        +add(tool, input, output)
    }

    BaseAgent <|-- Agent : 继承
    Agent --> CrewAgentExecutor : 使用
    Agent --> ToolsHandler : 使用
    CrewAgentExecutor --> ToolsHandler : 使用
    ToolsHandler --> CacheHandler : 使用

# 方法参数
class ExecuteTaskParams:
    task: Task                           # 要执行的任务
    context: Optional[str] = None        # 来自前序任务的上下文
    tools: Optional[list[BaseTool]] = None  # 任务特定的工具列表

# 返回值为 LLM 生成的原始字符串
# 经过后续处理后封装为 TaskOutput
return_value: Any  # 实际为 str，但类型标注为 Any

def execute_task(
    self,
    task: Task,
    context: str | None = None,
    tools: list[BaseTool] | None = None,
) -> Any:
    """执行任务的核心方法"""

    # 1. 启用推理规划（如果配置）
    if self.reasoning:
        reasoning_handler = AgentReasoning(task=task, agent=self)
        reasoning_output = reasoning_handler.handle_agent_reasoning()
        task.description += f"\n\nReasoning Plan:\n{reasoning_output.plan.plan}"

    # 2. 注入日期到任务描述（如果配置）
    self._inject_date_to_task(task)

    # 3. 构建任务提示词
    task_prompt = task.prompt()

    # 4. 添加输出格式指令（如果使用结构化输出）
    if task.output_json or task.output_pydantic:
        schema = generate_model_description(task.output_json or task.output_pydantic)
        task_prompt += self.i18n.slice("formatted_task_instructions").format(
            output_format=schema
        )

    # 5. 添加上下文（如果有）
    if context:
        task_prompt = self.i18n.slice("task_with_context").format(
            task=task_prompt, context=context
        )

    # 6. 检索记忆并添加到提示词
    if self._is_any_available_memory():
        memory = contextual_memory.build_context_for_task(task, context or "")
        task_prompt += self.i18n.slice("memory").format(memory=memory)

    # 7. 检索知识并添加到提示词
    if self.knowledge or (self.crew and self.crew.knowledge):
        self.knowledge_search_query = self._get_knowledge_search_query(task_prompt, task)
        if self.knowledge_search_query:
            # 检索 Agent 级知识
            if self.knowledge:
                agent_knowledge_snippets = self.knowledge.query([self.knowledge_search_query])
                self.agent_knowledge_context = extract_knowledge_context(agent_knowledge_snippets)
                task_prompt += self.agent_knowledge_context

            # 检索 Crew 级知识
            knowledge_snippets = self.crew.query_knowledge([self.knowledge_search_query])
            self.crew_knowledge_context = extract_knowledge_context(knowledge_snippets)
            task_prompt += self.crew_knowledge_context

    # 8. 创建 AgentExecutor 实例
    tools = tools or self.tools or []
    self.create_agent_executor(tools=tools, task=task)

    # 9. 处理训练数据（如果在训练模式）
    if self.crew and self.crew._train:
        task_prompt = self._training_handler(task_prompt=task_prompt)
    else:
        task_prompt = self._use_trained_data(task_prompt=task_prompt)

    # 10. 执行任务（带超时或不带超时）
    if self.max_execution_time is not None:
        result = self._execute_with_timeout(task_prompt, task, self.max_execution_time)
    else:
        result = self._execute_without_timeout(task_prompt, task)

    # 11. 检查工具最终性（如果工具标记了 result_as_answer）
    for tool_result in self.tools_results:
        if tool_result.get("result_as_answer", False):
            result = tool_result["result"]

    # 12. 发送执行完成事件
    crewai_event_bus.emit(
        self,
        event=AgentExecutionCompletedEvent(agent=self, task=task, output=result),
    )

    return result

# 上游调用者：Crew._execute_tasks()
def _execute_tasks(self, tasks: list[Task], start_index: int = 0) -> CrewOutput:
    """Crew 执行任务的核心流程"""
    task_outputs: list[TaskOutput] = []

    for task_index, task in enumerate(tasks):
        agent_to_use = self._get_agent_to_use(task)
        tools_for_task = task.tools or agent_to_use.tools or []
        context = self._get_context(task, task_outputs)

        # 调用 Agent.execute_task
        if task.async_execution:
            future = task.execute_async(
                agent=agent_to_use,
                context=context,
                tools=tools_for_task,
            )
            futures.append((task, future, task_index))
        else:
            task_output = task.execute_sync(
                agent=agent_to_use,
                context=context,
                tools=tools_for_task,
            )
            task_outputs.append(task_output)

    return self._create_crew_output(task_outputs)

# Task.execute_sync() 内部调用 Agent.execute_task()
def execute_sync(
    self,
    agent: BaseAgent | None = None,
    context: str | None = None,
    tools: list[BaseTool] | None = None,
) -> TaskOutput:
    """同步执行任务"""
    agent = agent or self.agent
    if not agent:
        raise Exception(f"The task '{self.description}' has no agent assigned")

    # 调用 Agent.execute_task
    result = agent.execute_task(
        task=self,
        context=context,
        tools=tools,
    )

    # 导出结构化输出
    pydantic_output, json_output = self._export_output(result)

    # 创建 TaskOutput
    task_output = TaskOutput(
        description=self.description,
        raw=result,
        pydantic=pydantic_output,
        json_dict=json_output,
        agent=agent.role,
        output_format=self._get_output_format(),
    )

    return task_output

sequenceDiagram
    autonumber
    participant Crew as Crew
    participant Task as Task
    participant Agent as Agent
    participant Executor as AgentExecutor
    participant LLM as LLM
    participant Memory as Memory
    participant Knowledge as Knowledge
    participant Tool as Tool

    Crew->>Task: execute_sync(agent, context, tools)
    Task->>Agent: execute_task(task, context, tools)

    alt 启用推理规划
        Agent->>Agent: AgentReasoning.handle_agent_reasoning()
    end

    Agent->>Agent: 构建 task_prompt

    alt 有记忆系统
        Agent->>Memory: build_context_for_task(task, context)
        Memory-->>Agent: memory_snippets
        Agent->>Agent: 添加 memory 到 task_prompt
    end

    alt 有知识库
        Agent->>Agent: _get_knowledge_search_query(task_prompt)
        Agent->>Knowledge: query([search_query])
        Knowledge-->>Agent: knowledge_snippets
        Agent->>Agent: 添加 knowledge 到 task_prompt
    end

    Agent->>Agent: create_agent_executor(tools, task)
    Agent->>Executor: invoke({"input": task_prompt})

    loop 推理循环（最多 max_iter 次）
        Executor->>LLM: call(messages)
        LLM-->>Executor: response

        alt 解析出 Action（工具调用）
            Executor->>Tool: execute(tool_input)
            Tool-->>Executor: tool_output
            Executor->>Executor: 添加 tool_output 到 messages
        else 解析出 Final Answer
            Executor->>Executor: 返回 Final Answer
        end
    end

    Executor-->>Agent: output
    Agent->>Memory: save(output)
    Agent-->>Task: return result
    Task->>Task: _export_output(result)
    Task-->>Crew: TaskOutput

def create_agent_executor(
    self, tools: list[BaseTool] | None = None, task: Task | None = None
) -> None:
    """创建 AgentExecutor"""
    raw_tools: list[BaseTool] = tools or self.tools or []
    parsed_tools = parse_tools(raw_tools)

    # 生成提示词模板
    prompt = Prompts(
        agent=self,
        has_tools=len(raw_tools) > 0,
        i18n=self.i18n,
        use_system_prompt=self.use_system_prompt,
        system_template=self.system_template,
        prompt_template=self.prompt_template,
        response_template=self.response_template,
    ).task_execution()

    # 生成停止词列表
    stop_words = [self.i18n.slice("observation")]
    if self.response_template:
        stop_words.append(
            self.response_template.split("{{ .Response }}")[1].strip()
        )

    # 创建 Executor 实例
    self.agent_executor = CrewAgentExecutor(
        llm=self.llm,
        task=task,
        agent=self,
        crew=self.crew,
        tools=parsed_tools,
        prompt=prompt,
        original_tools=raw_tools,
        stop_words=stop_words,
        max_iter=self.max_iter,
        tools_handler=self.tools_handler,
        tools_names=get_tool_names(parsed_tools),
        tools_description=render_text_description_and_args(parsed_tools),
        step_callback=self.step_callback,
        function_calling_llm=self.function_calling_llm,
        respect_context_window=self.respect_context_window,
        request_within_rpm_limit=(
            self._rpm_controller.check_or_wait if self._rpm_controller else None
        ),
        callbacks=[TokenCalcHandler(self._token_process)],
    )

def get_delegation_tools(self, agents: list[BaseAgent]) -> list[BaseTool]:
    """生成委托工具"""
    agent_tools = AgentTools(agents=agents)
    return agent_tools.tools()

class AgentTools(BaseTool):
    """提供委托和提问工具"""
    agents: list[BaseAgent]

    def tools(self) -> list[BaseTool]:
        tools = [
            self._delegate_work(),
            self._ask_question(),
        ]
        return tools

    def _delegate_work(self) -> BaseTool:
        """创建委托工作工具"""
        class DelegateWorkInput(BaseModel):
            coworker: str = Field(description="Agent 角色")
            task: str = Field(description="任务描述")
            context: str = Field(description="上下文信息")

        return Tool(
            name="Delegate work to coworker",
            description="Delegate a task to a specific coworker",
            args_schema=DelegateWorkInput,
            func=self._execute_delegation,
        )

    def _execute_delegation(self, coworker: str, task: str, context: str) -> str:
        """执行委托"""
        agent = self._get_agent_by_role(coworker)
        if not agent:
            return f"Error: Agent '{coworker}' not found"

        # 创建临时 Task 并执行
        sub_task = Task(description=task, expected_output="Result", agent=agent)
        result = agent.execute_task(sub_task, context=context)
        return result

sequenceDiagram
    autonumber
    participant Manager as Manager Agent
    participant DelegateTool as Delegate Tool
    participant Worker as Worker Agent
    participant Executor as AgentExecutor

    Manager->>Manager: 分析任务需求
    Manager->>DelegateTool: Delegate work to Worker1
    DelegateTool->>Worker: execute_task(sub_task, context)
    Worker->>Executor: invoke(task_prompt)
    Executor->>Executor: 执行推理循环
    Executor-->>Worker: 返回结果
    Worker-->>DelegateTool: 返回结果
    DelegateTool-->>Manager: 返回结果
    Manager->>Manager: 整合结果

class LiteAgentOutput(BaseModel):
    output: str                       # 原始输出
    pydantic: BaseModel | None        # 结构化输出（如果指定 response_format）
    json_dict: dict[str, Any] | None  # JSON 输出
    token_usage: dict[str, int]       # Token 使用统计

def kickoff(
    self,
    messages: str | list[LLMMessage],
    response_format: type[Any] | None = None,
) -> LiteAgentOutput:
    """使用 LiteAgent 执行"""
    lite_agent = LiteAgent(
        id=self.id,
        role=self.role,
        goal=self.goal,
        backstory=self.backstory,
        llm=self.llm,
        tools=self.tools or [],
        max_iterations=self.max_iter,
        max_execution_time=self.max_execution_time,
        respect_context_window=self.respect_context_window,
        verbose=self.verbose,
        response_format=response_format,
        i18n=self.i18n,
        original_agent=self,
        guardrail=self.guardrail,
        guardrail_max_retries=self.guardrail_max_retries,
    )

    return lite_agent.kickoff(messages)

class Prompts(BaseModel):
    """管理和生成 Agent 的提示词"""

    i18n: I18N = Field(default_factory=I18N)
    has_tools: bool = Field(default=False, description="是否有工具")
    system_template: str | None = Field(default=None, description="自定义系统提示词模板")
    prompt_template: str | None = Field(default=None, description="自定义用户提示词模板")
    response_template: str | None = Field(default=None, description="自定义响应模板")
    use_system_prompt: bool | None = Field(default=False, description="是否使用系统提示词")
    agent: Any = Field(description="Agent 引用")

    def task_execution(self) -> SystemPromptResult | StandardPromptResult:
        """生成任务执行的提示词"""
        # 1. 构建提示词组件
        slices: list[str] = ["role_playing"]  # 角色扮演部分

        if self.has_tools:
            slices.append("tools")  # 工具使用说明
        else:
            slices.append("no_tools")  # 无工具说明

        # 2. 构建系统提示词
        system: str = self._build_prompt(slices)

        # 3. 添加任务组件
        slices.append("task")

        # 4. 根据配置选择提示词模式
        if not self.system_template and not self.prompt_template and self.use_system_prompt:
            # 分离系统提示词和用户提示词
            return SystemPromptResult(
                system=system,
                user=self._build_prompt(["task"]),
                prompt=self._build_prompt(slices),
            )
        else:
            # 单一提示词模式
            return StandardPromptResult(
                prompt=self._build_prompt(
                    slices,
                    self.system_template,
                    self.prompt_template,
                    self.response_template,
                )
            )

    def _build_prompt(
        self,
        components: list[str],
        system_template: str | None = None,
        prompt_template: str | None = None,
        response_template: str | None = None,
    ) -> str:
        """构建提示词字符串"""
        prompt: str

        if not system_template or not prompt_template:
            # 使用默认格式
            prompt_parts: list[str] = [
                self.i18n.slice(component) for component in components
            ]
            prompt = "".join(prompt_parts)
        else:
            # 使用自定义模板
            template_parts: list[str] = [
                self.i18n.slice(component)
                for component in components
                if component != "task"
            ]
            system: str = system_template.replace(
                "{{ .System }}", "".join(template_parts)
            )
            prompt = prompt_template.replace(
                "{{ .Prompt }}", "".join(self.i18n.slice("task"))
            )

            if response_template:
                response: str = response_template.split("{{ .Response }}")[0]
                prompt = f"{system}\n{prompt}\n{response}"
            else:
                prompt = f"{system}\n{prompt}"

        # 5. 注入 Agent 的角色信息
        return (
            prompt.replace("{goal}", self.agent.goal)
            .replace("{role}", self.agent.role)
            .replace("{backstory}", self.agent.backstory)
        )

You are {role}.
{backstory}

Your personal goal is: {goal}

To use a tool, please use the following format:

Thought: Do I need to use a tool? Yes
Action: the action to take, should be one of [{tool_names}]
Action Input: the input to the action, always a simple python dictionary, enclosed in curly braces, using \" to wrap keys and values.
Observation: the result of the action

When you have a response to say to the Human, or if you do not need to use a tool, you MUST use the format:

Thought: Do I need to use a tool? No
Final Answer: [your response here]

Begin! This is VERY important to you, your job depends on it!

Current Task: {task_description}

Expected Output: {expected_output}

flowchart TB
    Start[开始] --> LoadI18N[加载国际化模板]
    LoadI18N --> SelectMode{选择模式}

    SelectMode -->|SystemPrompt| SplitMode[分离系统/用户提示词]
    SelectMode -->|Standard| SingleMode[单一提示词]

    SplitMode --> BuildSystem[构建系统提示词]
    BuildSystem --> AddRole[角色扮演]
    AddRole --> AddToolGuide[工具使用指南]
    AddToolGuide --> BuildUser[构建用户提示词]
    BuildUser --> AddTask[任务描述]

    SingleMode --> CombineAll[合并所有组件]
    CombineAll --> AddRole2[角色扮演]
    AddRole2 --> AddToolGuide2[工具使用指南]
    AddToolGuide2 --> AddTask2[任务描述]

    AddTask --> InjectVars[注入变量]
    AddTask2 --> InjectVars

    InjectVars --> ReplaceRole[替换 {role}]
    ReplaceRole --> ReplaceGoal[替换 {goal}]
    ReplaceGoal --> ReplaceBackstory[替换 {backstory}]
    ReplaceBackstory --> AddContext{有上下文?}

    AddContext -->|是| AppendContext[追加 context]
    AddContext -->|否| AddMemory{有记忆?}
    AppendContext --> AddMemory

    AddMemory -->|是| AppendMemory[追加 memory snippets]
    AddMemory -->|否| AddKnowledge{有知识?}
    AppendMemory --> AddKnowledge

    AddKnowledge -->|是| AppendKnowledge[追加 knowledge snippets]
    AddKnowledge -->|否| AddFormat{结构化输出?}
    AppendKnowledge --> AddFormat

    AddFormat -->|是| AppendSchema[追加 output schema]
    AddFormat -->|否| End[完成]
    AppendSchema --> End