AI Agent开发：手写代码与四大框架全对比，小白也能快速上手-优快云博客

首先回顾一下我们的业务流程：

在这里插入图片描述

接下来分别使用手写代码和几种框架来实现这个业务流程逻辑，看看差异所在。

1、手写代码

纯编码时，我们直接根据业务逻辑来串联工作流：

# sql agentdef sql_agent(user_query):    # 1. 语义匹配    table = semanticService.hybrid_search(user_query, 1)    if not table:        print(f"未匹配到字段")        return Result.error()    table_struct = [t["table_info"] for t in table]    prompt = f"""            你是一个MySQL专家。根据以下表结构信息：            {table_struct}            历史问答（仅供参考）："{mm.get_messages(session_id)}"                        用户查询："{user_query}"            生成标准MYSQL查询语句。            要求：            1. 只输出MYSQL语句，不要额外解释            2. 根据语义和字段类型，使用COUNT/SUM/AVG等聚合函数进行计算，非必须            3. 给生成的字段取一个简短的中文名称            输出格式：使用[]包含sql文本即可，不需要其他输出，便于解析，例如:[select 1 from dual]        """    print(f"SQL AGENT PROMPT={prompt}")    # 2. 大模型生成SQL    str1 = analysisService.analysis(prompt)    sql = re.search(r'\[(.*?)\]', str1, re.DOTALL).group(1).strip()    # 3. 执行查询    if not sql:        print("\nSQL生成失败")        return Result.error()    resultSet = queryService.query_with_column(sql)    if not resultSet:        print("\nSQL查询失败")        return Result.error()    return Result.success(data={ "tableStruct": table_struct, "resultSet": resultSet, "sql": sql })# analysis agentdef analysis_agent(user_query, data):    # 基础分析    prompt = f"""                根据以下表结构信息：                {data['tableStruct']}                                查询SQL：                {data['sql']}                                和以下数据信息：                {data['resultSet']}                历史问答（仅供参考）："{mm.get_messages(session_id)}"                                用户查询："{user_query}"                生成一段简要分析，加上一些预测总结的内容            """    print(f"ANALYSIS AGENT PROMPT={prompt}")    return Result.success(analysisService.analysis(prompt))def workflow(user_input):    # 1 - SQL Agent    result = sql_agent(user_input)    if not result.success:        returnNone    # 2 - Analysis Agent    return analysis_agent(user_input, result.data)

2、LangChain框架

使用LangChain框架的Chain模式时，可以手动串联业务流程逻辑：

# 构建顺序链overall_chain = SequentialChain(    chains=[        TransformChain(            input_variables=["user_query"],            output_variables=["table_schema"],            transform=get_table_schema        ),        TransformChain(            input_variables=["user_query", "table_schema"],            output_variables=["sql_result", "generated_sql"],            transform=execute_sql        ),        analysis_chain    ],    input_variables=["user_query"],    output_variables=["analysis_result"],    verbose=True)

LangChain 已经发展出丰富的 Chain 类型，用于构建复杂、模块化的 LLM 应用，这里就不一一介绍了。

LangChain框架除了提供Chain模式外，还可以使用的Agent模式来实现，通过提示词来指定业务流程逻辑，然后直接调用工具，如下：

# 初始化Agentagent = initialize_agent(    tools=[semantic_tool, sql_tool],    llm=llm,    agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,    verbose=True,    handle_parsing_errors=True,    max_iterations=10,  # 增加最大迭代次数以支持多步查询    early_stopping_method="generate")def chat(user_query):    print("执行方法chat")    # 更明确的指令    enhanced_query = f"""    问题：{user_query}    请特别注意：这个问题可能需要从多个表中查询数据。    1. 首先确定需要查询哪些数据    2. 使用match_metadata工具分别匹配包含这些数据的表结构    3. 对每个表生成相应的SQL查询语句    4. 执行查询并汇总结果    5. 最后计算并给出答案    请确保逐步执行，不要跳过任何步骤。    """    try:        result = agent.run(enhanced_query)        print(f"\n最终结果: {result}")    except Exception as e:        print(f"执行过程中出错: {str(e)}")        # 这里可以添加重试或更详细的错误处理逻辑

3、QwenAgent框架

QwenAgent框架则只能通过提示词方式指定业务流程逻辑，然后直接调用Assistant等待用户输入：

