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

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

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

用户得到什么

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

左边是代理的执行过程，右边是审批收件箱：每一步完成就出现，退款等审批人决定，点击批准后代理继续做完。

用到的功能

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

步骤与结果

你的代理每个步骤一个事件

trigger()

Hibira

WebSocket

用户的页面实时步骤列表

需要审批的工具调用

你的代理暂停运行

approvals.request()

Hibira

WebSocket

审核者的收件箱批准、修改或拒绝

代理的步骤实时送到用户面前，有风险的工具调用先等人审批

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

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

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：

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 事件。

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) 会把答案交回代理，而且只执行一次，即使两位审核者同时按下发送也一样：

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 审批会把收件箱放进你的 Filament 面板，供用 Laravel AI SDK 构建的代理使用。

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

在 MCP 客户端里运行的代理，不需要你写任何代码就能使用 Hibira。添加 MCP 服务器后，代理可以：

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

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

步骤 4：无代码流程

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

n8n，其 Hibira 节点也能作为 n8n AI 代理的工具
Make
Node-RED
Activepieces

小提醒

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