跳转到主要内容
@hexagon/agent-sdk 是 ESM 包,当前版本 0.1.0,package manifest 要求 Node.js >=20;控制平面仓库单独要求 Node.js >=22.19.0。不能从 Node 包要求推断浏览器或 edge runtime 兼容。本地发现会导入 Node filesystem、path、OS 模块,应在可信后端运行。 从当前 checkout 构建,再安装到自己的 Node 应用:
绝对路径为占位,不代表已公开发布到 npm。参见 package.json,记录版本之外的安装产物与源码 revision。

安装打包快照

若要检查独立应用实际收到的文件,可先构建,再生成本地 tarball。在 Hexagon 仓库根目录执行以下命令;将产物目录和应用目录替换为自己的真实路径:
最后一条命令应输出 function。版本变化时,使用 npm pack 实际输出的文件名。--ignore-scripts 跳过包的 prepack 构建,因此前面的显式构建必须成功。打包只写入本地归档,不会发布到 npm。保留归档及其对应源码 revision,以便复现。包从 dist 导出 ESM 和 TypeScript 声明,没有声明 CommonJS require 入口。 这条 tarball 安装路径已在仓库外的临时应用中检查。回环模拟 HTTP 服务验证了携带鉴权头的 Run 查询、超过 JavaScript 安全整数范围的十进制事件游标,以及 HexagonError 的状态码和错误码转换。它证明包的使用路径与这些客户端行为,不证明真实服务端授权或云端执行。见安装检查记录。

初始化客户端

显式 URL 不包含 /v1,SDK 会追加它。构造不发验证请求。local({dataDirectory, baseUrl}) 返回 Promise,验证私有工作区文件与回环身份;可选 baseUrl 核对发现端点,不切换为 hosted 认证。见 local.ts。 不要把控制平面 Token 打包到前端。由后端认证业务用户并转发有权访问的结果。没有客户端级 dispose 方法;close(session) 请求关闭 Session。退出事件迭代会释放 reader,不取消执行。

公共方法与实际返回类型

清单使用已安装 TypeScript 编译器,从源码声明及推断返回类型生成。初始化值体现真实默认参数,保留 Promise<any>,不编造响应模型。类型不会在运行时校验 JSON。通用 request 遇到 HTTP 204 返回 undefined,即使调用者给出了不兼容的泛型也如此。 运行 node tooling/generate-typescript-doc-index.mjs 重新生成。unknown、输入对象与查询值仍由服务端 schema 验证。可选查询字段应省略,不显式传 undefined,因为列表方法会字符串化已提供的键值。分页显式处理;events、artifacts 保留 collection envelope。

导出类型

定义见 index.ts。LocalOptions 在 local.ts 声明,package exports 暴露根入口,不承诺提供公开 local 子路径导入。

类型声明与 HTTP 契约的宽窄差异

即使 TypeScript 接受对象,服务端校验仍然生效;声明省略响应字段也不代表服务端丢弃了该字段。运行时验证与类型断言应分开,两者都不会改变权限或重试语义。

带上下文的常见调用

片段需要已初始化客户端、就绪连接 ID、已保存提交意图及应用持久化函数,不含完整恢复与清理;完整流程见首个 Session 程序。
与 Python upload 不同,TypeScript 接收含已编码 Base64 字符串的数组。在应用 journal 保存 Session、Run ID 与精确 input/origin/key。提交响应丢失可用相同意图恢复,Session 创建没有同等 Run 提交幂等保证。参见后端集成与项目上下文。

事件流、取消与错误

stream(run, after='0', signal?) 是 AsyncGenerator,使用 for await 迭代,只持久化有 ID 的事件,从最后提交的游标重连原 Run。ID 保持字符串。stream.end 没有持久 ID,结束后仍查询 Run。意外 EOF 或截断抛普通 Error,不自动重连。 传入 stream 的 AbortSignal 只停止本地观察,不取消 Run。cancel(run) 请求取消执行,close(session) 单独处理资源清理。并非所有便捷方法都接受 signal;通用 request 在第五个参数接受它,不提供统一默认请求超时。支持处可传 signal,但必须正确处理操作结果未知。 普通 JSON 错误转为 HexagonError,使用服务端 code 或 http_error;流打开错误为 event_stream_failed,下载缺省错误为 artifact_download_failed。Fetch、abort、JSON 错误可能保持原生异常。通用 request 拒绝重定向,而 stream、download 使用 fetch 缺省重定向行为,应配置实际可信 API origin,不依赖跳转。详见错误。

管理流程与缺口