# 创建Agent实例agent = Assistant(    name='ai_agent_assistant',    llm={        'model': 'qwen3:32b',        'model_server': 'http://localhost:11434/v1',    },    system_message="""        你是一个数据分析助手，负责帮助用户查询数据库信息。        请特别注意：用户的问题可能需要从多个表中查询数据。        1. 首先确定需要查询哪些数据        2. 使用match_metadata工具分别匹配包含这些数据的表结构        3. 对每个表生成相应的SQL查询语句        4. 执行查询并汇总结果        5. 最后计算并给出答案        请确保逐步执行，不要跳过任何步骤。    """,    function_list=[MatchMetadataTool(), ExecuteSQLTool()],)

4、AgentScope框架

AgentScope框架中支持单体Agent模式，将工具提供给框架，再通过提示词来指定业务流程逻辑：

async def interactive_react_agent() -> None:    """创建一个支持多轮对话的ReAct智能体。"""    # 准备工具    toolkit = Toolkit()    toolkit.register_tool_function(match_metadata)    toolkit.register_tool_function(execute_sql)    jarvis = ReActAgent(        name="Jarvis",        sys_prompt="""            你是一个数据分析助手，负责帮助用户查询数据库信息。            请特别注意：用户的问题可能需要从多个表中查询数据。            1. 首先确定需要查询哪些数据            2. 使用match_metadata工具分别匹配包含这些数据的表结构            3. 对每个表生成相应的SQL查询语句            4. 执行查询并汇总结果            5. 最后计算并给出答案            请确保逐步执行，不要跳过任何步骤。        """,        model=OllamaChatModel(            model_name="qwen3:32b",  # 指定模型名称            stream=True,  # 根据需要设置是否流式输出            enable_thinking=True,  # 为Qwen3启用思考功能（可选）            # host="http://localhost:11434" # 如果Ollama不在默认地址，需指定        ),        formatter=OllamaChatFormatter(),        toolkit=toolkit,        memory=InMemoryMemory(),    )

小结

手写代码需人工串联各个步骤，灵活但开发成本高，维护复杂。各框架则提供了丰富的链（Chain）或Agent模式，支持流程模块化、工具调用自动化，极大提升开发效率和可维护性。

模型调用对比

接下来看看手写代码和使用开发框架，都是如何调用大模型的，如何处理大模型的流式输出的。

1、手写代码

通过HTTP方式调用外部大模型示例：

import requests# Analysis APIclass AnalysisService:    def __init__(self):        self.ollama_host = "http://localhost:11434/api/chat"    def analysis(self, prompt, model="deepseek-r1:32b", messages=None):        # 发送POST请求        if messages isNone:            messages = []        str = ""        newMessages = messages[:]        newMessages.append({"role": "user", "content": prompt})        # 请求数据        data = {            "model": model,            "messages": newMessages,            "stream": True        }        isThinking = False        with requests.post(self.ollama_host, json=data, stream=True) as response:            # 处理流式响应            for line in response.iter_lines():                if line:                    decoded_line = line.decode('utf-8')                    try:                        # 解析JSON数据                        chunk = json.loads(decoded_line)                        content = chunk['message']['content']                        if"<think>"in content:                            isThinking = True                        if"</think>"in content:                            isThinking = False                        ifnot isThinking and"</think>"notin content:                            str += chunk['message']['content']                        # 打印消息内容                        print(chunk['message']['content'], end='', flush=True)                    except json.JSONDecodeError:                        print(f"无法解析JSON: {decoded_line}")        return str

使用官方或社区封装的 Python 包（如 ollama 包）调用示例：

import ollama# 调用模型生成回复，流式输出for chunk in ollama.chat(    model='deepseek-r1:32b',    messages=[{'role': 'user', 'content': '讲一个笑话'}],    stream=True):    print(chunk['message']['content'], end='', flush=True)

在这里插入图片描述

2、LangChain框架

LangChain内部集成支持多种类型的模型调用，以下列举部分：

3、QwenAgent框架

QwenAgent内部集成支持通用HTTP方式调用大模型：

...# 创建Agent实例agent = Assistant(    name='ai_agent_assistant',    llm={        'model': 'qwen3:32b',        'model_server': 'http://localhost:11434/v1',    },    ...

