第1章-Agentic AI范式演进-从Prompt到Harness-《Agentic AI 智能体应用开发》
第1章：Agentic AI 范式演进 —— 从 Prompt 到 Harness
本章导引
2023年，AI圈最火的关键词无疑是 Prompt Engineering。人们发现，精心设计的提示词可以让大语言模型（LLM）产生惊人的输出。一时间，"提示词工程师"成为热门岗位，各种 Prompt 模板、技巧、最佳实践如雨后春笋般涌现。
到了2025年，Context Engineering 悄然兴起。当上下文窗口从 4K 扩展到 128K、1M、甚至更多，当模型能够处理整本书、整个代码库、整个对话历史时，问题的焦点从"怎么写提示词"转向了"如何构建上下文"。这是一种系统化思维：将多维度的信息——对话历史、用户画像、知识库片段、工具执行结果——有机整合为一个高质量上下文包。
而现在，2026年，Harness Engineering 应运而生。面对越来越复杂的 Agent 应用场景——多步推理、工具链调用、多 Agent 协作——仅靠上下文工程已经不够。我们需要一套完整的工程体系来驾驭（Harness）这一切。这套体系覆盖上下文管理、工具集成、推理控制、安全护栏、记忆系统和可观测性六大核心领域。
Agent = Model + Harness。如果说 Model 是 Agent 的"大脑"，那么 Harness 就是 Agent 的"身体"——大脑负责思考，身体负责行动。一个完整的 Agent 应用，不仅仅是调用模型 API，而是构建一个让模型可以在真实世界中安全、高效地运作的完整工程体系。
本章是全书的总纲。我们将一起回顾这三个工程范式的演变历程，深入理解 Agent 的核心定义和能力谱系，最终建立起 Harness Engineering 的完整认知框架。
1.1 三个时代的工程范式
AI 应用的工程范式演变，本质上是对"如何用模型构建可靠系统"这一根本问题的三次回答。每一次范式转换，都不是否定前一个，而是包容前一个，在更广阔的系统边界中重新定位工程重心。
1.1.1 Prompt Engineering (2023)：输入即编程
2023年初，ChatGPT 横空出世，让全世界意识到大语言模型的力量。但很快，人们就发现一个核心挑战：同样的模型，不同的提示词会产生天壤之别的结果。
"Prompt Engineering"这个概念由此诞生。它的核心信条是：输入即编程。通过精心构造输入文本的格式、结构、内容和约束，你可以"编程"模型的行为。
核心实践：提示词模板与模式
经典 Prompt Engineering 围绕以下核心模式展开：
1. 角色设定（Role Prompting）
你是一位拥有15年经验的资深Python后端工程师。
你对 Django、Flask、FastAPI 了如指掌，擅长编写清晰、可维护、高性能的代码。
请用你的专业知识回答以下问题。
这是 Prompt Engineering 最基础也最有效的模式。通过赋予模型一个具体角色，激活其对应领域的能力。
2. 少样本提示（Few-Shot Prompting）
在不改变模型参数的情况下，通过输入示例来引导模型输出格式：
将以下英文翻译成中文，格式为：英文 -> 中文
hello -> 你好
world -> 世界
artificial intelligence -> 人工智能
machine learning ->
模型会自然地输出"机器学习"。这种模式在分类、格式化输出、特定风格生成等任务中特别有效。
3. 思维链提示（Chain-of-Thought Prompting）
2022年，Google 研究团队发现，在提示词中加入"让我们一步步思考（Let’s think step by step）"可以显著提升模型在推理任务上的表现。这就是 Chain-of-Thought (CoT) 的起源。
问：一个农场有23只鸡和16只兔子。每只鸡被7个人买走，
每只兔子被5个人买走。总共有多少人参与了购买？让我们一步步思考。
1. 23只鸡 × 7人/只 = 161人买鸡
2. 16只兔子 × 5人/只 = 80人买兔子
3. 161 + 80 = 241人
答：总共有241人参与了购买。
4. 结构化输出提示
要求模型以特定格式（JSON、XML、Markdown 表格等）输出：
请分析以下代码的安全漏洞，以JSON格式输出：
{
"vulnerabilities": [
{
"severity": "高/中/低",
"type": "漏洞类型",
"location": "代码行号",
"description": "漏洞描述",
"fix": "修复建议"
}
]
}
Prompt Engineering 的局限性
然而，随着应用场景的复杂化，Prompt Engineering 的局限性逐渐暴露：
-
上下文长度限制：早期模型的上下文窗口只有 4K-8K tokens，无法容纳足够多的背景信息。即使精心构造了提示词，模型也很快就会"遗忘"前面的内容。
-
模板的死板性：一个模板适合A场景可能完全不适合B场景。维护大量的 Prompt 模板本身就是一件痛苦的事，更不用说不同版本模型对同一模板的反应可能截然不同。
-
无法获取外部信息：纯粹的 Prompt Engineering 只能依赖模型训练数据中的知识。当需要实时信息、私有数据或专业领域知识时，仅靠提示词无法解决问题。
-
缺乏行动能力：模型只能"说"，不能"做"。当用户需要模型操作文件、查询数据库、调用 API 时，Prompt Engineering 束手无策。
-
脆弱性：提示词对措辞极其敏感。一个词的改变可能导致输出质量的巨大波动。加之 Prompt Injection 等安全威胁，使得 Prompt 本身的管理变得困难。
这些局限，推动着工程范式向下一阶段演进。
1.1.2 Context Engineering (2025)：上下文作为系统化输入
如果说 Prompt Engineering 关注的是"怎么说"，那么 Context Engineering 关注的是"给什么信息"。这是一个从"写好提示词"到"构建好上下文"的思维转变。
范式转变的核心驱动力
推动 Context Engineering 成为主流的核心驱动力有三方面：
驱动一：上下文窗口的极大扩展
| 时间 | 模型 | 上下文窗口 | 意味着 |
|---|---|---|---|
| 2022 | GPT-3.5 | 4K tokens | 约一本小册子的几页 |
| 2023 | GPT-4 | 8K-32K tokens | 约一篇中等长度的论文 |
| 2024 | Claude 3 | 200K tokens | 约一本中等厚度的书 |
| 2024 | Gemini 1.5 Pro | 1M-2M tokens | 约《战争与和平》全本 |
| 2025 | Claude 4 | 200K tokens | 深度推理+长上下文 |
| 2026 | 各主流模型 | 128K-2M tokens | 长上下文成为标配 |
当上下文窗口从 4K 扩展到 200K 甚至 2M 时，"在提示词中塞入什么信息"就从一个战术问题变成了一个战略问题。你可以把整个代码仓库、项目文档、对话历史、用户偏好全部放入上下文，让模型拥有前所未有的信息广度。
驱动二：工具调用的普及
2023年6月，OpenAI 发布了 Function Calling 能力，让模型可以调用外部工具。这意味着上下文不再只是静态的提示词——工具的执行结果、API 的返回值、数据库的查询结果都可以动态注入上下文。
Anthropic 随后推出了 Tool Use，Google 推出了 Function Calling，各大模型厂商都将工具集成作为核心能力。上下文的来源从"人工编写"扩展到"系统动态组装"。
驱动三：RAG 技术的成熟
检索增强生成（Retrieval-Augmented Generation，RAG）让模型可以在推理时动态检索外部知识。向量数据库的流行（Chroma、Qdrant、Pinecone、Weaviate）使得构建企业级知识检索系统变得简单。
Context Engineering 的核心要义
Context Engineering 将上下文视为一个系统化构建的工程产物，而非简单的手写文本。一个高质量的上下文包括：
┌─────────────────────────────────────────────┐
│ 模型上下文 (Context) │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ System Prompt（系统提示） │ │
│ │ - 角色定义 │ │
│ │ - 行为约束 │ │
│ │ - 安全规则 │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Dynamic Context（动态上下文） │ │
│ │ - 用户画像与偏好 │ │
│ │ - 当前会话状态 │ │
│ │ - 环境信息（时间、地点、设备） │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Retrieved Context（检索上下文） │ │
│ │ - RAG 检索到的文档片段 │ │
│ │ - 知识图谱查询结果 │ │
│ │ - API 返回的数据 │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Tool Results（工具执行结果） │ │
│ │ - 文件读取结果 │ │
│ │ - 代码执行输出 │ │
│ │ - Shell 命令结果 │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Conversation History（对话历史） │ │
│ │ - 用户消息 │ │
│ │ - 模型回答 │ │
│ │ - 工具调用记录 │ │
│ └───────────────────────────────────────┘ │
│ ┌───────────────────────────────────────┐ │
│ │ Current Task（当前任务） │ │
│ │ - 用户的最新输入 │ │
│ │ - 附带文件/图片 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
Context Engineering 的关键挑战在于：
-
窗口预算分配：不管窗口多大，总会用完。如何在有限的空间内分配"预算"给不同类型的上下文？System Prompt 占多少？检索结果占多少？对话历史占多少？这需要一个系统化的窗口管理策略。
-
上下文质量：不是所有信息都对当前任务有用。上下文中的低质量信息不仅浪费窗口，还可能干扰模型推理（即"上下文污染"）。需要对检索结果做相关性过滤、去重、排序。
-
上下文时效性：不同信息有不同的半衰期。用户画像变化慢，而工具执行结果几秒后就可能过时。需要精细地管理每类信息的生命周期。
-
跨任务上下文复用：同样的用户在不同任务中需要不同的上下文策略。如何在不重新构建整个上下文的前提下灵活切换？
从 Prompt Engineering 到 Context Engineering：一个对比
| 维度 | Prompt Engineering | Context Engineering |
|---|---|---|
| 核心关注 | 如何写提示词 | 如何构建上下文 |
| 输入来源 | 人工编写 | 多源动态组装 |
| 信息维度 | 单一文本 | 多层次结构化信息 |
| 动态性 | 静态 | 高度动态 |
| 工程复杂度 | 低 | 中 |
| 典型工具 | Prompt模板 | 向量数据库、RAG流水线、上下文管理器 |
| 适用场景 | 单轮对话、简单任务 | 多轮对话、知识密集型任务 |
Context Engineering 标志着 AI 工程走向系统化。但它仍有局限：它只解决了"给什么信息"的问题，没有解决"模型如何行动"的问题。这正是下一阶段——Harness Engineering——的历史使命。
1.1.3 Harness Engineering (2026)：模型之外的完整工程体系
为什么需要 Harness Engineering？
考虑一个真实场景：你正在构建一个 DevAssistant Agent，它可以：
- 阅读和理解项目代码
- 根据需求生成代码
- 执行单元测试
- 使用 Git 管理版本
- 部署到测试服务器
- 监控部署结果
这样一个 Agent 所面临的挑战，远超"给一个好上下文"能够解决的范围：
-
推理控制：Agent 需要自主决策何时读文件、何时写代码、何时运行测试、何时部署。它需要一个推理循环（Reasoning Loop）来驱动这个 OODA（Observe-Orient-Decide-Act）过程。
-
工具编排：Agent 需要调用十几种工具——文件系统、Shell、Git、Docker、API。每个工具有不同的参数格式、执行时间、错误模式。需要一个统一的工具执行引擎（Tool Executor）。
-
安全边界：Agent 拥有写入文件系统、执行 Shell 命令的能力。如何防止它误删重要文件？如何阻止它执行危险命令？需要多层安全护栏（Safety Guard）。
-
长期记忆：Agent 需要记住用户的编码风格、项目的架构约定、之前做出的设计决策。这需要持久化的记忆系统（Memory System）。
-
可观测性：当 Agent 执行了 20 步推理、调用了 15 个工具后给出了错误答案，如何快速定位问题出在哪一步？需要全链路追踪和调试能力（Observability）。
-
上下文管理：这仍然是重要的——如何将项目代码、对话历史、工具执行结果、检索到的文档有效地组织进上下文窗口？需要精细的上下文管理（Context Manager）。
这六大能力——上下文管理、工具集成、推理控制、安全护栏、记忆系统、可观测性——共同构成了 Harness。
Agent = Model + Harness
这个公式是整个 Harness Engineering 理论的基石：
┌──────────────────────────────────────────────────┐
│ Agent │
│ │
│ ┌─────────────────┐ ┌──────────────────────┐ │
│ │ Model │ │ Harness │ │
│ │ (推理引擎) │◄──┤ (工程体系) │ │
│ │ │ │ │ │
│ │ - 语言理解 │ │ - 上下文管理 │ │
│ │ - 推理与规划 │ │ - 工具集成 │ │
│ │ - 代码生成 │ │ - 推理控制 │ │
│ │ - 知识储备 │ │ - 安全护栏 │ │
│ │ │ │ - 记忆系统 │ │
│ └─────────────────┘ │ - 可观测性 │ │
│ └──────────────────────┘ │
│ │
│ 大脑负责思考 身体负责行动、感知、记忆、保护 │
└──────────────────────────────────────────────────┘
Model 层负责：
- 理解自然语言指令
- 进行逻辑推理和任务规划
- 生成代码、文本、结构化数据
- 决定调用哪些工具
Harness 层负责：
- 为 Model 准备高质量的上下文（信息输入）
- 执行 Model 决定的工具调用（行动输出）
- 管理推理流程和错误恢复（过程控制）
- 确保操作安全合法（边界约束）
- 持久化记忆和状态（记忆存储）
- 全链路追踪和监控（质量保障）
Model 和 Harness 之间存在信息闭环：Harness 通过上下文向 Model 传递信息 → Model 基于上下文推理和决策 → Model 发出工具调用指令 → Harness 执行指令并将结果反馈回上下文 → Model 继续推理。这个循环往复，直到任务完成。
Harness Engineering 与 Prompt/Context Engineering 的关系
关键理解：Harness Engineering 不是替代 Context Engineering，而是包容和扩展它。
Prompt Engineering ────→ Context Engineering ────→ Harness Engineering
(2023) (2025) (2026)
写好提示词 构建高质量上下文 构建完整工程体系
│
┌────────┴────────┐
│ 包含并扩展 │
│ Context Engineering│
│ + 工具执行的能力 │
│ + 推理控制的能力 │
│ + 安全保护的能力 │
│ + 持久记忆的能力 │
│ + 可观测的能力 │
└─────────────────┘
三个时代的递进关系：
| 时代 | 核心问题 | 工程重心 | 关键能力 |
|---|---|---|---|
| Prompt Engineering | 如何引导模型产生好结果？ | 提示词设计 | 文本生成 |
| Context Engineering | 如何给模型提供好信息？ | 上下文组装 | 信息检索+文本生成 |
| Harness Engineering | 如何让模型安全高效地行动？ | 完整工程体系 | 信息+推理+行动+安全+记忆 |
1.1.4 范式转换的底层驱动力
这三轮范式转换并非凭空发生，而是由底层技术能力的跃迁驱动：
驱动力一：上下文窗口的指数级扩展
从 GPT-2 的 1024 tokens 到 Gemini 1.5 Pro 的 2M tokens，上下文窗口在五年内扩展了近 2000 倍。这不仅是量的变化，更是质的飞跃：
- 4K era：只能容纳当前对话。Prompt Engineering 是唯一可行方案。
- 128K era：可以容纳整个项目状态。Context Engineering 应运而生。
- 2M+ era：可以容纳海量上下文。系统需要管理复杂的信息组织→Harness Engineering。
驱动力二：模型推理能力的跃迁
从 GPT-3.5 到 Claude 4、GPT-5，模型不再只是"文本补全器"，而进化为真正的"推理引擎"：
- 多步推理能力：从简单的 next-token prediction 到能规划复杂任务步骤
- 工具使用意识：模型能主动判断何时需要调用工具来获取更多信息
- 自我纠错能力：能发现自己的错误并主动修正
这些能力使得模型的自主性大幅提升，同时也对工程体系的健壮性提出了更高要求。
驱动力三：工具化生态的成熟
| 能力 | 2023 | 2026 |
|---|---|---|
| Function Calling | 概念验证 | 标准化、所有主流模型支持 |
| MCP 协议 | 不存在 | 成为 Agent-工具集成的事实标准 |
| 沙箱执行 | 简陋 | Docker/WebAssembly 沙箱成熟 |
| API 生态 | 各自为政 | OpenAPI 标准化 |
工具化的成熟使得 Agent 从"只能说话"变成"能动手做事"——这既带来了巨大的可能性，也带来了巨大的工程挑战。
驱动力四：Multi-Agent 的兴起
当单个 Agent 的能力达到瓶颈时，自然的思路是让多个 Agent 协作：
- 一个 Agent 负责理解用户意图
- 一个 Agent 负责检索相关知识
- 一个 Agent 负责编写代码
- 一个 Agent 负责审查代码
- 一个 Agent 负责部署
这种 Multi-Agent 模式要求每个 Agent 都有完整的 Harness 支持，以及 Agent 之间的通信、协调、状态同步机制——这些都超出了单纯的 Context Engineering 范畴。
驱动力五：生产环境的严苛要求
从实验室到生产环境，Agent 应用面临的挑战是数量级的提升：
可靠性要求：一个 Demo 级 Agent 跑通一次就行；一个生产级 Agent 需要在成千上万次调用中保持 >99% 的可用性。这意味着需要完善的错误处理、重试、降级、熔断机制。
安全合规要求：当 Agent 接触真实用户数据、操作真实生产系统时，安全问题从"理论上的担忧"变为"可能导致公司倒闭的灾难"。Prompt Injection、数据泄露、越权操作——每个都是真实且紧迫的威胁。
成本约束：一个企业的 Agent 系统每天可能处理百万级请求。Token 成本、计算资源成本、API 调用成本——每一项都需要精细的管理和优化。不做成本管理，一个月的 LLM 账单可能吃掉全年的利润。
可运维性：当 Agent 在生产环境中出问题时，运维团队需要快速定位根因——是哪一步推理出了问题？是哪个工具调用失败了？是模型幻觉还是上下文污染？没有完善的可观测性体系，排查一个问题可能需要数天。
这些生产环境的硬性要求，共同推动了 Harness Engineering 的形成——它不是一个学术概念，而是一套从实战中生长出来的工程方法论。
范式转换的内在逻辑：从"用模型"到"建系统"
综合以上五大驱动力，我们可以总结出范式转换的内在逻辑：
用模型 (Use Model)
│
├── Prompt Engineering: 写好提示词，用好模型
│ 问题：模型能力有限，上下文太短，无法获取外部信息
│
▼
增强模型 (Augment Model)
│
├── Context Engineering: 给模型更多更好的上下文
│ 问题：只能"说"，不能"做"；缺乏自主性和行动力
│
▼
建系统 (Build System)
│
└── Harness Engineering: 围绕模型构建完整工程体系
解决：推理+行动+安全+记忆+可观测 → 生产级 Agent
这不是否定——Context Engineering 没有否定 Prompt Engineering，而是将其作为上下文的一部分；Harness Engineering 也没有否定 Context Engineering，它本身就是 Harness 六大组件之一。每一层都建立在之前层的基础上，每一层都将前一层的核心能力纳入自己体系。
这正是软件工程中"分层抽象"的经典模式：从函数调用（Prompt）到数据结构（Context）到系统架构（Harness），抽象层次不断上升，解决的问题域不断扩大。
1.2 Agent 的核心定义
1.2.1 什么是 Agent？
在 AI 工程领域，"Agent"这个词被广泛使用，但其含义却经常混淆。我们需要一个精确的定义。
Agent = 一个由 Model（推理引擎）和 Harness（工程体系）组成的自主系统，能够感知环境、推理决策、执行行动，并基于反馈持续优化其行为。
这个定义包含三个关键要素：
-
自主性（Autonomy）：Agent 不是被动的输入-输出映射器，而是能主动规划步骤、选择工具、决定下一步做什么。一个纯粹的聊天模型不是 Agent；一个能自主调用工具、多步推理完成目标的系统才是 Agent。
-
目标导向（Goal-Oriented）：Agent 的行为不是随机的，而是围绕一个明确的目标展开的。"帮我写一个用户管理系统"是一个目标，"回答1+1等于几"也是一个目标，但前者的实现需要多步推理和多次工具调用。
-
环境交互（Environment Interaction）：Agent 不只是在"头脑"中思考，它通过工具和环境进行真实交互——读文件、写代码、执行命令、查询数据库、调用 API。每一次交互的结果都会影响下一步的决策。
1.2.2 Agent 的能力谱系
Agent 不是一个"有或无"的二元概念，而是一个能力谱系：
能力级别
▲
│ ┌─────────────────┐
│ │ 全自主 Agent │
│ ┌──────│ 独立规划、执行、 │
│ │ │ 验证、迭代 │
│ ┌──────┤ └─────────────────┘
│ │ │
│ ┌──────┤ │ ┌─────────────────┐
│ │ │ │ │ 工具增强 Agent │
│ ┌──────┤ │ └──────│ 多工具组合、 │
│ │ │ │ │ 多步推理 │
│ ┌──────┤ │ │ └─────────────────┘
│ │ │ │ │
│ ┌──────┤ │ │ └─────────────┌─────────────────┐
│ │ │ │ │ │ RAG 增强型 │
│ │ │ │ └────────────────────│ 知识检索+生成 │
│ │ │ │ └─────────────────┘
│ │ │ │
│ │ │ └───────────────────────────┌─────────────────┐
│ │ │ │ 指令型 Agent │
│ │ └──────────────────────────────────│ 遵循复杂指令、 │
│ │ │ 格式化输出 │
│ │ └─────────────────┘
│ │
│ └─────────────────────────────────────────┌─────────────────┐
│ │ Simple Chatbot │
│ │ 一问一答 │
└────────────────────────────────────────────└─────────────────┘
Level 1: Simple Chatbot
- 能力：单轮对话，无状态，无工具
- 典型实现：基础 ChatGPT 对话
- 适用场景：简单问答、闲聊
Level 2: 指令型 Agent
- 能力：遵循复杂 System Prompt，格式化输出
- 典型实现：带角色定义和 JSON Schema 约束的 API
- 适用场景：文本分类、信息提取、格式化翻译
Level 3: RAG 增强型 Agent
- 能力：检索外部知识库，基于检索结果生成回答
- 典型实现：LangChain RAG Chain
- 适用场景：企业知识库问答、文档摘要
Level 4: 工具增强 Agent
- 能力：调用单个或多个外部工具，基于工具结果迭代推理
- 典型实现：ReAct Agent
- 适用场景：数据分析、代码辅助、信息聚合
Level 5: 全自主 Agent
- 能力：独立规划多步任务、自主选择工具和策略、验证结果、迭代改进
- 典型实现：HappyClaw、Devin、Claude Code
- 适用场景：全栈开发、DevOps 自动化、复杂研究任务
本书聚焦于 Level 4 和 Level 5 的 Agent，因为这是真正体现 Harness Engineering 价值的领域。
1.2.3 Agent = Model + Harness 深度解析
让我们用代码来精确表达这个公式：
// TypeScript: Agent 的核心抽象
interface Model {
// Model 的职责：接收上下文，返回决策
reason(context: Context): Promise<Decision>;
}
interface Decision {
type: 'respond' | 'act' | 'ask';
content?: string; // 当 type='respond' 时的回复内容
toolCall?: ToolCall; // 当 type='act' 时的工具调用
clarification?: string; // 当 type='ask' 时的澄清问题
}
interface Harness {
// Harness 的职责：管理上下文、执行工具、保障安全
contextManager: ContextManager;
toolExecutor: ToolExecutor;
reasoningController: ReasoningController;
safetyGuard: SafetyGuard;
memorySystem: MemorySystem;
observability: Observability;
}
// Agent = Model + Harness
class Agent {
private model: Model;
private harness: Harness;
constructor(model: Model, harness: Harness) {
this.model = model;
this.harness = harness;
}
// Agent 主循环
async run(task: string): Promise<string> {
// 1. 从记忆中加载相关上下文
const memoryContext = await this.harness.memorySystem.load(task);
// 2. 构建初始上下文
let context = await this.harness.contextManager.build({
task,
memory: memoryContext,
history: [],
});
// 3. 推理-行动循环
for (let step = 0; step < this.maxSteps; step++) {
// 3a. 安全检查（输入）
await this.harness.safetyGuard.checkInput(context);
// 3b. Model 推理
const decision = await this.model.reason(context);
// 3c. 记录推理步骤
this.harness.observability.trace(decision);
// 3d. 根据决策类型处理
if (decision.type === 'respond') {
// 安全检查（输出）
const safeOutput = await this.harness.safetyGuard.checkOutput(
decision.content!
);
await this.harness.memorySystem.save(task, safeOutput);
return safeOutput;
}
if (decision.type === 'act') {
// 执行工具调用
const result = await this.harness.toolExecutor.execute(
decision.toolCall!
);
// 将结果注入上下文
context = await this.harness.contextManager.append(context, result);
}
// 3e. 推理控制器决定是否继续循环
if (this.harness.reasoningController.shouldStop(step, context)) {
break;
}
}
return "任务超出最大步数限制";
}
}
# Python: Agent 的核心抽象
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Optional
from enum import Enum
class DecisionType(Enum):
RESPOND = "respond"
ACT = "act"
ASK = "ask"
@dataclass
class ToolCall:
name: str
arguments: dict
@dataclass
class Decision:
type: DecisionType
content: Optional[str] = None
tool_call: Optional[ToolCall] = None
clarification: Optional[str] = None
@dataclass
class Context:
task: str
system_prompt: str
messages: list = field(default_factory=list)
memories: list = field(default_factory=list)
tool_results: list = field(default_factory=list)
class Model(ABC):
"""推理引擎接口"""
@abstractmethod
async def reason(self, context: Context) -> Decision:
...
class Harness:
"""Harness 工程体系"""
def __init__(
self,
context_manager: 'ContextManager',
tool_executor: 'ToolExecutor',
reasoning_controller: 'ReasoningController',
safety_guard: 'SafetyGuard',
memory_system: 'MemorySystem',
observability: 'Observability',
):
self.context_manager = context_manager
self.tool_executor = tool_executor
self.reasoning_controller = reasoning_controller
self.safety_guard = safety_guard
self.memory_system = memory_system
self.observability = observability
class Agent:
"""Agent = Model + Harness"""
def __init__(self, model: Model, harness: Harness, max_steps: int = 50):
self.model = model
self.harness = harness
self.max_steps = max_steps
async def run(self, task: str) -> str:
# 1. 加载记忆
memories = await self.harness.memory_system.load(task)
# 2. 构建上下文
context = await self.harness.context_manager.build(
task=task,
memories=memories,
history=[],
)
# 3. 推理-行动主循环
for step in range(self.max_steps):
# 安全检查（输入）
await self.harness.safety_guard.check_input(context)
# Model 推理
decision = await self.model.reason(context)
# 记录推理
self.harness.observability.trace(step, decision)
if decision.type == DecisionType.RESPOND:
output = await self.harness.safety_guard.check_output(
decision.content
)
await self.harness.memory_system.save(task, output)
return output
if decision.type == DecisionType.ACT:
result = await self.harness.tool_executor.execute(
decision.tool_call
)
context = await self.harness.context_manager.append(
context, result
)
if self.harness.reasoning_controller.should_stop(step, context):
break
return "任务超出最大步数限制"
这段代码虽然简洁，但已经包含了生产级 Agent 的核心骨架。在后面的章节中，我们将逐一深入每个 Harness 组件的完整实现。
1.2.4 Harness 六大组件全景图
本节给出 Harness 六大组件的高层描述，为后续章节（第4-8章）的深入讲解建立认知框架。
┌──────────────────────┐
│ Harness 体系 │
│ │
┌─────────────────────────┤ ┌─────────────────┐ │
│ 用户输入 │ │ Safety Guard │ │
│ (可能有恶意) │ │ 安全护栏 │ │
│ │ │ │ │
│ ┌──────────────────────┤ │ - 输入过滤 │ │
│ │ │ │ - 输出审核 │ │
│ │ 过滤后的输入 ────────┤ │ - 权限控制 │ │
│ │ │ └─────────────────┘ │
│ │ │ │
│ │ ┌───────────────────┤ ┌─────────────────┐ │
│ │ │ Context Manager │ │ Memory System │ │
│ │ │ 上下文管理器 │◄─┤ 记忆系统 │ │
│ │ │ │ │ │ │
│ │ │ - 对话窗口 │ │ - 工作记忆 │ │
│ │ │ - System Prompt │ │ - 短期记忆 │ │
│ │ │ - 动态上下文 │ │ - 长期记忆 │ │
│ │ └───────┬───────────┘ └─────────────────┘ │
│ │ │ │
│ │ │ 组装好的 Context │
│ │ ▼ │
│ │ ┌───────────────────┐ │
│ │ │ Model │ │
│ │ │ 推理引擎 │ │
│ │ └───────┬───────────┘ │
│ │ │ │
│ │ │ Decision (reply / tool_call) │
│ │ ▼ │
│ │ ┌───────────────────┐ │
│ │ │Reasoning Controller│ │
│ │ │ 推理控制器 │ │
│ │ │ │ │
│ │ │ - CoT/ReAct/ │ │
│ │ │ Plan-Execute │ │
│ │ │ - 迭代控制 │ │
│ │ │ - 超时/熔断 │ │
│ │ └───────┬───────────┘ │
│ │ │ │
│ │ ┌─────┴──────┐ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ respond tool_call │
│ │ │ │ │
│ │ │ ┌─────┴──────────┐ │
│ │ │ │ Tool Executor │ │
│ │ │ │ 工具执行器 │ │
│ │ │ │ │ │
│ │ │ │ - 工具注册 │ │
│ │ │ │ - 参数校验 │ │
│ │ │ │ - 沙箱执行 │ │
│ │ │ │ - 结果格式化 │ │
│ │ │ └─────┬──────────┘ │
│ │ │ │ │
│ │ │ │ 工具执行结果 │
│ │ │ │ (反馈回 Context) │
│ │ │ └─────────────┐ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌────────────────────────────────────┐ │
│ │ │ Observability │ │
│ │ │ 可观测性 │ │
│ │ │ │ │
│ │ │ - 全链路追踪 (每一步推理+工具调用) │ │
│ │ │ - 指标监控 (延迟/成功率/Token消耗) │ │
│ │ │ - 会话回放 (debug必用) │ │
│ │ └────────────────────────────────────┘ │
│ └──────────────────────────────────────────────┤
│ │
│ 输出给用户 │
└─────────────────────────────────────────────────┘
组件速览：
| 组件 | 一句话定位 | 对应章节 | 核心挑战 |
|---|---|---|---|
| Context Manager | 为 Model 构建高质量的"所见" | 第4章 | 窗口预算、信息去重、动态组装 |
| Tool Executor | 让 Agent 的"手"能做事 | 第5章 | 工具注册、参数校验、安全执行 |
| Reasoning Controller | 控制 Agent “怎么想” | 第6章 | 策略选择、迭代控制、质量保障 |
| Safety Guard | Agent 的"免疫系统" | 第7章 | 输入过滤、权限分级、输出审核 |
| Memory System | Agent 的"海马体" | 第4章 | 三层记忆、生命周期、冲突解决 |
| Observability | Agent 的"体检报告" | 第8章 | 全链路追踪、实时监控、会话回放 |
1.2.5 三个时代的实际工程对比
为了帮助读者建立更直观的认知，我们用一个具体场景——“帮用户查询某只股票信息并给出分析建议”——来看三个工程范式下的实现差异：
Prompt Engineering 时代（2023）的实现
提示词：
你是一位专业的股票分析师。请根据你的知识，分析苹果公司(AAPL)的股票。
模型回复：
（基于训练数据中的知识，可能已过时，无法获取实时股价）
特点：只能依赖模型训练数据中的知识，无法获取实时信息。如果模型训练数据截止于2023年，它甚至不知道2024年之后的事情。
Context Engineering 时代（2025）的实现
// 系统先通过 RAG 检索最新信息，再拼接上下文
const stockData = await searchStockInfo("AAPL"); // 从知识库检索
const newsData = await searchNews("AAPL"); // 获取最新新闻
const financials = await getFinancialData("AAPL"); // 获取财报数据
const context = `
你是专业的股票分析师。以下是关于 AAPL 的最新信息：
【实时行情】
${stockData}
【最新新闻】
${newsData}
【财务数据】
${financials}
请基于以上信息，分析苹果公司(AAPL)的股票。
`;
const analysis = await model.reason(context);
特点：能够集成多源实时信息，但仍然依赖人工预先组织上下文。如果分析过程中发现还需要其他数据（比如行业对比），需要人工修改代码重新查询。
Harness Engineering 时代（2026）的实现
// Agent 自主决策信息获取和分析流程
const agent = new Agent({
model: claudeModel,
harness: {
contextManager: new ContextManager({ maxWindowTokens: 180000 }),
toolExecutor: new ToolExecutor({
tools: [stockAPI, newsAPI, financialAPI, calculatorTool, chartTool],
}),
reasoningController: new ReActController({ maxSteps: 15 }),
safetyGuard: new SafetyGuard({ financialCompliance: true }),
memorySystem: new MemorySystem({ persistent: true }),
observability: new Observability({ traceLevel: 'detailed' }),
},
});
// 用户只需提出目标，Agent 自主完成全流程
const analysis = await agent.run(
"分析苹果公司(AAPL)的投资价值，对比其与微软(MSFT)和谷歌(GOOGL)在AI领域的竞争优势"
);
// Agent 的自主推理路径（由 Harness 自动追踪）：
// Step 1: 查询 AAPL 实时股价 → Tool: stockAPI.getQuote("AAPL")
// Step 2: 查询 MSFT 实时股价 → Tool: stockAPI.getQuote("MSFT")
// Step 3: 查询 GOOGL 实时股价 → Tool: stockAPI.getQuote("GOOGL")
// Step 4: 获取三家公司的 AI 相关新闻 → Tool: newsAPI.search("AI", companies=[...])
// Step 5: 获取最新财报数据 → Tool: financialAPI.getFilings(["AAPL","MSFT","GOOGL"])
// Step 6: 计算关键财务指标对比 → Tool: calculatorTool.evaluate(...)
// Step 7: 发现自己遗漏了研发投入对比，主动补充 → Tool: financialAPI.getR&DExpense(...)
// Step 8: 综合所有数据生成分析报告 → respond
特点：Agent 自主决定需要什么信息、以什么顺序获取、发现遗漏后主动补充。整个过程无需人工干预，Harness 确保每一步的安全、可追溯和可回放。
三时代对比总结
| 维度 | Prompt Engineering | Context Engineering | Harness Engineering |
|---|---|---|---|
| 信息获取 | 仅模型训练数据 | 预先检索+组装 | Agent 自主按需检索 |
| 决策模式 | 单次推理 | 单次推理（信息更丰富） | 多步迭代推理+行动 |
| 工具使用 | 无 | 需要人工编排 | Agent 自主选择和编排 |
| 错误恢复 | 无 | 需要人工干预 | Agent 自我纠错+重试 |
| 安全保障 | Prompt 层面约束 | Prompt+检索过滤 | 多层次安全护栏 |
| 可追溯性 | 仅看输入输出 | 看上下文+输出 | 全链路每一步可追踪 |
| 开发者体验 | 写提示词 | 搭建检索管道+写提示词 | 定义工具+配置Harness |
| 适用场景 | 简单问答 | 知识密集型问答 | 复杂多步自主任务 |
这个对比揭示了 Harness Engineering 的核心价值：不是替代人的工作，而是让机器拥有自主获取信息和决策的能力——人类从"操作者"变为"设计者和监督者"。
1.3 本书的技术栈与学习路径
1.3.1 全书技术选型
本书选择 TypeScript 和 Python 作为双语言教学，这一决策基于以下考量：
为什么选 TypeScript？
- 生产级 Agent 的首选：TypeScript 的强类型系统天然适配 Harness 工程的组件化、接口化设计。本书中的 Harness 核心框架代码使用 TypeScript 实现。
- 全栈统一：从后端 Agent 运行时到前端界面，一套语言覆盖全栈。
- 企业级标准：大量企业在 Agent 工程化落地时首选 TypeScript/Node.js 生态。
为什么选 Python？
- AI/ML 生态最丰富：Embedding 模型、向量数据库、RAG 流水线等 AI 基础设施的 Python SDK 最成熟。
- 快速实验：Python 适合快速验证想法和算法，本书中的 RAG、Embedding、评估等代码使用 Python 实现。
- 入门友好：Python 的简洁语法降低了 AI 工程师的学习成本。
语言分工：
| 技术领域 | 主语言 | 典型应用 |
|---|---|---|
| Harness 框架核心 | TypeScript | Agent 主循环、工具执行器、推理控制器 |
| API 与服务端 | TypeScript | Web API、WebSocket、认证 |
| 前端界面 | TypeScript (React) | Agent 交互界面、管理控制台 |
| RAG 流水线 | Python | 文档处理、Embedding、向量检索 |
| 评估与测试 | Python | Agent 评估框架、数据集构建 |
| 数据分析 | Python | Token 分析、成本优化 |
1.3.2 读者学习路径
本书设计了三条学习路径，分别适配不同起点的读者：
路径A：全栈 Agent 工程师（推荐）
第1章(范式) → 第2章(LLM基础) → 第3章(Agent架构)
→ 第4章(上下文) → 第5章(工具) → 第6章(推理)
→ 第7章(安全) → 第8章(可观测) → 第9章(Multi-Agent)
→ 第10章(RAG) → 第11章(评估) → 第12章(实战) → 第13章(部署)
适合：希望从零到一系统掌握 Agent 应用开发的工程师。路径A覆盖全书所有章节。
路径B：快速实战路线
第1章(范式) → 第2章(LLM基础) → 第3章(Agent架构)
→ 第12章(实战) → 第13章(部署)
→ 回到第4-11章按需深入
适合：有一定 AI 基础、希望快速上手构建 Agent 应用的工程师。先通读基础+实战，建立全局认知后再深入细节。
路径C：Harness 专家路线
第1章(范式) → 第3章(Agent架构核心)
→ 第4-8章(Harness组件篇，深入每一个组件)
→ 第12章(实战，看如何集成)
适合：已有 LLM 和 Agent 基础、希望深入掌握 Harness Engineering 的工程师。聚焦于 Harness 六大组件的工程细节。
1.3.3 本书的代码约定与运行环境
代码风格约定：
// TypeScript 代码约定
// 1. 接口使用 interface，类型别名使用 type
interface ToolCall {
name: string;
arguments: Record<string, unknown>;
}
// 2. 异步函数显式标注返回类型
async function execute(call: ToolCall): Promise<ToolResult> { ... }
// 3. Result 模式处理错误（不抛异常）
type Result<T, E = Error> =
| { ok: true; value: T }
| { ok: false; error: E };
# Python 代码约定
# 1. 使用 dataclass 定义数据结构
from dataclasses import dataclass
@dataclass
class ToolCall:
name: str
arguments: dict
# 2. 类型注解优先
def execute(call: ToolCall) -> ToolResult: ...
# 3. async/await 异步模式
async def run(self, task: str) -> str: ...
运行环境：
| 组件 | 环境要求 |
|---|---|
| Node.js | v20+，推荐 v22 LTS |
| Python | v3.11+，推荐 v3.12 |
| 包管理器 | pnpm (TypeScript) / uv 或 pip (Python) |
| 数据库 | PostgreSQL 16+ (生产) / SQLite (开发) |
| 向量数据库 | Chroma / Qdrant |
| 容器 | Docker 24+ |
随书代码仓库：
本书的所有代码示例均可在随书代码仓库中找到。每章代码按以下结构组织：
code/
chapter-01/ # 第1章：范式篇（本章为概念性章节，代码较少）
chapter-02/ # 第2章：LLM 工程基础
typescript/ # TypeScript 实现
python/ # Python 实现
chapter-03/ # 第3章：Agent 架构核心
typescript/
src/
agent.ts # Agent 核心实现
harness/ # Harness 六大组件
model/ # Model 适配器
tests/
python/
agent.py
harness/
model/
...
chapter-12/ # 第12章：DevAssistant Pro 完整项目
typescript/
python/
1.4 最小可运行 Agent：50行代码建立全局认知
在深入各组件之前，让我们先用一个最简单的 Agent 来建立全局认知。这个 Agent 只有50行代码，但包含了 Model + Harness 的核心结构。
TypeScript 版本
// 最小可运行 Agent - TypeScript 版本（~50行）
import { Anthropic } from '@anthropic-ai/sdk';
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
// Model 层：调用 Claude API
async function model(context: string): Promise<string> {
const response = await anthropic.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
system: '你是一个有用的 AI 助手。如果无法回答，如实告知。',
messages: [{ role: 'user', content: context }],
});
// 提取文本内容
const textBlock = response.content.find(b => b.type === 'text');
return textBlock ? textBlock.text : '';
}
// Harness 层：工具执行
async function executeTool(name: string, args: any): Promise<string> {
// 目前只支持查询当前时间
if (name === 'get_current_time') {
return `当前时间：${new Date().toISOString()}`;
}
return `未知工具：${name}`;
}
// Agent 主循环
async function agent(task: string): Promise<string> {
let context = task;
for (let step = 0; step < 10; step++) {
const result = await model(context);
// 检查是否需要调用工具
if (result.includes('【调用工具】')) {
const match = result.match(/【调用工具】(\w+)\s*\n(.+)/s);
if (match) {
const toolResult = await executeTool(match[1], match[2]);
context = `工具执行结果：${toolResult}\n\n请基于此结果继续回答用户的问题。`;
continue;
}
}
return result;
}
return '任务超出最大步数限制。';
}
// 运行
const answer = await agent('现在几点了？');
console.log(answer);
Python 版本
# 最小可运行 Agent - Python 版本（~50行）
import os
import asyncio
from datetime import datetime
from anthropic import AsyncAnthropic
client = AsyncAnthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
# Model 层：调用 Claude API
async def model(context: str) -> str:
response = await client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="你是一个有用的 AI 助手。如果无法回答，如实告知。",
messages=[{"role": "user", "content": context}],
)
for block in response.content:
if block.type == "text":
return block.text
return ""
# Harness 层：工具执行
async def execute_tool(name: str, args: str) -> str:
if name == "get_current_time":
return f"当前时间：{datetime.now().isoformat()}"
return f"未知工具：{name}"
# Agent 主循环
async def agent(task: str) -> str:
context = task
for step in range(10):
result = await model(context)
# 检查是否需要调用工具
if "【调用工具】" in result:
import re
match = re.search(r"【调用工具】(\w+)\s*\n(.+)", result, re.DOTALL)
if match:
tool_result = await execute_tool(match.group(1), match.group(2))
context = f"工具执行结果：{tool_result}\n\n请基于此结果继续回答用户的问题。"
continue
return result
return "任务超出最大步数限制。"
# 运行
if __name__ == "__main__":
answer = asyncio.run(agent("现在几点了？"))
print(answer)
这个最小 Agent 虽然简陋，但已经包含了生产级 Agent 的核心骨架：
- Model 层：通过 API 调用获取推理结果
- Harness 层：工具注册与执行
- Agent 主循环：推理 → 判断工具调用 → 执行工具 → 反馈结果 → 继续推理
在后续章节中，我们将逐一展开这个骨架中的每个部分，从玩具级实现逐步演进到生产级系统。
1.5 本章小结
本章建立了 Agentic AI 应用开发的完整认知框架：
-
三个范式时代：Prompt Engineering（写好提示词）→ Context Engineering（构建好上下文）→ Harness Engineering（构建完整工程体系）。每一次范式跃迁都是对上一范式的包容和扩展。
-
Agent 的核心定义：Agent 是一个由 Model（推理引擎）和 Harness（工程体系）组成的自主系统，能够感知环境、推理决策、执行行动。Agent 的能力从简单 Chatbot 到全自主 Agent 构成一个谱系，本书聚焦 Level 4（工具增强）和 Level 5（全自主）。
-
Agent = Model + Harness：Model 是"大脑"，负责理解、推理、规划。Harness 是"身体"，负责上下文管理、工具执行、推理控制、安全护栏、记忆系统、可观测性。两者通过信息闭环紧密协同。
-
Harness 六大组件：Context Manager、Tool Executor、Reasoning Controller、Safety Guard、Memory System、Observability——这六大组件覆盖了从模型调用到生产部署的全链路。
-
本书技术栈：TypeScript（Harness 框架核心、API、前端）+ Python（RAG、Embedding、评估），双语言覆盖 Agent 应用开发全栈。
从下一章开始，我们将进入第二部分——基础篇，首先学习 LLM 工程基础，包括模型选型、API 调用、成本优化和环境搭建。
关键术语
| 术语 | 英文 | 定义 |
|---|---|---|
| 提示词工程 | Prompt Engineering | 通过精心设计输入文本来引导模型行为的方法论 |
| 上下文工程 | Context Engineering | 系统化构建多维度上下文信息的工程实践 |
| Harness 工程 | Harness Engineering | 构建模型之外完整工程体系的方法论 |
| Agent | Agent | Model + Harness 组成的自主系统 |
| 推理引擎 | Model / Reasoning Engine | Agent 中负责理解、推理、规划的组件 |
| 工程体系 | Harness | Agent 中负责执行、安全、记忆、观察的组件 |
| 能力谱系 | Capability Spectrum | Agent 从简单到复杂的五级能力分层 |
| Agent 主循环 | Agent Main Loop | Perceive → Reason → Act → Observe 的核心循环 |
思考与练习
-
范式演变分析：结合你自身的项目经验，分析你目前处于三个范式中的哪一个？你的项目在 Prompt、Context、Harness 三个维度上各有哪些做得好的地方和不足之处？
-
Agent 能力定级：你用过哪些 AI 产品？它们在 Agent 能力谱系上分别处于哪个级别？为什么？
-
最小 Agent 改造：运行本章末尾的最小 Agent 代码，尝试添加一个新的工具（如
calculator计算器工具），感受 Agent 主循环的工作方式。 -
Harness 组件映射：如果你正在构建或使用一个 AI 应用，它的六个 Harness 组件分别由什么实现？哪些是成熟的？哪些是缺失或薄弱的？
-
技术选型：除了 TypeScript 和 Python，你认为还有哪些语言适合 Agent 应用开发？各自的优缺点是什么？
欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！
更多推荐
1
0- 0
已为社区贡献48条内容
所有评论(0)