如果说大模型是AI Agent的大脑」，那么工具调用系统就是 Agent 的「双手」。没有工具的Agent，就像一个被关小黑屋的聪明人，空有一堆想法却无法落地。今天咱们基于nanobot开源项目的源码分析，深入解析AI Agent的四种主流工具调用机制。

一、Tools：最基础的内置工具系统

什么是 Tools？

Tools 是 Agent 最原生的能力，直接注册到 ToolRegistry，每次调用大模型时都会通过 `tools` 参数完整传递。这样大模型就可以根据实际需求，调用对应的工具。

工作原理

# Tool 基类定义
class Tool(ABC):
    @property
    @abstractmethod
    def name(self) -> str: ...        # 工具名，如 "exec"
    
    @property
    @abstractmethod
    def description(self) -> str: ... # 一句话描述
    
    @property
    @abstractmethod
    def parameters(self) -> dict: ... # JSON Schema 参数定义
    
    @abstractmethod
    async def execute(self, **kwargs): ...  # 执行逻辑

实际示例：`exec` 工具的完整定义

@tool_parameters(
    tool_parameters_schema(
        command=StringSchema("The shell command to execute"),
        working_dir=StringSchema("Optional working directory"),
        timeout=IntegerSchema(
            60,
            description="Timeout in seconds. Increase for long-running commands",
            minimum=1,
            maximum=600,
        ),
    )
)
class ExecTool(Tool):
    name = "exec"
    description = "Execute a shell command and return its output. Use for tests, builds, package commands, git operations."
    
    async def execute(self, command, working_dir=None, timeout=60, **kwargs):
        # 安全检查：防止路径穿越、内网访问
        guard_error = self._guard_command(command, working_dir)
        if guard_error:
            return guard_error
        
        # 异步执行子进程
        process = await asyncio.create_subprocess_shell(
            command,
            cwd=working_dir,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        
        try:
            stdout, stderr = await asyncio.wait_for(
                process.communicate(),
                timeout=timeout,
            )
        except asyncio.TimeoutError:
            await process.kill()
            return f"Error: Command timed out after {timeout} seconds"
        
        return stdout.decode() + stderr.decode() + f"\nExit code: {process.returncode}"

大模型看到的 Tool 定义

每次调用 LLM 时，OpenAI 协议会传输这样的 JSON：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "exec",
        "description": "Execute a shell command and return its output...",
        "parameters": {
          "type": "object",
          "properties": {
            "command": {
              "type": "string",
              "description": "The shell command to execute"
            },
            "working_dir": {
              "type": "string",
              "description": "Optional working directory"
            },
            "timeout": {
              "type": "integer",
              "minimum": 1,
              "maximum": 600
            }
          },
          "required": ["command"]
        }
      }
    },
    // ... 其他工具
  ]
}

典型 Tools 清单

关键特征

✅ 每次都传递：所有注册的 Tool 每次都会传给大模型
✅ 强类型约束：通过 JSON Schema 严格校验参数
✅ 统一入口：所有调用都经过 `ToolRegistry.execute()`
❌ 扩展性有限：太多 Tool 会撑爆上下文窗口

二、MCP：远程工具协议（Model Context Protocol）

什么是 MCP？

MCP 是一个开放协议，允许 Agent 连接到远程服务器提供的工具，就像调用本地工具一样。

工作原理

MCP同样是注册到ToolRegistry，每次调用大模型时都会通过 `tools` 参数完整传递。这样大模型就可以根据实际需求，调用对应的MCP。ToolRegistry通过MCP Tool Wrapper，实现MCP工具的调用。

┌─────────────────────────────────────────────────────┐
│ 大模型                                               │
│  prompt: "打开 bing.com 并截图首页"                   │
└───────┬─────────────────────────────────────────────┘
        │
        ▼ 大模型决定调用：mcp_browser_navigate(url="https://bing.com")
┌─────────────────────────────────────────────────────┐
│ ToolRegistry                                        │
│   └─ MCP Tool Wrapper（动态生成）                   │
│      name: mcp_browser_navigate                     │
│      description: Navigate to a URL with browser    │
│      parameters: {url: string}                      │
└───────┬───────────────────────────────────────────────┘
        │
        ▼ STDIO / HTTP 传输调用请求
┌─────────────────────────────────────────────────────┐
│ MCP Server（本地 Node.js 进程）                     │
│   └─ 真正控制 Playwright/Puppeteer 浏览器           │
│      → 访问 URL                                     │
│      → 截图                                          │
│      → 返回 base64 图片                             │
└─────────────────────────────────────────────────────┘

MCP示例：Playwright MCP Server

MCP Server 暴露的工具列表：

Agent 调用时的实际工具名（自动加前缀）：

mcp_browser_navigate
mcp_browser_click
mcp_browser_evaluate
mcp_browser_screenshot

完整调用示例：

用户：帮我打开 bing.com 并截一张首页的图
    ↓
[1] 大模型看到 Tool 列表中有 mcp_browser_navigate
    ↓
[2] 调用工具：
    mcp_browser_navigate(url="https://www.bing.com")
    ↓
[3] MCP Server 控制浏览器访问，返回："已导航到 bing.com，页面标题是 Bing"
    ↓
[4] 大模型继续调用：
    mcp_browser_screenshot(full_page=true)
    ↓
[5] 返回 base64 图片
    ↓
[6] 大模型："已完成截图，这是 bing.com 首页" + 显示图片

MCP 的巧妙之处

1. 工具名自动生成：`mcp_{server_name}_{tool_name}`
2. Schema 自动转换：MCP 定义自动转成 OpenAI Function Schema
3. 支持资源和提示：不仅是工具，还可以是数据源和 Prompt 模板

为什么 MCP 很重要？

MCP 把「工具」从代码级的扩展，变成了服务级的扩展。
任何人都可以用任何语言写一个 MCP Server，Agent 立刻就能用它的所有能力 — 无需修改 Agent 一行代码。

三、CLI APP：最巧妙的混合形态

什么是 CLI APP？

CLI APP 是 NanoBot 最精妙的设计之一，它通过 「统一工具 + 动态生成 Skill + 运行时提示」 的三重组合，实现了零成本扩展数百个外部应用。

四层架构

CLI APP统一通过run_cli_app注册到ToolRegistry，这个工具注册时会列出全部已安装的APP列表，每次调用大模型时都会通过 `tools` 参数进行传递，这样大模型知道有哪些安装的CLI APP。
同时CLI APP在安装时会主动生成skill，skill也会附在提示词中。这样，当大模型准备用一个skill时，就会首先找到run_cli_app注册的工具，通过run_cli_app工具执行对应的命令，做到了安全控制。