4、AgentScope框架

AgentScope内部集成多模型支持：

在这里插入图片描述

小结

手写代码通常直接调用HTTP接口或使用官方SDK，需自行处理流式输出的循环响应和异常。而几种开发框架都内置对多种模型的统一封装，只要简单配置即可，简化了调用过程，提升了稳定性和扩展性。

工具调用对比

现在AI Agent中调用工具Tools已经是典型场景了，所以接下来对这块做个对比分析。

1、手写代码

需要手动调用外部工具：

...# sql agentdef sql_agent(user_query):    # 1. 语义匹配    table = semanticService.hybrid_search(user_query, 1)    ...    # 3. 执行查询    if not sql:        print("\nSQL生成失败")        return Result.error()        resultSet = queryService.query_with_column(sql)    ...

2、LangChain框架

Agent模式初始化传入tools即可：

# 初始化Agentagent = initialize_agent(    tools=[semantic_tool, sql_tool],    llm=llm,    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,    verbose=True,    handle_parsing_errors=True,    max_iterations=10,  # 增加最大迭代次数以支持多步查询    early_stopping_method="generate",    memory=memory)

3、QwenAgent框架

Agent模式初始化传入tools即可：

# 创建Agent实例agent = Assistant(    name='ai_agent_assistant',    llm={        'model': 'qwen3:32b',        'model_server': 'http://localhost:11434/v1',    },    system_message="""        你是一个数据分析助手，负责帮助用户查询数据库信息。        请特别注意：用户的问题可能需要从多个表中查询数据。        1. 首先确定需要查询哪些数据        2. 使用match_metadata工具分别匹配包含这些数据的表结构        3. 对每个表生成相应的SQL查询语句        4. 执行查询并汇总结果        5. 最后计算并给出答案        请确保逐步执行，不要跳过任何步骤。    """,    function_list=[MatchMetadataTool(), ExecuteSQLTool()],)

需要处理一下流式输出结果，获取文本内容：

def read_steam_response(response_generator):    # 处理生成器响应    full_response = ''    start = 0    end = 0    for response in response_generator:        # 检查响应类型并适当处理        if isinstance(response, list):            # 如果是列表，提取内容            for item in response:                ifisinstance(item, dict) and'content'in item:                    full_response = item['content']                    end = full_response.__len__()                elifisinstance(item, str):                    full_response = item                    end = full_response.__len__()        elif isinstance(response, dict) and'content'in response:            full_response = response['content']            end = full_response.__len__()        elif isinstance(response, str):            full_response = response            end = full_response.__len__()        print(f"{full_response[start:end]}", end="")        start = end    return full_response

4、AgentScope框架

Agent模式初始化传入tools即可：

# 准备工具toolkit = Toolkit()toolkit.register_tool_function(match_metadata)toolkit.register_tool_function(execute_sql)jarvis = ReActAgent(    name="Jarvis",    sys_prompt="""        你是一个数据分析助手，负责帮助用户查询数据库信息。        请特别注意：用户的问题可能需要从多个表中查询数据。        1. 首先确定需要查询哪些数据        2. 使用match_metadata工具分别匹配包含这些数据的表结构        3. 对每个表生成相应的SQL查询语句        4. 执行查询并汇总结果        5. 最后计算并给出答案        请确保逐步执行，不要跳过任何步骤。    """,    model=OllamaChatModel(        model_name="qwen3:32b",  # 指定模型名称        stream=True,  # 根据需要设置是否流式输出        enable_thinking=True,  # 为Qwen3启用思考功能（可选）        # host="http://localhost:11434" # 如果Ollama不在默认地址，需指定    ),    formatter=OllamaChatFormatter(),    toolkit=toolkit,    memory=InMemoryMemory(),)

小结

手写开发中需显式调用语义检索、SQL查询等工具，几种框架都支持通过工具注册机制自动完成调用与路由，降低耦合并增强复用。

上下文记忆对比

在AI Agent实践过程中，如果需要实现多轮对话，就会碰到上下文记忆的处理，所以接下来对这块做个对比。

1、手写代码

这种模式需要手写代码来管理上下文消息：

