> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tool-approval.md).

# 工具审批

在工具调用执行前审核、批准或拒绝所选调用。

{% hint style="warning" %}

#### 编码代理技能

使用 **`/neuron-tool-approval`** 教你的编码代理如何在应用中实现完整的工具审批流程。

[AI 辅助开发](https://docs.neuron-ai.dev/neuron-v3-zh/gai-lan/agentic-development.md)
{% endhint %}

Neuron 为你提供对“人在回路”模式的全面支持，包括工具审批。框架会拦截工具调用并暂停，等待用户的最终决定。要启用工具审批，你需要为你的 Agent 配备两个组件：

* 一个持久化的 [MessageStore](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/chat-history-and-memory.md#message-store)
* 该 [持久化](https://docs.neuron-ai.dev/neuron-v3-zh/gong-zuo-liu/persistence.md) 组件

```php
use NeuronAI\Agent\Middleware\ToolApproval;
use NeuronAI\Chat\History\FileChatHistory;
use NeuronAI\Workflow\Persistence\FilePersistence;

class MyAgent extends Agent
{
    ...
    
    /**
     * 注册工具
     */
    protected function tools(): array
    {
        return [
            BuyTicketTool::make(),
        ];
    }
    
    /**
     * 持久化聊天历史
     */
    protected function chatHisotry(): ChatHistoryInterface
    {
        return new FileChatHistory(
            directory: '/path-to-filesystem',
            key: 'conversation ID',
        );
    }
    
    /**
     * 工作流持久化
     */
    protected function persistence(): PersistenceInterface
    {
        return new FilePersistence(
            directory: '/path-to-filesystem'
        );
    }
}
```

框架会自动管理整个审批流程。你只需要负责用户界面。但在深入了解这个流程之前，我们先看看如何为你的工具定义审批策略。

只需覆盖 `approvalPolicy()` Tool 类中的方法，以决定该工具是否应进入审批流程。该方法会接收模型想要用于调用该工具的输入。返回字符串将被视为 true，并同时作为审批请求原因。

```php
class BuyTicketTool extends Tool
{
    ...,
    
    protected function approvalPolicy(): bool|string
    {
        // 当金额大于 100 时，该工具需要审批
        return $this->getInput('amount') > 100;
    }
}
```

当你把工具附加到 Agent 时，也可以覆盖默认策略：

```php
class MyAgent extends Agent
{
    ...,
    
    protected function tools(array $inputs): array
    {
        return [
            BuyTicketTool::make()->requireApproval(true|false),
            
            /*
             * 当回调运行时，它接收到的工具实例 
             * 不是原始注册表中的工具，而是一个已带上本次调用输入的克隆 
             * 并且已经绑定好了。
             */
            BuyTicketTool::make()->withApprovalPolicy(
                fn(ToolInterface $tool): bool|string => $tool->getInput('amount') > 100
            )
        ];
    }
}
```

### 管理审批流程

**聊天历史是工具审批的权威记录。** 你的 UI 所需的一切：哪些工具正在等待决策， *原因* 每个工具在询问什么，以及已经决定了什么，都保存在 **线程的最后一条消息中**.

在审批待处理期间，框架会保证最后 `ToolCallMessage` 是线程的尾部。因此，你的 UI 渲染逻辑只会查看这条最后消息。

#### 在 UI 中检测审批

当你加载一个线程时，检查最后一条消息：

1. `类型` 都是 `"tool_call"`
2. 在 `tools[]` 中至少有一个条目 `具有 "approval": "pending"`

如果两者都满足，会话就会被挂起：渲染审批界面并 **锁定输入框**，在所有决策完成之前，不能再发送新的用户消息。

```javascript
const last = thread.messages.at(-1);
const pendingTools = last?.type === 'tool_call'
    ? last.tools.filter(t => t.approval === 'pending')
    : [];
const isSuspended = pendingTools.length > 0;
```

#### 你将要处理的 JSON

这是一个真实序列化的 `ToolCallMessage` 等待审批：两个受控工具，一个仍在待处理，另一个已在早先的部分提交中被拒绝：

```json
{
    "__id": "msg_7488585683808067584",
    "resume_token": "workflow_6650a1b2c3d4e",
    "role": "assistant",
    "content": [],
    "type": "tool_call",
    "tools": [
        {
            "callId": "toolu_01A2B3C4D5E6F7",
            "name": "delete_file",
            "description": "从文件系统中删除一个文件",
            "parameters": [],
            "inputs": { "path": "C:/old_logs.txt" },
            "result": null,
            "approval": "pending",
            "approvalReason": "删除文件是不可逆的",
            "rejectReason": null
        },
        {
            "callId": "toolu_08G9H0I1J2K3L4",
            "name": "send_email",
            "description": "向收件人发送电子邮件",
            "parameters": [],
            "inputs": { "to": "team@example.com", "subject": "Logs cleanup" },
            "result": null,
            "approval": "rejected",
            "approvalReason": "外发邮件会发送给此工作区之外的人",
            "rejectReason": "不要给整个团队发邮件"
        }
    ]
}
```

`approvalReason` 是 *工具向人类说明* （“我为什么要问”）， `rejectReason` 是 *人类向模型回应* （“我为什么说不”）。

#### 渲染指南

* 为以下内容中的每个条目渲染一张卡片： `tools[]` 该 **中至少有一个条目** 一个 `审批` 字段：工具名称、其 `输入`，以及 `approvalReason` 如果存在的话，还有批准/拒绝操作。拒绝应提供一个可选的纯文本理由——模型会原样接收，因此好的理由会产生更好的模型响应。
* 工具 `"approved"`/`"rejected"` 会显示为已决策——但仍然 **在全部决策完成前可修改** （后写覆盖前写）。一旦最后一个决策落定，工作流会立即继续，状态也会变为历史记录。
* 审批是纯粹的——没有“带评论批准”这种说法。

### 整个会话只需一个端点

从端点的角度看，正常轮次和审批恢复是同一个操作：根据线程构建代理，传入客户端发送的内容，并返回线程的新状态。框架会处理其余部分——配合 `载荷`恢复令牌时，会从聊天历史尾部获取；配合消息时，则会开启一个新的轮次。

你的端点只需要 `threadId`:

```php
class ChatController
{
    public function chat(ChatRequest $request, string $threadId)
    {
        $agent = MyAgent::make($threadId);
    
        $state = $request->has('decisions')
            ? $agent->submitApprovalDecisions($request->get('decisions'))->run()
            : $agent->chat(new UserMessage($request->get('message')));
        
        return [
            'status'  => $state->isInterrupted() ? 'awaiting_approval' : 'completed',
            'message' => $state->getMessage()?->jsonSerialize(),
        ];
    }
}
```

### 提交决策

线程已挂起，并有待处理的工具。以下是你需要发送的请求体，用于解决等待中的审批：

```
POST /threads/thread_42/chat
    { "decisions": { "toolu_01A2B3C4D5E6F7": "approve" } }
```

决策以一个普通映射的形式传递，并以工具的 `callId`为键。每个值都且仅有以下三种形式之一：

| 你发送                        | 含义         | 模型看到的内容                                  |
| -------------------------- | ---------- | ---------------------------------------- |
| "approve"                  | 运行工具       | 工具的真实输出，仅此而已。审批是纯粹的——没有“带评论批准”这种说法。      |
| "reject"                   | 跳过工具       | 带有 *"No specific instruction provided."* |
| \["reject", "your reason"] | 跳过工具，并附带反馈 | 拒绝模板会原样包含你的理由。                           |
