---
title: "第七章：Interrupt/Resume（中断与恢复）"
---

本章目标：理解 Interrupt/Resume 机制，实现 Tool 审批流程，让用户在敏感操作前进行确认。

## 代码位置

- 入口代码：[cmd/ch07/main.go](https://github.com/cloudwego/eino/blob/main/examples/quickstart/chatwitheino/cmd/ch07/main.go)

## 前置条件

与第一章一致：需要配置一个可用的 ChatModel（OpenAI 或 Ark）。

## 运行

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

```bash
# 设置项目根目录
export PROJECT_ROOT=/path/to/your/project

go run ./cmd/ch07
```

输出示例：

```text
you> 请执行命令 echo hello

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

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

hello
```

## 从自动执行到人工审批：为什么需要 Interrupt

前几章我们实现的 Agent 会自动执行所有 Tool 调用，但在某些场景下这是危险的：

**自动执行的风险：**
- 删除文件：误删重要数据
- 发送邮件：发送错误内容
- 执行命令：执行危险操作
- 修改配置：破坏系统设置

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

**简单类比：**
- **自动执行** = "自动驾驶"（完全信任系统）
- **Interrupt** = "人工接管"（关键决策由人来做）

## 关键概念

### Interrupt 机制

`Interrupt` 是 Eino 中实现人机协作的核心机制：

```go
// 在 Tool 中触发中断
func myTool(ctx context.Context, args string) (string, error) {
    // 检查是否已经中断过
    wasInterrupted, _, storedArgs := tool.GetInterruptState[string](ctx)
    
    if !wasInterrupted {
        // 第一次调用：触发中断，等待审批
        return "", tool.StatefulInterrupt(ctx, &ApprovalInfo{
            ToolName: "my_tool",
            ArgumentsInJSON: args,
        }, args)
    }
    
    // 恢复后：检查审批结果
    isTarget, hasData, data := tool.GetResumeContext[*ApprovalResult](ctx)
    if isTarget && hasData {
        if data.Approved {
            // 用户批准：执行操作
            return doSomething(storedArgs)
        } else {
            // 用户拒绝：返回拒绝原因
            return "Operation rejected by user", nil
        }
    }
    
    // 其他情况：重新中断
    return "", tool.StatefulInterrupt(ctx, &ApprovalInfo{
        ToolName: "my_tool",
        ArgumentsInJSON: storedArgs,
    }, storedArgs)
}
```

### ApprovalMiddleware

`ApprovalMiddleware` 是一个通用的审批中间件，可以拦截特定 Tool 的调用：

```go
type approvalMiddleware struct {
    *adk.BaseChatModelAgentMiddleware
}

func (m *approvalMiddleware) WrapInvokableToolCall(
    _ context.Context,
    endpoint adk.InvokableToolCallEndpoint,
    tCtx *adk.ToolContext,
) (adk.InvokableToolCallEndpoint, error) {
    // 只拦截需要审批的 Tool
    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)
        }
        
        isTarget, hasData, data := tool.GetResumeContext[*commontool.ApprovalResult](ctx)
        if isTarget && hasData {
            if data.Approved {
                return endpoint(ctx, storedArgs, opts...)
            }
            if data.DisapproveReason != nil {
                return fmt.Sprintf("tool '%s' disapproved: %s", tCtx.Name, *data.DisapproveReason), nil
            }
            return fmt.Sprintf("tool '%s' disapproved", tCtx.Name), nil
        }
        
        // 重新中断
        return "", tool.StatefulInterrupt(ctx, &commontool.ApprovalInfo{
            ToolName:        tCtx.Name,
            ArgumentsInJSON: storedArgs,
        }, storedArgs)
    }, nil
}

func (m *approvalMiddleware) WrapStreamableToolCall(
    _ context.Context,
    endpoint adk.StreamableToolCallEndpoint,
    tCtx *adk.ToolContext,
) (adk.StreamableToolCallEndpoint, error) {
    // 如果 agent 配置了 StreamingShell，则 execute 会走流式调用，需要实现该方法才能拦截到
    if tCtx.Name != "execute" {
        return endpoint, nil
    }
    return func(ctx context.Context, args string, opts ...tool.Option) (*schema.StreamReader[string], error) {
        wasInterrupted, _, storedArgs := tool.GetInterruptState[string](ctx)
        if !wasInterrupted {
            return nil, tool.StatefulInterrupt(ctx, &commontool.ApprovalInfo{
                ToolName:        tCtx.Name,
                ArgumentsInJSON: args,
            }, args)
        }

        isTarget, hasData, data := tool.GetResumeContext[*commontool.ApprovalResult](ctx)
        if isTarget && hasData {
            if data.Approved {
                return endpoint(ctx, storedArgs, opts...)
            }
            if data.DisapproveReason != nil {
                return singleChunkReader(fmt.Sprintf("tool '%s' disapproved: %s", tCtx.Name, *data.DisapproveReason)), nil
            }
            return singleChunkReader(fmt.Sprintf("tool '%s' disapproved", tCtx.Name)), nil
        }

        isTarget, _, _ = tool.GetResumeContext[any](ctx)
        if !isTarget {
            return nil, tool.StatefulInterrupt(ctx, &commontool.ApprovalInfo{
                ToolName:        tCtx.Name,
                ArgumentsInJSON: storedArgs,
            }, storedArgs)
        }

        return endpoint(ctx, storedArgs, opts...)
    }, nil
}
```

### CheckPointStore

`CheckPointStore` 是实现中断恢复的关键组件：

```go
type CheckPointStore interface {
    // 保存检查点
    Put(ctx context.Context, key string, checkpoint *Checkpoint) error
    
    // 获取检查点
    Get(ctx context.Context, key string) (*Checkpoint, error)
}
```

**为什么需要 CheckPointStore？**
- 中断时保存状态：Tool 参数、执行位置等
- 恢复时加载状态：从中断点继续执行
- 支持跨进程恢复：进程重启后仍可恢复

## Interrupt/Resume 的实现

### 1. 配置 Runner 使用 CheckPointStore

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

### 2. 配置 Agent 使用 ApprovalMiddleware

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

### 3. 处理中断事件

```go
checkPointID := sessionID

events := runner.Run(ctx, history, adk.WithCheckPointID(checkPointID))
content, interruptInfo, err := printAndCollectAssistantFromEvents(events)
if err != nil {
    return err
}

if interruptInfo != nil {
    // 注意：建议使用同一个 stdin reader 同时读取「用户输入」与「审批 y/n」
    // 避免审批输入被当成下一轮 you> 的消息
    content, err = handleInterrupt(ctx, runner, checkPointID, interruptInfo, reader)
    if err != nil {
        return err
    }
}

_ = session.Append(schema.AssistantMessage(content, nil))
```

## Interrupt/Resume 执行流程

```
┌─────────────────────────────────────────┐
│  用户：执行命令 echo hello               │
└─────────────────────────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  Agent 分析意图       │
        │  决定调用 execute     │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  ApprovalMiddleware  │
        │  拦截 Tool 调用       │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  触发 Interrupt       │
        │  保存状态到 Store     │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  返回 Interrupt 事件  │
        │  等待用户审批         │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  用户输入 y/n         │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  runner.ResumeWith... │
        │  恢复执行             │
        └──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │  执行 execute         │
        │  或返回拒绝信息       │
        └──────────────────────┘
```

## 本章小结

- **Interrupt**：Agent 的暂停机制，在关键操作前暂停等待确认
- **Resume**：恢复执行，用户确认后继续或拒绝后返回错误
- **ApprovalMiddleware**：通用审批中间件，拦截特定 Tool 调用
- **CheckPointStore**：保存中断状态，支持跨进程恢复
- **人机协作**：关键决策由人来确认，提高安全性

## 扩展思考

**其他 Interrupt 场景：**
- 多选项审批：用户选择多个选项之一
- 参数补全：用户提供缺失的参数
- 条件分支：用户决定执行路径

**审批策略：**
- 白名单：只审批敏感操作
- 黑名单：审批所有操作，除了安全的
- 动态规则：根据参数内容决定是否审批