AI Agent Hooks

AI Agent Hooks（智能体钩子）是在AI Agent执行生命周期的特定节点上，预设的程序化拦截点。你可以把它理解为Agent的“安全控制面板”和“行为开关”，通过在关键步骤插入自定义逻辑，实现对Agent行为的精细、确定性控制。

💡 核心价值：从“说服”到“控制”

在没有Hooks的情况下，我们依赖Prompt来“说服”AI遵循指令。但这种软性约束并不可靠，模型可能会“遗忘”或“自信地”绕过。

Hooks则提供了一种确定性的工程化保障。它不依赖AI的“主观意愿”，而是在代码层面强制执行规则。例如，用Prompt告诉Agent“不要编辑生成的文件”，它可能不听；但一个PreToolUse Hook可以在编辑发生前就将其阻止。

这种机制之所以重要，是因为经验数据显示，用户对AI权限提示的批准率高达93%，资深用户更有超40%的情况会转为自动批准。这说明依赖人工审批的安全模型效率不高，需要Hooks这样的自动化程序化方案来接管。

⚙️ 工作原理：事件、处理器与决策

Agent Hooks的工作流程可概括为：事件发生 → 匹配过滤器 → 执行处理器 → 做出决策。

1. 事件 (Event)：Agent生命周期中的特定时刻，如开始、结束、工具调用前后等。

2. 匹配器/过滤器 (Matcher/Filter)：可选，用于指定Hook仅在特定条件下触发，例如只拦截“编辑文件”这个操作。

3. 处理器 (Handler)：事件触发时执行的自定义逻辑，可以是一个Shell脚本、Python函数，甚至是一个LLM调用。

4. 决策 (Outcome/Decision)：处理器执行后返回的结果，用于影响Agent的后续行为。

根据实现方式不同，Hook主要分为两类：

• 命令挂钩 (Command Hooks)：执行Shell命令或脚本，适合确定性检查（如路径黑名单验证）、策略执行和审计日志记录。

• 提示挂钩 (Prompt Hooks)：将上下文发给LLM评估并返回决策，适合主观性判断，如检查回答是否完整。

📋 常见的Hook类型

尽管不同框架的实现略有差异，但以下是一些通用的Hook类型：

此外，LangChain等框架还提供了before_model/after_model（模型调用前后）等更细粒度的Hook。

⚙️ 通用编写模式

无论采用哪种方式，编写Hook都遵循一个核心流程：事件触发 → 匹配过滤 → 执行处理 → 返回决策。

• 事件 (Event)：决定Hook何时运行，如PreToolUse（工具调用前）、PostToolUse（工具调用后）等。

• 匹配器 (Matcher)：可选。用于过滤，让Hook只在特定条件下触发，例如只针对execute_command这个工具。

• 处理器 (Handler)：Hook的核心逻辑，可以是一个Shell脚本、Python函数等。

• 决策 (Outcome)：处理器执行后的结果，用于影响Agent行为，如allow（允许）、block（阻止）。

下面来看看两种主流的编写方式。

📄 方式一：声明式编写 (基于配置文件)

这是最通用的方式，通过一个JSON配置文件（如hooks.json）来定义Hook，无需编写复杂的集成代码。

1. 定义事件与命令
在配置文件中，为特定事件指定要执行的命令。

{
  "hooks": {
    "PostToolUse": [  // 1. 指定事件：在工具使用后触发
      {
        "type": "command",
        "command": "npx prettier --write ." // 2. 指定处理命令
      }
    ]
  }
}

示例：一个在PostToolUse事件触发后，自动运行代码格式化工具Prettier的Hook。

2. 使用匹配器 (Matcher) 进行过滤
通过matcher字段，可以让Hook更精准。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "execute_command", // 仅在 execute_command 工具被调用时触发
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/safety_check.sh",
            "timeout": 5 // 设置5秒超时
          }
        ]
      }
    ]
  }
}

示例：一个在execute_command工具执行前，运行安全检查脚本的Hook。

3. 处理输入与输出
Hook脚本可以通过标准输入 (stdin) 接收事件详情（JSON格式），并通过标准输出 (stdout) 返回JSON来控制Agent行为。

• 输入示例 (PreToolUse): 包含会话ID、工具名称和参数等信息。

  {
    "session_id": "abc123",
    "hook_event_name": "PreToolUse",
    "tool_name": "execute_command",
    "tool_input": { "command": "rm -rf /" }
  }

• 输出示例 (阻止执行): 通过"continue": false来阻止危险操作。

  { "continue": false, "systemMessage": "检测到危险命令，已阻止。" }

