AGNT5 类型脚本 SDK
以 TypeScript 构建可靠的AI代理和可持久的工作流程. 第5条 检查每一个工作流程步骤, 所以一个故障的运行 从它的复通 而不是重新开始。 SDK 提供了打入函数 和工作流程,复写,流线,工具呼叫,多代理交接, 人入LOOP(HITL)批准,MCP,evals,以及运行时间可观察性.
所需资源
- 节点.js 18或更新
- 部署执行的 AGNT5 运行时间
安装
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 到达工人手中
进程,而不是兄弟应用程序进程.
快开始
定义输入函数并启动工人 :
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 (单位:千美元)
完全进入点.
长期工作流程
对应当安全检查和重放的行动使用命名步骤:
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 而不是还原
旧结果。 无服务器和本地运行将输入传递给正文,而不包含
检查一下:
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。
生成历史,然后是新事件,然后结束于
运行的最后活动。 如果连接下降, 它会从上次的抵消恢复
已生成 :
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· ;
只登记工作流程供单独引用.
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 提供者的选项,或
使用清晰的包装:
import * as ai from 'ai';
import { wrapAISDK } from '@agnt5/sdk/integrations';
const { generateText, streamText } = wrapAISDK(ai);
JournalSpanProcessor 用于构建其
拥有 OpenTeleometry 追踪器提供者。 处理器和包装器只在
调用在一个 AGNT5 组件上下文中运行,抓取失败永远不会改变
提供商呼叫的结果.
无工/无役入站点为 API 使用相同的自动可操作钩 等价,但它今天没有建立 Async LocalStorage 执行上下文 . 因此,在没有工人之前,第三方抓捕仍然是一条不能走的道路 实施环境传播.
实例和文件
共同的罗斯德基金会生活在
agnt5dev/sdk-core. 供应商沙盒
适配器居住于
agnt5dev/sdk-integrations。 。 。 .
管理下的评价
使用 client.eval() 运行已注册组件,并通过
POST /v1/eval这需要能够达到的AGNT5运行时间和为残疾人服务的工人
组件;不是离线实验跑道.
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 立即返回待收 验收后。 此控制响应等待, 不是工作流程执行 截止日期:当等待到期或客户端断开时,接受的工作继续进行.
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:
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 默认为
- 配置和输入错误总是失败 。 见 SDK核心合同 用于支持的表达式和执行限制。 边缘客户端可能提交食谱 用于运行时执行; 本地评价需要节点和匹配的本地绑定.
无服务器签名
过 signingSecret 改为 serve() 从 @agnt5/sdk/serverless 或去节点或
云花调适器. 使用读取您的提供者的字符串或解析器
环境约束。 未解密密还原的提示 HTTP 503
(单位:千美元)WORKERLESS_SIGNING_SECRET_REQUIRED)在运行用户代码之前. 失踪或
配置了密报的无效签名 401. 名单还在
可供发现.
只为了地方发展, serve({ allowUnsigned: true }) 未签名的许可
当启动时没有解密并记录警告时引用 。 还在验证
当密钥配置时请求。 启动时缺少静态机密;
空请求- 时间解析器在其第一次失败的引用时警告 。 AGNT5 启动
无论SDK选项如何 发送仍然需要签名保密.
发展
npm ci
npm run build:ts
npm test
本土约束性开发还需要稳定的Rust工具链和兄弟关系
离职 sdk-core。 。 。 .
释放核查
Npm 成功上传并不能保证立即提供软件包 。 无 扫描新版本,并可能对其进行审查。 发布工作流程等待 至20分钟(加请求时间)用于公共本地包装元数据和沥青球 在发布主SDK之前,然后验证主包也.
如果一个版本仍然无法使用,请使用 npm 检查其扫描/阶段状态 维护者账户。 通过 npm 完成任何必要的复审或上诉。 别 继续重试一个返回“以前已预设的版本”的不可改变版本; 仅靠新版本并不能解决扫描或批准问题.
见 npm 发布时间扫描 财务报告和审定财务报表 分阶段出版。 。 。 .
捐款
许可证
凭 Apache 许可证 2.0。 。 。 .
宣布步骤超时中止处理器的信号 。 处理器应该通过该信号可以取消 I/O. 失败、取消和重试等处理器解决, 所以忽略了信号延迟和解; 延迟结果会被丢弃 .