大模型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 V1.0链式编排、组件标准化、提示词管理基于LangChain的LLM调用链与工具编排LangGraph图状态编排、循环控制、多Agent协作可维护、可恢复的Agent执行图Harness工程Agent执行脚手架、工具清单管理、上下文控制稳定可控的Agent运行框架智能体工具Function Calling、Tool Schema、工具注册与执行可扩展的工具集TextToSQL自然语言转SQL、Schema注入、执行纠错可直接对接业务的查询助手从学习优先级看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与LangGraphAgent编排框架怎么选LangChain系列是整个Agent开发里最容易被误解的部分。很多人把LangChain当成一个库但实际开发中会意识到它更像一套生态里面至少包含LangChain核心库和LangGraph两套思路。3.1 LangChain V1.0到底做了什么LangChain V1.0的出现核心目的是把API收敛、让组件标准化。从开发体验上看V1.0对可观测性、流式输出、工具调用和LCELLangChain Expression Language做了强化。LCEL是理解LangChain的关键。它用|管道符把提示词模板、模型、输出解析器串起来写法非常直观from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI prompt ChatPromptTemplate.from_template( 你是数据分析助手请回答{question} ) model ChatOpenAI(modelgpt-4o-mini, temperature0) 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通常包含这几个模块模块职责Tool Registry统一注册和发现可用工具State Manager维护多轮对话和工具调用状态Context Manager控制上下文窗口避免无限增长Guardrails输入输出校验拦截危险操作Retry Handler工具超时、报错时的重试策略Execution Loop模型与工具之间的循环控制逻辑4.3 Harness和Agent的关系可以参考这样一个类比Agent是业务逻辑Harness是运行框架。业务逻辑定义这个助手能干什么运行框架定义它怎么稳定地干完一件事。很多项目的Agent一开始没有Harness层直接循环调用工具。初期数据量小看不出来等到并发上来、工具变多、模型偶尔返回畸形参数时整个流程就会卡死。Harness的价值就在这个节点体现出来。5. 智能体工具设计从Function Calling到Tool RegistryAgent要真正完成任务光靠模型自身的知识远远不够必须接工具。工具是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 Schemafrom 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(modelgpt-4o-mini, temperature0) | 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( modelgpt-4o-mini, temperature0, api_keyyour-api-key, base_urlhttps://api.openai.com/v1 )本地部署方案以Ollama为例先拉取模型ollama pull qwen2.5:7b ollama serve然后LangChain里这样接入from langchain_ollama import ChatOllama local_model ChatOllama(modelqwen2.5:7b, temperature0)本地模型的优势是数据不出内网但要重点验证它的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(modelgpt-4o-mini, temperature0) 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(rsql|, , 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(titleTextToSQL 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, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) 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项目跑不通大多数不是模型的问题而是工程链路的问题。下面列一份高频排查清单。问题现象可能原因排查方式解决方案模型不调用工具工具Schema不清晰或模型不支持Function Calling检查工具描述和参数定义能否正确返回tool_calls简化工具描述、换支持工具调用的模型SQL生成后执行报错字段名或表名不存在、SQL方言不兼容查看具体报错信息把错误信息回传给模型重写SQLSchema提示词过长表太多、字段太多统计Token占用先做表路由只注入相关表Schema工具返回数据太大查询返回全量数据检查工具返回行数默认Top-N或聚合返回上下文窗口溢出多轮工具调用结果堆积查看模型调用日志在Harness层截断、概括历史批量任务卡住单条任务异常未捕获查看任务日志增加超时和重试机制API调用限流并发过高或触发供应商限制检查接口返回码增加退避重试和并发控制本地模型效果差模型参数小、指令遵循弱对比同一问题在不同模型上的输出换更大模型或调整提示词端口冲突服务端口被占用检查端口监听情况换端口或清理旧进程数据库越权查询权限控制不到位检查SQL是否包含敏感表使用只读账号并做SQL白名单拦截从实践经验看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落地的开发者有帮助建议收藏备用。