@ arbidocs/ sdk

ARBI平台的TypeScript SDK. 处理认证,工作空间加密,并流出AI查询.

从下起. 完整 开发者快速启动 财务报告和审定财务报表 兼容表 还在 npm 包件中 node_modules/@arbidocs/sdk/docs/;不需要访问仓库.

快速启动

npm install @arbidocs/sdk

import { Arbi } from '@arbidocs/sdk'

const arbi = new Arbi({ url: 'https://your-arbi-deployment.example' })
await arbi.login(email, password)
await arbi.selectWorkspace(workspaceId) // an explicit choice
const response = await arbi.responses.create({ input: 'Say hello in one sentence.' })
console.log(response.output_text)

只浏览器代码导入相同的 API @arbidocs/sdk/browser。对于已实现的聊天,请使用基本反应实例或网站iframe。 Node.js不需要索引DB多填充. SDK 实例的密钥会留在内存中, 除非您提供明确的持久性适配器 :

import { Arbi } from '@arbidocs/sdk'

添加聊天部件

安装的SDK包括一个独立的回放启动器(在包含此指南的发布中):

cp -R node_modules/@arbidocs/sdk/examples/react-chat ./my-arbi-chat
cd my-arbi-chat
mv gitignore .gitignore
npm install
cp .env.example .env
# Set the public VITE_ARBI_URL, then:
npm run dev

在部件内签名并明确选择工作空间。 要部署,跑 npm run build 服务 dist/ 作为静态网站。 从不把证书放进去 VITE_ 变量。 部署 必须允许此应用程序的 API 调用 。 该应用程序使用 @arbidocs/blocks/embed匹配 已提供软件包版本和样式表设置.

使用前端部署主机面板:

<iframe src="https://YOUR-ARBI-FRONTEND/embed/chat" title="ARBI chat"
  style="width:380px;height:640px;border:0" allow="clipboard-write"></iframe>

面板拥有登录和工作空间选择权. 您的部署必须允许主机站点设定框架 此路由; 父 CSP 必须允许前端进入 frame-src。这是经过认证的 工作空间聊天。 嵌入式存储限制可以要求单独签入.

生命周期

const arbi = new Arbi({ url: 'https://www.arbidocs.com' })

await arbi.login(email, password)            // or arbi.loginWithKey(email, keyBase64)
await arbi.selectWorkspace(workspaceId)
// ... use the SDK ...
await arbi.logout()

业务

处理人工智能查询

const stream = await arbi.responses.create({ input: 'What does section 3 say?', stream: true })
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') console.log(event.delta)
  if (event.type === 'response.failed') console.error(event.response.error)
}

现有的召回整合

assistant.ask 继续支持和使用 /v1/responses。新的整合可以从 responses.create 上; 当您的 UI 已经使用时, 请保留调用助手 .

const result = await arbi.assistant.ask(
  {
    question: 'What does section 3 say?',
    docIds: [docId],
    previousResponseId: lastMessageId, // for multi-turn conversations
  },
  {
    onToken: (token) => { /* append to UI */ },
    onStreamStart: ({ assistant_message_ext_id }) => { /* save for follow-ups */ },
    onOutputItemDone: (event) => { /* an agent step settled */ },
    onError: (error) => { /* the server's report (string) or the connection (Error) */ },
    onComplete: () => { /* done */ },
  }
)

// result.text — full accumulated response
// result.assistantMessageExtId — use as previousResponseId for follow-ups

转换到哪个工作空间

转一圈 workspaceId (默认:当前工作空间),当 ask 或者说 startResponse 在请求中被调用并命名,所以在请求时使用工作空间切换 发送不能移动它 。 为本届会议开放一个不属于当前的工作空间 首先(其密钥已保存;当前工作空间不变)。 后续运行在 其线程的工作空间: 如果服务器用 409 拒绝了它 workspace_mismatch,转弯 被再次发送到那里 onWorkspace(workspaceId) 报告是否被接受. 409号 workspace_key_required 重新保存密钥并重发一次。 当 无法打开工作空间, 无法发送任何信息, 并且拒绝呼叫 ArbiWorkspaceUnavailableError。 。 。 . workspaceConflictOf(error) 改为409. assistant.submit 财务报告和审定财务报表 assistant.retrieve 带 workspaceId 同样的方式.

哪个工作空间其他呼叫在

