大模型Agent开发学习路线：框架选型、Harness工程与TextToSQL落地

大模型Agent开发最近被问到最多的几个问题基本是：LangChain和LangGraph到底选哪个、Agent的"Harness工程"是什么意思、工具调用怎么设计、TextToSQL项目怎么从零落地。这次我们把这些问题串成一条完整的学习路线来梳理，不聊概念堆砌，直接按"路线规划 -> 框架选型 -> 工程化设计 -> 项目落地 -> 部署测试 -> 排查优化"的顺序走一遍。

先说结论：大模型Agent开发早就不是"调API拼提示词"的阶段了，它是一套组合工程。你要面对的是模型层、编排层、工具层、执行层和业务层的协同。LangChain V1.0解决了编排层的标准化问题，Harness工程解决的是Agent执行过程的控制问题，工具设计解决的是模型能力边界的扩展问题，而TextToSQL则是把这套能力落到数据库业务场景里的典型项目。

这篇文章更适合已经跑通过基础LLM调用、想往Agent方向进阶的开发者。会覆盖技术栈全景、LangChain V1.0与LangGraph的区别、Harness工程的核心组成、Agent工具设计方法、TextToSQL的完整推理链路，以及本地部署、接口封装、批量任务和问题排查。

1. 大模型Agent开发核心知识点速览

从学习优先级看，LangChain和LangGraph解决的是"Agent怎么组织"，Harness工程解决的是"Agent怎么稳定跑"，工具设计解决的是"Agent能干什么"，TextToSQL则是把以上能力综合起来的实战项目。

这套路线的关键不是记住某个框架的全部API，而是理解每一个模块在Agent系统里的职责边界。框架只是工具，工程化能力才是能不能把Agent项目推上线的那道坎。

2. 大模型Agent开发技术栈全景

一个完整的Agent系统，按层拆开看是下面这个结构。

2.1 模型层

模型层是Agent的"大脑"。选择模型时要考虑推理能力、Function Calling的稳定性、上下文长度和部署成本。

常见选择分两类：

• 云端大模型API：上下文长、指令遵循能力强、无需本地显卡，适合快速验证和正式业务。
• 本地部署模型：数据不出内网、无按量费用，但对显卡显存有要求，工具调用能力又参差不齐，适合数据敏感或离线环境。

本地部署可以参考Ollama这类工具，一行命令就能把模型跑起来，作为LangChain的本地模型后端非常方便。

2.2 编排层

编排层负责把一次用户请求拆解成模型调用、工具调用、结果聚合等步骤。

这里就是LangChain和LangGraph的主场。简单任务是"线性调用"，复杂任务会变成"有条件的分支循环"。如果你的Agent需要多轮思考、反复调用工具，直接上LangGraph这类图编排方案，会比硬写死循环稳定得多。

2.3 工具层

工具层决定Agent的能力边界。搜索、查数据库、调HTTP接口、执行代码、访问文件系统，都是常见工具。

工具层设计的关键是：给模型一份清晰的"工具说明书"，包括工具名称、参数结构、返回格式。模型本身不执行工具，它只是决定"该调用哪个、参数填什么"，真正的执行发生在你的代码里。

2.4 执行层

执行层也叫Harness，是Agent跑动过程中的"脚手架"。它管理模型当前处于什么状态、已调用过哪些工具、上下文窗口还剩多少、反馈结果要不要截断、出错之后如何重试。

没有执行层的Agent是"demo级"的。一旦进入真实场景，token长度、重复调用、超时、工具返回脏数据这四类问题会反过来把模型搞糊涂。Harness工程就是提前把这些不确定性管住。

2.5 业务层

业务层把Agent能力封装成用户可用的产品。比如TextToSQL项目的Web界面、API接口、权限控制、审计日志，都属于这一层。

3. LangChain V1.0与LangGraph：Agent编排框架怎么选

LangChain系列是整个Agent开发里最容易被误解的部分。很多人把LangChain当成"一个库"，但实际开发中会意识到它更像一套生态，里面至少包含LangChain核心库和LangGraph两套思路。

3.1 LangChain V1.0到底做了什么

LangChain V1.0的出现，核心目的是把API收敛、让组件标准化。从开发体验上看，V1.0对可观测性、流式输出、工具调用和LCEL（LangChain Expression Language）做了强化。

LCEL是理解LangChain的关键。它用|管道符把提示词模板、模型、输出解析器串起来，写法非常直观：