┌─────────────────────────────────────────────────────────┐
│ 【1】统一入口：run_cli_app 工具                          │
│     只有这一个 Tool 注册到 ToolRegistry                  │
│     description 动态列出已安装的 APP 列表                 │
└──────────────────┬──────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│ 【2】CLI-Anything Registry（远程目录）                   │
│     维护数百个可用 CLI APP 的元数据：安装命令、入口点等   │
└──────────────────┬──────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│ 【3】自动生成 Skill                                      │
│     安装 APP 时，自动在 workspace/skills/ 下生成 SKILL.md│
│     包含详细用法、参数说明、最佳实践                      │
└──────────────────┬──────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│ 【4】Runtime Context 动态提示                            │
│     用户输入 @feishu 时，在消息末尾悄悄注入：              │
│     "CLI App Mention: @feishu，用 run_cli_app 调用它"    │
└─────────────────────────────────────────────────────────┘

完整调用链路示例

场景：用户想让 Agent 用飞书 CLI 导出今天的会议记录

Step 1：用户输入

用户：帮我用 @feishu 导出一下今天的会议记录

Step 2：Gateway 检测 @ 提及，注入 Runtime Context
用户消息实际变成了这样（用户看不到这部分）：

帮我用 @feishu 导出一下今天的会议记录

[Runtime Context]
CLI App Mention: @feishu (installed; tool=run_cli_app;
entry_point=feishu; skill=skills/cli-app-feishu/SKILL.md).
Read the skill when useful, then run this app with run_cli_app;
do not bypass it with shell.
[/Runtime Context]

Step 3：大模型看到提示，决定先读 Skill

模型思考：
用户提到了 @feishu
Runtime Context 说这是一个已安装的 CLI APP
应该先用 read_file 读一下对应的 SKILL.md 了解用法

→ 调用工具：
read_file(path="~/.openclaw/workspace/skills/cli-app-feishu/SKILL.md")

Step 4：获取到 Skill 完整内容

Skill 内容示例：

name: cli-app-feishu
description: 使用飞书 CLI 与 Lark 套件交互

# Feishu CLI
使用此技能当用户要求操作飞书文档、表格、机器人、会议等。

## 常用命令

### 会议相关

# 列出会议
feishu meeting list [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]

# 获取会议详情
feishu meeting get <meeting_id>

# 导出会议纪要
feishu meeting notes <meeting_id> --format json

### 优先使用 JSON 输出
所有命令支持 `--json` 参数，可以获得结构化的机器可读输出，优先使用此方式。

Step 5：大模型理解用法，调用 run_cli_app

模型思考：
现在我知道怎么用了
命令是 feishu meeting list --start-date 2026-06-16
加上 --json 获取结构化输出

→ 调用工具：
run_cli_app(
  name="feishu",
  args=["meeting", "list", "--start-date", "2026-06-16", "--json"]
)

Step 6：获取会议列表，整理输出

工具返回：

{
  "meetings": [
    {
      "id": "MSxY2ZkOWE",
      "topic": "产品周会",
      "start_time": "2026-06-16 10:00:00",
      "duration": 60,
      "attendees": ["张三", "李四"]
    },
    {
      "id": "MTdkNmFjYj",
      "topic": "技术方案评审",
      "start_time": "2026-06-16 14:00:00",
      "duration": 90,
      "attendees": ["王五", "赵六", "我"]
    }
  ]
}

大模型整理后回答用户：

今天你有两个会议：

📅 产品周会（10:00-11:00）
   参与人：张三、李四

📋 技术方案评审（14:00-15:30）
   参与人：王五、赵六、你

需要我帮你导出某个会议的详细纪要吗？

CLI APP 生态示例

当前 CLI-Anything 目录已经有上百个可用 APP：

CLI APP 的设计智慧

本质：CLI APP 系统是一个「延迟加载的 Tool 扩展机制」，在不增加任何常驻 Tool 的前提下，把 Agent 的能力边界扩展到了数百个外部应用。

CLI APP执行方式与安全设计

CLI APP通过argv数组执行，不走shell,这是极其重要的安全设计。

result = subprocess.run(
    [resolved, *clean_args],  # ← 传的是 list，不是字符串，不走shell
    cwd=str(cwd),
    capture_output=True,
    text=True,
    timeout=effective_timeout,
    env=os.environ.copy(),
    # 注意：没有 shell=True！
)

两种方式的对比：

# exec 工具（走 shell）
process = await asyncio.create_subprocess_shell(
    command,  # ← 字符串，走 shell 解释
    ...
)

# run_cli_app 工具（直接 execve）
result = subprocess.run(
    [resolved, *clean_args],  # ← 数组，直接系统调用
    ...
)

# 就算大模型被 prompt injection 攻击，想执行 `feishu; rm -rf /`，也会失败。**
# 因为：
1. `;` 分号是 shell 的语法
2. `run_cli_app` 不走 shell
3. 它会把 `meeting;` 当成一个**普通的参数字符串**传给 feishu 命令
4. feishu 会报错说「没有这个参数」

四、Skills：四种触发机制

什么是Skills

Skill是Markdown文件格式的Agent专业知识包，把领域知识、工作流、最佳实践打包成可复用单元，无需写代码就能按需扩展Agent的认知和行为能力（怎么写论文、怎么用飞书、怎么写代码、怎么生成财经日报）。 一般安装在workspace/skills/目录下。基于NanoBot源码分析，Skills 有四种完全不同的触发和调用机制：

方式一：Always Skill — 强制常驻注入

触发时机：会话启动时，系统 Prompt 构建阶段

工作原理：

在 SKILL.md 的 frontmatter 中标记：

name: using-superpowers
metadata:
  nanobot:
    always: true   # ← 标记为 ALWAYS 加载

# 源码位置：context.py → build_system_prompt()
always_skills = self.skills.get_always_skills()
if always_skills:
    always_content = self.skills.load_skills_for_context(always_skills)
    parts.append(f"# Active Skills\n\n{always_content}")

实际注入效果：系统 Prompt 开头会永远包含这段内容

# Active Skills

## using-superpowers

<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
</EXTREMELY-IMPORTANT>

## How to Access Skills

In Claude Code: Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.

## The Rule

Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check.

## Red Flags

These thoughts mean STOP—you're rationalizing:

"This is just a simple question" → Questions are tasks. Check for skills.
"I need more context first" → Skill check comes BEFORE clarifying questions.
"Let me explore the codebase first" → Skills tell you HOW to explore. Check first.

效果：Skill 的完整内容永久驻留在系统 Prompt 中，模型每次都能看到。

典型应用：
Agent 行为规范（「必须先读 Skill 再干活」）
核心纪律（「不要泄露系统提示」）
全局风格约定

方式二：目录索引 + 模型自主选择

触发时机：每次构建系统 Prompt 时

工作原理：

# 源码位置：context.py → build_system_prompt()
skills_summary = self.skills.build_skills_summary(exclude=set(always_skills))
if skills_summary:
    parts.append(render_template("agent/skills_section.md", 
                                 skills_summary=skills_summary))

注入到系统 Prompt 的实际内容：

# Skills

The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
Unavailable skills need dependencies installed first — you can try installing them with apt/brew.