事实facts.create, (中文(简体) ), createBatch, (中文(简体) ), list, (中文(简体) ), search),对话 (单位:千美元)conversations.list, (中文(简体) ), search, (中文(简体) ), createWork, (中文(简体) ), plan, (中文(简体) ), assistant.listSkills, (中文(简体) ), files.list 财务报告和审定财务报表 files.upload 在当前工作空间或 workspaceId 选项,它首先为本届会议开放,而不成为当前. 无论哪种方式,请求都给工作空间取名(workspace_ext_id),所以一个开关同时它是 发送不能移动它 。 音符、任务或由 id 更改的谈话会自行更改 工作空间,服务器来自它。 拒绝工作空间(409个) workspace_key_required,或 workspace_mismatch 用于父母在 另一个工作空间)是 ArbiApiError 与那个 code说什么都没救.

会话恢复

浏览器坚持索引DB中加密的签名密钥. 没有索引DB,每个SDK客户端都会在内存中保存自己的密钥;它不会与其他实例共享,也不会被保存到磁盘上. 恢复没有密码的会话 :

await arbi.loginWithKey('[email protected]', signingKeyBase64)

SDK还使用存储的密钥对401个响应进行自动回收.

警卫

• 零知识认证 ——密码从不离开客户端
• E2E 工作空间加密 ——用公用钥匙包裹的对称密钥
• 加密密钥存储 —— IndexedDB 中的私密密钥加密,不可提取 AES-GCM
• 会话清理 ——登录结束活的会话;存储的身份支持下线解锁,默认存储在每次登录时清除

反应

用于反应应用程序, 使用 @arbidocs/react 相反,它用钩子和一个上下文提供者包裹着这个SDK. 见 @ arbidocs/ react README (中文)。 。 。 .

所需资源

• 浏览器: 任何带有 Web Crypto API 的现代浏览器
• 节点.js: 本地取取/Web Crypto 运行时间; 节点22+被可执行示例和包烟检查使用( 否) fake-indexeddb (所需)
• 类型脚本: 5.0+(可选)

自动化

这个 workflows 命名空间显示创建/获取/列表/更新/删除/运行 listWorkflowRuns。触发器使用时间表或通知类型;每个保存的规则也可以立即运行。 文件行动( A)annotate_documents 或者说 email_documents)返回执行引用而不是对话. 其持续的历史包含一些选定的文件、运行标签引用、结果元数据和失败;注释答案仍然是文件字段。 每一次执行都有WorkflowRuns记录;聊天动作也链接到对话.

import { workflows } from '@arbidocs/sdk'
const run = await workflows.runWorkflow(arbi, 'wfl-example')
if (run.error) throw new Error(run.error)
if (run.execution_id) {
  const history = await workflows.listWorkflowRuns(arbi, 'wfl-example')
  console.log(history)
}

文档选择者可以指定执行时解决的ID,标签,或者 latest 文档。 未出席的文档动作需要拥有常态工作空间访问权限的助理;创建规则不会给予该访问权限.

对于最新文件摘要,第一次运行覆盖前24小时;后次运行使用前次成功运行截止. 交付失败不会推进。 电子邮件中包含文档名称和认证的平台链接,没有附件.

释放

出版的版本列于 无。 。 。 . 拥有寄存器访问权限的维护者也可以读取详细的GitHub发布注释.

错误和流出结果

SDK HTTP 故障保留其结构化服务器机体 ArbiApiError.apiError, (中文(简体) ), 与 status, (中文(简体) ), detail选择 code, (中文(简体) ), requestId,以及 responseId。 。 。 . AssistantTurnRefused 仍为 ArbiApiError 何时 ask() 拒绝。 网络 失败使用 ArbiTransportError 并保留原件 cause; 本地语 AbortError 物体传播不变.

ask(), (中文(简体) ), attachRun(),以及 streamSSE() 保留现有的回调和结果 字段。 添加 onErrorDetails(error) 以检查输入错误和遗留错误 onError 回话,和 onOutcome(outcome) 以观察终端结果。 SDK 软件 流出结果还包括: outcome 财务报告和审定财务报表 errorDetails。结果保持 现有助理 msg- 标识符和原始终端 response 载荷. 它的地位是 completed, (中文(简体) ), failed, (中文(简体) ), cancelled, (中文(简体) ), incomplete, (中文(简体) ), disconnected,或 acknowledged。只有控制方的确认没有反应身份。 这个 遗产 completed 布尔表示收到 response.completed· ; 使用情况 outcome.status 以区分服务器的明确终端状态.

本地中止或断开连接报告 disconnected,与 reason aborted, (中文(简体) ), connection_closed,或 connection_error从来没有证明 服务器已取消执行 。 读者拒绝失败并通知 结果。 明确的终端服务器事件完成阅读而不等待 连接到关闭 。 第一个终端框架获胜:后期框架,包括 在同一块中相互冲突的终端或符号会被忽略。 背景反应 APIs 继续曝光原作 答复信封及其 status 财务报告和审定财务报表 error 字段.