from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI prompt = ChatPromptTemplate.from_template( "你是数据分析助手，请回答：{question}" ) model = ChatOpenAI(model="gpt-4o-mini", temperature=0) chain = prompt | model result = chain.invoke({"question": "本月销售额趋势如何？"}) print(result.content)

这种链式写法把一个完整的LLM调用拆分成了可替换、可测试的独立组件。以后换模型、换提示词、加输出解析，都不用动整条链路。

3.2 LangGraph和LangChain到底有什么区别

这是热词里出现频率很高的问题。

LangChain偏"说人话"：它是组件库和链式编排框架，处理的是"把模型、提示词、工具串起来"。LangGraph偏"说逻辑"：它用图的方式来定义Agent的状态流转，节点和边是核心抽象。

实际项目里的经验是：

• 纯线性任务，用LangChain就够了。
• 带条件分支、循环重试、多Agent协作的任务，LangGraph更合适。它允许Agent在"调用工具 -> 观察结果 -> 再次推理"之间反复循环，而且状态管理是显式的，出问题能走查。
• 从学习节奏看，先掌握LangChain组件用法，再进入LangGraph状态图，不要一上来就啃图编排。

3.3 LangChain V1.0生态中的TextToSQL支持

TextToSQL这类任务很适合用LangChain的链式结构来落地。一段自然语言经过提示词模板、模型、SQL校验器、执行器，最后把查询结果返回给用户。下面会给完整示例，这里先理解链路即可。

4. Harness工程：Agent执行的"脚手架"

"Harness"这个词在Agent开发里的含义，可以理解为"控制Agent运行的一套工程框架"。它不负责具体业务逻辑，而是负责Agent在调用工具、管理上下文、处理错误时的那层"基础设施"。

4.1 为什么需要Harness

直接让大模型自由调用工具，会出现几个问题：

• 模型忘记前面已经问过什么，重复调用同一个工具。
• 工具返回结果太长，把上下文窗口塞满。
• 工具调用报错后，模型开始胡编乱造。
• 模型在多个工具之间来回横跳，始终不产出最终答案。
• 用户权限没有贯穿到工具调用过程，越权查询。

Harness工程就是给Agent套上"结构化护栏"：定义好工具清单、限定上下文、跟踪状态、控制重试，不让模型在开放空间里自由发挥。

4.2 Harness的核心组成

一个工程化的Agent Harness通常包含这几个模块：

4.3 Harness和Agent的关系

可以参考这样一个类比：Agent是业务逻辑，Harness是运行框架。业务逻辑定义"这个助手能干什么"，运行框架定义"它怎么稳定地干完一件事"。

很多项目的Agent一开始没有Harness层，直接循环调用工具。初期数据量小看不出来，等到并发上来、工具变多、模型偶尔返回畸形参数时，整个流程就会卡死。Harness的价值就在这个节点体现出来。

5. 智能体工具设计：从Function Calling到Tool Registry

Agent要真正完成任务，光靠模型自身的知识远远不够，必须接工具。工具是Agent与外部世界交互的"手和脚"。

5.1 Function Calling的基础

大模型本身没有"执行"能力，它只能输出一段结构化调用意图。以OpenAI风格的Tool Calling为例，模型会返回类似下面这样的内容：

{ "tool_call": { "name": "query_sales_data", "arguments": { "start_date": "2025-01-01", "end_date": "2025-01-31" } } }

你的代码解析这个JSON，调用真实的query_sales_data函数，再把执行结果作为新的上下文返回给模型。

关键点：工具调用是否成功，取决于工具的Schema定义是否清晰。参数描述要写清楚，枚举值要给全，返回结构要固定，否则模型会猜。

5.2 工具注册与路由

工程化项目建议用"工具注册表"来管理所有工具。新增工具时只需要注册，不需要改动Agent主流程。

tools = [ { "type": "function", "function": { "name": "query_sales_data", "description": "查询指定时间段的销售数据，返回JSON数组", "parameters": { "type": "object", "properties": { "start_date": {"type": "string", "description": "开始日期，格式YYYY-MM-DD"}, "end_date": {"type": "string", "description": "结束日期，格式YYYY-MM-DD"} }, "required": ["start_date", "end_date"] } } } ]

当然，实际项目中直接用LangChain的@tool装饰器会更方便，它会把Python函数的签名自动转成Tool Schema：

