# @economic/agents-react 中文文档

规范地址：https://npmcn.com/package/%40economic/agents-react/

版本：2\.1\.0
npm 元数据更新时间：2026-11-09T12:44:03.412Z
中文译文更新时间：2026-11-13T06:02:26.464Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40economic/agents-react
原文对照：https://npmcn.com/package/%40economic/agents-react/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：42.3 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^19
- 首次发布：2026-04-12T22:13:40.476Z
- 最新版本发布：2026-11-09T12:44:03.089Z
- 近 30 天下载量：2668（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

连接到代理机的反应钩 [`@economic/agents`](https://npmcn.com/package/%40economic/agents/README.md)他们包了"云花" `agents` 财务报告和审定财务报表 `@cloudflare/ai-chat` 钩并添加打入的连接状态,消息反馈,以及 \`Assis' 使用的每个用户多聊天模式

## 安装

```sh
npm install @economic/agents-react
```

也可以使用：`pnpm add @economic/agents-react`、`yarn add @economic/agents-react`、`bun add @economic/agents-react`

## README

# @ 经济/代理反应

连接到代理机的反应钩 [`@economic/agents`](https://npmcn.com/package/%40economic/agents/README.md)他们包了"云花" `agents` 财务报告和审定财务报表 `@cloudflare/ai-chat` 钩并添加打入的连接状态、消息反馈和每个用户使用的多聊天模式 `Assistant`。 。 。 .

## 安装

```sh
npm install @economic/agents-react
```

反应19是一种对等依赖.

## 我用哪根钩子?

套件输出出三个钩子,相上分层:

-   **`useAgent`** —— 薄接原始两者都建立在上. 只有当您需要原始连接时, 才能联系它 .
-   **`useChat`** ——直接连接到a **单人** 聊天代理名. 使用它当您自己在一次对话中(例如每条路由一次聊天)而不是通过一个 `Assistant`。 。 。 .
-   **`useAssistant`** ——v2型的高水平钩子: **每个用户一个助手,很多聊天**。它管理聊天列表(创建/打开/删除),连接到正确的聊天面,并曝光活动聊天. 当您的服务器使用时使用此选项 `Assistant`。 。 。 .

* * *

## `useAgent`

连接原始 `useChat` 财务报告和审定财务报表 `useAssistant` 继续发展。 以名称连接代理并暴露其连接和 `call` 引用时 `@callable` 方法。 。 .

```tsx
import { useAgent } from "@economic/agents-react";

const agent = useAgent({
  host: "localhost:8787",
  agentName: "SupportAgent",
  name: "support",
  actorId: userId, // when set, the DO name becomes `${actorId}:${name}`
  authToken,
});

await agent.call("checkOrder", ["1234"]);
console.log(agent.state?.status);
```

* * *

## `useChat`

以名称连接到单个聊天代理 — no `Assistant` 需要帮助。 返回连接、 消息接口和消息反馈帮助器 .

```tsx
import { useChat } from "@economic/agents-react";

const { status, chat, submitMessageFeedback, getMessageFeedback } = useChat({
  host: "localhost:8787",
  agentName: "MyChatAgent",
  name: `${userId}:${chatId}`,
  authToken,
  toolContext: { locale: "en-DK" },
});

// send a message
chat.sendMessage({ role: "user", parts: [{ type: "text", text: "Hello" }] });

// rate a message (1 = up, -1 = down) and read all feedback
await submitMessageFeedback(messageId, 1, "Helpful!");
const feedback = await getMessageFeedback();
```

### 回返

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `AgentConnectionStatus` | 连接状态 . |
| `refusalReason` | `string | undefined` | 为什么服务器拒绝连接,如果它说. |
| `canChat` | `boolean` | `false` 当用户可以读取聊天但不能在里面聊天时. |
| `agent` | 连接对象 | 基础 `useAgent` 连接. |
| `chat` | `useAgentChat` 结果 | `messages`, (中文(简体) ), `sendMessage`, (中文(简体) ), `setMessages`, (中文(简体) ), `status`, (中文(简体) ), `stop`,, , , , , , , , |
| `submitMessageFeedback` | `(id, rating, comment?) => Promise<void>` | 为消息提交上下拇指反馈 . |
| `getMessageFeedback` | `() => Promise<Record<string, MessageFeedback>>` | 聊天的所有反馈, 由消息 ID 键入 . |

* * *

## `useAssistant`

对于每个用户,多聊天模式:连接到用户的 `Assistant` Do, 保持聊天列表同步, 并管理哪个聊天活动 .

```tsx
import { useAssistant } from "@economic/agents-react";

function Chat({ userId, authToken }: { userId: string; authToken: string }) {
  const { status, chats, currentChatName, assistant, chat } = useAssistant({
    host: "localhost:8787",
    agentName: "MyAssistant", // matches the Assistant DO binding/class name
    name: userId, // the Assistant is keyed by user
    authToken,
    toolContext: { locale: "en-DK" }, // forwarded to server tools as the request body
    welcomeMessage: "Hi! How can I help?",
  });

  return (
    <div>
      <button onClick={() => assistant.createChat()}>New chat</button>

      <ul>
        {chats.map((c) => (
          <li key={c.name}>
            <button onClick={() => assistant.openChat(c.name)}>{c.title ?? "Untitled"}</button>
            <button onClick={() => assistant.deleteChat(c.name)}>Delete</button>
          </li>
        ))}
      </ul>

      {chat.chat.messages.map((m) => (
        <Message key={m.id} message={m} />
      ))}

      <Composer
        onSend={(text) =>
          chat.chat.sendMessage({
            role: "user",
            parts: [{ type: "text", text }],
          })
        }
      />
    </div>
  );
}
```

### 回返

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `AgentConnectionStatus` | 助理的连接状态, 或一旦打开就主动聊天的连接状态 . |
| `chats` | `ChatSummary[]` | 开始聊天外加活性空草稿,最近一次是先更新. |
| `currentChatName` | `string | undefined` | 如果有的话 正在聊天的ID. |
| `assistant` | `AssistantActions` | `getChats`, (中文(简体) ), `createChat`, (中文(简体) ), `openChat`, (中文(简体) ), `deleteChat`, (中文(简体) ), `renameChat`。 。 。 . |
| `chat` | `useChat` 结果 | 活动聊天—— `chat.chat` 是消息界面(见下文). |

`assistant` 动作 :

| 行动 | 签署 | 说明 |
| --- | --- | --- |
| `createChat()` | `() => Promise<string>` | 创建聊天,使其活动,返回其ID. |
| `openChat(chatId)` | `(chatId: string) => void` | 切换活动聊天. |
| `getChats()` | `() => Promise<ChatSummary[]>` | 刷新并返回聊天列表 . |
| `deleteChat(chatId)` | `(chatId: string) => Promise<void>` | 删除聊天并清除活动选择. |
| `renameChat(chatId)` | `(chatId: string, title: string) => Promise<void>` | 重命名已注册的聊天. |

> 标题和摘要在第一个消息发出后几秒钟生成服务器侧面, 因此重排 `getChats()` 如果您想要出现新的标题, 请在发送开幕词后不久 .

活动空聊天在当地被代表,直到其第一次回合在服务器上注册为止.

在第一回合完成后, `useAssistant` 自动刷新聊天列表, 这样临时条目会被其顽固的标题和摘要所取代 .

* * *

## 选项

所有钩子都共享这些连接选项( A)`useAssistant` 省略 `actorId`:

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `host` | `string` | 工人主持人,例如:. `localhost:8787` 或者说 `my-agent.workers.dev`。 。 。 . |
| `agentName` | `string` | 代理的DO绑定/类名. |
| `name` | `string` | 写名字 对于 `useAssistant` 这是用户 id; 用于 `useChat`聊天钥匙. |
| `actorId` | `string?` | 如果设定, DO 名称变为 `${actorId}:${name}` (单位:千美元)`useAgent` 编号 : `useChat`) (中文(简体) ). |
| `authToken` | `string?` | 持有者代号; 以 `Authorization` 头和WebSocket分议定书. |
| `enabled` | `boolean?` | 关闭连接( 默认情况下启用) `name` 页:1. |
| `sub` | `{ agent; name }[]?` | 子代理路由(由 `useAssistant`) (中文(简体) ). |
| `toolContext` | `Record<string, unknown>?` | 转发到服务器工具作为请求正文( S)`useChat` 编号 : `useAssistant`) (中文(简体) ). |
| `welcomeMessage` | `string?` | 当聊天为空时种子初始助理消息 . |
| `onOpen` 编号 : `onClose` 编号 : `onError` | 事件处理器 | WebSocket生命周期召回. |