消费者的回调例外没有改变。 他们不会触发一秒钟 输入出错或结果通知,而不归为服务器故障 或运输中断. onOutcome 当 SDK 消费达到时一次起火 (a) 结果 通知.

可编译的响应手柄

assistant.startResponse(request, { signal }) 使用相同的请求构建器和工作空间 选择为 ask。它会返回一个对当前 msg-… 答复,或 控制确认而不创建消息。 现有 ask,召回,和 attachRun 继续支持.

const started = await arbi.assistant.startResponse({ question: 'Summarize this document', docIds })
if (started.kind === 'response') {
  const handle = started.handle
  const unsubscribe = handle.subscribe((snapshot) => render(snapshot.displayText))
  try {
    const outcome = await handle.outcome
    if (outcome.status === 'disconnected') {
      const stored = await arbi.assistant.getResponse(handle.id)
      // Inspect stored status; attachResponse(handle.id) again if still active.
    }
  } finally {
    unsubscribe()
    handle.detach()
  }
}

使用 await handle.cancel() 用于明确认证的服务器注销请求. detach() 而可选的中止符号只关闭此读取器。 取消请求确实如此 未将控件解析为已取消: 终端服务器事件决定结果 。 工作空间 而本地代理权限继续由服务器执行.

attachResponse('msg-…') 观测现有的监视流,并保留其范围; a 404需要储存反应/历史核对。 处理不重试或重连接 背景,且附件的断开结果并不意味着服务器执行已停止 .

快照及其输出项目不可改变. 订阅立即收到当前 快照,包括快速完成。 快照收听器中的例外在微任务中重播 没有阻止读者或其他听众。 未知的服务器状态和原始终端结果 被保留下来. displayText 是现有的渲染投影,而不是最后的答案选择器.

handle.events() 提供 一个活生生的活路人,从呼叫开始。 它保存未知数 JSON事件/现场和SSE身份证; reasoning 框保留其原始文本。 错误的 JSON 和 生成冲突反应ID arbi.sdk.protocol_error 诊断与原始框架. 这不是回放或持久恢复光标 。 每次都保留已有的回调 需要启动框架。 最多256个框架的延展缓冲器,涵盖现有工具和 控制固定装置; 溢出拒绝用代码读取 RESPONSE_EVENT_OVERFLOW,同时快照 继续减少。 返回/ 打破执行器以释放其缓冲; 拒绝第二个执行器 .

节点示例和软件包检查

运行 实例/节点响应.mjs 安装后使用节点 22+ @arbidocs/sdk (单位:千美元)node node_modules/@arbidocs/sdk/examples/node-response.mjs) (中文(简体) ). 设定 ARBI_URL, (中文(简体) ), ARBI_EMAIL, (中文(简体) ), ARBI_PASSWORD 财务报告和审定财务报表 ARBI_WORKSPACE_ID· ; ARBI_QUESTION 是可选的。 它明确选择当前的工作空间, 提交一个回复 转动,区分断开与补全,并切换一个被接受的响应,而不是 重新报到 Ctrl-C解析了阅读器;它并不声称取消背景执行.

默认节点存储仅持续该客户端实例 。 为了在重启过程中保持持久性, 通过 persistence: { getSession, saveSession, clearSession } 改为 Arbi 或者说 createArbiClient。 。 。 . 现有 SessionPersistence 保留接口; clearSession 对现有 适配器,在提供时在任何地方都通过登录引用。 在任何自定义持久中保护密钥 存储。 正常登录保留已存在的离线-解锁行为的存储身份; 在所有清除默认内存适配器的地方登录 。 浏览器加密存储未变 .

仓库维护者可以运行 node scripts/sdk-node-smoke.mjs 在建立客户端和SDK之后. 它包了两个包,在新的临时npm中安装了他们的柏油球/运行时的依赖性 消费者,检查无害环境管理/共同JS/浏览器/测试进口品,并进行关键登录、回收和 对本地的假捕捉器的反应 它需要 npm 登记依赖性, 不部署 证书,没有索引 DB 多填。 它验证软件包/运行时的行为,而不是后端访问 控制或现场部署集成.

配置 HTTP 运输

React Query仍然管理 React 缓存,突变和还原. 地下的SDK运输 它可以配置一次,用于输入请求、响应流和多部分 API 上传:

