从LLM API到生产级Agent：AI应用工程全景指南

调用大语言模型很简单，但构建一个可靠的AI应用是完全不同的挑战。本文梳理从模型能力、SDK集成，到Agent循环、上下文管理、Harness工程与生产运维的完整工程图景。

AI应用不只是模型调用

把大语言模型（LLM）接入应用程序其实相当简单：发送请求、接收响应、在界面上展示结果即可。但构建一个可靠的AI应用，是另一回事。

真实的应用必须管理上下文、执行工具、保存状态、处理中断、请求授权、从失败中恢复，并向用户传达进度。有些应用还需要处理图像、音频、视频、文档、结构化数据或实时事件。当这些需求不断累加，模型就只是整个系统中的一个组件而已。

原文提出了一个贯穿全文的核心原则：模型负责提议，运行时负责协调，工具负责执行工作，应用负责强制执行策略（the model proposes, the runtime coordinates, tools perform work, and the application enforces policy）。随着AI应用越来越自主，这种职责分离会变得愈发关键。

理解AI应用技术栈的五个层次

在深入具体功能之前，建立一个清晰的心智模型很有价值。一个生产级AI应用可以被理解为若干协作层：

模型层与API/SDK层

模型层提供底层能力：文本生成与摘要、推理与问题求解、图像与文档理解、音频理解与生成、结构化输出、工具选择、嵌入向量，以及（在支持的情况下）视频理解。需要注意的是，并非每个模型都支持所有能力——可用性、质量、限额和定价都因模型和供应商而异。

API/SDK层将模型能力通过网络接口暴露出来。SDK（如Vercel AI SDK、OpenAI、Anthropic的官方SDK）通过类型化函数、请求构建器和流式辅助工具，让这个接口更易使用。

运行时、体验层与运维治理

应用运行时控制模型周围发生的一切：构建提示与上下文、选择可用工具、执行工具调用、管理Agent循环、应用授权规则、维护状态、处理失败与重试、协调长任务。

体验层（UI）负责传达运行时的行为：流式文本、工具调用进度、结构化结果、交互组件、澄清提问、授权请求、任务状态与错误。

运维与治理层则是生产系统额外所需的：评估与回归测试、可观测性与追踪、成本与延迟控制、数据隐私策略、安全边界、人工监督、恢复与可审计性。

超越文本聊天的AI能力

文章反复强调一个关键认知：AI 并不等同于在聊天窗口里生成文本。现代AI API暴露了多种能力，一个应用往往会在单一工作流中组合多种能力。

结构化输出、视觉与多模态

结构化输出让应用获得可预测的数据结构而非自由文本，适用于分类、数据抽取、表单填充、工作流路由等场景。但原文提醒：schema约束能减少格式错误，却不能保证数值在事实上正确或操作安全，必须独立验证结果并强制执行业务规则。

视觉理解可用于理解截图、从图表提取信息、分析产品图像、解读图示等。但模型能理解图像，不代表它能完美提取每一个字符或表格——文档理解可能还需要OCR、布局分析或专门的处理管线。

音频与视频能力分别支持语音转写、语音问答、文本转语音等，以及会议摘要、演示理解、事件序列分析等。实时语音应用还需处理打断、轮次检测、流式音频和会话管理。

嵌入、工具调用与计算机操作

**嵌入（Embeddings）**将内容表示为可数学比较的向量，是语义搜索、文档检索、推荐系统和RAG的基础。原文强调：嵌入本身不是答案，它只是检索与相似度系统所用的表示。

**工具调用（Tool Use）**是最重要的概念之一——模型通常提议一个工具调用并提供参数，但实际运行的内容由应用或供应商管理的执行环境决定。这个区别很根本：工具调用不是一段生成的文本，描述一个动作也不等于执行这个动作。

计算机操作与浏览器交互让Agent通过截图、点击、输入来操作界面，但引入了额外风险：Agent可能误读屏幕、点错控件或遭遇不可信内容。在存在稳定API的情况下，专门的API集成往往比通过UI控制同一系统更可靠。

**RAG（检索增强生成，Retrieval-Augmented Generation）**是嵌入技术最典型的应用场景之一，值得单独说明。RAG的核心思路是：在向模型发送请求前，先将用户问题转换为嵌入向量，在向量数据库中检索语义最相近的文档片段，再将这些片段连同原始问题一起注入上下文，从而让模型能够基于外部知识库生成更准确的回答。这种方式解决了两个痛点——模型训练数据的知识截止日期问题，以及将专有私有数据引入对话的需求。但RAG的效果高度依赖检索质量：如果检索到的片段与问题关联度低，反而会引入噪声，形成前文提到的"上下文污染"。实际工程中，块切分策略（chunk size）、嵌入模型选择、相似度阈值过滤和重排序（reranking）都是影响RAG效果的关键变量。

