> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 人机协同

> Zeus Human-in-the-Loop — Auto-Run 模式与工具审批机制

## 概述

HITL（Human in the Loop）机制确保 AI Agent 在执行敏感操作时获得人类确认。Zeus 通过 Auto-Run 模式和工具审批流程，让用户灵活控制 Agent 的自动化程度。

***

## Auto-Run Mode

Auto-Run 模式控制 AI Agent 执行工具的自动化程度。

### 三种模式

| 模式             | 描述         | 适用场景      |
| -------------- | ---------- | --------- |
| Run Everything | 自动执行所有工具   | 信任度高、简单任务 |
| Use Allowlist  | 仅自动执行白名单工具 | 部分信任      |
| Ask Everytime  | 每次都询问用户    | 敏感操作      |

### Tool Approval UI

当工具需要审批时，前端显示审批卡片，包含工具名称、参数、当前状态（pending / approved / rejected / running / completed），以及批准和拒绝按钮。

### 审批决策逻辑

审批决策基于当前 Auto-Run 模式：

* **Run Everything**：所有工具自动执行，无需审批
* **Use Allowlist**：仅白名单中的工具自动执行，其他工具需要审批
* **Ask Everytime**：所有工具都需要用户审批

### 数据持久化

用户的 Auto-Run 模式设置和工具白名单通过数据库持久化，每个用户拥有独立的配置。白名单按用户和工具名唯一约束，确保不重复。

***

## 触发条件

HITL 审批在以下条件下触发：

1. 工具不在白名单中
2. Auto-Run 模式为 "Ask Everytime"
3. 工具标记为需要确认

***

## 交互流程

```mermaid theme={null}
flowchart TD
    A["Agent 决定调用工具"] --> B["检查是否需要审批"]
    B --> C{"需要审批?"}
    C -->|"不需要"| D["直接执行"]
    C -->|"需要"| E["显示审批 UI"]
    E --> F["用户决定"]
    F --> G{"审批结果"}
    G -->|"批准"| H["执行工具"]
    G -->|"拒绝"| I["返回拒绝"]
```

***

## 中断与恢复

当工具需要审批时，Agent 的执行会被中断，状态通过 Checkpointer 持久化保存。用户审批后，Agent 从断点恢复继续执行。

用户审批决策类型：

| 决策         | 行为                     |
| ---------- | ---------------------- |
| `approved` | 执行工具（可带修改后的参数）         |
| `rejected` | 跳过执行，Agent 收到拒绝原因，不会重试 |
| `modified` | 用修改后的参数执行（旧版兼容）        |
| `timeout`  | 超时自动跳过                 |

被拒绝的工具会附加系统消息，明确告知 Agent 不要重试该工具。

更多关于中断恢复的技术细节，请参阅 [Agent Loop](/ai-backend/fundamentals/agent-loop) 和 [Runtime](/ai-backend/fundamentals/agent-runtime) 文档。