• 输出示例 (修改参数): 通过modifiedInput来修改工具参数。

  {
    "continue": true,
    "hookSpecificOutput": {
      "hookEventName": "PreToolUse",
      "permissionDecision": "allow",
      "modifiedInput": { "command": "npm install --legacy-peer-deps" }
    }
  }

4. 存放位置
配置文件通常放在项目根目录下，如.github/hooks/、.claude/settings.json等，具体位置依平台而定。

💻 方式二：编程式编写 (基于代码)

这种方式更灵活，通过直接编写代码（如Python、TypeScript）来定义Hook，并集成到Agent的开发框架中。

• LangChain (Python): 使用@before_model、@after_model等装饰器。

  from langchain.agents.middleware import before_model, AgentState
  
  @before_model
  def check_message_limit(state: AgentState):
      # 在每次调用模型前检查消息数量
      if len(state["messages"]) >= 50:
          return {"messages": [AIMessage("达到消息上限，结束对话。")], "jump_to": "end"}
      return None

  示例：一个在模型调用前检查消息数量，超限则强制结束的Hook。

• AutoGen: 通过注册AutoReply等钩子函数来实现。

  # 注册一个自动回复钩子，用于检测并执行消息中的代码块
  agent.register_reply([Agent, None], reply_func_dotnet_code_executor)

  示例：注册一个钩子，让Agent能自动检测并执行消息中的C#代码块。

• Agno: 提供pre_hook和post_hook，分别在Agent处理输入前和后执行。

🔧 方式三：混合式 (配置+代码)

这是最强大的方式，通过配置文件定义触发规则，然后调用一个功能完整的脚本（如Python）作为处理器。

1. 编写处理器脚本 (hook_handler.py)
这个脚本负责核心逻辑，如读写文件、调用API等。

#!/usr/bin/env python3
import json, sys

def main():
    # 1. 从 stdin 读取输入
    input_data = json.load(sys.stdin)
    tool_name = input_data.get("tool_name")
    tool_input = input_data.get("tool_input", {})

    # 2. 执行核心逻辑（例如：安全检查）
    if tool_name == "execute_command":
        command = tool_input.get("command", "")
        if "rm -rf" in command:
            # 3. 返回决策（阻止操作）
            print(json.dumps({"continue": False, "systemMessage": "阻止了危险命令"}))
            return

    # 4. 默认允许操作
    print(json.dumps({"continue": True}))

if __name__ == "__main__":
    main()

2. 在配置文件中引用脚本

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "execute_command",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/hook_handler.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

💎 最佳实践与调试技巧

• 脚本开发：使用绝对路径引用脚本；确保脚本有完善的错误处理和快速执行能力；脚本应具备幂等性，多次执行结果一致。

• 安全性：始终验证输入的合法性；采用白名单机制进行权限控制；以最小权限运行Hook脚本。

• 性能优化：设置合理的timeout；避免Hook间相互依赖以利并行执行；对重复计算使用缓存。

• 调试技巧：模拟测试，通过echo向脚本注入测试JSON数据；使用sys.stderr输出调试信息，避免污染stdout。

🌐 主流框架与生态

Hook机制已成为AI Agent领域的共识，被众多主流平台和框架采纳。

• 编程智能体平台：Claude Code、Cursor、GitHub Copilot 等均已支持。

• 开发框架：LangChain、Haystack、AutoGen、AgentScope等均提供Hook或类似中间件机制。

• 统一管理工具：由于各平台配置不同，出现了如Swiz和agent-hooks等工具，允许开发者通过统一配置管理不同Agent的Hook。

🚀 典型应用场景

• 安全与合规护栏：在PreToolUse Hook中检查并阻止危险Shell命令或未经授权的文件访问。

• 保证输出质量：使用Stop Hook验证Agent的最终结果是否满足预设条件，避免任务过早完成。

• 自动化工作流：在PostToolUse Hook中自动运行测试、格式化代码或触发部署流程。

• 成本控制：在PreToolUse或before_model Hook中检查token消耗，并在超出预算时终止任务。

• 审计与可观测性：在任何Hook中记录Agent的决策和操作，形成完整的审计日志。

• 实现“人在回路”：在关键Hook中暂停执行，等待人工审批后再继续。

• 上下文注入：在UserPromptSubmit或PreToolUse Hook中，根据当前状态动态向Agent注入额外指令或数据。

💎 总结

AI Agent Hooks通过在Agent的执行循环中设置确定性的拦截点，将关键行为的控制权从不可靠的AI“意愿”转移到了开发者可控的代码逻辑上。它是构建安全、可控、高质量生产级AI Agent的核心工程范式之一。

编写AI Agent Hook，主要分为声明式和编程式两种方式。选择哪种取决于你使用的平台和具体需求。

总的来说，从简单的配置文件开始，当逻辑变复杂时再升级为混合模式，是上手AI Agent Hook开发的不错路径。