# @agnt5/sdk 中文文档

规范地址：https://npmcn.com/package/%40agnt5/sdk/

版本：0\.11\.2
npm 元数据更新时间：2026-11-06T07:37:18.508Z
中文译文更新时间：2026-11-06T06:11:40.596Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：2.3 MB，315 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-04-20T23:26:37.401Z
- 最新版本发布：2026-11-06T07:37:18.196Z
- 近 30 天下载量：4574（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

AGNT5 TypeScript SDK - 持久的AI工作流程和代理

## 安装

```sh
npm install @agnt5/sdk
```

也可以使用：`pnpm add @agnt5/sdk`、`yarn add @agnt5/sdk`、`bun add @agnt5/sdk`

## README

[![AGNT5: the reliable platform for AI agents and workflows](https://agnt5.com/images/github/github-repo-sdk-banner.png)](https://agnt5.com/)

# AGNT5 类型脚本 SDK

[![npm](https://img.shields.io/npm/v/@agnt5/sdk)](https://www.npmjs.com/package/@agnt5/sdk) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://npmcn.com/package/%40agnt5/sdk/LICENSE)

以 TypeScript 构建可靠的AI代理和可持久的工作流程. 第5条 检查每一个工作流程步骤, 所以一个故障的运行 从它的复通 而不是重新开始。 SDK 提供了打入函数 和工作流程,复写,流线,工具呼叫,多代理交接, 人入LOOP(HITL)批准,MCP,evals,以及运行时间可观察性.

[文档](https://agnt5.com/docs) • 妇女 [启动模板](https://github.com/agnt5dev/templates) • 妇女 [网站](https://agnt5.com/)

## 所需资源

-   节点.js 18或更新
-   部署执行的 AGNT5 运行时间

## 安装

```bash
npm install @agnt5/sdk
```

## 网关配置

`Client` 用途 `https://gw.agnt5.com` 当未提供网关 URL 或 `AGNT5_GATEWAY_URL` 为空。 设定 `AGNT5_API_KEY` 用于认证。 一个 明确 `gatewayUrl` 选项优先于 `AGNT5_GATEWAY_URL`。 。 。 . 工人会话-历史请求使用相同的环境设置和默认.

例如,对于本地运行时间,请明确规定其终点 `AGNT5_GATEWAY_URL=http://localhost:34183`。单独的应用程序需求 环境设置: 由 `agnt5 dev` 到达工人手中 进程,而不是兄弟应用程序进程.

## 快开始

定义输入函数并启动工人 :

```typescript
import { fn, Worker } from '@agnt5/sdk';

const greet = fn('greet').run(async (ctx, name: string) => {
  ctx.logger.info(`Greeting ${name}`);
  return { message: `Hello, ${name}!` };
});

const worker = new Worker('hello-typescript');
await worker.run();
```

进口的功能,工作流程,工具和计分员向工人登记. 启用 `autoRegister` 包括特工,或呼叫 `worker.registerAgents(...)`。见 [`examples/simple-worker.ts`](https://npmcn.com/package/%40agnt5/sdk/examples/simple-worker.ts) (单位:千美元) 完全进入点.

## 长期工作流程

对应当安全检查和重放的行动使用命名步骤:

```typescript
import { workflow } from '@agnt5/sdk';

export const prepareReport = workflow(
  'prepare-report',
  async (ctx, reportId: string) => {
    const source = await ctx.step('load-source', () => loadSource(reportId));
    const report = await ctx.step('build-report', () => buildReport(source));
    return { reportId, report };
  },
);
```

将其投入与 `input` 和身体接受它。 在一个管理 工人,重放比较 与输入的第一步运行。 如果是 变了,步子提高了 `NON_DETERMINISTIC_REPLAY` 而不是还原 旧结果。 无服务器和本地运行将输入传递给正文,而不包含 检查一下:

```typescript
const receipt = await ctx.step(
  'charge',
  ({ orderId, amount }) => charge(orderId, amount),
  { input: { orderId, amount } },
);
```

一步没有 `input` 不选中此选项: 值它的关闭抓取可以 变化和记录的结果仍然会回来。 获取来自 工作流程输入或更早的步骤结果,从未来自 `Date.now()` 或随机身份证明, 或者每次重播都失败。 步骤是复制一个输入 当它叫, 与 `undefined` 属性下降, 尸体运行在复制。 通过普通 数据:作为字符串的日期(`toISOString()`),以及 `value ?? null` 的数值 也许 `undefined`,从 `undefined` 财务报告和审定财务报表 `null` 大麻一样。 A 类 `Date`, (中文(简体) ), `Map`, (中文(简体) ), `Set`,函数, 其他类实例或 `undefined` 数组项目被拒绝。 输入也是 在台阶的日记记录上显示, 所以通过一个秘密的名字而不是它 数值.

保留步骤名称,在复试中稳定订购,这样完成的工作就可以 复用过. 直接调用创建的函数 `fn(...).run(...)` 并创建一个 从管理下的工作流程调用检查站时。 明确 `ctx.step` 保留 包含函数调用时其边界。 嵌入式函数 重试和倒置设置; `ctx.attempt` 以零为基础。 产生外部效果 一能,因为中断的尝试可以在结果之前再次执行 被记录.

嵌入式流线功能将检查点打开直至其执行器 完成或关闭。 说吧 `for await`,或打电话 `return()` 在此之前 工作流程等待或返回。 已完成的流重放其记录的播放器 操作并验证他们的参数,而不再给处理器打电话. 提出改变的论据 `NON_DETERMINISTIC_REPLAY`。溪流在 它的传动器已经暴露在呼叫者面前。 重放延时器也必须消耗 在工作流程等待或完成之前记录的终端操作.

从管理下的工作流程调用已登记的工作流程,或使用 `executeChildWorkflow`中,提交单独的孩子运行并加入结果. 呈文使用稳定的一能键. 儿童工作流程需要一个网关 URL和父母项目的证明,以及他们自己的工人能力. 独立儿童电话使用单独的本地上下文并继承取消 包括由 `withTimeout`。 。 。 .

打电话 `ctx.waitForUser`, (中文(简体) ), `ctx.waitForSignal`,并持久 `ctx.sleep` 介于 步骤。 未完成步骤或活动工具/功能激活中的等待 筹集 `ConfigurationError`信号 反应和完成的步骤在随后的停顿中存活下来。 用于管理和 无工人用户/信号等待, `{ timeoutMs }` 规定一个持久的等待期限; 过期运行失败 `WAIT_TIMEOUT`。这需要运行时间版本 支持等待最后期限。 和客户的反应不同 说明如下.

从您的申请中恢复运行等待 `ctx.waitForSignal` 与 `client.signal(runId, name, payload)`。收据的 `resumed` 说明是否 跑在等那个信号 为了显示跑步的进展 跟着跑步 与 `client.followEvents(runId)`,包括它发送的 `ctx.emit`。 生成历史,然后是新事件,然后结束于 运行的最后活动。 如果连接下降, 它会从上次的抵消恢复 已生成 :

```typescript
await client.signal(runId, 'page_read', { url });
for await (const event of client.followEvents(runId)) {
  if (event.eventType === 'crm.progress') render(event.data);
}
```

`saga(ctx, steps, { name: 'order' })` 检查站前行和倒行逆施 补偿。 保持名称稳定 跨调度。 暂停无风 开始补偿。 赔偿失败不能阻止剩余回滚; `SagaCompensationError` 维护原因和所有补偿 错误。 赔偿也必须是专有的. 失败的动作结果在回滚开始前被记录. 后来发送 恢复回滚,并保持失败,即使这一行动现在取得成功. 启动新的 saga 引用, 在补偿后重试交易 .

在拉动工作流程中, `await ctx.set(key, value)` 财务报告和审定财务报表 `await ctx.delete(key)` 等待持久的国家变革承认. `ctx.get(key)` 读取本地工作流程状态。 在成功完成之前, 工人坚持最后 `WorkflowEntity` 与现行租约的快照 并进行版本检查,匹配 Python 的工作流程状态持久性。 状态 在每个工作流程内命令写; 独立工作流程可以继续 同时 独立的进程内背景保留其本地状态行为.

## 宣布的持久步骤

宣布工作流程-当地业务 `step`。让他们通过 `ctx.step`· ; 只登记工作流程供单独引用.

```typescript
import { step, workflow } from '@agnt5/sdk';

const prepareSearch = step('prepare-search', async (ctx, input: { topic: string }) => {
  return { query: input.topic.trim() };
}, { retries: { maxAttempts: 3 }, timeoutMs: 5000 });

const research = workflow('research', async ctx => {
  return ctx.step(prepareSearch, { input: { topic: 'durable agents' }, key: 'query' });
});
```

处理器在持久录取后开始,结果在 确认已完成。 这两个激活呼叫记录了生命周期; 没有额外功能检查站。 每次重试都收到一份新副本 输入和基于零的 `ctx.attempt`完成的步骤重现承诺 结果。 外部效应仍然需要一能; 被认可的处理器可以使用 `ctx.activation.idempotencyKey`。 。 。 .

返回 JSON 可序列化结果; 使用 `null` 为空结果. 对同时或重复的工作使用明确的密钥. 宣布的步骤要求 运行时激活支持, 没有它就明显失败 。 现有 `fn(...)` 函数和字符串/召回 `ctx.step(...)` 电话保持他们的行为.

## 事件触发

使用 `event(...)` 或者说 `webhook(...)` 在工作流程中 `triggers` 声明. 过滤、输入映射、分批和延迟尚未支持。 离开 `filterExpression`, (中文(简体) ), `inputMapping`, (中文(简体) ), `batchWindowMs`,以及 `delayExpression` 未设置; 工作流程注册拒绝非空表达式和非零批次 窗口中,命名选项出错.

## 代理限制和取消

代理筹取 `MaxIterationsExceededError` 当它耗尽的时候 `maxIterations`。 。 。 . `maxHandoffDepth` 默认为10并适用于整个交接链; 超过它升起 `HandoffDepthExceededError`。 。 。 .

传递中止信号为 `agent.run(input, ctx, history, { signal })` 或在一个 LM生成请求. SDK将其与跑道的取消信号结合. 原生和边缘 LM 供应商取消 HTTP 生成和流出. 自定义模式 执行者接受信号,必须尊重信号,以阻止他们自己的I/O. 代理工具通过 `ctx.signal`; 也取消 停止代理等待飞行工具。 工具执行必须尊重 停止他们自己的I/O的信号.

设定 `autoRegister: true` 发现注册的制剂,或使用 `worker.registerAgents(...)` 明确代理人名单。 自动发现代理商 选项被删除时已禁用。 工人拥有 解约 拒绝和定时器例外, 失败的原运行, 并保留错误分类和堆栈 `result.error.type` 财务报告和审定财务报表 `result.error.stack`。 。 。 . `containProcessErrors: false` 禁用 处理程序错误的应用程序. 活动运行以外的错误保留默认的致命处理或应用程序的 已有的处理器,包括运行后解开的错误.

## 软件包入口

| 导入 | 目的 |
| --- | --- |
| `@agnt5/sdk` | 部件、客户、工人、代理人、工具和工作流程 |
| `@agnt5/sdk/integrations` | 第三方OpenAI,代理SDK,Vercel AI SDK,和Google ADK捕获 |
| `@agnt5/sdk/serverless` | 共享无服务器适配器 |
| `@agnt5/sdk/serverless/node` | Node.js 无服务器适配器 |
| `@agnt5/sdk/serverless/cloudflare` | Cloudflare 无服务器适配器 |
| `@agnt5/sdk/workerless/node` | 节点.js 无工人 HTTP 适配器 |
| `@agnt5/sdk/workerless/cloudflare` | Cloudflare 无工人 HTTP 适配器 |

默认工人对其支持的节点使用已公布的本地装订 平台。 无服务器和无工人入境点有单独的运行时间 ;在部署到边缘运行时间之前审查相关实例.

## 第三方抓获

长期工自动观察支持的第三方图书馆 它们由应用程序安装。 集成是软载 SDK 不安装或捆绑这些库作为运行时间依赖性 。 设定 `AGNT5_CAPTURE=off` 以禁用所有抓取或使用 `AGNT5_CAPTURE_OPENAI`, (中文(简体) ), `AGNT5_CAPTURE_OPENAI_AGENTS`, (中文(简体) ), `AGNT5_CAPTURE_VERCEL_AI`,以及 `AGNT5_CAPTURE_GOOGLE_ADK` 作为图书馆 开关( e)`off`, (中文(简体) ), `0`, (中文(简体) ), `false`,以及 `no` 禁用开关).

捕获的生命周期事件带有字符串出处元数据: `source` 识别整合( e)`openai`, (中文(简体) ), `openai_agents`, (中文(简体) ), `vercel_ai`,或 `google_adk`和 `capture_mode=observed` 区分最佳第三方 从明确标记的本地 SDK 事件观测(`capture_mode=native`) (中文(简体) ). Google ADK 抓取支持 `@google/adk` 1.0.0和较新;遗存0.x发行 故意没有支持.

Vercel AI SDK 7+通过它公开的全球遥测登记册被捕获. 在早期的 AI SDK 版本上的应用程序可以启用库的 `experimental_telemetry` 带有已存在的 OpenTeleometry 提供者的选项,或 使用清晰的包装:

```typescript
import * as ai from 'ai';
import { wrapAISDK } from '@agnt5/sdk/integrations';

const { generateText, streamText } = wrapAISDK(ai);
```

`JournalSpanProcessor` 用于构建其 拥有 OpenTeleometry 追踪器提供者。 处理器和包装器只在 调用在一个 AGNT5 组件上下文中运行,抓取失败永远不会改变 提供商呼叫的结果.

无工/无役入站点为 API 使用相同的自动可操作钩 等价,但它今天没有建立 Async LocalStorage 执行上下文 . 因此,在没有工人之前,第三方抓捕仍然是一条不能走的道路 实施环境传播.

## 实例和文件

-   [`examples/`](https://npmcn.com/package/%40agnt5/sdk/examples/) 包括功能,工作流程,代理,流出, HITL、MCP、聊天和无工人的HTTP例子.
-   [`docs/`](https://npmcn.com/package/%40agnt5/sdk/docs/) 包含 TypeScript SDK 指南.
-   [AGNT5文件](https://agnt5.com/docs) 涵盖平台概念和 部署.

共同的罗斯德基金会生活在 [`agnt5dev/sdk-core`](https://github.com/agnt5dev/sdk-core). 供应商沙盒 适配器居住于 [`agnt5dev/sdk-integrations`](https://github.com/agnt5dev/sdk-integrations)。 。 。 .

## 管理下的评价

使用 `client.eval()` 运行已注册组件,并通过 `POST /v1/eval`这需要能够达到的AGNT5运行时间和为残疾人服务的工人 组件;不是离线实验跑道.

```typescript
const result = await client.eval('greet', { name: 'Alice' }, {
  expected: 'Hello, Alice!', // Defaults to the built-in exact_match scorer.
});
console.log(result.isSuccess, result.passed, result.scores);
```

`isSuccess` 报告成功执行组成部分的情况; `passed` 报告评分 结果。 因此,一个分数不匹配 `isSuccess === true` 财务报告和审定财务报表 `passed === false`. 内建计分员不需要申请登记.

用于多种输入 `client.batchEval(component, items, { maxConcurrency: 5 })`。 。 。 . 每个项目都通过管理的终点进行评价. `maxConcurrency` 一定是个 正整数。 本地自定义计分器呼叫仍可通过 `runScorer`· ; 它们不创建管理下的实验运行,也不提供离线数据集运行器.

## 回复等待

运行和流调用等待 **5分钟** 默认。 设定每次呼叫等待 从零到24小时的任何值。 0 立即返回待收 验收后。 此控制响应等待, 不是工作流程执行 截止日期:当等待到期或客户端断开时,接受的工作继续进行.

```typescript
const options = { componentType: 'workflow' as const, waitTimeoutMs: 60000 };
const result = await client.run('process_order', order, options);
for await (const event of client.events('process_order', order, options)) {
  console.log(event.eventType, event.runId);
}
```

`waitTimeoutMs` 使用整个毫秒。 运行调用返回 `202` 待收款项 直接,没有额外的投票。 事件流喷出 `stream.wait_expired` 当等待到期时,或 `stream.detached` (单位:千美元) `202` 收讫. 使用运行的ID 改为读取状态/结果。 只弹簧 `stream` 筹集 `RunError` 用运行的ID 当等待结束.

默认的 HTTP 超时允许至少等待加10秒, 或者客户端 超时。 过 `timeoutMs: 75000` 来明确它.

## 结构化主张

`structured_assertions` 是一个内置计分器,配备自动工人 发送。 在节点中,本地的帮助者通过本地绑定来称呼 SDK-core:

```typescript
import { structuredAssertions } from '@agnt5/sdk';

const result = structuredAssertions({
  output: [1, 2, 3],
  expected: { expected_length: 3 },
  config: { assertions: [
    { name: 'unique_ids', expr: 'unique(output_json)' },
    { name: 'count', expr: 'size(output_json) == expected.expected_length' },
  ] },
});
```

得分是通过断言的分数; `score_threshold` 默认为

1.  配置和输入错误总是失败 。 见 [SDK核心合同](https://github.com/agnt5dev/sdk-core/tree/82e98e984749f80a31ff6302ba508d55974c608d/crates/eval-scorers) 用于支持的表达式和执行限制。 边缘客户端可能提交食谱 用于运行时执行; 本地评价需要节点和匹配的本地绑定.

## 无服务器签名

过 `signingSecret` 改为 `serve()` 从 `@agnt5/sdk/serverless` 或去节点或 云花调适器. 使用读取您的提供者的字符串或解析器 环境约束。 未解密密还原的提示 HTTP 503 (单位:千美元)`WORKERLESS_SIGNING_SECRET_REQUIRED`)在运行用户代码之前. 失踪或 配置了密报的无效签名 401. 名单还在 可供发现.

只为了地方发展, `serve({ allowUnsigned: true })` 未签名的许可 当启动时没有解密并记录警告时引用 。 还在验证 当密钥配置时请求。 启动时缺少静态机密; 空请求- 时间解析器在其第一次失败的引用时警告 。 AGNT5 启动 无论SDK选项如何 发送仍然需要签名保密.

## 发展

```bash
npm ci
npm run build:ts
npm test
```

本土约束性开发还需要稳定的Rust工具链和兄弟关系 离职 `sdk-core`。 。 。 .

## 释放核查

Npm 成功上传并不能保证立即提供软件包 。 无 扫描新版本,并可能对其进行审查。 发布工作流程等待 至20分钟(加请求时间)用于公共本地包装元数据和沥青球 在发布主SDK之前,然后验证主包也.

如果一个版本仍然无法使用,请使用 npm 检查其扫描/阶段状态 维护者账户。 通过 npm 完成任何必要的复审或上诉。 别 继续重试一个返回“以前已预设的版本”的不可改变版本; 仅靠新版本并不能解决扫描或批准问题.

见 [npm 发布时间扫描](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/) 财务报告和审定财务报表 [分阶段出版](https://docs.npmjs.com/staged-publishing/)。 。 。 .

## 捐款

见 [捐款额](https://npmcn.com/package/%40agnt5/sdk/CONTRIBUTING.md)报告安全问题 [警卫](https://npmcn.com/package/%40agnt5/sdk/SECURITY.md)。 。 。 .

## 许可证

凭 [Apache 许可证 2.0](https://npmcn.com/package/%40agnt5/sdk/LICENSE)。 。 。 .

宣布步骤超时中止处理器的信号 。 处理器应该通过该信号可以取消 I/O. 失败、取消和重试等处理器解决, 所以忽略了信号延迟和解; 延迟结果会被丢弃 .

## 常见问题

### @agnt5/sdk 是什么？

AGNT5 TypeScript SDK - 持久的AI工作流程和代理

### 如何安装 @agnt5/sdk？

在项目目录运行 npm install @agnt5/sdk，或使用 pnpm add / yarn add / bun add。

### @agnt5/sdk 支持 TypeScript 吗？

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

### @agnt5/sdk 支持 ESM 还是 CommonJS？

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

### @agnt5/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agnt5/sdk 可以商用吗？

@agnt5/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agnt5/sdk 的下载量有多少？

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

### @agnt5/sdk 还在维护吗？

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