from langchain_core.tools import tool @tool def query_sales_data(start_date: str, end_date: str) -> str: """查询指定时间段的销售数据。""" # 这里写真正的数据查询逻辑 return "[{'month': '2025-01', 'amount': 120000}]"

5.3 工具返回值的"清洁"问题

这是最容易踩坑的地方。工具直接从数据库返回几百行数据，直接塞给模型，结果就是上下文爆炸、模型理解混乱。

比较好的做法是：

• 默认只返回摘要或Top-N条数据。
• 在工具内部做聚合统计，返回"总数、均值、Top 5"这类压缩结果。
• 保留一个detail模式，用户明确要看明细时才返回完整结果。

6. TextToSQL项目落地全流程

TextToSQL是Agent开发里最典型的"工具型落地场景"：用户说一句自然语言，系统自动生成SQL，执行后返回查询结果。听起来简单，做起来有四个环节都必须打通。

6.1 项目目标与整体架构

TextToSQL项目的完整链路是：

自然语言 -> 意图识别与Schema选择 -> SQL生成 -> SQL校验 -> 执行查询 -> 结果解释

落地的核心难点不只在于"生成正确SQL"，更在于：

• 数据库表很多时，模型怎么知道该用哪几张表。
• 表字段含义模糊时，模型怎么理解业务口径。
• SQL生成错误时，要不要自动重写。
• 查询结果返回后，怎么转成用户能看懂的自然语言。

6.2 Schema注入：让模型知道库长什么样

模型不知道你的业务库有什么表。所以每次查询前，要把数据库Schema作为上下文提供给模型。Schema不是全库DDL硬塞，而是提炼出表名、字段名、字段类型、注释和常用枚举值。

schema_info = """ 表名: sales_order 字段: - id (INT): 主键 - order_no (VARCHAR): 订单号 - amount (DECIMAL): 订单金额 - created_at (DATETIME): 下单时间 表名: customer 字段: - id (INT): 主键 - name (VARCHAR): 客户名称 - level (VARCHAR): 客户等级，枚举VIP/普通 """

Schema注入最常见的坑是：表太多导致提示词太长。实际项目通常先做一次"表路由"，让模型从表清单里选出相关表，再只把相关表的Schema注入SQL生成环节。

6.3 SQL生成与执行

在LangChain里，可以把"生成SQL"和"执行SQL"串成一条链。

from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate sql_prompt = ChatPromptTemplate.from_template( """你是SQL专家，根据数据库Schema生成SQL查询语句。 数据库Schema: {schema} 用户问题: {question} 只输出可执行的SQL语句，不要额外解释。""" ) sql_chain = sql_prompt | ChatOpenAI(model="gpt-4o-mini", temperature=0) | StrOutputParser() sql = sql_chain.invoke({ "schema": schema_info, "question": "统计2025年1月每位客户的订单总额" }) print(sql)

生成SQL只是第一步，执行才是真正考验工程能力的地方。SQL语法错误、字段不存在、权限不足，都会在执行阶段报错。工程上通常会把执行错误返回给模型，让它根据错误信息修正SQL，形成"生成-执行-报错-重写"的闭环。

6.4 结果解释

SQL执行结果是一堆数字或表格，用户不一定看得懂。最后一步是把结果转成自然语言摘要：

"2025年1月共有12位客户产生订单，订单总额为36万元，其中VIP客户贡献占比62%。"

这一步可以直接复用LangChain的链式结构，把查询结果作为上下文，让模型总结成口语化回答。

7. 本地环境准备与依赖安装

TextToSQL和Agent实战项目，建议先准备一套干净的Python环境。

7.1 基础环境检查

• 操作系统：Windows / Linux / macOS均可，推荐Linux做正式部署。
• Python版本：建议3.10以上。
• 包管理工具：pip或poetry。
• 模型服务：优先用云端API快速验证，再考虑本地Ollama部署。

7.2 安装LangChain相关依赖

以pip为例，典型的安装命令如下：

pip install langchain langchain-core langchain-openai langchain-community

如果你使用LangGraph做编排，再补一个：

pip install langgraph

本地模型部署如果使用Ollama，则安装：

pip install langchain-ollama

需要说明的是，LangChain V1.0之后的包结构可能与旧版本有差异，具体以官方文档为准。安装时建议用虚拟环境隔离，避免系统Python环境被搞乱。

7.3 模型服务准备

云端API方案很简单，配置好密钥即可：