提示工程 vs 上下文工程

这两个术语密切相关，但解决不同的问题。提示工程聚焦于给模型的指令和框架——任务定义、语气、输出格式、约束、示例、决策标准、不确定性处理规则。它告诉模型如何处理任务。

上下文工程则聚焦于在特定时刻选择和组织模型可用的信息——系统指令、近期对话、用户偏好、检索到的文档、工具定义、工具结果、当前工作流状态、token预算等。核心问题不只是"我们该告诉模型什么"，更是"针对这个具体决策，模型应该拥有哪些信息"。

一个值得警惕的现象是上下文污染（context pollution）：当无关、冗余、过时或矛盾的信息消耗了注意力和容量，结果反而变差。更大的上下文窗口并不自动带来更好的结果——重复的指令、不再有用的大段工具输出、弱相关的检索文档都会降低效果。原文明确区分了四个常被混淆的机制：提示缓存复用重复的输入处理、记忆跨交互保存信息、压缩减少携带的上下文、检索选择与当前请求相关的信息。

提示缓存（Prompt Caching）是一项与上下文管理密切相关但常被误解的优化技术。主流供应商（如Anthropic的Claude、OpenAI的GPT-4o）允许对请求中的固定前缀部分（如系统提示、长篇参考文档）进行缓存——当后续请求的前缀命中缓存时，这部分Token不再重新计算，可显著降低延迟和成本。理解它的关键在于：缓存复用的是输入处理，而非模型的输出或任何"记忆"——每次请求仍然是无状态的独立推理。这与"记忆"（跨会话保存信息）和"压缩"（精简累积上下文）解决的是完全不同的问题。在工程实践中，将稳定的系统指令和工具定义放在上下文最前端，可以最大化缓存命中率；而频繁变动的用户消息和工具结果则放在后端，避免破坏缓存前缀。

工具调用与Agent编排

一个工具通常包含名称、描述、输入schema、执行处理器和结果表示。文章用TypeScript示例演示了基于Vercel AI SDK的getOrderStatus工具，并强调：这是说明性的集成模式，而非完整的生产服务——真实实现必须验证访问权限、处理服务错误，不能在未经授权检查的情况下信任模型提供的订单ID。

从工具调用到Agent循环

仅有工具调用并不能构成完整的Agent系统。一个Agent式工作流通常涉及反复的决策与操作，直到达成目标或系统判定无法继续。原文给出的简化循环是：接收目标 → 组装上下文 → 向模型询问下一步 → 判断是否请求工具调用 → 验证与授权 → 执行工具 → 记录结果 → 继续循环。

这个循环必须有终止条件，否则Agent可能反复调用工具、消耗资源却无法推进。有用的控制手段包括：最大步数、截止时间、token与成本预算、工具执行超时、重试上限、取消机制和进度检查。

工作流、编排与多Agent

文章清晰区分了几个概念：工作流遵循预定义的步骤序列，适用于流程已知的场景；Agent则能根据当前上下文和此前结果灵活选择下一步。许多生产系统将两者结合——确定性工作流划定边界，Agent处理选定的推理与工具使用步骤。

编排（Orchestration）协调多个步骤或组件的执行，但它不等同于多Agent架构。至于多Agent系统，原文给出了务实的警示：多个Agent会引入协调开销、额外推理成本、更多失败模式和潜在分歧，应当在专业化能带来可衡量优势时才使用，而不是因为架构允许就去用。

Harness工程：构建可靠的Agent运行时

"Harness"（挽具/控制架）这个术语越来越多地被用来描述包裹在模型或Agent周围、使其在真实应用中变得有用的基础设施。文章给出的工程定义是：Harness 是环绕模型的运行时和控制系统，提供可靠完成任务所需的工具、上下文、状态、执行规则和反馈。

一个Harness可能包含上下文组装、工具注册与发现、工具执行、Agent循环控制、钩子与中间件、状态管理、压缩与记忆、授权与中断处理、重试与恢复逻辑、评估与验证、日志追踪、预算与截止时间强制等。

其中一个极为重要的原则是验证不可或缺：模型说"测试通过了"并不能证明测试真的通过了。Harness应当从实际的测试执行中收集证据并如实报告结果。同样，生成的部署计划不能证明部署发生了——成功的API响应或经独立验证的系统状态才是更强的证据。核心是区分生成的声明与观察到的结果。