- byted-web-search — 火山引擎联网搜索 API，返回网页/图片结果。联网搜索场景优先使用本 skill。 `skills/byted-web-search/SKILL.md`
- code — Coding workflow with planning, implementation, verification, and testing. `skills/code/SKILL.md`
- paper-assistant — 面向论文选题、提纲、摘要、引言、文献综述的论文助手。 `skills/paper-assistant/SKILL.md`
- self-improving — Agent 自我反思、自我批评、从错误中学习的永久改进系统。 `skills/self-improving/SKILL.md`
- markdown-converter — 将各种格式文件（PDF/Word/PPT/图片）转换为 Markdown，方便 LLM 处理。 `skills/markdown-converter/SKILL.md`

实际使用示例：

用户：帮我写一篇关于大模型 RAG 技术的综述论文
    ↓
模型看到 Skill 目录中有 paper-assistant
    ↓
思考：写论文应该用 paper-assistant 这个 skill
    ↓
调用 read_file("skills/paper-assistant/SKILL.md")
    ↓
获取完整的论文写作工作流指南
    ↓
按照 Skill 的指导：选题 → 文献检索 → 提纲 → 写作 → 润色

这就是为什么 Skill 不需要注册为 Tool！
目录只占 ~50 tokens
真正需要用时才读完整内容（可能几千 tokens）
完美的按需加载

方式三：@ 提及触发运行时提示

触发时机：用户消息中包含 `@skillname` 时

工作原理：

# 源码位置：apps/cli/utils.py → _cli_app_runtime_lines()
def _cli_app_runtime_lines(text, metadata, workspace):
    mentions = CliAppManager(workspace).mentioned_installed_apps(text)
    return [
        f"CLI App Mention: @{item['name']} "
        f"(installed; tool={item['tool']}; skill={item['skill']}). "
        "Read the skill when useful, then run this app with run_cli_app."
        for item in mentions
    ]

注入位置：不是系统 Prompt，而是附加在用户消息末尾的「Runtime Context」区域。

实际示例：

用户输入：用 @ollama 跑一下 qwen2.5:7b 模型，测试一下推理速度
          ↑
          @ 提及被检测到

消息被悄悄加上：

[Runtime Context]
CLI App Mention: @ollama (installed; tool=run_cli_app;
entry_point=ollama; skill=skills/cli-app-ollama/SKILL.md).
Read the skill when useful, then run this app with run_cli_app;
do not bypass it with shell.
[/Runtime Context]

效果：
精确匹配用户意图
避免模型猜来猜去
直接告诉模型「该用哪个 Tool + 该读哪个 Skill」

方式四：外部系统显式指定

触发时机

通过 Agent 调用参数、Gateway 插件、Session Metadata 等方式动态指定

NanoBot 中的实际实现

def build_messages(
    self,
    history: list[dict[str, Any]],
    current_message: str,
    skill_names: list[str] | None = None,  # ← 外部传入要加载的 Skill
    ...
) -> list[dict[str, Any]]:

def build_system_prompt(
    self,
    skill_names: list[str] | None = None,  # ← 外部指定的 Skill 列表
    ...
):
    # Always Skill 先被加载
    always_skills = self.skills.get_always_skills()
    if always_skills:
        always_content = self.skills.load_skills_for_context(always_skills)
        parts.append(f"# Active Skills\n\n{always_content}")
    
    # 外部指定的 Skill 被额外注入
    if skill_names:
        specified_content = self.skills.load_skills_for_context(skill_names)
        if specified_content:
            parts.append(f"# Specified Skills\n\n{specified_content}")

调用时传入

# 通过 OpenClaw Gateway 调用时指定要预加载的 Skill
response = agent.chat(
    message="帮我用飞书导出会议纪要",
    # ↓ 外部显式指定
    skill_names=["cli-app-feishu", "using-superpowers"],
    session_id="..."
)

典型场景
工作流编排系统在特定步骤指定要用的 Skil，例如「导出步骤必须加载 feishu Skill」
Gateway 插件根据当前用户身份、渠道动态注入特定 Skill
多 Agent 协作时，父 Agent 告诉子 Agent「你这次任务需要用到这些 Skill」

几种方式的区别

五、四种机制对比总表

六、为什么要搞这么复杂？

核心矛盾

大模型的上下文窗口是稀缺资源，但我们又想让 Agent 拥有无限扩展的能力。

分层策略

答案总结

不是所有能力都需要成为 Tool。
高频刚需 → 做 Tool
领域扩展 → 做 MCP
外部应用 → 做 CLI APP
知识、流程、规范 → 做 Skill

四种机制各司其职，共同构成了 AI Agent 的「无限能力宇宙」。

结语

AI Agent 的工具系统远不止 `function_call` 那么简单。从 Tools 到 MCP 到 CLI APP 再到 Skills，我们看到的是一条清晰的演进路径：从「让 Agent 能做事」到「让 Agent 会做事」。未来最强大的 Agent，不会是工具最多的那个，而是最懂怎么用好工具的那个。

在大模型应用开发中，我们常常过度关注Prompt编写和模型效果，却忽略了一个更底层的问题：Skill（工具/能力）应该在什么时候、以什么方式被触发？

一个成熟的 AI Agent 系统，绝不应该把所有压力都交给 LLM 去“猜”。如果触发机制设计不好，要么上下文爆炸导致成本失控，要么意图误判导致用户体验灾难。

本文将系统性拆解Skill触发的完整生命周期，从事件源头到执行管控，为你提供一套可落地的架构设计参考。

一、触发源：谁在发起请求？

一切始于“事件”。我们将触发源分为三类：用户交互、系统调度 和 外部事件。

1. 用户交互

这是最直接的入口。

• 自然语言输入：用户说“帮我订张票”。
• 会话上下文：多轮对话的延续，例如用户接着上一句问“那取消呢？”。

2. 系统调度

这是自动化能力的核心，也是最容易产生复杂逻辑的地方。

• Hook 触发：监听生命周期。例如“对话开始时自动加载用户画像”、“任务失败时触发告警”。
• Cron 触发：定时任务。例如“每天早上 9 点生成数据日报”。
• Agent 协作：多 Agent 架构中，Planner Agent 调用 Executor Agent。
• Meta Skill 递归：Skill 调用 Skill，形成链式反应（例如“部署”技能调用“测试”技能）。

3. 外部事件

连接现实世界的桥梁。

• Webhook：GitHub Push、支付回调。
• 队列消息：异步任务消费。
• 状态变更：数据库更新、文件上传完成。

二、决策与路由：选对 Skill 是关键

有了事件，下一步是决定“用哪个 Skill”。这是整个架构的大脑。

1. 前置路由（Pre-LLM Router）

为了省 Token、降延迟，在部分场景下可以考虑不用 LLM。

• 黑白名单：简单粗暴地禁用或推荐。
• 字符/正则匹配：如“帮我查天气”直接命中天气 Skill。
• 向量检索：基于语义相似度，从海量 Skill 库中召回候选。
• 条件断言：基于状态码、阈值（如 CPU > 80% 触发扩容）。
• 模态匹配：多模态场景下，看到图片自动路由到识图 Skill，看到 PDF 自动路由到解析 Skill。