from langchain_openai import ChatOpenAI model = ChatOpenAI( model="gpt-4o-mini", temperature=0, api_key="your-api-key", base_url="https://api.openai.com/v1" )

本地部署方案以Ollama为例，先拉取模型：

ollama pull qwen2.5:7b ollama serve

然后LangChain里这样接入：

from langchain_ollama import ChatOllama local_model = ChatOllama(model="qwen2.5:7b", temperature=0)

本地模型的优势是数据不出内网，但要重点验证它的Function Calling能力。不是所有本地小模型都能稳定输出结构化工具调用参数，这个必须实测后再决定是否用于生产。

8. TextToSQL推理链路完整代码示例

把上面拆开的环节合成一个完整示例，方便直接跑通。这里用FastAPI做一个接口服务。

8.1 核心推理函数

import re import sqlite3 from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI from langchain_core.output_parsers import StrOutputParser model = ChatOpenAI(model="gpt-4o-mini", temperature=0) sql_prompt = ChatPromptTemplate.from_template( """根据数据库Schema生成SQL查询。 Schema: {schema} 用户问题: {question} 要求：只输出SQL，不要额外解释。""" ) explain_prompt = ChatPromptTemplate.from_template( """根据用户问题和查询结果，生成通俗易懂的回答。 用户问题: {question} 查询结果: {result} 请用中文口语化总结，包含关键数字。""" ) sql_chain = sql_prompt | model | StrOutputParser() explain_chain = explain_prompt | model | StrOutputParser() def text_to_sql(question: str, schema: str) -> dict: sql = sql_chain.invoke({"schema": schema, "question": question}) sql = re.sub(r"```sql|```", "", sql).strip() return sql def execute_sql(db_path: str, sql: str): conn = sqlite3.connect(db_path) try: cursor = conn.cursor() cursor.execute(sql) columns = [desc[0] for desc in cursor.description] rows = cursor.fetchall() return {"columns": columns, "rows": rows[:50]} except Exception as e: return {"error": str(e)} finally: conn.close()

8.2 FastAPI接口封装

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI(title="TextToSQL Agent API") class QueryRequest(BaseModel): question: str schema: str db_path: str = "./test.db" @app.post("/api/query") def query_endpoint(req: QueryRequest): sql = text_to_sql(req.question, req.schema) result = execute_sql(req.db_path, sql) if "error" in result: return {"sql": sql, "status": "error", "message": result["error"]} explain = explain_chain.invoke({ "question": req.question, "result": str(result["rows"][:10]) }) return {"sql": sql, "status": "success", "data": result, "explain": explain}

启动服务：

uvicorn main:app --host 127.0.0.1 --port 8000

这个示例展示了一个可工作的接口雏形。实际项目里还需要加上权限控制、SQL审计、敏感字段脱敏和查询超时。

9. Agent接口API与批量任务设计

真实业务里，TextToSQL服务不会只用一次就结束，更多是以接口或批量任务的方式被反复调用。

9.1 接口层设计建议

接口参数里除了问题文本和Schema，还要加入用户身份、数据库连接配置、是否允许执行写操作等控制项。写操作默认禁止，查询类操作也建议走只读账号。

9.2 批量任务处理

批量场景通常出现在"定时生成报表"或"离线分析大量问题"时。示范思路是把待处理问题放进任务队列，逐个执行，记录日志，失败重试。