import threadingfrom dataclasses import dataclassfrom typing importList, Dict, Any@dataclassclass Message:    role: str# "system", "user", "assistant"    content: str    def to_dict(self) -> Dict[str, str]:        return {"role": self.role, "content": self.content}class MessageManager:    def __init__(self, max_history: int = 10):        """        初始化消息管理器        :param max_history: 每个 session 最多保留的历史消息数量（不包括 system 消息）        """        self.max_history = max_history        self._sessions: Dict[str, Dict[str, Any]] = {}        self._lock = threading.Lock()  # 保证线程安全    def set_system_message(self, session_id: str, content: str) -> None:        """为指定 session 设置 system 消息（会覆盖旧的）"""        with self._lock:            if session_id notinself._sessions:                self._sessions[session_id] = {                    "system": None,                    "history": []  # 只存 user/assistant 对话                }            self._sessions[session_id]["system"] = Message(role="system", content=content)    def add_user_message(self, session_id: str, content: str) -> None:        """添加用户消息"""        self._add_message(session_id, "user", content)    def add_assistant_message(self, session_id: str, content: str) -> None:        """添加助手回复"""        self._add_message(session_id, "assistant", content)    def _add_message(self, session_id: str, role: str, content: str) -> None:        with self._lock:            if session_id notin self._sessions:                self._sessions[session_id] = {                    "system": None,                    "history": []                }            history = self._sessions[session_id]["history"]            history.append(Message(role=role, content=content))            # 限制历史长度（只保留最近的 max_history 条 user/assistant 消息）            if len(history) > self.max_history * 2:  # 每轮对话含 user + assistant                # 保留最后 max_history * 2 条                self._sessions[session_id]["history"] = history[-(self.max_history * 2):]    def get_messages(self, session_id: str) -> List[Dict[str, str]]:        """获取可用于 Ollama /api/chat 的 messages 列表"""        with self._lock:            session = self._sessions.get(session_id)            if not session:                return []            messages = []            # 添加 system 消息（如果有）            if session["system"]:                messages.append(session["system"].to_dict())            # 添加历史对话            for msg in session["history"]:                messages.append(msg.to_dict())            return messages    def clear_session(self, session_id: str) -> None:        """清除指定 session 的所有消息"""        with self._lock:            self._sessions.pop(session_id, None)    def list_sessions(self) -> List[str]:        """列出所有 session ID"""        with self._lock:            returnlist(self._sessions.keys())    def delete_session(self, session_id: str) -> bool:        """删除 session，返回是否删除成功"""        with self._lock:            if session_id inself._sessions:                del self._sessions[session_id]                return True            return False

调用时手动传入：

# sql agentdef sql_agent(user_query):    # 1. 语义匹配    table = semanticService.hybrid_search(user_query, 1)    if not table:        print(f"未匹配到字段")        return Result.error()    table_struct = [t["table_info"] for t in table]    prompt = f"""            你是一个MySQL专家。根据以下表结构信息：            {table_struct}            历史问答（仅供参考）："{mm.get_messages(session_id)}"                        用户查询："{user_query}"            生成标准MYSQL查询语句。            要求：            1. 只输出MYSQL语句，不要额外解释            2. 根据语义和字段类型，使用COUNT/SUM/AVG等聚合函数进行计算，非必须            3. 给生成的字段取一个简短的中文名称            输出格式：使用[]包含sql文本即可，不需要其他输出，便于解析，例如:[select 1 from dual]        """    print(f"SQL AGENT PROMPT={prompt}")    # 2. 大模型生成SQL    str1 = analysisService.analysis(prompt)    sql = re.search(r'\[(.*?)\]', str1, re.DOTALL).group(1).strip()    # 3. 执行查询    if not sql:        print("\nSQL生成失败")        return Result.error()    resultSet = queryService.query_with_column(sql)    if not resultSet:        print("\nSQL查询失败")        return Result.error()    return Result.success(data={ "tableStruct": table_struct, "resultSet": resultSet, "sql": sql })# analysis agentdef analysis_agent(user_query, data):    # 基础分析    prompt = f"""                根据以下表结构信息：                {data['tableStruct']}                                查询SQL：                {data['sql']}                                和以下数据信息：                {data['resultSet']}                历史问答（仅供参考）："{mm.get_messages(session_id)}"                                用户查询："{user_query}"                生成一段简要分析，加上一些预测总结的内容            """    print(f"ANALYSIS AGENT PROMPT={prompt}")    return Result.success(analysisService.analysis(prompt))