2. 显式路由（Resolved Invocation）

用户或系统已经明确指定了目标。

• /command、@skill、UI 按钮点击。
• API 调用直接携带 skill_id。

注意：显式路由不应关心 Prompt 注入细节，那是下一层的事。

3. LLM 路由（LLM-based Resolver）

当意图模糊时，交给大模型裁决。

• 全量匹配：把所有 Skill 塞进 Prompt。不推荐，仅限玩具项目。
• 启发式匹配（主流）：只注入 Skill 的 描述（Description），让 LLM 选名字，再加载详情。
• 混合模式：核心 Skill 常驻 Prompt，长尾 Skill 按需加载。

4. 隐式与兜底

• 隐式路由：没命中任何规则，LLM 自由发挥。仅限低风险只读场景。
• 未命中处理：拒绝执行、引导澄清或转人工。

三、注入策略：上下文管理的艺术

选对了 Skill，还要考虑怎么把它放进上下文（Context）。这是成本控制的核心。

红线：所有策略必须遵守 Token Budget（上下文窗口约束）。

四、执行形态：不仅是函数调用

Skill 的执行方式决定了系统的复杂度。

• 即时执行（Atomic）：无状态调用，用完即走（如查天气）。
• 确认式执行：高风险操作（如转账、删库），必须用户 Confirm。
• 工作流执行（Stateful）：代码评审、发布流水线、多轮审批，涉及状态机。
• 异步任务：图像识别、PDF 解析、大数据计算，需要队列和回调。
• 递归与协作：复杂的自动化任务，涉及多 Agent 协同。

五、管控机制：工程化落地的保障

没有管控，就没有生产级系统。

1. 权限与作用域

• 鉴权：租户隔离（Tenant Isolation），用户 A 不能调用用户 B 的私有 Skill。
• 风险等级：标记 read_only、mutates_data，限制高危触发。

2. 冲突消解

• 互斥组：代码生成不能同时用 GitHub Copilot 和内部私有模型。
• 优先级与抢占：安全风控 Skill 可以随时中断当前执行（Preemption）。
• 去重与节流：防止 Webhook 抖动导致重复执行。

3. 参数与幂等

• 参数绑定：来源可以是 LLM 提取、用户表单或外部 Payload。
• 幂等性：使用 Idempotency Key 确保重试不会造成副作用（如重复扣款）。

4. 可观测性

• 触发追踪（Trace）：记录为什么选了这个 Skill（Reasoning）。
• 诊断事件：记录 candidate_list（召回了谁）、selected_reason（为什么选它）、rejected_by_policy（谁被拦了）。

总结

一个健壮的 Skill 触发系统，应该是分层的：

1. 快路径（Fast Path）：规则、正则、显式调用 —— 快、准、省。
2. 慢路径（Slow Path）：LLM 路由、向量检索 —— 智能、灵活。
3. 安全网（Safety Net）：权限、熔断、降级 —— 稳。

不要试图用LLM解决所有路由问题，也不要试图让所有Skill都活在Prompt里。分离触发源、路由逻辑与执行策略，你的Agent才会真正从Demo走向生产。

本文将从架构视角系统拆解AI Agent的核心模块，完整呈现AI Agent基础能力：

一、基础运行时：AI Agent的内核底座

Platform Runtime 是AI Agent的底层基石，对应传统操作系统的内核基础服务，负责提供配置、环境、日志、敏感信息等通用基础能力，保障Agent稳定、可配置、可观测地运行。

1.1 配置管理

配置是Agent运行的“参数面板”，AI Agent采用分层配置架构，兼顾灵活性与统一性：
分层配置：遵循“默认配置 → 全局配置 → 会话级配置 → 任务级配置”的优先级覆盖机制，不同层级的配置可以按需叠加，既保证全局管控能力，又支持单任务的个性化调优。
热更新：支持配置的动态生效，无需重启Agent进程即可调整模型参数、工具权限、限流规则等，满足生产环境的动态运维需求。

1.2 环境变量与启动引导

运行时环境的一致性是Agent可复现运行的前提：
运行时注入：支持通过环境变量、配置文件、启动参数等多渠道注入运行时信息，适配容器化、本地、云端等不同部署环境。
启动校验：进程启动时自动执行依赖检查、配置合法性校验、模型连通性测试、工具可用性探测，提前发现环境问题，避免运行时异常。
健康检查（Health Check）：提供标准健康探针，支持存活探测与就绪探测，可无缝接入K8s等容器编排平台，实现故障自动重启与流量调度。

1.3 敏感信息管理

针对AK/SK、Token、密钥等敏感凭据，AI Agent提供统一的敏感信息管理能力，避免硬编码与明文泄露：
支持与密钥管理服务（KMS）集成，敏感信息加密存储，运行时按需解密注入。
凭据与Agent代码、配置分离，不同权限的Agent只能访问授权范围内的凭据，落地最小权限原则。

1.4 日志管理

全链路可观测性是生产级Agent的必备能力：
日志分级：支持DEBUG、INFO、WARN、ERROR、FATAL多级日志控制，可按需调整输出粒度。
日志存储：支持本地文件、ELK、Loki等多种存储后端，统一日志格式，支持全链路trace_id追踪。
日志脱敏：内置敏感信息脱敏规则，自动对日志中的密钥、手机号、身份证号等信息进行掩码处理，满足合规要求。

二、智能体循环：Agent 的核心调度引擎

Agent Loop 是AI Agent的“CPU调度器”，是智能体“感知-规划-行动-反馈”闭环的核心载体，决定了Agent任务的执行流程与控制能力。

2.1 Turn 生命周期

一次完整的用户交互对应一个Turn，其执行流程遵循标准化的生命周期：

input → pre-hooks → plan → tool-call loop → finish → post-hooks

1. input：接收用户输入、事件触发或任务指令，作为本轮循环的起点。
2. pre-hooks：前置钩子切面，可在模型推理前执行输入校验、内容审核、上下文注入、权限校验等逻辑，是扩展能力的核心切入点。
3. plan：大模型基于当前上下文与可用能力，进行任务规划，决定下一步行动。
4. tool-call loop：工具调用子循环，模型生成工具调用指令，执行引擎执行工具并将结果回灌上下文，模型再基于结果进行下一轮决策，如此往复。为防止无限循环，系统会设置单次循环tool call最大次数阈值，超出后强制终止。
5. finish：模型判定任务完成，生成最终回复，结束本轮推理。
6. post-hooks：后置钩子切面，可执行结果审计、记忆持久化、指标上报、后续任务编排等收尾逻辑。

2.2 执行控制