连接 CRUD 和验证见连接生命周期,操作选择见应用、MCP,revision 见Agent 模板,决定流程见审批与对账。Secret、Token、OAuth、部署方法要求相应管理角色,类中存在方法不等于调用者获得授权。grant 和返回凭据不能进入日志。 通用 request<T>(method, path, ...) 可访问已实现但没有便捷方法的 JSON 端点,例如某 Session 的 Run 列表,不能创造端点、替代浏览器 OAuth 或代理任意二进制响应。泛型是编译期断言,不是 schema 校验。SDK 没有内置持久 journal、统一自动分页或副作用安全重试机制。 已逐个审阅公开方法的源码清单、所链接示例的调用点及返回/错误契约映射。示例复用初始化上下文和 HTTP 规范;存在调用点不等于所有操作均已执行。安装包检查和实云旅程保持原有证据范围与日期;源码、类型、确定性与实云证据的区别见测试指南。

Managed Secret 与应用 Token 调用

以下是彼此独立的辅助函数,需要已初始化的 owner 客户端。定义函数不会发送请求;只调用你实际需要的操作。同租户资源 ID 来自私有管理记录,凭据值来自你的凭据存储。示例向调用方传播错误,不自动重试写入。TypeScript 片段使用前文的 Hexagon 导入。

保存和检查 Provider 凭据

inspect_secrets / inspectSecrets 返回元数据和依赖信息,不返回已保存的值。其中 Session 依赖数组有数量上限,不是完整历史审计。创建返回的 ID/version 应持久化;名称不是去重键。 替换值会使引用连接失效:连接变为 disabled、draft,需要重新验证后再显式启用。返回的 Secret version 是状态观察,不是乐观锁条件。超时后不要自动重复调用此函数,应先检查原 Secret 和连接状态。删除可能返回 secret_in_use;停用连接不会解除引用。成功删除没有 JSON 响应。这些操作都不会撤销外部 Provider 的凭据。完整定义见 Secret 契约。

签发、轮换和撤销后端凭据

创建和轮换辅助函数返回包含明文的对象,字段为 id、token、label、role、expires_at、created_at。应立即将 token 转存至后端的凭据存储,并在私有管理记录中保留 ID。不要打印整个对象、返回给浏览器,或放入异常诊断。如果写入凭据存储失败,私下保留回执并对账该凭据;重新执行辅助函数会发起另一项操作,不能找回第一次的明文。 元数据列表包含已到期和已撤销的应用 Token;按 role 过滤不表示结果都是有效凭据。轮换返回新的 ID,立即使旧 Token 失效,并保留原到期时间。没有重叠有效窗口,重放旧轮换也无法取回替代凭据。撤销返回包含 revoked_at 的 JSON,与 Secret 删除的空响应不同;同一应用 Token 可以重复撤销,但不会取消已接受的 Run。 写入前私下记录操作意图和目标。创建或轮换响应丢失时需要通过元数据调查,名称和 label 本身不足以唯一确认结果。响应丢失处理见 Token 契约,部署和凭据验证见身份运维指南。这些示例说明 SDK 调用方式;语法或类型检查不证明真实凭据签发、外部 Provider 撤销或完整轮换上线成功。

连接生命周期调用

以下辅助函数彼此独立,需要已初始化的 owner 客户端;定义函数不会创建或修改连接。Vercel 创建示例需要真实的 project/team 配对,以及来自私有凭据存储的 Token。调用前记录创建意图,取得连接 ID 后先持久化,再进入验证步骤。Vercel 配置指南说明 Provider 专属要求;使用其他 Provider 时,先阅读对应指南再替换完整定义。
按当前阶段选择函数,不要把整个代码块当作创建、发现、断开、删除的连续流程运行: 验证可能访问 Provider、刷新 OAuth 凭据,模型验证也可能产生用量。并发配置变更可能返回 connection_changed_during_validation;再次尝试前重新读取连接,核对预期配置。验证和启用不是一个原子请求,也没有客户端比较并交换保护,应在应用中协调管理变更。 更新 config 会替换整个配置对象。凭据或配置变更会重置就绪状态,不应与 enabled: true 合并发送。即使重复停用、断开或发送空 PATCH,也可能推进版本。示例向调用方传播 HTTP 和网络错误,不自动重试;响应丢失后检查原 ID 和状态。检查函数可能返回私有账户元数据,不能直接作为日志输出。 准确字段与错误见连接响应契约,既有 Session 的处理见连接变更指南,用户同意见 OAuth。这些示例经过本地语法和类型检查,不代表本轮完成真实 Provider 验证或云任务执行。

目录与 OAuth 用户同意调用

这些辅助函数需要已初始化的 owner 客户端。目录查询用于检查已声明的集成和应用操作要求,不会验证你的账户,也不能证明执行组合可用。先选择支持 OAuth 的应用,按预期操作创建 Tool 连接,再使用 Provider 已注册的 client ID/secret 和匹配的回调 URL。回调路径必须为 /oauth/callback,详见 OAuth 配置约束。
将这些函数作为后端用户同意流程的独立阶段调用:
  1. 初始化集成或明确变更配置时,配置 OAuth 客户端。不要在每次状态轮询时重复配置,否则可能使正在进行的流程失效。返回的 {configured, provider, client_id, redirect_uri} 只确认配置,不代表用户同意。
  2. 发起一次用户同意流程,私下持久化返回的 flow ID 及其连接、业务用户关联,再仅向预期用户展示 authorization_url。URL 包含流程 state,不应写入日志,也不要向浏览器传 owner Token。用户在 Provider 页面完成同意,SDK 不自动操作该页面。
  3. 用保存的 flow ID 调用 inspect_consent / inspectConsent。每次只读取一次流程,完成后再读取一次连接授权状态。应用自行安排有上限的轮询;函数不休眠、不循环,也不发起第二次流程。浏览器跳转本身不能证明成功。
  4. 用户放弃时,针对保存的 flow 调用取消函数。返回的是流程对象,不是空响应。取消只改变 pending 流程;若回调先完成,返回状态仍可能是 completed。