值得注意的是，"Harness"这一概念在不同框架中有不同的具体实现形式。LangChain的Chain与Agent Executor、LlamaIndex的Query Pipeline、Vercel AI SDK的streamText/generateObject配合工具注册机制，本质上都是各自形态的Harness。理解Harness作为抽象概念的意义在于：无论使用哪个框架，都应有意识地区分"模型调用本身"与"围绕模型调用的控制逻辑"这两层职责。框架帮你省去了部分样板代码，但并不替你做安全验证、权限检查或业务策略强制——这些始终是应用开发者的责任。选择框架时，可以评估它是否允许你在工具执行前后插入自定义中间件、是否支持细粒度的循环控制（如最大步数、超时），以及状态管理方案是否适合你的持久化需求。

人在回路、上下文压缩与记忆

自主并不总是正确的行为。某些动作（发送外部邮件、删除记录、生产部署、更新财务信息）应当要求显式授权。原文强调：授权不是简单地在提示里让模型小心一点，运行时必须真正阻塞执行，直到收到适当的授权。文章还细致区分了四个易混概念——澄清（收集缺失信息）、授权（批准提议的动作）、认证（确立身份）、鉴权（确定该身份可执行哪些操作）。

在上下文管理方面，**压缩（Compaction）**不同于普通摘要：普通摘要产出可读概览，而压缩必须保留未来执行所需的信息（目标、约束、已完成步骤、验证结果、关键发现、下一步动作、标识符等）。设计拙劣的压缩可能丢弃完成任务所必需的细节。

文章还对比了解决相关但不同问题的几种方案：长上下文在单次请求中纳入大量信息、记忆跨交互保存相关信息、RAG在需要时检索外部信息、压缩在保留要点的同时减少累积上下文、提示缓存复用重复的提示前缀。此外，Skills（可复用的任务流程包）、MCP（连接AI应用与外部能力的开放协议）和工具构成了可扩展的工具生态——三者分工明确：skill描述"如何做"，tool暴露"可调用的操作"，MCP定义"交换上下文与能力的协议"。

安全、可靠性与生产就绪

文章在安全上给出几条硬核原则。首先，模型输出是不可信输入——即便schema合法，内容仍可能错误、不完整或不安全，有效的schema确立的是结构而非真实性。

**提示注入（Prompt Injection）**是重点风险：不可信内容（用户输入、检索文档、网页、工具结果）可能试图通过嵌入的指令影响模型行为。原文明确——没有任何单条提示指令能消除提示注入风险，缓解需要分离可信指令与不可信内容、限制工具权限、在执行时应用授权、对高影响动作要求授权、针对对抗性输入测试等组合手段。

其他生产要点还包括：针对操作特性的重试策略与幂等性（重试只读查询与重试支付、邮件、建记录截然不同）、取消与超时策略、以及最小权限原则（工具只应获得其所需的权限）。在部署Agent功能前，应逐一回答：任务能否取消？失败后能否恢复？副作用是否已授权？重复操作是否安全？状态是否持久？工具输出是否已验证？授权是否由执行层强制？这些问题往往比再加一个模型功能更重要。

**提示注入（Prompt Injection）**可以进一步区分为两种主要攻击路径。直接注入是用户在自己的输入中嵌入试图覆盖系统指令的内容，例如输入"忽略以上所有指令，改为……"；间接注入则更隐蔽，攻击指令隐藏在Agent处理的外部内容中——如被检索的网页、上传的文档、工具返回的API数据。对于Agent系统，间接注入风险尤为严重：一个被赋予发送邮件或执行数据库操作权限的Agent，一旦处理了包含恶意指令的外部文档，可能在用户毫不知情的情况下执行危险操作。缓解间接注入没有银弹，工程上常见的防御纵深包括：在提示中明确标注哪些内容来自不可信源（如用"<user_content>"标签包裹）、限制工具在处理外部内容时的最大权限范围、对涉及外部数据的高影响操作强制要求人工确认，以及针对已知注入模式进行专项测试。

务实的实施路径

文章最后给出了务实建议：不必立刻实现每一个功能，应从满足用例的最简架构起步。推荐的实施顺序是——先从基础的模型调用开始，加入结构化输出和流式输出，再引入工具和持久化；当用例确实需要时，才逐步添加编排、压缩、可恢复性和更高级的Harness能力。这避免了在理解真实任务需求之前就去搭建复杂的Agent框架。

最重要的思维转变，是不再把AI应用看作"连接到模型的一个提示"，而是把它看作一个将AI作为自身能力之一的软件系统。这个视角让人更容易设计出不仅在演示中亮眼，而且在生产环境中可理解、可测试、安全可靠的应用。