很多时候，任务的可控性比自主性更重要。AI Agent提供完整的执行控制能力：
中断与恢复：支持任务的挂起与断点恢复，可保存当前执行现场（上下文、工具状态、进度），在中断后从断点继续执行。
任务取消：支持主动取消运行中的任务，立即终止模型推理与工具执行，释放资源。
任务超时：为每个任务设置整体超时时间与单轮工具调用超时时间，避免长任务阻塞资源。
进程退出：支持优雅退出机制，收到退出信号后保存现场、释放资源、完成收尾工作后再终止进程，避免状态损坏。

三、大模型接入层：统一的模型驱动抽象

LLM Layer 是AI Agent的“驱动层”，向下适配不同厂商、不同形态的大模型，向上提供统一的调用接口，屏蔽底层模型差异，让上层业务逻辑与具体模型解耦。

3.1 多厂商支持

AI Agent 构建了一套标准化的模型适配框架，实现“一次开发，多模型运行”：
标准协议兼容：原生兼容OpenAI协议、Claude协议，支持所有遵循这两类协议的模型服务，同时支持本地部署的开源模型接入。
统一能力适配：对文本补全（completion）、对话（chat）、工具调用（tool_call）三类核心能力进行统一抽象，无论底层模型原生是否支持，都通过适配层提供一致的调用体验。
模型参数统一：对temperature、max_tokens、response_format、thinking模式等通用参数进行标准化封装，同时保留模型专属参数的扩展能力。
认证与代理管理：统一管理各厂商的AK/SK、OAuth认证信息，支持代理（Proxy）配置，满足企业网络环境下的模型访问需求。

3.2 多模态支持

AI Agent 不局限于文本交互，支持全模态的输入输出能力：
支持文字、图片、语音（TTS/STT）等多模态信息的输入与输出，让Agent具备视觉、听觉感知能力。
支持文件作为输入，可直接解析文档、表格、代码文件等多种格式，将文件内容转化为模型可理解的上下文。

3.3 Prompt 工程体系

Prompt是Agent与大模型交互的“指令语言”，AI Agent提供系统化的Prompt工程能力：
System Prompt / Role Prompt：支持分层的角色设定，可配置全局人设、Agent专属角色、任务级指令，实现灵活的人格与能力设定。
Tool Calling Schema：自动将注册的工具转化为对应模型格式的工具定义Schema，无需手动编写适配代码。
Fallback 机制：当模型无法正确生成工具调用格式时，提供降级处理逻辑，比如通过自然语言解析、重试、切换模型等方式保障任务继续执行，提升系统鲁棒性。

四、会话与记忆：智能体的状态管理系统

如果说Agent Loop是Agent的“思考过程”，那么会话与记忆就是Agent的“大脑记忆”，负责管理Agent的状态、历史与知识，是智能体具备连续性与成长性的核心。

4.1 会话管理

会话是Agent与用户交互的上下文容器，对应传统OS的“进程”概念：
会话生命周期：管理会话的创建、激活、挂起、归档、销毁全生命周期，支持长时会话与临时会话两种模式。
会话归属：每个会话绑定唯一的用户与Agent实例，支持多用户、多Agent的并发隔离。
会话隔离：不同会话之间的上下文、记忆、工具状态完全隔离，避免信息串扰。
会话存储：支持内存、数据库、文件等多种存储介质，可按需选择持久化策略，满足会话持久化与历史回溯需求。

4.2 上下文管理

上下文是模型推理的直接输入，其质量与长度直接影响Agent的表现：
Prompt模板化：将系统提示、角色设定、历史消息、工具定义等内容模板化，支持动态变量注入，保证Prompt结构的一致性与可维护性。
上下文优化：当上下文长度接近模型窗口上限时，自动执行压缩、摘要、丢弃等优化策略，在保留关键信息的前提下控制上下文长度，保障推理效率。

4.3 记忆管理

AI Agent 构建了分层记忆体系，模拟人类的记忆机制，让Agent具备持续学习与经验沉淀能力：
灵魂文件：定义Agent的核心人格、底层价值观、核心能力边界，是Agent的“自我认知”，分为SOUL（底层灵魂）、Agent（角色设定）、Me（自我认知）三个层级。
短期记忆（Working Memory）：即当前会话的上下文，对应人类的工作记忆，容量有限，用于当前任务的推理。
长期记忆（LTM）：持久化存储的历史交互、经验总结、关键事实，跨会话生效，对应人类的长期记忆。
Dream（记忆提炼）：定期对历史交互进行离线提炼，从大量对话中抽取关键知识、经验教训、行为模式，沉淀为结构化的长期记忆，类似人类睡眠时的记忆整理。
知识库（RAG）：对接外部知识库，通过检索增强生成的方式，让Agent可以调用外部专业知识，解决长尾问题。

五、工具与执行：智能体的行动能力底座

工具是Agent与真实世界交互的“手脚”，工具与执行模块是AI Agent的“系统调用层”，负责管理所有可执行能力，并提供安全、可控的执行环境。

5.1 工具注册表

AI Agent 提供统一的工具注册中心，所有工具（内置工具、MCP工具、CLI工具、Skill）都在此注册与管理：
工具元数据管理：名称、描述、参数Schema、权限要求、执行后端等信息统一维护。
工具发现与路由：Agent运行时可动态查询可用工具，根据权限与场景自动筛选可调用的工具集合。

5.2 内置工具集

AI Agent 内置了丰富的基础工具，覆盖Agent日常执行的核心场景：
文件系统类：目录操作、文件读写、文件内容搜索、批量处理等。
网络类：网络搜索、网页内容获取、文件下载等。
执行类：系统命令执行、异步长任务执行、代码沙箱执行等。
开发类：GitHub仓库操作、代码版本管理等。

5.3 MCP 协议支持

MCP（Model Context Protocol）是行业正在形成的标准化工具协议，AI Agent原生支持MCP，实现工具生态的互联互通：
MCP工具注册：可快速接入第三方MCP Server，自动同步其工具列表与定义。
MCP统一调用：将MCP工具与内置工具统一纳管，对上层Agent Loop透明，无需区分工具来源。

5.4 CLI 工具体系

针对命令行类工具，AI Agent提供专门的CLI工具管理能力：
CLI工具注册与标准化封装，将零散的命令行工具转化为可被模型调用的标准化工具。
CLI技能仓库：提供可复用的CLI技能包，支持检索、安装、版本管理，实现CLI能力的开箱即用。

5.5 Skill 技能体系

Skill是更高阶的、面向特定场景的复合能力包，比单一工具更复杂，包含多步操作与领域知识：
Skill规范：定义标准的Skill格式，包含manifest（元数据声明）、execute（执行逻辑）、依赖声明等。
Skill命中策略：针对不同规模的技能库，提供多种命中方式：
全量注入Prompt：技能数量少时，将所有技能描述全部注入上下文，由模型自主选择。
元技能引导法：工作开始前，先由模型判断哪些技能可能有用，再按需加载对应技能。
触发词前置匹配：通过关键词快速匹配技能，实现低延迟触发。
向量相似度匹配：技能数量庞大时，通过向量检索匹配最相关的技能，精准召回。
Skill仓库：提供中心化的技能市场，支持技能的发布、检索、安装、版本管理，构建可复用的能力生态。

