def ask(
    question,
    debug=False,
    max_plan_iterations=1,
    max_step_num=3,
    enable_background_investigation=True,
):
    """Run the agent workflow with the given question."""
    asyncio.run(
        run_agent_workflow_async(
            user_input=question,
            debug=debug,
            max_plan_iterations=max_plan_iterations,
            max_step_num=max_step_num,
            enable_background_investigation=enable_background_investigation,
        )
    )

logger.info("Starting DeerFlow API server")
uvicorn.run(
    "src.server:app",
    host=args.host,
    port=args.port,
    reload=reload,
    log_level=args.log_level,
)

def _build_base_graph():
    """Build and return the base state graph with all nodes and edges."""
    builder = StateGraph(State)
    builder.add_edge(START, "coordinator")
    # 协调员，确定查询是否应由规划器直接处理或需要背景调查
    builder.add_node("coordinator", coordinator_node)
    # 背景调查人员，进行初步的网络搜索，为规划师收集背景信息
    builder.add_node("background_investigator", background_investigation_node)
    # 规划师，创建包含步骤的结构化研究计划，是否需要更多研究或现有背景是否足够
    builder.add_node("planner", planner_node)

    builder.add_node("reporter", reporter_node)
    # 研究团队
    builder.add_node("research_team", research_team_node)
    # 研究员
    builder.add_node("researcher", researcher_node)
    # 编码
    builder.add_node("coder", coder_node)
    # 人工反馈，允许用户审查和修改研究计划
    builder.add_node("human_feedback", human_feedback_node)
    # 汇报
    builder.add_edge("reporter", END)
    return builder

def background_investigation_node(state: State) -> Command[Literal["planner"]]:
    logger.info("background investigation node is running.")
    # 列表中最后一条消息的内容作为用户的查询字符串。
    query = state["messages"][-1].content
    # 搜索引擎选择执行搜索
    if SELECTED_SEARCH_ENGINE == SearchEngine.TAVILY:
        searched_content = LoggedTavilySearch(max_results=SEARCH_MAX_RESULTS).invoke(
            {"query": query}
        )
        background_investigation_results = None
        if isinstance(searched_content, list):
            background_investigation_results = [
                {"title": elem["title"], "content": elem["content"]}
                for elem in searched_content
            ]
        else:
            logger.error(
                f"Tavily search returned malformed response: {searched_content}"
            )
    else:
        background_investigation_results = web_search_tool.invoke(query)
    # 搜索结果（转成 JSON 字符串）保存在 background_investigation_results
    # 跳转到下一节点 "planner"，继续流程执行
    return Command(
        update={
            "background_investigation_results": json.dumps(
                background_investigation_results, ensure_ascii=False
            )
        },
        goto="planner",
    )

def planner_node(
    state: State, config: RunnableConfig
) -> Command[Literal["human_feedback", "reporter"]]:
    """Planner node that generate the full plan."""
    logger.info("Planner generating full plan")
    # 获取允许的最大 plan 次数
    configurable = Configuration.from_runnable_config(config)
    plan_iterations = state["plan_iterations"] if state.get("plan_iterations", 0) else 0
    # 生成 prompt 模板
    messages = apply_prompt_template("planner", state, configurable)
    # 加入背景调查结果
    if (
        plan_iterations == 0
        and state.get("enable_background_investigation")
        and state.get("background_investigation_results")
    ):
        messages += [
            {
                "role": "user",
                "content": (
                    "background investigation results of user query:\n"
                    + state["background_investigation_results"]
                    + "\n"
                ),
            }
        ]
    # 初始化 Planner 使用的 LLM
    if AGENT_LLM_MAP["planner"] == "basic":
        llm = get_llm_by_type(AGENT_LLM_MAP["planner"]).with_structured_output(
            Plan,
            method="json_mode",
        )
    else:
        llm = get_llm_by_type(AGENT_LLM_MAP["planner"])

    # if the plan iterations is greater than the max plan iterations, return the reporter node
    # 超过最大计划迭代次数，直接跳转 reporter
    if plan_iterations >= configurable.max_plan_iterations:
        return Command(goto="reporter")
    # 调用语言模型生成计划
    full_response = ""
    if AGENT_LLM_MAP["planner"] == "basic":
        response = llm.invoke(messages)
        full_response = response.model_dump_json(indent=4, exclude_none=True)
    else:
        response = llm.stream(messages)
        for chunk in response:
            full_response += chunk.content
    logger.debug(f"Current state messages: {state['messages']}")
    logger.info(f"Planner response: {full_response}")
    # 尝试解析计划 JSON 内容
    try:
        curr_plan = json.loads(repair_json_output(full_response))
    except json.JSONDecodeError:
        logger.warning("Planner response is not a valid JSON")
        if plan_iterations > 0:
            return Command(goto="reporter")
        else:
            return Command(goto="__end__")
    # 判断计划是否足够有上下文，决定下一步跳转
    if curr_plan.get("has_enough_context"):
        logger.info("Planner response has enough context.")
        new_plan = Plan.model_validate(curr_plan)
        return Command(
            update={
                "messages": [AIMessage(content=full_response, name="planner")],
                "current_plan": new_plan,
            },
            goto="reporter",
        )
    return Command(
        update={
            "messages": [AIMessage(content=full_response, name="planner")],
            "current_plan": full_response,
        },
        goto="human_feedback",
    )

async def _setup_and_execute_agent_step(
    state: State,
    config: RunnableConfig,
    agent_type: str,
    default_agent,
    default_tools: list,
) -> Command[Literal["research_team"]]:
    """Helper function to set up an agent with appropriate tools and execute a step.

    This function handles the common logic for both researcher_node and coder_node:
    1. Configures MCP servers and tools based on agent type
    2. Creates an agent with the appropriate tools or uses the default agent
    3. Executes the agent on the current step

    Args:
        state: The current state
        config: The runnable config
        agent_type: The type of agent ("researcher" or "coder")
        default_agent: The default agent to use if no MCP servers are configured
        default_tools: The default tools to add to the agent

    Returns:
        Command to update state and go to research_team
    """
    configurable = Configuration.from_runnable_config(config)
    mcp_servers = {}
    enabled_tools = {}

    # Extract MCP server configuration for this agent type
    if configurable.mcp_settings:
        for server_name, server_config in configurable.mcp_settings["servers"].items():
            if (
                server_config["enabled_tools"]
                and agent_type in server_config["add_to_agents"]
            ):
                mcp_servers[server_name] = {
                    k: v
                    for k, v in server_config.items()
                    if k in ("transport", "command", "args", "url", "env")
                }
                for tool_name in server_config["enabled_tools"]:
                    enabled_tools[tool_name] = server_name

    # Create and execute agent with MCP tools if available
    if mcp_servers:
        try:
            async with MultiServerMCPClient(mcp_servers) as client:
                loaded_tools = default_tools[:]
                for tool in client.get_tools():
                    if tool.name in enabled_tools:
                        tool.description = (
                            f"Powered by '{enabled_tools[tool.name]}'.\n{tool.description}"
                        )
                        loaded_tools.append(tool)

                agent = create_agent(agent_type, agent_type, loaded_tools, agent_type)
                return await _execute_agent_step(state, agent, agent_type)

        except Exception as e:
            logger.exception(f"[{agent_type}] MCP agent setup or execution failed: {repr(e)}")
            raise ToolException(f"Error: {str(e) or repr(e)}\nTraceback:\n{traceback.format_exc()}")
    else:
        # Use default agent if no MCP servers are configured
        return await _execute_agent_step(state, default_agent, agent_type)