2、LangChain框架

Agent模式指定：

# 记忆memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)# 初始化Agentagent = initialize_agent(    tools=[semantic_tool, sql_tool],    llm=llm,    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,    verbose=True,    handle_parsing_errors=True,    max_iterations=10,  # 增加最大迭代次数以支持多步查询    early_stopping_method="generate",    memory=memory)

除了上面用到的 ConversationBufferMemory，LangChain还提供了多种Memory组件，以适应不同场景的需求。可以根据具体情况选择：

注意确认Agent类型兼容性：在选用Memory前，请确认你使用的AgentType 支持Memory功能。例如，ZERO_SHOT_REACT_DESCRIPTION 默认不支持记忆，而CONVERSATIONAL_REACT_DESCRIPTION则专为多轮对话设计。

注意上下文长度：为Agent添加记忆会占用模型的上下文窗口。如果对话很长，考虑使用Conversation Summary Memory或Conversation Buffer Window Memory来避免超出限制。

调试工具：将 verbose 参数设为 True，可以在控制台看到详细的决策过程，有助于观察Memory是否正常工作。

3、QwenAgent框架

Agent模式的Assistant类不支持，需要手动管理：

def analysis(user_query):    try:        # 运行Agent        messages = mm.get_messages(session_id) + [{'role': 'user', 'content': user_query}]        response_generator = agent.run(messages=messages)        # 处理生成器响应        full_response = ''        start = 0        end = 0        for response in response_generator:            # 检查响应类型并适当处理            ifisinstance(response, list):                # 如果是列表，提取内容                for item in response:                    ifisinstance(item, dict) and'content'in item:                        full_response = item['content']                        end = full_response.__len__()                    elifisinstance(item, str):                        full_response = item                        end = full_response.__len__()            elifisinstance(response, dict) and'content'in response:                full_response = response['content']                end = full_response.__len__()            elifisinstance(response, str):                full_response = response                end = full_response.__len__()            print(f"{full_response[start:end]}", end="")            start = end        print(f"最终结果: {full_response}")        # 缓存历史对话        if full_response:            mm.add_user_message(session_id, user_query)            mm.add_assistant_message(session_id, full_response)        return full_response    except Exception as e:        print(f"执行过程中出错: {str(e)}")        # 这里可以添加重试或更详细的错误处理逻辑        return f"错误: {str(e)}"

4、AgentScope框架

Agent初始化指定对应类型即可：

jarvis = ReActAgent(    name="Jarvis",    sys_prompt="""        你是一个数据分析助手，负责帮助用户查询数据库信息。        请特别注意：用户的问题可能需要从多个表中查询数据。        1. 首先确定需要查询哪些数据        2. 使用match_metadata工具分别匹配包含这些数据的表结构        3. 对每个表生成相应的SQL查询语句        4. 执行查询并汇总结果        5. 最后计算并给出答案        请确保逐步执行，不要跳过任何步骤。    """,    model=OllamaChatModel(        model_name="qwen3:32b",  # 指定模型名称        stream=True,  # 根据需要设置是否流式输出        enable_thinking=True,  # 为Qwen3启用思考功能（可选）        # host="http://localhost:11434" # 如果Ollama不在默认地址，需指定    ),    formatter=OllamaChatFormatter(),    toolkit=toolkit,    memory=InMemoryMemory(),)

小结

手写代码需自行实现消息管理和上下文传递，工作量大且需要手动维护。框架提供多样化记忆组件，支持对话上下文的灵活管理，适配不同对话场景，有效提升对话质量。

多智能体协作对比

自从Google提出A2A协议，多智能体协作已经成为业界实践过程的热点，为进一步对比手写代码和开发框架在多Agent协作上的区别，我们将本案例的程序设计拆分为以下两个Agent：

1、SQL Agent

调用外部语义检索(RAG)API匹配元数据
调用大模型根据元数据和用户提问生成查数SQL
调用查数API查询数据

2、Analysis Agent

调用大模型分析数据回答问题

1、手写代码

需要手动串联多个Agent调用，消息格式自定义传递：

...def workflow(user_input):    # 1 - SQL Agent    result = sql_agent(user_input)    if not result.success:        return None    # 2 - Analysis Agent    return analysis_agent(user_input, result.data)    ...