* * *

## 类型

```ts
type AgentConnectionStatus =
  | "connecting"
  | "reconnecting"
  | "connected"
  | "disconnected"
  | "unauthorized"
  | "error";
type AgentConnectionType = "agent" | "chat" | "assistant";

type AgentConnectionState = {
  status: AgentConnectionStatus;
  type: AgentConnectionType;
  subAgentName?: string;
};

type ChatSummary = {
  name: string;
  isTemporary?: boolean; // true for the active chat before its first turn is registered
  title?: string;
  summary?: string;
  created_at: number;
  updated_at: number;
};

type MessageFeedback = {
  message_id: string;
  rating: number; // 1 = up, -1 = down
  comment?: string;
  created_at: number;
  updated_at: number;
};
```

软件包还导出处理器类型 `AssistantActions`, (中文(简体) ), `GetChatsHandler`, (中文(简体) ), `CreateChatHandler`, (中文(简体) ), `OpenChatHandler`, (中文(简体) ), `DeleteChatHandler`, (中文(简体) ), `MessageFeedbackHandler`,以及 `GetMessageFeedbackHandler`。 。 。 .

* * *

## 认证

通过 JWT 作为 `authToken`。它是作为 `Authorization: Bearer …` 页眉和作为 WebSocket 子议定书(`["bearer", token]`),匹配服务器侧 [`getAuthenticator(env)`](https://npmcn.com/package/%40economic/agents/README.md#authentication)当验证失败时,连接状态变为 `"unauthorized"`。 。 。 .

当经纪人拒绝打电话时 `reason` (单位:千美元) `AuthenticationError` 与 `{ reason }` 在服务器上, `useChat` 返回为 `refusalReason`,所以客户端可以在不匹配近端消息的情况下区分拒绝:

```tsx
const { status, refusalReason } = useChat({/* … */});

if (status === "unauthorized" && refusalReason === "access-denied") {
  // the user has no access: don't retry with a new token
}
```

与 `useAssistant`这是 `chat.refusalReason`。 。 。 .

* * *

## 工具核准

`useChat` 财务报告和审定财务报表 `useAssistant` 显示一个持久工具的步骤批准( e)`step.requestApproval` 在服务器上),恰好显示工具的认可:其部分相同 `state` (单位:千美元)`approval-requested`,则 `approval-responded` 或者说 `output-denied`和 `approval`,以及 `chat.addToolApprovalResponse({ id, approved })` 回答两个。 一个客户端用相同的代码处理它们.