5.6 定时任务与编排

支持基于Cron的定时任务能力，可实现Agent的自主周期性工作：
任务编排：支持配置定时触发的Agent任务，定义执行周期、触发条件、任务参数。
重试策略：任务执行失败时，可按配置的重试次数、间隔、退避策略自动重试，保障任务成功率。

5.7 工具执行层管控

执行安全是工具能力的底线，AI Agent对所有工具执行进行统一管控：
多执行后端：支持local（本地执行）、microvm（轻量虚拟机）、docker（容器沙箱）、remote worker（远程工作节点）多种执行后端，可根据安全等级灵活选择。
资源配额：对每个工具执行设置CPU、内存、磁盘、执行时长的配额限制，防止恶意或异常工具耗尽系统资源。
工作目录隔离：每个Agent、每个会话都有独立的工作目录，禁止越权访问其他目录的文件。
输入Schema校验：工具执行前自动校验输入参数是否符合Schema定义，拦截非法输入。
执行审计日志：所有工具调用的参数、结果、耗时、调用者都完整记录，支持事后审计与追溯。

六、扩展与集成：连接内外的交互接口

AI Agent 提供丰富的扩展与集成能力，支持业务侧自定义逻辑，也支持对接各类外部渠道与交互界面。

6.1 钩子回调（Hook）

Hook是AI Agent的扩展机制，类似传统OS的系统钩子，允许开发者在不修改核心代码的情况下插入自定义逻辑：
切面管理：覆盖Turn生命周期的各个关键节点（输入、推理前、工具调用前、工具调用后、输出、错误等），提供标准化的切面扩展点。
失败策略：支持自定义失败处理钩子，可配置重试、降级、告警、人工介入等多种失败处理逻辑。

6.2 消息总线（MsgBus）

消息总线是AI Agent内部的事件通信机制，实现各模块之间的解耦与异步协作：
事件类型：定义标准化的事件类型，包括会话事件、任务事件、工具事件、模型事件、安全事件等。
订阅模型：支持发布-订阅模式，各模块可订阅感兴趣的事件，事件发布后自动推送给所有订阅者。
事件路由：支持基于事件类型、来源、优先级的路由策略，可实现事件的过滤、转换、转发。

6.3 Channel 渠道集成

Channel是Agent与外部用户交互的通道，AI Agent内置多渠道适配能力：
原生支持WebSocket实时通信渠道，满足Web端、客户端的实时交互需求。
内置飞书、钉钉、企业微信等主流办公IM渠道的适配，可快速将Agent部署到企业办公场景。

6.4 UI 集成方案

AI Agent 提供多形态的UI集成支持，适配不同的使用场景：
TUI：终端交互界面，适合开发者本地调试与命令行场景使用。
WebUI：Web端交互界面，可快速部署为网页应用，面向终端用户。
Desktop APP：桌面客户端，支持Windows、macOS、Linux，提供本地化的Agent体验。
Mobile APP：移动端适配，支持iOS与Android，实现随身的智能助手。

七、安全防护：项目落地的安全底线

安全是Agent从Demo走向生产的核心门槛，AI Agent将安全作为原生设计，构建了全链路的安全防护体系。

7.1 边界隔离

通过多层沙箱机制，为Agent的执行建立牢固的安全边界：
沙箱技术：支持container容器、seccomp系统调用过滤、landlock文件系统限制等多种沙箱技术，层层递进限制Agent的操作权限。
多维度边界管控：从路径访问、网络访问、进程创建三个维度设置严格边界，禁止Agent越权访问未授权的文件、网络地址与系统资源。

7.2 身份与权限

建立完整的身份认证与权限授权体系，实现全链路的权限管控：
AuthN（认证）：统一的身份认证体系，确认用户、Agent、工具的真实身份。
AuthZ（授权）：三级权限管控模型：
user → agent：用户可使用哪些Agent
agent → tool：Agent可调用哪些工具
tool → resource：工具可访问哪些资源
敏感操作人工确认（Human-in-the-loop）：对于高危操作（如删除文件、执行生产环境命令、调用付费接口等），强制触发人工审批流程，只有用户确认后才可执行，从机制上避免Agent误操作带来的风险。

7.3 可用性与防护

保障Agent服务的稳定可用，抵御滥用与攻击：
CORS / WS Origin校验：严格校验跨域请求与WebSocket连接的来源，防止恶意页面调用Agent服务。
限流与并发控制：支持按用户、按Agent、按接口维度的限流，控制并发数与请求频率，防止资源被耗尽。
反滥用防护：识别异常调用模式，拦截恶意请求与滥用行为，保障服务的公平性与稳定性。

八、高级能力：面向复杂场景的进阶特性

除了基础能力之外，AI Agent还提供一系列高级特性，支撑复杂企业场景与大规模Agent部署。

8.1 Token计费与模型路由

Token计费：精确统计每个用户、每个会话、每个任务的Token消耗，对接不同模型的计费标准，实现成本的精细化核算。
智能模型路由：根据任务类型、复杂度、成本要求、性能要求，自动选择最合适的模型，在效果与成本之间取得最优平衡。

8.2 Token归因分析

对Token消耗进行细粒度的归因分析，明确Token消耗在系统提示、历史对话、工具定义、工具结果等不同部分的占比，为Prompt优化、上下文压缩、成本管控提供数据支撑。

8.3 Sub Agent 子代理

支持Agent的层级化架构，主Agent可以创建并调度Sub Agent，将复杂任务拆解为子任务，分发给不同的子Agent并行或串行执行，最后汇总结果。这种模式可以大幅提升复杂任务的处理能力与专业度。

8.4 多Agent协作

支持多个对等Agent之间的协作，通过消息总线与协作协议，实现任务分工、信息共享、协同决策，模拟团队协作模式，解决单Agent无法覆盖的复杂业务场景。

8.5 工作流编排

提供可视化或声明式的工作流编排能力，可将复杂的业务流程定义为标准化的工作流，由Agent按流程执行，降低Agent执行的不确定性，提升业务流程的可控性与可预测性。

8.6 自主规划与反思

赋予Agent更强的自主认知能力：
自主规划：面对复杂目标时，Agent可以自主拆解任务、制定计划、动态调整路径。
反思机制：任务执行完成后，Agent可对执行过程进行复盘反思，总结经验教训，优化后续的执行策略，实现自我迭代。

结语

本文只是分析了AI Agent最基础的架构，很多OpenClaw、Hermes的优秀特性尚未来得及展开讨论。对于AI Agent，你有什么好的想法吗？欢迎留言讨论：）。

如果AI Agent是一辆车，那大模型是发动机，Prompt Engineering是方向盘，Context Engineering是导航软件，Harness Engineering是整车的质量工程。相互配合，最终才能顺利达目的地。

