如果说大模型是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，你有什么好的想法吗？欢迎留言讨论：）。