const arbi = new Arbi({
  url: 'https://arbi.example.com',
  transport: {
    fetch: customFetch, // optional fetch-compatible adapter
    timeoutMs: 30_000, // optional; no deadline by default
    onResponse: ({ method, url, status, durationMs }) => {
      recordRequest({ method, url, status, durationMs })
    },
  },
})

对于主机主机会话,配置 transport 打开 createArbiClient 将客户端传递给 Arbi;其包装会继承主机运输和会话门. 在主机上配置它, 而不是为包装提供不同的运输工具。 现有的主机客户端适配器 无 http 保留之前用于原始 SDK 操作的 Global-fetch回扣 .

超时持续到适配器返回 a Response: 本地取回的响应头, 或 XMLHttp 请求上传进度适配器的缓冲回复。 它没有盖住一个活 溪来之体. 停止签名取消和签出 仍然停止身体 之后标题. 元数据钩子接收方法、消毒的URL(没有查询、片段或证书)、状态和 时间已过;没有标题或尸体被传递. onError 收到原始获取失败. 钩子是选入并同步的;一个被丢弃的钩子例外拒绝了请求. 无遥测 或默认启用日志.

默认浏览器上传保留了 XMLHttp 请求字节进度 。 被注入的获取优先 上传完成一次,而不是预示字节的进展。 现有 预签名存储 PUT 适配器、 公共预订辅助器、 媒体下载和 WebSockets 分别使用 运输,不因API-运输选项而改变.

连接失败仅针对生成的 GET/ HEAD 请求进行重试, 且已有的界限 备份。 突变和反应生成在模糊的连接失败后再也没有重复过. 现有的明确认证/工作空间状态拒绝追偿办法仍保持不变 已配置运输 。 此选项没有添加工作空间选择器、 标题、 权限或切换 .

经核实的结构化反应

const format = {
  type: 'json_schema' as const,
  name: 'invoice',
  strict: true,
  schema: {
    type: 'object',
    properties: { total: { type: 'number' } },
    required: ['total'],
    additionalProperties: false,
  },
}
const response = await arbi.responses.parse<{ total: number }>({
  input: 'Extract the total from: Invoice total 125.50',
  text: { format },
})
// response.output_parsed.total is validated; output, usage and metadata are retained.

一样 text 选项为 ask, (中文(简体) ), startResponse 和背景情况 submit。 。 。 . 对于流/背景工作,保留格式并验证已完成的资源 await parseStructuredResponse(response, format)现场JSON碎片是暂时的. 解析器期望有一个最后的助理输出消息; 它不加入描述和回答 信件或处理 metadata.content 作为标准产出项目的替换.

无效的 JSON 、 计划错配、 拒绝、 不完整/ 无效/ 非永久性反应和无效 计划有不同的错误代码. ArbiStructuredOutputError.response 保存原始内容 答复; 请求/答复识别码仍然可用。 没有类型的强制, 默认插入, Markdown 进行修理或自动重新提交。 TypeScript 通用描述您的计划 形状;运行时验证来自JSON Schema,而不是通用参数.

Schemas使用2020-12草案和地方参考;格式说明不坚持. 客户端 验证按要求加载Ajv,并使用运行时间编译,同时禁用日志. 禁止运行时间政策 编译生成 STRUCTURED_OUTPUT_VALIDATOR_UNAVAILABLE 发送请求前; 原始 没有此客户端解析器, 仍然可以通过现有的API提供服务器验证的回复 .

需要后端结构化输出能力. 它验证了现有的模型/代理循环 最后的答案不改变工作空间,身份或工具权限. 土著代理人和 无法履行合同的斜线/委托路径明确拒绝 STRUCTURED_OUTPUT_UNSUPPORTED他们从不默默地忽视它 其他请求字段和旧 召回消费者保持他们现有的行为.

熟悉情况的反应行动

const response = await arbi.responses.create({ input: 'Hello', model: 'cfg-my-config' })
console.log(response.output_text)
const stream = await arbi.responses.create({ input: 'Hello', stream: true })
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') process.stdout.write(event.delta)
}
const queued = await arbi.responses.create({ input: 'Review this', background: true })
const current = await arbi.responses.retrieve(queued.id)

当前的工作空间提供ARBI的工作空间背景. workspace_ext_id 是一个线层 根据已有的服务器检查,它不会切换会话或允许访问. create 财务报告和审定财务报表 retrieve 保留信封的输出、元数据、使用和终端状态,并添加 a 一个 output_text 方便场. create 还揭露 _request_id 当服务器提供时 这个 JSON 回复失败仍是回复失败;检查 status 财务报告和审定财务报表 error。 。 。 .