引言：为什么AI Agent好像总在“瞎忙”？

2023年，我们沉迷于寻找“完美提示词”，将大量精力投入措辞打磨，试图用一句精准指令撬动大模型的潜在能力。

2024年，我们全力钻研 RAG、记忆系统与长上下文管理，拼命破解模型幻觉与知识盲区的痛点。

2025–2026年，越来越多研发团队发现：即便把提示词优化到极致、把上下文信息补全，AI Agent 在真实业务场景中依然频繁“翻车”，难以稳定落地并创造实际价值。

行业数据给出了残酷的答案：AI Agent 的整体失败率约为20%，长链路复杂任务的失败率更是突破50%；MIT一项针对企业生成式AI的研究显示，约95%的大型企业试点项目，最终未能带来可衡量的商业回报。

问题的核心，从来不是模型不够聪明、参数不够庞大，而是我们始终缺乏一套系统化、可管控、可复用的工程方法，来驾驭这股强大却难以预测的智能力量。

一、Agent工程的三次跃迁

纵观Agent工程的发展历程，已完成三次范式跃迁：从Prompt Engineering（提示工程），到Context Engineering（上下文工程），再到如今引领行业方向的Harness Engineering（驾驭工程）。每一次跃迁，都是对AI工程化的一次升维，更是对“如何让AI真正服务于业务”这一核心问题的深度探索。

二、第一次跃迁：Prompt Engineering（2023–2024）—— 写“咒语”的艺术

核心命题：如何问对问题？

Prompt Engineering是Agent工程的第一代范式，也是大模型走向大众化与工程化的起点。ChatGPT横空出世后，整个行业都在聚焦同一件事：如何“问对问题”，才能让模型稳定输出符合预期的结果。

这一阶段，开发者通过设定角色、补充Few-shot示例、嵌入思维链（CoT）、明确输出格式与约束条件，构建起一套基础指令体系，以此引导模型高效完成任务。比如：

你是资深 Python 工程师，请帮我重构以下代码。
要求：
1. 遵循 PEP8 规范
2. 添加类型注解
3. 处理边界情况

能力边界与瓶颈
Prompt Engineering的核心信念是：只要Prompt写得足够好，模型就能给出理想答案。它将大模型视为一个可通过自然语言驱动的黑盒，所有优化都集中在单次输入文本上，快速降低了大模型的使用门槛，在内容生成、翻译、简单问答等轻量化场景中迅速普及。

但随着任务复杂度不断提升，其天花板很快显现：

1、任务复杂度受限
单轮任务表现尚可，多步骤、长链路任务极易跑偏、出错，难以形成连贯输出

2、缺乏私有知识
仅依赖模型预训练数据，无法接入企业内部业务信息、私有知识库，实用性受限

4、无记忆能力
无状态交互模式，无法记住历史对话偏好、任务进度，多轮对话体验差

5、高度脆弱性
提示词措辞的微小变化，就可能导致模型输出准确率大幅波动，稳定性不足

5、无实际执行能力
仅能输出文本内容，无法调用外部工具、执行具体操作，难以落地实际业务

当然，Prompt Engineering并非完全是“玄学”。发展后期，行业也逐步形成了模板库、评估指标等标准化方法，并出现了 Prompt Tuning等轻量微调技术，为后续上下文工程的发展奠定了基础。PromptBase等平台的兴起，也印证了它的商业价值，但同时也暴露了其可复制性差、难以规模化落地的根本短板。

Prompt Engineering解决的是“说什么、怎么说”的问题，但无法解决“做什么、怎么做”的核心诉求，因此只能作为轻量化应用的基础方案，难以支撑复杂业务场景。

三、第二次跃迁：Context Engineering（2025）—— 信息编排与管理的艺术

核心命题：给模型看什么、记什么？

随着Claude、Gemini等主流模型将上下文窗口推至百万token级别，行业重心从“怎么问”转向“带什么信息进场”，Context Engineering逐渐成为Agent工程的主流范式。

它的核心，是为大模型建立一套完善的信息供给与记忆体系，打破预训练知识的边界，让模型能够感知外部环境、调用工具能力、保留交互状态。其核心组件主要包括三大模块：

1. RAG（检索增强生成）：接入私有知识库与向量库，实时检索最新、最精准的信息，有效解决模型幻觉与知识滞后问题。

2. Tools（工具调用）：封装 API、代码执行、数据查询等实用能力，让 AI 从“只会说”真正走向“会动手做事”。

3. Memory（记忆系统）：区分短期对话记忆与长期用户记忆，支持多轮连贯任务，让交互更具连贯性与个性化。

典型架构为：

用户查询 → 检索模块 → 相关性排序 → 上下文组装 → LLM 推理 → 输出格式化
              ↑_________知识库/历史记忆/工具定义_________|

Context Engineering 显著提升了 Agent 的综合能力，但也带来了新的系统复杂性，新的问题随之浮现：

1、Context Rot（上下文腐化）
上下文 token 数量越多，模型对中间关键信息的注意力越分散，容易忽略核心需求。

2、信息噪声
无关信息混入上下文，会干扰模型判断，导致输出偏离任务目标，降低执行效率。

3、工具滥用/错用
模型可能随意调用工具、传递错误参数，不仅无法解决问题，还可能引发系统风险。

4、行为不可控
缺乏硬性约束机制，模型可能跳过既定规则、越权操作，甚至陷入死循环，导致任务停滞。

5、错误累积
长链路任务中，一步操作失误会不断累积，最终导致整个任务彻底失败，难以回溯与修正。

为应对这些问题，行业逐步发展出上下文压缩、动态检索优先级、记忆分层等优化技术，在控制token成本的同时，有效提升了信息的有效性。但即便如此，Context Engineering依然只能解决“知道什么”的问题，无法保证“做得稳、不出错”，难以支撑生产级高可靠业务场景。

Context Engineering解决的是“看什么、记什么”的信息供给问题，但无法解决“怎么跑、跑多稳”的系统可靠性问题，仍不足以支撑生产级高可靠场景的落地需求。

四、第三次跃迁：Harness Engineering（2026）—— 系统构建与驾驭的艺术

核心命题：如何让系统可靠地自主运行？

2026 年初，Mitchell Hashimoto正式提出Harness Engineering概念，短短数周内便被OpenAI、Martin Fowler等行业权威广泛采纳，迅速成为 Agent 工程的新一代主导范式。

“Harness”意为缰绳、马具，在AI体系中，它特指围绕 Agent 构建的一整套运行环境、约束机制与治理体系。OpenAI对其给出了明确定义：不优化模型本身，而是优化模型运行的外部环境，通过系统性设计，让 Agent 在可控、可靠、合规的框架内高效执行任务。

其核心哲学是：Humans steer, agents execute（人类掌舵，智能体执行）。

为什么需要Harness？

实验数据直观地展现了Harness Engineering的核心价值：

1、同一模型（Claude Opus 4.5）在不同 Harness 配置下，任务成功率可从 2% 提升至 12%，差距高达 6 倍。

