先讲个我从实际项目里带出来的观察很多团队做Agentic AI应用模型从GPT-4换到Claude再到DeepSeek效果始终上不去问题不在模型本身而在你喂给模型的那堆上下文。你塞进去的内容顺序不对、脏数据太多、历史对话全混在一起再强的模型也会被带偏。这个问题的解法就是上下文工程——一个比提示词工程更系统、更底层、也更值钱的活儿。这篇文章我结合自己用FastAPILangChainLangGraphRAGPGVector搭的一套Agentic AI系统把上下文工程的架构思路、核心组件、实操代码、踩坑记录全部拆开讲一遍。无论你是刚开始做智能体开发还是已经在用Dify、Coze这类平台搞Agent又或者准备自建复杂的多智能体系统这篇指南都能给你一套可以直接抄作业的上下文架构方案。1. 上下文工程为什么它是智能体理解问题的核心钥匙1.1 从提示词工程到上下文工程到底升级了什么提示词工程大家都很熟就是精心设计Prompt让模型输出更好的结果。但做Agentic AI的时候你会发现光靠提示词根本不够。智能体跟单轮问答最大的区别在于它要自己规划步骤、调用工具、读取外部数据、记住中间状态然后一步步完成目标。这意味着模型每次推理时看到的上下文不再是一段静态的Prompt而是一整套动态拼装的信息集合。这套信息集合包括系统指令、用户当前意图、历史对话摘要、检索到的知识片段、工具返回的原始数据、中间推理过程等等。怎么把这些信息在正确的时机、以正确的顺序、用正确的格式组织起来才是决定智能体理解能力的关键。我把这个区别总结成一句话提示词工程解决的是“怎么问问题”上下文工程解决的是“怎么把问题相关的所有信息组织好”。前者是点后者是面和链。1.2 Agentic AI上下文工程的三个核心矛盾做上下文架构之前必须先想清楚三个绕不开的矛盾不然架构搭出来必然是空中楼阁。第一个是信息容量与质量之间的矛盾。上下文窗口再大也是有限的尤其当你接入RAG检索、多个工具返回结果、多轮对话历史之后塞进上下文的内容很容易膨胀。但内容越多不代表效果越好全是噪声反而会稀释真正关键的信息。所以上下文工程的本质是“在有限的窗口里做信息的最优配置”。第二个是短期记忆与长期记忆之间的矛盾。用户跟智能体聊天上下文是连续的。但你不能把全部历史消息都塞给模型成本太高。必须设计一套机制把短期的工作记忆和长期的事实记忆分开管理该记住的记住该忘记的忘记。第三个是单智能体与多智能体之间的上下文隔离问题。单Agent的上下文管理已经够复杂了多Agent系统中各个Agent处理的是不同子任务上下文是共享还是隔离共享会互相污染隔离又丢失了协作所需的信息。这个矛盾必须在架构层解决而不是靠模型自适应。理解了这三个矛盾你再看下面的架构方案就会明白每一步设计都不是拍脑袋而是针对这些核心问题的正面回应。2. 智能体上下文架构的整体蓝图五层模型拆解2.1 五层上下文架构总览我自己在项目里沉淀了一套五层上下文架构从底层到顶层依次是接入层、理解层、检索层、记忆层、编排层。每一层负责一类问题层与层之间通过标准化的数据结构衔接。接入层管的是消息从哪进来用户的提问、系统的定时触发、外部API的回调都要在这一层统一转换成内部的消息格式。理解层负责意图识别、实体抽取、任务拆解属于把用户模糊的诉求变成机器能执行的计划。检索层负责从外部知识库中召回与当前任务相关的信息这是RAG和上下文工程结合最紧密的地方。记忆层维护短期会话历史和长期用户画像、业务事实相当于智能体的“大脑缓存”。编排层则决定推理流程怎么走什么时候调用工具、什么时候查库、什么时候直接回答对应LangGraph里的图逻辑。这套分层最大的好处是每一层的变化不会牵动全局。比如你换Embedding模型只动检索层改Prompt策略只动理解层调整用户会话策略只动记忆层。2.2 为什么选择RAGPGVector作为上下文供给底座上下文工程离不开外部知识的注入而RAG是目前最成熟的知识注入方案。我选了PGVector而不是专门的向量数据库如Milvus、Pinecone核心原因有三个。第一技术栈统一。我主后端是FastAPI数据层用的是PostgreSQLPGVector作为PostgreSQL的扩展直接复用现有的数据库连接、事务机制、备份恢复方案不需要额外引入一个高可用的向量库服务。很多人觉得越专业的工具越好实际上对于千万级以下的向量规模PGVector完全够用而且运维成本低得多。第二元数据过滤能力强。RAG场景里单纯靠向量相似度是不够的经常需要结合业务条件过滤。PGVector支持标准的SQL WHERE过滤我可以轻松实现“在某个用户的项目空间内检索、排除过期文档”这类需求。这在专门的向量数据库里实现起来要绕很多弯。第三事务一致性。文档入库通常是多表联动的文档表、分块表、向量表必须保证原子性。PGVector天然继承PostgreSQL的事务能力一条事务里同时写业务数据和向量数据绝无中间状态。这在Milvus里要先写向量再写业务表一旦失败很难对齐。2.3 上下文工程不只是RAG还有记忆与规划我必须强调一下很多团队把上下文工程等同于RAG这个理解是片面的。RAG解决的是“把外部知识拉进来”的问题但上下文工程还要解决“怎么把这个知识跟历史对话、当前意图组合起来”的问题。举个例子。用户问“帮我把上次那篇关于Transformer的文档翻译成英文”这里的关键信息“上次那篇文档”在知识库里根本搜不到它藏在历史会话记忆里。你必须从记忆层把用户上次浏览的文档ID找出来再拿这个ID去检索层精准获取文档内容。这个过程涉及记忆层和检索层的协同光有RAG是做不到的。另外Agent在推理过程中生成的中间结果比如拆解出的子任务列表、确认过的约束条件也是上下文的一部分。这些内容如果不通过编排层妥善管理要么丢失导致Agent“失忆”要么全部堆进上下文导致混乱。所以上下文架构中的编排层负责把记忆、检索、推理状态串成一条线本质上是智能体的“工作记忆管理器”。3. 核心组件落地FastAPILangChainLangGraph全套实践3.1 FastAPI作为Agent服务骨架的关键设计FastAPI在这个架构里不只是一个HTTP框架它是整个Agent服务的请求入口、任务分发中枢和事件回调网关。我的做法是给Agent服务设计了三个核心接口。第一个是同步执行接口。用户发起一次请求服务端同步执行完整个Agent流程返回最终结果。适合问答类场景逻辑简单直接。第二个是异步任务接口。Agent流程比较长或者需要人工介入审批就先提交任务返回任务ID跑完后通过Webhook或轮询获取结果。第三个是流式接口。用Server-Sent EventsSSE把Agent的思考过程、工具调用过程逐步推给前端。这个在智能体应用中特别重要用户看到智能体在“一步步干活”信任感会强很多。FastAPI的异步机制和LangGraph的异步执行配合得很好。用async def定义端点调用graph.ainvoke()整个链路从请求到响应都是异步的不会阻塞事件循环。我在生产环境里单实例可以稳定支撑每秒20个并发Agent请求瓶颈反而出在LLM API的速率限制上而不是服务本身。3.2 LangGraph工作流的状态设计与上下文装配LangGraph的核心概念是状态图每个节点的输入输出都是全局状态对象。上下文工程在这里的体现就是把所有上下文信息挂载到状态对象上并在不同节点间传递和更新。我的状态对象设计分几个关键字段。messages字段存对话历史_internal字段存Agent内部推理状态比如子任务列表、当前步骤编号retrieved_docs字段存检索结果memory字段存从记忆层加载的用户画像和长期事实。每个字段有明确的写入方和读取方比如retrieved_docs只在检索节点写入在生成节点读取其他节点不允许修改。LangGraph提供了StateGraph和图状态管理器可以让状态在节点之间安全流转。我实际用下来最有价值的功能是条件边它允许你根据当前状态动态决定下一步走向。比如Agent在生成过程中检测到信息不足可以触发检索节点重新检索再回到生成节点继续执行而不是傻乎乎地硬编答案。这种动态装配上下文的能力是传统Chain式调用做不到的也是Agentic AI和普通RAG问答的本质区别。3.3 上下文组装的三段式Prompt结构有了状态对象之后最核心的一步就是把这些状态动态组装成最终发给LLM的Prompt。我的组装策略是严格的三段式结构。第一段是System Message包含系统指令、可用工具清单、输出格式约束、行为准则。这里我特别强调指令要用“必须有/不允许有/如果遇到X则Y”这种强约束句式少用“可以尝试/尽量”这种软性词。模型对强约束的服从率明显更高。第二段是Dynamic Context按优先级排列检索结果、工具返回数据、记忆层加载的用户画像。每个信息块都用XML风格的标签包裹比如retrieved_docs、user_profile不同信息源之间用清晰的分隔符。模型对结构化的信息块理解准确度远高于混在一起的大段文本。第三段是Conversation History由最近的几轮完整对话加上更早历史的摘要组成。近处细、远处粗这是对话记忆的基本原则。3.4 PGVector向量检索的完整实现检索层的实现我分成入库和召回两条链路。入库链路文档清洗后按500个字符的块大小切分重叠50个字符。这里对中文场景要特别注意直接用字符切分会把语义切碎我在项目里是用句子边界做切断的保证每个块至少包含一个完整的语义单元。Embedding模型用的是BGE-M3它在中文语义匹配上表现比OpenAI的text-embedding-ada-002要好不少而且是开源的可以本地部署数据不出内网。召回链路LangChain里定义PGVector的Retriever配置检索参数。真实场景中只用向量相似度远远不够我做了混合检索。向量检索负责“语义相关”全文检索负责“关键词精确匹配”两条召回结果通过RRFReciprocal Rank Fusion算法融合再经重排模型二次排序。这个策略把检索准确率从纯向量的62%提升到了81%差距非常大。4. 上下文智能化记忆分层与检索增强的进阶玩法4.1 短期工作记忆与长期事实记忆的分层设计记忆层是整个上下文架构里最容易被人忽略却后劲最大的模块。我把它拆成两层。短期工作记忆是指当前会话周期内的消息序列、状态变量、临时产出的中间结果用Redis存储设置两小时的过期时间。这层记忆对智能体保持对话连贯性至关重要。用户中途问一句“刚才那个方案的成本是多少”Agent需要从短期记忆中精准定位“刚才那个方案”的具体内容。做法是给每条消息都打上时间戳和业务标签查询时先过滤标签再取文本。长期事实记忆是关于用户业务信息的持久化存储用PostgreSQL存储。用户的公司规模、偏好、历史订单记录、收藏的模板等这些信息结构稳定、生命周期长。每次会话开始时根据用户身份加载到上下文中让Agent从一开始就“了解”用户。分层的核心价值在于不同来源、不同生命周期的信息走不同的存储和加载路径互不干扰。没有分层的系统什么信息都往上下文里塞就像电脑C盘什么都往桌面放迟早卡死。4.2 对话历史的滑动窗口与摘要压缩对话历史是所有上下文组件中最容易失控的部分。特别是跟Agent做长任务时用户可能来回调整需求消息数量迅速膨胀。我的方案是双通道历史管理。最近10轮消息完整保留超过10轮的部分每次触发摘要生成用单独一次LLM调用把旧消息压缩成300字以内的结构化摘要然后塞进System Message里作为背景信息。由于摘要本身也占token我不能无限压缩当摘要超过5份时做二次压缩轮换掉最早的摘要。这套机制实测下来context token占用下降约40%关键信息召回率反而提升了。原因很简单完整的消息历史里大量重复表达和客套话稀释了关键内容的密度摘要化之后模型对核心信息的注意力更集中。4.3 多智能体场景下的上下文路由与隔离策略当你做多Agent系统时上下文工程从单机问题变成了分布式问题。我的实践是按“上下文域”来划分智能体。每个Agent有专属的上下文域域内包含自己的系统指令、工作记忆、检索索引子空间。Agent之间不直接共享上下文通信通过一个消息总线机制进行。消息总线上的消息是标准化的上下文包包含发送者ID、接收者ID、任务描述、业务数据。接收方拿到上下文包后会把它注入自己的上下文域中作为“外部输入”但不会让它污染系统指令和工作记忆。这种设计既保留了协作能力又防止了上下文传染。我在项目中试过三层级联的Agent结构主管Agent负责拆解任务专家Agent法律咨询Agent、财税计算Agent、文书生成Agent各自执行子任务质检Agent负责最终检查。每层之间通过上下文包协作上下文隔离性做得很好单个Agent的Prompt几乎不会因为多Agent协作而变得臃肿。5. 架构演进从RAG到Agentic RAG的关键升级5.1 被动检索和主动规划的本质区别现在大家都在讨论Agentic RAG也就是智能体化的检索增强生成。传统的RAG是被动的用户问一个问题系统检索一次拼装上下文模型回答一次就结束。Agentic RAG是主动的Agent自己判断需要哪些信息决定什么时候去检索检索什么检索完之后怎么用甚至检索结果不充分时会重新组织查询再检索一次。吃了很多亏之后我得说RAG的瓶颈从来不在检索算法本身而在于“何时检索、检索什么、用几次检索”这个决策逻辑。LangGraph给了实现Agentic RAG的图编排能力但图编排只是骨架真正的灵魂是“自我评估节点”。我做了一个信息充分性评估节点每次生成的候选回答会先过一遍自评对照用户问题检查关键信息是否覆盖。如果发现有信息缺口就重新进入检索循环最多循环三次。这套机制让Agent在复杂问题上的答对率提高了27%。5.2 多轮检索中的查询改写技术Agentic RAG中有一个特别实用的技巧——查询改写。用户的原始提问往往不是最优的检索查询语句。比如用户说“我记不太清了好像是一个客户来咨询劳务纠纷的事还问了赔偿金”这段话口语化严重、关键实体模糊直接拿去向量检索效果很差。我的做法是在检索前增加一个查询理解节点由LLM把用户的原话改写成一到三个适合检索的查询词再统一执行检索。改写的约束是不添加原文没有的信息、不改变用户意图、尽量提取关键实体。实际效果对比下来查询改写能将检索结果的相关性分数提升约20%在多轮对话场景中提升更明显因为模型会把对话历史中的隐含信息也纳入改写考量。5.3 上下文工程的成本控制与性能优化上下文工程做得越好LLM调用成本越可控。我在项目里做了两层优化。第一层是Token预算管理。每个Agent执行前根据用户类型免费用户/付费用户和场景复杂度预设Token预算。上下文装配时严格按照预算分配系统指令固定3000字、检索结果最多4000字、对话历史最多6000字超出部分截断或摘要化。这套预算机制实施后单次请求的平均Token消耗下降了约35%。第二层是缓存复用。相同用户、相同场景下的上下文片段是可以缓存的。我今天在项目里用了Redis做两级缓存——全局高频问题的检索结果缓存以及同一会话内重复信息的片段缓存。实测命中率在25%左右每次命中可以省掉一次Embedding计算和一次向量检索IO响应时间也能降下来。6. 常见问题与排查技巧实战实录6.1 上下文丢失Agent中途忘记关键指令怎么办症状Agent在长流程执行到后半段时不再遵循初始系统指令比如任务拆解后开始自说自话或者把用户早期提的约束条件忘了。根因排查先确认是不是上下文窗口溢出把中间过程的Token消耗打印出来看峰值如果接近模型窗口上限多半是旧内容被截断。再看是不是Prompt结构问题系统指令被淹没在大量检索内容里模型注意力偏移了。解决方案一是把系统指令放到消息序列开头并在关键步骤节点重复携带“核心约束卡片”二是用LangGraph的条件检查节点每次生成前都过一遍约束校验发现偏离就拦截并由LLM重新生成三是检索内容严格控制在预算范围内宁缺毋滥。6.2 检索噪声召回了一堆不相关内容怎么治理症状RAG检索召回的结果跟当前问题只有字面关联没有语义关联模型被这些噪声带偏输出质量下降。根因排查第一看Embedding模型是不是跟语料领域不匹配通用模型在专业领域法律、医疗、技术文档效果往往欠佳。第二看召回策略相似度阈值定太低大量无关块混进来。解决方案一是根据领域微调或替换Embedding模型二是设置Score阈值低于阈值的直接过滤三是引入重排模型对TopK结果二次打分用交叉编码器大幅提升相关性排序质量。我实测过BGE-Reranker重排能让最终生成的准确性提升12%以上。6.3 对话爆炸上下文无限膨胀导致性能和成本失控症状对话轮次增加后每次请求的Latency持续攀升Token消耗成倍增长最终上下文窗口溢出。根因排查缺少历史消息的裁剪策略所有消息全部发送给模型是典型错误。解决方案用我在4.2节讲的滑动窗口摘要压缩机制。另外还要注意工具调用结果和推理过程属于“过程上下文”一旦该步骤完成就没必要保留完整内容只把摘要写回状态即可。这个优化对长Agent流程太重要了一次20步的执行原始过程记录能占5000多token摘要记录只需600token。7. 最后的经验之谈做了大半年Agentic AI上下文工程我最大的感受是这个领域的核心技能已经从“写提示词”变成了“设计上下文生命周期”。你在搭建智能体系统时最先思考的应该是信息从哪来、在哪存、怎么流转、何时过期这是典型的架构工程思维而不是依赖模型在运行时随机应变。我个人保留的一个小习惯建议你也试试每次Agent执行完毕后把实际发往LLM的完整上下文日志存下来定期分析。你会发现上下文中的信息构成跟结果质量之间的关联度比Prompt措辞的影响大多了。这个分析数据就是你下一轮优化上下文架构的最可靠依据。如果你正在搭建自己的Agent系统按本文的五层架构去梳理先用PGVector把RAG链路跑通再用LangGraph把状态编排起来最后再处理记忆分层的细节这条路是清晰且可行的。踩过的坑我都写在问题章节了遇到相同的症状直接对照排查就行。
