XEngineers/CamTalk

Fork 0

Files

hhs 16302af7d2 docs: 添加 Eino 框架参考文档

2026-06-19 14:35:06 +08:00

9.9 KiB

Raw Permalink Blame History

tags, create time

第七章：Interrupt / Resume（中断与恢复）

概述

本章引入 Eino 的 Interrupt / Resume 机制——一种在人机协作中实现人工审批的能力。当 Agent 需要执行敏感操作（如删除文件、发送邮件、执行命令）时，可以在执行前暂停并等待用户确认；确认后继续，拒绝则返回错误。这是让 Agent 从"全自动"走向"安全可控"的关键一步。

为什么需要 Interrupt

前三章我们逐步为 Agent 添加工具能力，使其能够读取文件、搜索代码、执行命令。但全自动执行工具也存在风险：

风险场景	后果
误删文件	不可逆的数据丢失
发送错误邮件	严重的沟通事故
执行危险命令	系统环境被破坏
修改关键配置	服务不可用

Interrupt 的定位：

Interrupt 是 Agent 的暂停机制：在关键操作前暂停，等待用户确认
Interrupt 可携带信息：向用户展示即将执行的操作详情
Interrupt 可恢复：确认后继续执行，拒绝后优雅返回错误

[!tip] 简单类比

自动执行 = "自动驾驶"（完全信任系统）

Interrupt = "人工接管"（关键决策由人来做）

关键概念

Interrupt 的两阶段执行

一个受审批保护的 Tool 在执行时被分成两个阶段：

flowchart LR
    A["Agent\n决定调用 Tool"] --> B{"Tool 内部"}
    B -->|"第一阶段"| C["保存参数"]
    C --> D["触发 Interrupt"]
    D --> E["Runner 暂停"]
    E --> F["向调用方返回\nInterrupt 事件"]
    F --> G["用户看到审批提示"]
    G --> H{"用户选择"}
    H -->|"批准"| I["runner.ResumeWith... 带上审批结果"]
    H -->|"拒绝"| J["runner.ResumeWith... 带上拒绝结果"]
    I --> K{"Tool 内部"}
    J --> K
    K -->|"第二阶段 Resume"| L["读取审批结果"]
    L -->|"Approved"| M["执行实际操作"]
    L -->|"Rejected"| N["操作被拒绝"]

核心 API：

API	作用
`tool.GetInterruptState[T](ctx)`	判断当前是第一阶段还是 Resume 后的第二阶段
`tool.StatefulInterrupt(ctx, info, state)`	触发中断，`info` 展示给用户，`state` 供 Resume 后取回
`tool.GetResumeContext[T](ctx)`	获取用户的审批结果数据

[!note] 两阶段设计精妙之处

同一个 Tool 函数被调用两次，通过 GetInterruptState 区分：第一次返回 false（触发中断），第二次返回 true（Resume 恢复）。这种"自反式"设计无需引入额外的状态机或外部协调器，中断逻辑就内聚在 Tool 自身内部。

ApprovalMiddleware

生产实践中，推荐将中断逻辑放入 Middleware 而非每个 Tool 内部实现。这样审批规则集中管理、Tool 本身保持干净：

ApprovalMiddleware 拦截特定的 Tool 调用（如 execute），对每次调用统一施加审批逻辑：

type approvalMiddleware struct {
    *adk.BaseChatModelAgentMiddleware
}

func (m *approvalMiddleware) WrapInvokableToolCall(
    _ context.Context,
    endpoint adk.InvokableToolCallEndpoint,
    tCtx *adk.ToolContext,
) (adk.InvokableToolCallEndpoint, error) {
    // 仅拦截需审批的 Tool（例如 execute）
    if tCtx.Name != "execute" {
        return endpoint, nil
    }

    return func(ctx context.Context, args string, opts ...tool.Option) (string, error) {
        wasInterrupted, _, storedArgs := tool.GetInterruptState[string](ctx)

        if !wasInterrupted {
            // 第一次调用 → 触发中断
            return "", tool.StatefulInterrupt(ctx, &commontool.ApprovalInfo{
                ToolName:        tCtx.Name,
                ArgumentsInJSON: args,
            }, args)
        }

        // Resume 阶段 → 检查用户是否批准
        isTarget, hasData, data := tool.GetResumeContext[*commontool.ApprovalResult](ctx)
        if isTarget && hasData {
            if data.Approved {
                return endpoint(ctx, storedArgs, opts...)  // 通过中间件继续原 Tool 的执行
            }
            reason := ""
            if data.DisapproveReason != nil {
                reason = fmt.Sprintf(": %s", *data.DisapproveReason)
            }
            return fmt.Sprintf("tool '%s' disapproved%s", tCtx.Name, reason), nil
        }

        // 非目标 Tool → 重新中断
        return "", tool.StatefulInterrupt(ctx, &commontool.ApprovalInfo{
            ToolName:        tCtx.Name,
            ArgumentsInJSON: storedArgs,
        }, storedArgs)
    }, nil
}

[!warning] Streamable 变体不可遗漏

如果 Agent 启用了流式输出（EnableStreaming: true），某些 Tool 调用可能走 StreamableToolCall 路径。此时必须同时实现 WrapStreamableToolCall，否则审批逻辑会被绕过。ch07 完整代码中两者都已覆盖。

CheckPointStore