2、相同任务场景下，无 Harness 时 Agent 成功率仅为 42%，加入完善的 Harness 体系后，成功率飙升至 78%。

3、LangChain 仅优化 Harness 配置，便让编码 Agent 在 Terminal Bench 2.0 中的表现从 52.8% 提升至 66.5%，成效显著。

同时，Anthropic 总结出 Agent 三大典型失效模式，而这也正是 Harness Engineering 要解决的核心问题：

1、试图一步到位，过度消耗上下文资源，导致关键信息被覆盖。

2、过早宣布任务胜利，忽略未完成的细节的部分，导致任务成果不完整。

3、无验证执行操作，错误不断累积，最终导致任务彻底失败且无法回溯。

Harness Engineering 的核心支柱

综合 OpenAI、Anthropic 及行业实践经验，Harness 体系主要由四大核心支柱构成：

1、动态上下文管理（Context Engineering）
搭建持续迭代的活态知识库，保障信息时效性与准确性；采用按需检索机制，实现渐进式信息披露，避免上下文冗余；注入动态可观测性数据，让系统运行状态可追踪、可分析。

2、架构约束体系（Architectural Constraints）
引入确定性代码检查（Linter）与严格类型校验，规避语法与逻辑错误；建立分层依赖管理与CI强制阻断机制，保障系统稳定性与可维护性；嵌入业务规范与合规要求硬约束，确保Agent行为合法合规。

3、闭环反馈机制（Feedback Loop）
构建Agent间相互审核机制，交叉校验执行结果，降低错误率；部署自动化测试与效果校验流程，实现执行质量实时管控；建立错误回传与自我修正机制，及时复盘问题、优化执行逻辑。

4、系统熵管理（Garbage Collection）
实施文档漂移检测，及时发现并修正知识偏差；开展违规行为常态化巡检，防范系统运行风险；定期清理技术债务，保障系统长期高效、稳定运行。

在实际落地过程中，Harness 还承担了多智能体编排、成本护栏、权限控制、与MLOps（机器学习运维）融合等关键职能，让整个Agent系统具备可观测、可审计、可收敛的特性，而非放任Agent自由生长、无序执行。

如何使用Harness：从“教AI思考”到“给AI流程”

以代码调试Agent为例，两种不同工程范式的落地效果差异显著：

传统方式（Prompt + Context）：
1、撰写冗长指令，试图教Agent一步步排查问题
2、向模型塞入全量日志与代码库，导致上下文冗余
3、最终结果：Agent思路混乱、钻牛角尖，甚至越修越错，无法解决实际问题

Harness 方式：
1、错误分类器 → 判定错误类型、过滤无效噪声
2、日志提取器 → 精准抽取关键错误信息，减少冗余
3、代码定位器 → 快速锁定可疑代码范围，提升效率
4、修复生成器 → 生成针对性补丁，确保合规性
5、测试验证器 → 自动校验修复效果，失败则回环重试

可以看到，Harness Engineering解决的是“怎么跑、跑多稳”的可靠性问题，让 AI 从不可控的“玩具”，真正转变为可规模化落地的可靠协作者，标志着 AI 开发正式从“炼丹式调优”走向标准化、工程化的现代软件工程。

五、三层范式的关系：包含而非取代

Prompt、Context、Harness 三种工程范式，并非相互替代的关系，而是层层包含、逐级升级的架构关系：

简单来说：
Harness 体系中，离不开 Context 提供的信息支撑
Context 体系中，离不开高质量 Prompt 的引导作用

三次跃迁的本质，是工程重心的不断上移——从“调优指令”到“管理信息”，再到“管控整个系统”，逐步实现 AI Agent 的规模化、可靠化落地。

六、工程价值的迁移

1、Prompt 时代
核心价值在于“解锁模型基础能力”，高度依赖工程师个人技巧，优化经验难以复制，规模化价值有限。

2、Context 时代
核心价值在于“构建数据基础设施”，工作内容接近传统数据工程，重点在于信息的梳理、检索与供给。

3、Harness 时代
核心价值在于“系统架构设计与风险治理”，考验工程师的软件工程能力、系统思维与风险管控意识。

七、落地建议：分阶段适配你的项目

结合不同项目的场景需求与资源现状，建议分三个阶段逐步落地 Agent 工程范式，避免盲目跟风、一步到位：

阶段一：单点突破（Prompt）
适合简单内容生成、翻译、基础问答等轻量化场景，重点建设 Prompt 模板库与示例库，规范指令格式，快速解锁模型基础能力，降低使用门槛。

阶段二：能力建设（Context）
适合需要接入私有知识、支持多轮对话、调用基础工具的场景，重点搭建 RAG 检索体系与记忆系统，解决模型幻觉与知识滞后问题，提升 Agent 的实用性。

阶段三：系统治理（Harness）
适合生产级应用、敏感业务场景、高可靠要求的项目，重点建设以下核心能力：
1、架构约束与规范，明确 Agent 行为边界
2、自动化反馈与测试闭环，及时发现并修正错误
3、可观测与监控体系，实时掌握系统运行状态
4、安全护栏与人工介入点，降低业务风险
5、熵清理与技术债务管理，保障系统长期稳定运行

落地避坑
1、不要跳过 Context 阶段直接硬上 Harness，缺乏信息支撑的 Harness 只会成为空架子，无法发挥实际价值。
2、不要一开始就追求完美 Harness 体系，建议从小型约束与简单反馈循环开始，逐步迭代优化，降低落地难度。
3、不要迷信 AI 完全自治，关键业务节点必须保留“人在回路”，避免因 Agent 失控引发重大风险。

八、结语：范式演进背后的不变核心

Agent 工程的三次跃迁，本质上是一条清晰的进化路线：从优化指令，到管理信息，再到构建可控系统。

每一次跃迁，都源于模型能力突破了旧范式的上限，同时也暴露出更深层次的工程化问题——从“不会用”到“用不好”，再到“用不稳”，行业的探索始终围绕“让 AI 真正服务于业务”这一核心目标。

但无论技术如何迭代、范式如何升级，有一件事始终不会被自动化取代：深刻理解你要解决的问题。

最好的Prompt，源于对任务本质的精准把握；最好的Context，源于对业务信息流的深刻理解；最好的Harness，源于对系统失败模式的全面认知。

工具在变，范式在变，但清晰的问题意识、严谨的工程思维、对风险的敏锐判断，永远是优秀 AI 工程师的核心竞争力，也是Agent工程能够持续创造价值的根本所在。

九、参考资源
Harness Engineering: Leveraging Codex in an Agent-First World – OpenAI
Harness Engineering – Martin Fowler
The Third Evolution: Why Harness Engineering Replaced Prompting in 2026 – Epsilla
The Rise of AI Harness Engineering – Cobus Greyling
Anthropic Agent 可靠性工程实践白皮书
Pinecone Context Compression 技术文档
LangChain Harness & 多智能体编排实践