# AI 代理：实时步骤、人工审批与通知

> 代理每完成一个步骤就实时显示；有风险的工具调用先放进实时收件箱，等人审批后才执行；结果从代理、MCP 客户端与无代码流程送到浏览器和手机。

Source: https://hibira.io/zh-cn/use-cases/ai-agents

AI 代理在后台跑了一分钟，屏幕上却什么都没有，看起来就像卡住了；没问一声就把订单退款，更糟。Hibira 让你的代理使用和 App 其他部分相同的实时频道：每完成一个步骤就显示出来，有风险的工具调用先在实时收件箱里等人审批，结果则送到该看到的人的浏览器或手机上。

## 用户得到什么

- 代理每完成一个步骤（“查到订单了”“回复草稿写好了”），每个打开的标签页都立刻显示。
- 审批请求一发出就出现在收件箱，也看得到还有哪些审核者在看，两个人不会重复处理同一笔退款。
- 代理完成或需要人做决定、却没有人打开页面时，会收到推送通知。

![左边是代理的执行过程，右边是审批收件箱：每一步完成就出现，退款等审批人决定，点击批准后代理继续做完。](https://hibira.io/portal/articles/demo-ai-agents-zh-CN.mp4)

## 用到的功能

- 每次运行一个**私有频道**，例如 `private-agent-run-42`，用来发送步骤与结果。
- **[@hibira-io/approvals](https://github.com/hibira-io/approvals)** 提供审批收件箱：支持 Vercel AI SDK、Mastra 与 LangGraph（JavaScript 与 Python）的服务端辅助函数，以及 React 与 Vue 组件。
- **Presence 频道**，让审核者看到还有谁打开了同一个请求。
- **[MCP 服务器](https://hibira.io/zh-cn/mcp-server)**的 `publish_event`、`send_push` 与 `request_approval` 工具，供在 Claude、Cursor 或其他 MCP 客户端里运行的代理使用。
- 通过兼容 Beams 的 API 发送**推送通知**。

```text
flow: 代理的步骤实时送到用户面前，有风险的工具调用先等人审批
== 步骤与结果
你的代理|每个步骤一个事件 --`trigger()`--> *Hibira --WebSocket--> 用户的页面|实时步骤列表
== 需要审批的工具调用
你的代理|暂停运行 --`approvals.request()`--> *Hibira --WebSocket--> 审核者的收件箱|批准、修改或拒绝
```

## 步骤 1：从代理发布每个步骤

在 Vercel AI SDK 里，每个步骤结束后都会执行 `onStepFinish`。只发送工具名称、不发送输入内容，事件就能保持精简，敏感数据也不会经过 WebSocket：

```js
import { generateText, stepCountIs } from 'ai';

const channel = `private-agent-run-${run.id}`;
const result = await generateText({
  model,
  tools,
  messages,
  stopWhen: stepCountIs(10),
  onStepFinish: async ({ toolCalls }) => {
    if (toolCalls.length) {
      await pusher.trigger(channel, 'step', { tools: toolCalls.map((c) => c.toolName) });
    }
  },
});
await saveRun(run.id, result.text);
await pusher.trigger(channel, 'done', { id: run.id });
```

在浏览器里，先订阅再开始运行，并为每个工具显示一个标签。你的频道授权路由应该只让启动第 42 次运行的用户订阅 `private-agent-run-42`：

```js
const channel = pusher.subscribe(`private-agent-run-${runId}`);
channel.bind('step', ({ tools }) => tools.forEach((t) => steps.add(LABELS[t] ?? t)));
channel.bind('done', async ({ id }) => showResult(await fetch(`/runs/${id}`).then((r) => r.json())));
```

其他代理框架也一样：在步骤结束的地方调用 `trigger()` 即可。

## 步骤 2：有风险的工具执行前先问人

用 `needsApproval` 标记工具。运行停在这个工具时，创建一个请求：审核者会立刻在 `private-hibira-approvals.support.inbox` 收到 `approval` 事件。

```js
import { tool } from 'ai';
import { createApprovals } from '@hibira-io/approvals';
import { approvalCalls } from '@hibira-io/approvals/ai-sdk';

export const approvals = createApprovals({ pusher, scope: 'support', resume });

const tools = {
  refund_order: tool({ inputSchema, needsApproval: true, execute: refund }),
};

const calls = approvalCalls(result);
if (calls.length) {
  await approvals.request({ agent: 'Support agent', title: 'Refund order #1042', calls, metadata: { chatId } });
}
```

审核者在收件箱组件里做决定。组件通过 `approvals.handler()` 的路由调用你的后端，从不使用客户端事件；你的 `resume(request)` 会把答案交回代理，而且只执行一次，即使两位审核者同时按下发送也一样：

```jsx
import { ApprovalInbox, createApprovalsClient } from '@hibira-io/approvals/react';
import '@hibira-io/approvals/styles.css';

const client = createApprovalsClient({ endpoint: '/api/approvals', pusher, scope: 'support' });

export function ApprovalsPage({ me }) {
  return <ApprovalInbox client={client} me={me.id} />;
}
```

同一个软件包也有 Mastra（`requireApproval` 与 `suspend()`）和 LangGraph（`interrupt()`）的辅助函数。Python 方面，`pip install "hibira-approvals[pusher,fastapi]"` 让 LangGraph Python 创建同样的请求，并提供收件箱用的 FastAPI 路由。用 Laravel 开发吗？[Filament AI 审批](https://hibira.io/zh-cn/guides/filament-approvals)会把收件箱放进你的 Filament 面板，供用 Laravel AI SDK 构建的代理使用。

## 步骤 3：在 Claude、Cursor 等 MCP 客户端里的代理

在 MCP 客户端里运行的代理，不需要你写任何代码就能使用 Hibira。添加 [MCP 服务器](https://hibira.io/zh-cn/mcp-server)后，代理可以：

- 用 `publish_event` 把进度与结果发送到你的频道，让仪表板或同事的浏览器跟着看到工作进展，
- 完成时用 `send_push` 按 interest 或用户发送推送通知，
- 用 `request_approval` 问人：它会返回一个托管页面的链接，让对方选择答案，再用 `get_approval` 等待结果。指定频道的话，请求也会出现在上面的收件箱里。

```sh
claude mcp add --transport http hibira https://hibira.io/mcp
```

## 步骤 4：无代码流程

自动化工具也能发送同样的事件。流程可以把步骤或结果发布到频道、发送推送通知，或在频道上发生事情时启动：

- [n8n](https://hibira.io/zh-cn/guides/n8n)，其 Hibira 节点也能作为 n8n AI 代理的工具
- [Make](https://hibira.io/zh-cn/guides/make)
- [Node-RED](https://hibira.io/zh-cn/guides/node-red)
- [Activepieces](https://hibira.io/zh-cn/guides/activepieces)

## 小提醒

- 事件保持精简：只发送 ID 与简短标签，完整结果从你的服务器加载。大小上限按套餐而定，请看[价格](https://hibira.io/zh-cn/pricing)。
- 每个步骤与请求也存进数据库，之后才打开的页面也能看到整个运行过程。
- 代理要一个字一个字写出回答的话，请看[长时间任务的进度与 AI 回答流式输出](https://hibira.io/zh-cn/use-cases/job-progress)。
- 审批请求不会把工具的输入内容发上 WebSocket。收件箱会向你的后端加载内容，由后端确认这位用户可以审核。
- 没有审核者在线时，用 `createApprovals()` 的 `notify` 选项，照[推送通知指南](https://hibira.io/zh-cn/guides/push-notifications)发推送给审核者。