中断恢复还需要一个持久化组件来保存执行状态——这就是 CheckPointStore：

type CheckPointStore interface {
    Put(ctx context.Context, key string, checkpoint *Checkpoint) error
    Get(ctx context.Context, key string) (*Checkpoint, error)
}

它的作用不止于存储 Tool 参数，还包括 Runner 当前的执行进度。有了它，即使进程重启也能从中断点继续：

[!example] CheckPointStore 的两种典型实现

实现方式适用场景跨进程恢复

adkstore.NewInMemoryStore() 开发调试、单进程 ❌

Redis / SQLite 等外部存储生产部署 ✅

实现方式	适用场景	跨进程恢复
`adkstore.NewInMemoryStore()`	开发调试、单进程	❌
Redis / SQLite 等外部存储	生产部署	✅

代码实现

1. 配置 Runner 使用 CheckPointStore

runner := adk.NewRunner(ctx, adk.RunnerConfig{
    Agent:           agent,
    EnableStreaming: true,
    CheckPointStore: adkstore.NewInMemoryStore(),  // 内存存储
})

2. 配置 Agent 注册中间件

agent, err := deep.New(ctx, &deep.Config{
    // ... 其他配置
    Handlers: []adk.ChatModelAgentMiddleware{
        &approvalMiddleware{},       // 审批中间件
        &safeToolMiddleware{},       // 将 Tool 错误转为字符串（中断类错误继续向上抛出）
    },
})

3. 处理 Runner 返回的事件

checkPointID := sessionID

events := runner.Run(ctx, history, adk.WithCheckPointID(checkPointID))
content, interruptInfo, err := printAndCollectAssistantFromEvents(events)

if interruptInfo != nil {
    // 使用同一个 stdin reader 读取「用户输入」与「审批 y/n」
    // 避免审批输入被误认为下一轮对话消息
    content, err = handleInterrupt(ctx, runner, checkPointID, interruptInfo, reader)
    if err != nil {
        return err
    }
}

4. 完整的审批交互流程

flowchart TD
    U["用户：执行命令 echo hello"] --> S1["你> 请执行命令 echo hello"]
    S1 --> AGT["Runner.Run() 启动执行"]
    AGT --> A["Agent 分析意图\n决定调用 execute 工具"]
    A --> AM["ApprovalMiddleware\n拦截 Tool 调用"]
    AM --> SI["触发 StatefulInterrupt\n保存参数到 Store"]
    SI --> EVT["返回 Interrupt 事件"]
    EVT --> UI["控制台显示审批提示"]
    UI --> USER{"用户选择"}
    USER -->|"y"| RESUME["runner.ResumeWith\n携带审批结果 Approved=true"]
    USER -->|"n"| REJECT_DIRECT["runner.ResumeWith\n携带审批结果 Approved=false"]
    RESUME --> RTOOL["Tool 再次被调用\nGetInterruptState = true\n读取审批结果并批准"]
    RTOOL --> EXEC["执行 execute\necho hello"]
    EXEC --> OUT["输出: hello"]
    REJECT_DIRECT --> RTOOL2["Tool 再次被调用\nGetInterruptState = true\n读取审批结果并拒绝"]
    RTOOL2 --> NOP["输出: tool  disapproved"]

运行

在 examples/quickstart/chatwitheino 目录下执行：

export PROJECT_ROOT=/path/to/eino  # Eino 核心库根目录（不设置则默认使用当前目录）
go run ./cmd/ch07

输出示例：

you> 请执行命令 echo hello

⚠️  Approval Required ⚠️
Tool: execute
Arguments: {"command":"echo hello"}

Approve this action? (y/n): y
[tool result] hello

hello

[!question] 深入思考

上面的输出中有两条 hello——一条来自 [tool result]，另一条是 Assistant 的最终回复。你能解释它们分别来自哪里吗？
提示：第一条是 printAndCollectAssistantFromEvents 对流式事件中 Tool Result 片段的打印，第二条是 Agent 整合信息后生成的自然语言回复。理解了这一点，你就掌握了 Eino 事件模型的核心。

本章小结

概念	一句话理解
Interrupt	Agent 在敏感操作前的暂停机制
Resume	用户审批后恢复执行，支持批准与拒绝两种结果
Two-stage Execution	同一个 Tool 被调用两次，通过 `GetInterruptState` 区分阶段
ApprovalMiddleware	集中式拦截特定 Tool 的审批逻辑，使 Tool 保持干净
CheckPointStore	保存中断状态和执行位置，支持跨进程恢复
人机协作	关键决策由人类确认，兼顾 Agent 自动化与安全可控

扩展思考

场景	说明
多选项审批	用户从多个选项中选择一个（而非简单的 y/n）
参数补全	用户提供缺失的参数值后才继续执行
条件分支	用户决定不同的执行路径

审批策略

策略	适用场景
白名单	只审批极少数敏感操作（推荐默认做法）
黑名单	审批所有操作，除已知的安全操作外
动态规则	根据参数内容决定是否审批（如文件大小、操作范围）

关联笔记

Eino/quick_start/_index
Eino/quick_start/chapter_04_tool_and_filesystem — 文件系统访问与 DeepAgent（第三章的工具章节）
Eino/quick_start/chapter_05_middleware — Middleware 模式详解（上一章）

9.9 KiB Raw Permalink Blame History Unescape Escape