# @ag-ui/client 中文文档

规范地址：https://npmcn.com/package/%40ag-ui/client/

版本：1\.0\.4
npm 元数据更新时间：2026-11-05T13:31:53.210Z
中文译文更新时间：2026-11-05T16:52:15.095Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ag-ui/client
原文对照：https://npmcn.com/package/%40ag-ui/client/?lang=original
项目主页：https://github.com/ag-ui-protocol/ag-ui#readme
源码仓库：https://github.com/ag-ui-protocol/ag-ui

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

- 包体积（解压后）：1.2 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：zod ^3\.25\.18 \|\| ^4\.0\.0
- 首次发布：2025-04-30T11:36:35.673Z
- 最新版本发布：2026-11-05T13:31:52.720Z
- 近 30 天下载量：6052407（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 43 个）

## 中文简介

连接到的客户端 SDK **代理用户互动(AG-UI)议定书** 服务器.

## 安装

```sh
npm install @ag-ui/client
```

也可以使用：`pnpm add @ag-ui/client`、`yarn add @ag-ui/client`、`bun add @ag-ui/client`

## README

# @ag-ui/客户端

连接到的客户端 SDK **代理用户互动(AG-UI)议定书** 服务器.

`@ag-ui/client` 提供处理AG-UI通信全生命周期的代理执行:连接到服务器,处理流出事件,管理状态突变,以及提供被动用户钩.

## 安装

```bash
npm install @ag-ui/client zod
pnpm add @ag-ui/client zod
yarn add @ag-ui/client zod
```

zod(3.25.18+或4.x)是一种同级依赖. 客户的执行阶段 验证每个事件, 其方案在 `@ag-ui/core/schemas`,使用 zod 键 您的应用程序安装而不是捆绑的副本.

## 特征

-   🔗 **HTTP 连接** – 说吧 – `HttpAgent` 用于与 SSE/ protobuf 支持的直接服务器连接
-   🏗️ **自定义代理** – 说吧 – `AbstractAgent` 用于构建自己的运输层的基类
-   📡 **事件流** - AG-UI事件完全处理,并进行验证和转换
-   🔄 **国家管理** - 自动消息/状态跟踪,并进行被动更新
-   🪝 **订户系统** - 用于记录、持久性和自定义逻辑的中件式钩子
-   🎯 **中间软件支持** - 转换和过滤带有函数或基于类的中间软件的事件

## 快速实例

```ts
import { HttpAgent } from "@ag-ui/client";

const agent = new HttpAgent({
  url: "https://api.example.com/agent",
  headers: { Authorization: "Bearer token" },
});

const result = await agent.runAgent({
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(result.newMessages);
```

## 执行限制

每个事件,一个代理收到, 每一个输入 `HttpAgent` 发送,剥去和 对协议计划进行验证 为了保持工作范围,客户 拒绝超过 1 000 000个容器条目的单个事件或输入(阵列) 元素、对象密钥和记录密钥;不透明字段,例如 `state` 没有 页:1 运行失败 `AGUIEnforcementLimitError` 命名路径 越过了界限.

```ts
// Raise the limit, or pass Infinity to disable it.
const agent = new HttpAgent({ url, maxEnforcedEntries: 5_000_000 });
```

限制范围包括剥离和验证。 之前运行的单行传 它们,如分析运输流,不计算,不透明田地 完全不受限制: `state` 通过执行并被克隆 以全额成本适用于下游.

## 使用中间软件

```ts
import { HttpAgent, FilterToolCallsMiddleware } from "@ag-ui/client";

const agent = new HttpAgent({
  url: "https://api.example.com/agent",
});

// Add middleware to transform or filter events
agent.use(
  // Function middleware for logging
  (input, next) => {
    console.log("Starting run:", input.runId);
    return next.run(input);
  },

  // Class middleware for filtering tool calls
  new FilterToolCallsMiddleware({
    allowedToolCalls: ["search", "calculate"]
  })
);

await agent.runAgent();
```

## 文档

-   概念和结构 : [`docs/concepts`](https://docs.ag-ui.com/concepts/architecture)
-   完整 API 参考 : [`docs/sdk/js/client`](https://docs.ag-ui.com/sdk/js/client/overview)

## 捐款

欢迎虫子报告和拉出请求! 请读我们的 [贡献指南](https://docs.ag-ui.com/development/contributing) 先说.

## 许可证

《麻省理工学院2025 AG-UI议定书》

## 活动快照

`MESSAGES_SNAPSHOT.metadata["@ag-ui/client"].authoritativeActivityTypes` 控制快照所替换的活动。 拥有这些类型的阵列; `[]` 没有,而且 `null` 拥有各种类型,即使是空快照。 无 声明,适用现行规则:包含任何活动的快照 替换所有活动,而只保存记录的快照。 一个不见了 名称空间或缺失字段使用此遗留规则。 无效的命名空间或字段 没有类型,包括包含非字符串条目的数组.

权威控制删除省略的活动消息 。 匹配消息标识 总是有更新,即使是在宣布范围以外的类型。 现有 保留信件位置,并按快照顺序附上新的ID. 该公约没有协调改变身份证或重新定位恢复的活动.

历史投影仪必须保持充分权威,扩大明确的范围 他们重建的类型. `withAuthoritativeActivityTypes` 执行此功能 规则; 在替换信件前, 将其调用到收到的快照上 .

## 常见问题

### @ag-ui/client 是什么？

连接到的客户端 SDK 代理用户互动\(AG-UI\)议定书 服务器\.

### 如何安装 @ag-ui/client？

在项目目录运行 npm install @ag-ui/client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3\.25\.18 \|\| ^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ag-ui/client 支持 TypeScript 吗？

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

### @ag-ui/client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ag-ui/client 可以商用吗？

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

### @ag-ui/client 的下载量有多少？

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

### @ag-ui/client 还在维护吗？

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