`getToolApproval(part)` 返回与 `descriptor` 发送的代理: 动作 `approvalSummary` 或步骤 `summary` 作为 `summary`及其风险为 `risk`。 。 。 .

```tsx
import { getToolApproval, getToolPartState } from "@economic/agents-react";

if (getToolPartState(part) === "waiting-approval") {
  const approval = getToolApproval(part)!;

  // approval.descriptor?.summary, approval.descriptor?.risk ("low" | "medium" | "high")
  chat.addToolApprovalResponse({ id: approval.id, approved: true });
}
```

一个被拒绝的步态批准可以追溯到工具,工具决定接下来会发生什么,因此该部分随后会显示工具的结果而不是拒绝.

## 常见问题

### @economic/agents-react 是什么？

连接到代理机的反应钩 @economic/agents他们包了"云花" agents 财务报告和审定财务报表 @cloudflare/ai-chat 钩并添加打入的连接状态,消息反馈,以及 \`Assis' 使用的每个用户多聊天模式

### 如何安装 @economic/agents-react？

在项目目录运行 npm install @economic/agents-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @economic/agents-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @economic/agents-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @economic/agents-react 可以商用吗？

@economic/agents-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @economic/agents-react 的下载量有多少？

根据 npm 官方下载统计，@economic/agents-react 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,668 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @economic/agents-react 还在维护吗？

最新版本 2\.1\.0 发布于 2026/11/09（4 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 48 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。