create({ stream: true }) 返回带有标准的事件的同步可移动性 type 歧视者. 现有的信件观察者从第一个帧缓冲事件并应用回压,所以 快速回复和缓慢的消费者不会失去开始。 迭接被断开 读取器; 失败/不完整的终端帧仍可视为事件 。 打破迭代断层 读取器并让服务器执行运行。 明确取消用途 responses.cancel(id)。 。 。 . 可选 stream.handle 揭露ARBI的快照,结果,拆分和取消.

现有 responses.stream 财务报告和审定财务报表 assistant.startResponse 方法仍然返回 ARBI 控件 (或斜指命令确认). 使用这些助手执行控制命令. 流出背景 创建当前不支持并拒绝 HTTP; 创建方式 background: true,则 使用情况 responses.attach(id) 用于当前重播/直播事件。 一个 con- 包含很多 msg- 回应.

对于结构化成果, responses.parse<T>({ input, text: { format } }) 返回时 output_parsed 并行 output_text 和原始输出字段。 它在发送前验证了 JSON Schema 一个同步请求; 失败/ 反驳/ 不完全结果抛出现有的结构错误 . Schema为平原JSON Schema,并非Zod特有帮手. assistant.parseResponse 编辑 独立 parseStructuredResponse 继续支持现有消费者。 这些 SDK 模式 跟随官员 反应流程指南 财务报告和审定财务报表 结构化产出指南。 。 。 .

兼容性是指所记录的 /v1/responses 子集,而不是每个 OpenAI 的下放支持, Anthropic或Vercel的特征. 输入当前是一个字符串; 工具上下文使用 ARBI 所记录的工具 地图。 认证、cfg选择、agt身份、工作空间赠款和推迟执行仍然有效 ARBI合同. 本地功能工具和任意提供方选项没有得到实施. 见后端 docs/responses-api.md 用于精确支持的字段.

组成一个已有的配置

从配置开始 agentConfig.get(configId) 因此省略的设置保留 他们的当前价值。 没有帮助创建身份,授权或联系MCP服务器.

import { composeConfiguration, instructions, capabilities, mcpTools,
  documentTools, composeTools } from '@arbidocs/sdk/browser'

const existingConfiguration = { ...await arbi.agentConfig.get(configId), title: 'Evidence review' }
const updated = composeConfiguration(existingConfiguration,
  instructions('Answer with evidence.'),
  capabilities({ webSearch: true, codeExecution: false }),
  mcpTools(existingConfiguration, ['approved_search'], 'add'))
await arbi.agentConfig.save(updated)
const tools = composeTools(existingTools, documentTools({ search: [documentId] }), 'add')
await arbi.responses.create({ input: 'Summarise the evidence', tools })

配置部分合并一个级别; 数组替换; 明确无效清除 。 MCP和反应工具 帮助者需要明确 add 或者说 replace 选择。 添加工具时替换同名 保存其他名称。 指令既适用于QueryLLM,也适用于内置代理人a. 普通类 cfg- 配置不需要 agt- 身份证明 将配置固定为 现有代理人使用现有 agent_ext_id授权其任务仍然是一项单独的行动.

选择公共层

现有的出口品仍然可用。 通过已记录的软件包条目导入域帮助器; 从不导入 src/ 生成 dist/ 内出. 反应查询钩头使用相同的会话和 请求构建器作为 SDK; 应用程序不需要另一个聊天引擎.

发表 examples/ 目录包含 node-response.mjs, (中文(简体) ), stream-response.mjs, (中文(简体) ), background-response.mjs 财务报告和审定财务报表 structured-extraction.mjs。 。 。 . response-handle.mjs 显示可选 ARBI生命周期控制. 安装软件包, 设置所记录的环境变量 examples/session.mjs,并使用节点22+. 背景检查接受现有答复 身份证明并不会自动重新提交。 测试可以导入 frame 财务报告和审定财务报表 createSseFake 从 /testing 以不部署进行流程(见导出助手签名).

检查设置

运行 await arbi.diagnose() 或者说 arbi doctor --json 检查部署、会话和当前工作空间 设置时不登录,不切换工作空间或授予访问权限. 见包装 诊断指南。 。 。 .

人文审查

一个可操作的例子: node_modules/@arbidocs/sdk/examples/human-review复制到本地 文件夹, 重命名 gitignore 改为 .gitignore,安装依赖关系,配置 .env运行 npm start -- start。示例打印了现有的对话ID并命令检查, 并明确批准该草案。 它恢复了相同的工作流程对话 使用现有的步骤 API 处理。 见其 读取。 。 。 .