Hooks - Docs by LangChain中文

钩子允许外部程序对 Deep Agents Code 的生命周期事件做出反应。在 ~/.deepagents/hooks.json 中配置命令，每当事件触发时，Deep Agents Code 会将一个 JSON 载荷通过管道传递给每个匹配命令的 stdin。钩子在后台线程中即发即忘地运行。它们永远不会阻塞 Deep Agents Code，失败仅会被记录而不会中断你的会话。

设置

创建 ~/.deepagents/hooks.json 文件：

{
  "hooks": [
    {
      "command": ["bash", "-c", "cat >> ~/deepagents-events.log"],
      "events": ["session.start", "session.end"]
    }
  ]
}

现在，每次会话开始或结束时，Deep Agents Code 都会将事件载荷追加到 ~/deepagents-events.log 文件中。

钩子配置

配置文件包含一个单一的 hooks 数组。每个条目包含：

list[str]

required

要运行的命令及其参数。不进行 shell 展开：如果需要，请使用 ["bash", "-c", "..."]。

list[str]

optional

要订阅的事件名称。省略或留空以接收所有事件。

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "task.complete"]
    },
    {
      "command": ["bash", "log_everything.sh"]
    }
  ]
}

上面示例中的第二个钩子没有 events 过滤器，因此它会接收到 Deep Agents Code 发出的所有事件。

载荷格式

每个钩子命令在 stdin 上接收一个 JSON 对象，其中包含一个 "event" 键以及事件特定的字段：

{
  "event": "session.start",
  "thread_id": "abc123"
}

事件参考

`session.start`

当代理会话开始时触发（包括交互式和非交互式模式）。

string

required

会话线程标识符。

`session.end`

当会话退出时触发。

string

required

会话线程标识符。

`user.prompt`

在交互式模式下，当用户提交聊天消息时触发。无额外字段。

`input.required`

当代理需要人工输入（人机交互中断）时触发。无额外字段。

`permission.request`

当一个或多个工具调用需要用户权限时，在批准对话框之前触发。

list[str]

required

请求批准的工具名称列表。

`tool.error`

当工具调用返回错误时触发。

list[str]

required

发生错误的工具名称列表。

`task.complete`

当代理完成其当前任务时触发（流式循环结束且没有进一步中断）。

string

required

会话线程标识符。

`context.compact`

在 Deep Agents Code 压缩（摘要）对话上下文之前触发。无额外字段。

执行模型

后台线程：钩子子进程通过 asyncio.to_thread 在一个线程中运行，因此主事件循环永远不会被阻塞。
并发分发：当多个钩子匹配同一事件时，它们会在线程池中并发运行。
5秒超时：每个命令有5秒的超时时间。超过此时间的命令将被终止。
即发即忘：错误会按钩子捕获，并以调试/警告级别记录。失败的钩子永远不会导致 Deep Agents Code 崩溃或停滞。
延迟加载：配置文件在首次事件分发时读取一次，并在会话剩余时间内缓存。
无 shell 展开：命令直接执行（不通过 shell）。如果需要管道或变量展开等 shell 功能，请将其包装在 ["bash", "-c", "..."] 中。

钩子示例

将所有事件记录到文件

{
  "hooks": [
    {
      "command": ["bash", "-c", "jq -c . >> ~/.deepagents/hook-events.jsonl"],
      "events": []
    }
  ]
}

任务完成时发送桌面通知 (macOS)

{
  "hooks": [
    {
      "command": [
        "bash", "-c",
        "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents\"'"
      ],
      "events": ["task.complete"]
    }
  ]
}

Python 处理器

编写一个处理器脚本，从 stdin 读取 JSON 载荷：

my_handler.py

import json
import sys


def handle_hook_payload(payload: dict) -> None:
    event = payload["event"]
    if event == "session.start":
        print(f"Session started: {payload['thread_id']}", file=sys.stderr)
    elif event == "permission.request":
        print(f"Approval needed for: {payload['tool_names']}", file=sys.stderr)


if __name__ == "__main__":
    handle_hook_payload(json.load(sys.stdin))

~/.deepagents/hooks.json

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "permission.request"]
    }
  ]
}

安全性考虑

钩子遵循与 Git 钩子或 shell 别名相同的信任模型——任何能够写入 ~/.deepagents/hooks.json 的用户都可以执行任意命令。这是设计如此：

无命令注入：载荷数据仅作为 JSON 流式传输到 stdin，永远不会传递到命令行参数。json.dumps 会处理转义。
默认无 shell：命令以 shell=False 运行，防止 shell 注入。
配置格式错误：无效的 JSON 或意外类型会产生记录警告，而不会引发安全问题。

仅添加来自你信任来源的钩子。一个钩子拥有与你的用户账户相同的权限。

另请参阅

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​设置

​钩子配置

​载荷格式

​事件参考

​session.start

​session.end

​user.prompt

​input.required

​permission.request

​tool.error

​task.complete

​context.compact

​执行模型

​钩子示例

​安全性考虑

​另请参阅

设置

钩子配置

载荷格式

事件参考

`session.start`

`session.end`

`user.prompt`

`input.required`

`permission.request`

`tool.error`

`task.complete`

`context.compact`

执行模型

钩子示例

安全性考虑

另请参阅