import json import time from pathlib import Path tasks = [ {"id": 1, "question": "1月各区域销售额排名"}, {"id": 2, "question": "2月退货率最高的商品"}, {"id": 3, "question": "3月新增客户数量"} ] results = [] for task in tasks: try: sql = text_to_sql(task["question"], schema_info) result = execute_sql("./test.db", sql) results.append({"id": task["id"], "status": "ok", "sql": sql, "result": result}) except Exception as e: results.append({"id": task["id"], "status": "failed", "error": str(e)}) time.sleep(1) with open("./results.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2) print("batch done:", len(results))

批量任务一定要落日志。每个任务记录输入、输出、耗时、错误信息，后续排查会轻松很多。

10. 资源占用与性能观察

大模型Agent项目的性能瓶颈往往是多层的。TextToSQL这类任务尤其要关注以下几个方面。

10.1 模型部署的资源占用

使用云端API时，本机资源占用很低，主要瓶颈在网络延迟和API并发上限。使用本地模型时，显存和内存成为关键约束。

本地模型的选择策略是：先跑小参数模型验证流程，再根据效果升级模型。4B、7B级别的模型对显存要求较低，但SQL生成和工具调用的准确率可能不稳定；更大参数模型效果更好，但显存占用也更高。具体占用需要以本机实测为准。

建议观察：

• 显存占用：使用nvidia-smi命令监控。
• 单次推理耗时：记录每条SQL生成时间。
• 上下文长度：Schema注入越长，首Token延迟越高。

10.2 推理链路耗时分布

一个TextToSQL请求通常包含两次模型调用：一次生成SQL，一次生成结果解释。批量场景会更明显。

优化手段：

• SQL生成阶段使用独立的、温度设为0的模型实例。
• Schema注入只保留与问题相关的表。
• 查询结果在进入解释链之前先做截断。
• 结果解释可以异步执行，不让用户等太久。

10.3 并发与稳定性

接口上线后要关注的三个指标：P95延迟、错误率、上下文溢出率。工具返回数据过大、模型重复调用工具，是上下文溢出的两个主要原因，Harness层要做截断保护。

11. 常见问题与排查方法

大模型Agent项目跑不通，大多数不是模型的问题，而是工程链路的问题。下面列一份高频排查清单。

从实践经验看，"SQL执行报错后不重试"是TextToSQL项目初期最影响体验的问题。建议把执行错误当成正常上下文交给模型，让它自己修正。

12. 最佳实践与合规边界

Agent开发不是说把功能跑通就结束，工程化和合规是两道硬门槛。

12.1 工程化最佳实践

• 第一次跑通链路前，先用最小模型和最小Schema，成功后再逐步加复杂度。
• 保留一套最小可运行配置，包括基础提示词、标准Schema、测试数据库。遇到问题随时回退。
• 模型名、API密钥、数据库连接串等配置统一放环境变量或配置文件，不要硬编码。
• 所有工具调用、SQL执行、模型返回都要记录日志。
• 批量任务必须能断点续跑，不要从头再来。
• 接口服务启动时限制绑定地址，避免暴露到公网。

12.2 数据安全与合规边界

TextToSQL直接对接数据库，数据安全优先级最高。

• 数据库账号必须使用只读账号，禁止让Agent持有写权限。
• SQL执行前做关键字检查，拦截DROP、DELETE、UPDATE、TRUNCATE等危险操作。
• 查询结果中涉及的敏感字段要脱敏，尤其是手机号、身份证号、地址等信息。
• 涉及客户数据、内部经营数据的查询，要保留审计日志，记录谁在什么时间问了什么问题。
• 模型供应商选型时要确认数据处理协议，避免敏感数据未经允许送入外部API。
• 如果使用本地模型处理敏感数据，要评估模型本身的授权和合规要求。
• Agent生成SQL只是辅助判断，最终执行权限和业务决策权应保留在人工侧。

这些不是"加分项"，而是Agent项目能不能真正进入业务环境的准入门槛。

13. 总结与下一步

大模型Agent开发全栈技能的核心，说到底是把四件事想清楚：用LangChain/LangGraph这类框架解决编排问题，用Harness工程解决运行和控制问题，用工具设计解决能力扩展问题，再用TextToSQL这类具体项目把整套能力串起来验证。

真正值得优化的第一件事，是先跑通一个最小闭环。成本最低的路径是：准备一个小型SQLite数据库，写好Schema，调通云端API，让模型生成一条正确SQL，再手动把结果解释和错误重试补上。这个闭环跑通了，后面的工具扩展、Harness层加固、接口封装和批量任务设计都可以按部就班推进。

最容易踩的坑是过早追求框架复杂度。项目还在验证阶段，先把LangChain的最小链路跑通，没那么快需要LangGraph的图编排；工具数量没超过五个之前，也先不要过度设计Harness层。等真实场景里出现了状态混乱、工具调用失控、上下文溢出，再逐步引入更重的工程机制。

后续可以继续往这几个方向做：把TextToSQL升级成带表路由和记忆的数据库助手；把一次性工具调用改成多步任务编排；给Agent接入企业搜索、文档解析和报表生成工具，做成完整的业务智能助手；也可以结合本地模型部署，探索数据不出内网的私有化Agent方案。

这套路线的重点是"全栈"两个字：模型层、编排层、工具层、工程层、业务层，每一层都要能动手、能验证、能排错。希望这篇梳理对正在研究LangChain、Harness工程、智能体工具和TextToSQL落地的开发者有帮助，建议收藏备用。