# AI 에이전트: 실시간 진행 단계, 승인, 알림

> 에이전트가 일하는 단계를 실시간으로 보여 주고, 위험한 도구 호출은 사람이 승인할 때까지 실시간 수신함에서 기다리게 하며, 에이전트와 MCP 클라이언트, 노코드 플로에서 결과를 브라우저와 휴대폰으로 보냅니다.

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

AI 에이전트가 1분 동안 백그라운드에서 일하는데 화면에 아무것도 없으면 멈춘 것처럼 보입니다. 묻지도 않고 주문을 환불해 버리면 더 곤란합니다. Hibira를 쓰면 에이전트도 앱의 다른 부분과 같은 실시간 채널을 씁니다. 각 단계는 끝나는 대로 표시되고, 위험한 도구 호출은 사람이 승인할 때까지 실시간 수신함에서 기다리며, 결과는 받아야 할 사람의 브라우저나 휴대폰에 도착합니다.

## 사용자가 얻는 것

- 에이전트 작업의 각 단계("주문을 조회했습니다", "답장 초안을 작성했습니다")가 끝나는 대로 열려 있는 모든 탭에 표시됩니다.
- 승인 요청이 수신함에 바로 나타나고, 다른 검토자 중 누가 보고 있는지도 보이므로 두 사람이 같은 환불을 결정하지 않습니다.
- 에이전트가 끝났거나 결정이 필요한데 아무도 페이지를 열어 두지 않았다면 푸시 알림이 갑니다.

![왼쪽은 에이전트 실행, 오른쪽은 승인 받은편지함: 단계가 끝나는 대로 나타나고, 환불은 검토자를 기다리며, 승인하면 에이전트가 끝까지 이어갑니다.](https://hibira.io/portal/articles/demo-ai-agents-ko.mp4)

## 사용하는 기능

- 실행마다 하나의 **비공개 채널**(예: `private-agent-run-42`)로 단계와 결과를 보냅니다.
- 승인 수신함은 **[@hibira-io/approvals](https://github.com/hibira-io/approvals)**: Vercel AI SDK, Mastra, LangGraph(JavaScript와 Python)용 서버 헬퍼와 React, Vue 컴포넌트가 있습니다.
- **프레즌스 채널**로 같은 요청을 누가 또 열어 두었는지 검토자에게 보여 줍니다.
- Claude, Cursor 같은 MCP 클라이언트에서 실행되는 에이전트를 위한 **[MCP 서버](https://hibira.io/ko/mcp-server)** 도구 `publish_event`, `send_push`, `request_approval`.
- Beams 호환 API를 통한 **푸시 알림**.

```text
flow: 에이전트의 단계가 사용자에게 도착하고, 위험한 도구 호출은 사람을 기다린다
== 단계와 결과
에이전트|단계마다 이벤트 1개 --`trigger()`--> *Hibira --WebSocket--> 사용자의 페이지|실시간 단계 목록
== 승인이 필요한 도구 호출
에이전트|실행을 멈춤 --`approvals.request()`--> *Hibira --WebSocket--> 검토자의 수신함|승인, 수정 또는 거절
```

## 1단계: 에이전트에서 각 단계 발행

Vercel AI SDK에서는 `onStepFinish`가 단계마다 실행됩니다. 도구의 입력이 아니라 이름만 보내면 이벤트가 작게 유지되고 민감한 데이터가 소켓을 지나지 않습니다.

```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 });
```

브라우저에서는 실행을 시작하기 전에 구독하고, 도구마다 레이블을 보여 주세요. 채널 인가 라우트는 `private-agent-run-42`를 실행 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/ko/guides/filament-approvals)이 Laravel AI SDK 에이전트를 위한 수신함을 Filament 패널에 넣어 줍니다.

## 3단계: Claude, Cursor 등 MCP 클라이언트의 에이전트

MCP 클라이언트에서 실행되는 에이전트는 코드 없이 Hibira를 쓸 수 있습니다. [MCP 서버](https://hibira.io/ko/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/ko/guides/n8n): Hibira 노드는 n8n AI 에이전트의 도구로도 쓸 수 있습니다
- [Make](https://hibira.io/ko/guides/make)
- [Node-RED](https://hibira.io/ko/guides/node-red)
- [Activepieces](https://hibira.io/ko/guides/activepieces)

## 팁

- 이벤트는 작게 유지하세요. ID와 짧은 레이블을 보내고 전체 결과는 서버에서 가져옵니다. 크기 한도는 요금제에 따라 다르니 [요금](https://hibira.io/ko/pricing)을 보세요.
- 단계와 요청을 데이터베이스에도 저장하면 나중에 연 페이지에서도 실행 전체를 보여 줄 수 있습니다.
- 에이전트가 답을 토큰 단위로 쓴다면 [오래 걸리는 작업의 진행률과 AI 답변 스트리밍](https://hibira.io/ko/use-cases/job-progress)을 보세요.
- 승인 요청은 도구 입력을 소켓에 싣지 않습니다. 수신함이 백엔드에서 가져오고, 백엔드는 그 사용자가 검토할 수 있는지 확인합니다.
- 온라인인 검토자가 없을 때는 `createApprovals()`의 `notify` 옵션으로 [푸시 알림 가이드](https://hibira.io/ko/guides/push-notifications)대로 검토자에게 푸시를 보내세요.