连接授权有独立的 state 值:oauth、manual、disconnected、reauthorization_required、refreshing、refresh_unknown,与流程 status 不同。oauth 和 refresh_available 描述已存储的生命周期信息;读取不会刷新 Token,也不实时检查 Provider 撤销。刷新结果不确定时需要调查或明确重新授权,不能重放可能已轮换的 refresh token。 再次发起同意会取消该连接的 pending 流程。因此发起响应丢失后,不能盲目再次调用来恢复;保留结果不确定的事实,在适当时明确替换原尝试。取消流程不会撤销既有 Provider 凭据、取消 Run 或决定 Tool 审批。app_oauth_setup_required、app_oauth_unsupported、app_oauth_flow_not_found 和鉴权错误通过 SDK 传播,网络错误另行处理。详见 OAuth 响应与错误和应用集成指南。 这些函数是由调用方提供凭据和 ID 的 SDK 上下文示例。本地代码检查不证明浏览器用户同意、Token 交换或 Provider 账户验证成功。 Agent 列表、详情、预检、修订、复制、归档和固定初始化查询示例见准备并提交模板修订。示例保留最初观察的 revision,并说明环境保留和响应丢失处理。 六个 Session 环境、授权和 access grant 方法的上下文示例见 SDK 访问示例,区分明文读取、Token 签发、单 grant 撤销和 Session 绑定撤销。 运维 SDK 示例覆盖概览、Session/pending 分页、活动与 health,以及部署 revision 更新和入口重试/停止,区分状态观察、保存配置与运行中进程操作。 显式暂停/恢复示例与已验证 Tool 结果登记说明生命周期意图、部分响应丢失,以及保持请求体不变的对账重放。

按资源查阅响应契约

生成的签名说明客户端如何调用;精确响应投影、状态码、角色、状态前提和副作用应查看对应 HTTP 契约。大部分管理方法直接返回解码后的 JSON;调用没有抛异常,仍可能包含 invalid 的连接验证结果或 reconciliation_error,不能据此认定业务成功。 产物二进制下载和事件流使用上文说明的特殊返回路径。DELETE 并非统一空响应:Token 撤销返回 JSON,预览/access/Secret/连接删除使用 204,OAuth flow 取消返回 flow 对象。构建通用应用封装时必须保留这些差异。

查询已有 Run,不提交新工作

从仓库根目录运行完整诊断示例。Python 先安装本地 SDK;TypeScript 先执行 npm --prefix sdk/typescript run build。
程序核对 Run/Session 关联,读取 Session 状态和有页数上限的事件,重新查询 Run 并列出产物 ID/大小/摘要。报告不包含任务文本、事件 payload、最终输出或产物名称,资源 ID 仍需私有保存。它不会提交、审批、取消或关闭任务。事件 ID 保持十进制字符串,比较使用任意精度整数,不转换成有精度损失的数字。 Last_observed_cursor 是诊断观察位置,不是应用消费者检查点:程序只计数,没有持久保存事件内容。Reached_empty_event_page 只说明该次查询暂时没有后续页,不表示 Run 完成。状态、事件和产物是分开的读取,不是原子快照。达到页数上限可使用返回游标继续诊断,但不能据此跳过应用尚未处理的事件。 本地语法/类型与假客户端检查不证明真实 API 或云行为。解释结果请结合 Run 契约与恢复指南。 示例安装、阶段与恢复说明。

在两套 SDK 之间迁移

两套 SDK 都不会自动重试写入或保存恢复状态。更换语言不会改变租户权限、资源归属或已有 Session 的身份。跨客户端恢复同一提交时,保持 input、origin 和幂等键不变。

有界读取 Run 摘要分页

以下辅助函数要求已有可信后端客户端,读取的是租户级摘要端点,不是单 Session 的 Run 列表。返回 next_offset 非空表示达到页数预算,在观察到末尾之前停止。错误向调用方抛出;函数不发起写请求。
这里的 runs 是摘要,需要完整 input/output 时再调用 client.run(id)(TypeScript 加 await)。并发插入会移动 offset,因此本函数不是稳定导出,也不证明读取了每个 Run。返回的 next offset 是继续分页的提示,不是持久事件游标。事件重放应使用原 Run ID 和事件 after 契约。见列表语义与有界诊断示例。 接下来可阅读完整首个 Session、后端集成或事件与状态参考。