让一次 LLM 调用跑起来很容易。让五个智能体在生产环境里可靠协作是完全不同的问题。真实用户会打破假设真实成本会迅速累积真实故障会以本地环境里看不到的方式级联。核心差异在于 harness。这篇指南覆盖完整的工程图景什么是 Agent Harness它由哪些组件构成如何设计支撑它的后端以及如何把一个能跑的系统优化成生产级系统。Agent Harness1.1 它是什么Agent Harness 是把语言模型包成可用系统的基础设施层。它不是模型也不是提示词。它是一层支撑结构用来回答模型本身无法回答的问题智能体步骤之间的工作产物放在哪里每个智能体能看到什么上下文又被明确禁止看到什么多个智能体如何协作避免互相踩到对方的上下文窗口智能体产出坏结果或者调用失败时怎么办成本如何追踪、设限和控制LLM 是推理引擎。Harness 是让它变得可用的系统。每一个严肃的智能体部署都有一个 harness只是有些是显式设计出来的有些是在迭代中偶然堆出来的。显式设计的版本更快、更便宜也更容易调试。1.2 五个组件一个设计良好的 harness 由五个概念组合而成。每个概念都对应生产环境里运行智能体时会暴露出来的一类失败模式。这五个组件是Orchestrator读取 brief按顺序分派任务验证完成情况报告任务结束。Subagents隔离的执行上下文每个上下文只负责一个任务和一个输出产物。Skills每个智能体自己的知识文档用来定义角色、输出格式和规则。Backend承载共享虚拟文件系统的状态层智能体通过它在步骤之间传递工作产物。Context Engineering控制每个智能体看见什么、什么时候看见、以什么顺序看见的工程纪律。理解每个组件为什么存在比记住 API 更有用。理解这些原因后面的设计决策才更容易扩展。后端后端是 harness 的状态管理层。它回答每个多智能体系统都必须回答的问题工作产物放在哪里2.1 用消息传状态的问题最直观的做法是通过对话消息传递智能体输出。Agent A 产出结构化洞察并返回。Orchestrator 保存这段响应再把它作为消息内容传给 Agent B。这会带来三个叠加的问题。上下文膨胀。Orchestrator 线程里的每条消息都会在后续每次调用中消耗 token。四个智能体运行完并把输出回传后orchestrator 会携带几千个 token 的内容而这些内容往往只有下一个智能体需要。任务结束前每次调用都会为这些历史内容付费。缺少检查界面。想看 Agent A 产出了什么只能解析 orchestrator 的对话历史。调试会变成在推理轨迹里翻找内容。耦合。Agent B 的行为依赖 Agent A 的响应以某个精确格式出现在对话里。Agent A 的输出 schema 一变Agent B 就会坏掉。这种耦合在失败前通常不可见。2.2 虚拟文件系统StateBackend用虚拟文件系统解决这三个问题。它为每个任务提供一个内存中的工作区作用域只覆盖本次运行。智能体之间不通过消息传递内容。它们把文件写入工作区再从工作区读取文件。一个五智能体流水线的典型工作区会在任务开始时预置一个brief.md这是唯一输入。之后每个智能体各写一个文件提取出的洞察、各个平台的草稿、最终审查笔记。提取器完成后写入自己的输出文件并用一句话确认。Orchestrator 的线程里只保存这一行确认不保存内容。下一个智能体运行时直接从文件读取。这一个改动就能让五智能体流水线中 orchestrator 的累计上下文减少大约 85%。每个中间产物都可以检查。智能体之间也被解耦每个智能体按路径读文件而不是按消息位置读内容。2.3 预置文件与组装结果工作区一开始是空的。在 orchestrator 运行前把流水线需要的所有内容预先写入工作区skill 文件、共享上下文文档以及本次任务的 brief。这样可以把文件系统准备和智能体运行分开。第一次 LLM 调用发生前工作区已经被完整定义。流水线结束后再读取工作区来组装结构化结果。这是调用方代码唯一读取文件内容的地方。最佳实践在流水线运行期间orchestrator 代码不要读取工作区内容。Orchestrator 只根据文件是否存在来推断进度。内容只在最后读取一次。2.4 从工作区推断进度基于文件的工作区有一个容易被低估的性质你可以通过哪些文件已经存在来推断流水线进度。智能体代码不需要显式进度回调。工作区状态就是进度状态。Skills3.1 Skill 是什么每个智能体都有一个具体任务。任务说明定义产出内容、输出格式和执行规则。这些内容写在 Skill 文件里。Skill 是 Markdown 文档会和系统提示词一起加载到智能体上下文中。关键设计决策是渐进式披露每个智能体只加载自己需要的 skill。把所有智能体的所有 skill 都塞进上下文是一种常见但错误的做法原因有两个。Token 成本。Skill 是每次调用都会加载的静态上下文。一个 X 写作智能体如果加载了 LinkedIn 格式说明就会在每次运行时为这些无关 token 付费而且它们不会贡献到输出。注意力退化。模型有时会应用错误上下文里的指令。一个智能体带着自己不需要的指令就有一定概率被这些指令影响。无关上下文越多问题越明显。每个智能体明确声明自己加载哪个 skill。Skill resolver 只加载匹配的文件。五个智能体五个 skill。每个智能体只看见自己的那一份。3.2 工具作用域遵循同一原则工具是 skill 概念的延伸。它们同样会增加 token因为工具定义计入输入也会增加行为表面积。只给智能体它真正会用到的工具。审查智能体拿到事实核查工具并且只有它负责验证外部声明。其他智能体不需要这个工具。不能调用外部 API 的写作智能体不应该拿到任何工具。一个用不上的工具只是开销付了 token增加了行为风险没有收益。最佳实践一个智能体的 skill 和工具集合应该压到完成具体任务所需的最小范围。只有在任务明确需要时再扩大作用域。子智能体与隔离上下文4.1 共享上下文窗口为什么会失败如果把多智能体流水线跑在同一个对话线程里每个智能体都会累积完整历史。等审查智能体运行时它会带着 orchestrator 的计划推理、每个写作智能体的输出确认以及修正过程里的所有来回消息。你会为这些 token 付费。质量也会下降因为审查智能体在一堆与自己任务无关的内容里做推理。4.2 子智能体在隔离环境中运行每个子智能体都运行在独立会话中自己的系统提示词、自己的 skill以及它从工作区明确读取的内容。Orchestrator 维护一份扁平的智能体描述列表。需要分派时它根据描述选择智能体。子智能体在自己的上下文里运行完成工作后写入工作区然后这个上下文被回收。成本差异很明显。一个五智能体流水线如果完全跑在共享线程里到最后一步会累计 15,000 到 30,000 个历史 token。使用隔离子智能体时每个智能体的上下文保持在 2,000 到 5,000 个 token。Orchestrator 的线程也保持轻量因为它累积的是文件路径和单行确认不是内容。最佳实践每个子智能体只在工作区产出一个文件。一个任务一个文件。这样进度追踪简单输出也容易检查。上下文工程上下文工程是控制什么进入智能体上下文窗口、什么时候进入、以什么顺序进入的工程纪律。它对成本和质量的影响超过其他大多数工程决策。5.1 静态内容先于动态内容这是基础规则必须无例外遵守。静态内容是许多请求中完全相同的内容系统提示词、skill 文件、工具定义、共享上下文文档。动态内容是每次请求都会变化的内容任务 ID、用户输入、时间戳、本次任务参数。正确顺序是工具定义最先因为最稳定然后是系统提示词然后是 skill 文件然后是对话历史最后是当前用户消息也就是完全动态、永远无法缓存的部分。模型服务商提供的 prompt caching 会缓存从前缀开始直到第一个动态内容之前的计算结果。缓存读取成本是正常输入价格的 10%。缓存未命中则按 100% 计费。任何违反“静态先于动态”的做法都会破坏缓存前缀。常见问题包括把任务 ID 或时间戳放进系统提示词把用户特定数据嵌进 skill 文件路径把环境特定 flag 放进系统消息或者在请求之间改变工具定义。修正方式始终一样把动态值移到用户消息里。5.2 持久记忆与单次任务上下文不是所有上下文都会以同样速度老化。持久记忆是每个任务都稳定不变的内容项目约定、行为指南、智能体如何处理边界情况。它应该放在共享文档里在构建执行图时作为 memory 加载。每个 worker 进程只计算和缓存一次。单次任务上下文是任务特定内容用户的 README、请求的平台、语气要求。它应该放在任务开始时预置到工作区的 brief 文档里作为流水线唯一的动态输入。判断某段上下文应该放在哪里可以问一个问题它在 1,000 个不同任务中是否完全相同如果是它是持久记忆。如果会随任务变化就应该放进 brief绝不应该出现在系统提示词里。5.3 线程压缩长时间运行的流水线会让对话线程变长。旧轮次通常不如最近轮次相关但仍然会在后续每次调用中消耗 token。线程摘要中间件可以自动处理这个问题。当线程超过可配置的 token 阈值时较早轮次会被压缩成摘要段落最近 N 条消息保持原文因为近期上下文最相关。最佳实践不要把摘要阈值设得太低。在上下文容量的 80% 处做摘要能给智能体留下工作空间又不会频繁压缩。40% 就开始摘要会把 token 浪费在摘要开销上。Orchestrator6.1 协调而不是执行Orchestrator 只负责一件事读取 brief按顺序分派任务验证完成情况报告结束。它明确不产出内容。这是硬性的架构约束不是建议。Orchestrator 拥有系统里最宽的上下文。如果它开始推理领域任务比如写内容、做事实判断、格式化输出可能产出勉强可用的结果但会付出几个代价长推理轨迹填满上下文窗口协调角色和领域角色混淆并绕过子智能体实现的质量控制。只要 orchestrator 想产出领域内容就说明设计里少了一个子智能体。6.2 构建一次持续复用Orchestrator 的构建成本很高从磁盘加载 skill 文件、初始化模型客户端、编译 graph。应该在进程级缓存它。每个 worker 构建一次然后在所有任务之间复用。一个 worker 每小时处理 40 个任务只需要构建一次 graph然后复用 40 次。模块级单例是 Python 里最简单也最可靠的模式。6.3 在提示词中强制流水线不变量Orchestrator 的系统提示词用来固化流水线规则只生成 brief 中列出的平台始终最后运行验证把任务 ID 明确传给每个子智能体永远不要直接写草稿文件报告完成前确认文件存在。这些是协调规则不是提示。要写得明确、直接。Orchestrator 的提示词应该像技术运行手册而不是创意 brief。缓存栈智能体系统里的缓存比传统应用更有杠杆因为你可以在多个层级避免工作。每一层的成本节省、命中率和实现复杂度都不同。7.1 第一层Provider prompt cachingAnthropic 的 prompt cache 会缓存稳定提示词前缀的 KV tensor 计算结果。后续请求如果前缀完全相同就以正常输入 token 价格的 10% 从缓存读取。前提是严格遵守静态先于动态的顺序。Cache control 可以透明地应用在每条 system message 上调用点不需要改变。工程师容易漏掉几个约束最低 token 阈值是 1,024。低于这个阈值的内容会静默缓存失败没有错误、没有警告只会缓存未命中并按全价计费。工具定义变化会让整个缓存层级失效。每个请求最多只能设置四个 cache breakpoint。7.2 第二层Redis LLM 响应缓存Prompt caching 降低 token 成本但不会消除 API 延迟因为你仍然要发 HTTP 请求并等待响应。Redis 响应缓存位于 API 上游命中时没有 HTTP 调用、没有 API 延迟也没有 token 成本。系统中的每一次 LLM 调用包括 orchestrator 和所有子智能体都会在发起 API 调用前先检查 Redis。缓存 key 是完整序列化消息列表与模型配置的哈希。把模型配置放进 key意味着模型升级会自动生成新 key。提示词变更时要给 key 加版本。没有版本管理时坏提示词会被缓存并在几个小时里持续返回。部署时提升版本号就能在不直接操作 Redis 的情况下刷新整层缓存。TTL 按环境设置开发环境 5 分钟提示词编辑可以马上看到预发环境 1 小时足够稳定可以捕获回归生产环境 24 小时最大化节省成本。7.3 第三层内容身份缓存在一些系统里同一份源材料会反复出现比如不同用户提交同一个热门开源仓库同一份文档被多次处理。内容身份缓存可以直接跳过最昂贵的流水线步骤。对原始源内容做哈希。同一份文档即使用户指定参数不同也会落到同一个 key因为源内容相同。这层缓存基于内容身份不基于提示词身份。命中时完全绕过 LLM没有 API 调用、没有 token、没有延迟。TTL 可以更长对大多数内容来说七天也合理。Token 优化Token 是 LLM 系统的成本单位。每一处低效都会在每个用户、每个请求、每次重试中累积。8.1 执行前先估算不要在没有估算 token 成本的情况下运行任务。一个粗略估算器可以用字符数除以四这是英文文本的可靠近似值再加上 skill 和上下文文件的固定开销。每个任务都记录这个估算。生产流量跑一周后你会得到真实的 P50/P95 数据。这些数字能让你基于事实设置告警阈值而不是猜。8.2 在边界处校验并截断输入进入队列前先校验大小。输入过大时优先截断而不是拒绝。有些用户输入很长但仍然应该得到结果只是结果来自信息密度最高的部分。截断要贴到结构边界上比如段落换行或小节标题避免把半句话传给模型。追加截断标记让模型知道文档不完整。8.3 按任务路由模型流水线里的每个智能体不一定都需要最强、最贵的模型。从 Markdown 文档中做结构化抽取小模型就能处理得很好。涉及多文档交叉引用和判断的任务则更适合强推理模型。把便宜模型路由给抽取、分类和格式校验。把强模型留给最终审查和复杂多步推理。如果设计正确总流水线成本可以降低 40% 到 60%整体输出质量不下降。异步任务架构9.1 为什么需要任务队列非平凡智能体流水线通常需要 45 到 120 秒。HTTP 连接默认 30 秒就会超时。即使不超时为每个活跃任务占着一个连接也很浪费资源。正确架构是立即接受请求返回任务 ID异步运行流水线。客户端轮询状态。Worker 完成后立刻把结果写入快速存储。轮询循环的总开销只有毫秒级。9.2 用 Celery 处理 LLM 工作负载LLM 任务是 I/O 密集型不是 CPU 密集型。Worker 线程大部分时间都在等待 API 响应。这意味着并发数可以远高于 CPU 核数。geventpool 使用协作式多任务线程在等待 I/O 时让出执行权让其他任务运行。对于 4 核机器如果每个任务 70% 到 80% 的时间在等 API 响应同时跑 32 个 LLM 任务是合理的。9.3 双存储模式Redis 快但不适合作为持久事实来源。Postgres 持久但访问更慢。两者应该负责不同用途。Redis 处理实时轮询场景比如客户端每隔几秒检查状态需要亚毫秒级响应。Postgres 处理历史场景用户任务历史、计费、调试昨天的任务。写入模式每次状态变化都同时写入两边。读取模式先查 Redis如果 key 已过期再回退到 Postgres。不要把 Redis 当成事实来源。TTL 过期是静默发生的。开发工作流10.1 先用本地模型再用云模型验证通过让 harness 接受任何 LangChain 兼容模型把开发迭代和成本分开。开发阶段使用本地 Ollama 模型免费、快速也不需要 API key。本地输出质量低于前沿模型。但它足以验证文件是否写入正确的工作区路径、orchestrator 是否按正确顺序分派任务、结果组装是否把工作区文件解析成预期结构以及错误处理是否按设计运行。当某个 skill 文件变化需要做质量验证时切到云厂商跑一次测试。跑完立刻切回本地。这样提示词和 skill 开发的迭代成本基本为零。10.2 测试 harness而不是测试模型Agent Harness 的单元测试应该测试 harness 行为而不是模型输出。模型是不确定的harness 不是。应该测试的内容包括工作区初始化是否产生预期文件结构结果组装是否正确读取每种文件类型token 估算是否对已知输入返回正确总量截断是否正确贴到段落边界缓存 key 生成是否确定状态转移是否遵循定义好的合法转移图。不应该在单元测试层面测试模型是否产出好内容。那属于使用真实模型的集成测试应该定期运行而不是每次提交都跑。可观测性LLM 系统的可观测性比传统系统更难因为最重要的失败模式往往是质量退化。没有合适工具时它是不可见的。慢 API 调用会出现在延迟指标里。智能体产出细微错误内容时指标未必会告诉你。11.1 结构化日志每一行日志都应该可被机器解析。所有日志使用一致字段名比如任务 ID、状态、步骤、耗时、响应是否来自缓存。这样即使没有结构化日志系统也可以在完整日志历史里 grep、过滤和聚合。用这种格式从日志文件里提取 P95 延迟就是一行 shell 命令。11.2 LLM 调用追踪结构化日志提供任务级可见性。追踪层提供调用级可见性完整提示词、响应、实际 token 数、每次调用的延迟并拆分到首 token 时间和生成时间以及 orchestrator 与子智能体之间的完整调用树。当用户报告输出错误时你可以打开对应任务 ID 的 trace直接看到哪个提示词产出了问题。没有这层能力调试幻觉或错误智能体行为基本是在猜。11.3 缓存命中率是成本信号要显式追踪缓存表现。LLM 响应缓存命中率突然下降通常意味着提示词发生了变化动态值泄漏进了原本静态的区域模型升级了或者 skill 文件被意外修改。应该对它告警。这是成本事件很容易等到账单周期结束才发现。总结设计原则这篇指南里的每个决策都来自五条原则。减少累计上下文。携带更少上下文的智能体更便宜、更快也更专注。工作区后端、子智能体隔离、线程压缩都服务于这条原则。静态内容永远先于动态内容。Prompt caching 是已部署智能体系统里投资回报率最高的优化。它要求每个提示词中静态内容都排在动态内容之前没有例外。把知识限定在角色范围内。智能体应该只知道完成自己任务所需的内容。Skills、工具和上下文文件都应该收窄到最小范围。不必要的上下文会消耗 token也会削弱专注度。清晰分离职责。Orchestrator 负责协调子智能体负责执行后端负责保存状态。这些角色不应该重叠。一旦重叠调试会明显变难。花钱之前先估算、校验和设边界。Token 成本会累积。输入校验、执行前估算和硬性上限可以避免失控支出变成生产事故。这里描述的基础设施并不炫目也不会出现在演示里。但它决定了一个智能体是只能在你笔记本上跑还是能可靠服务真实用户。结语这篇指南来自另一种视角你有真实用户、真实成本系统还必须在凌晨三点你没有盯着的时候正常工作。这五个组件解决的不是有趣的 AI 问题。它们解决的是枯燥的基础设施问题。而生产系统往往就栽在这些枯燥问题上。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】