@aglit-ai/sdk
MIT授权SDK针对Aglit AI桌面API和工具运行时间进行建设.
- 需要本地运行的 Aglit AI 桌面应用/ API
- 类型安全
fetch桌面 API 的包装 - JSON-RPC 工具执行器
x_aglit_ai_tool_reason - 桌面 + 工具构建器 + 提供方 SPI API 的 OpenAPI 规格
您必须让 Aglit AI 桌面应用程序/ API 本地运行( 本地主机) 。 设定
SERVER_PORT编号 :PORT编号 :AGLIT_DESKTOP_BASE_URL视需要而定.
加密的私人网站内容
值得信赖的人 /_sites/bootstrap shell 可以制作一个普通的设备本地网站
而不将其 HTML,脚本,资产或HTTP API 机构暴露于网关:
import { createAuthenticatedSiteRuntimeFetch, mountEncryptedSite } from '@aglit-ai/sdk/browser';
const response = await fetch('/_sites/context', { credentials: 'same-origin', cache: 'no-store' });
if (!response.ok) throw new Error('Sign in to this site’s team');
const context = await response.json();
const runtimeFetch = await createAuthenticatedSiteRuntimeFetch({
deviceId: context.site.deviceId,
authenticatedEmail: context.user.email,
});
const surface = await mountEncryptedSite(document.querySelector('#site')!, {
siteName: context.site.name,
deviceId: context.site.deviceId,
agentId: context.site.agentId,
initialPath: new URLSearchParams(location.hash.slice(1)).get('path') ?? '/',
runtimeFetch,
});
// On teardown: await surface.destroy();
单干SDK site-worker.js 作为可信,认证
/_sites/worker.js,与 Service-Worker-Allowed: / 和一个 JavaScript 内容类型.
提供捆绑的外壳密码 /_sites/bootstrap.js壳,工人,
b. 环境与现有 /remote-access/api/... 终点仍受到其
犬形服务器认证和路由许可列表. 其他网站内容是:
仅通过生成 proxyPrivateSiteRequest 内部操作
已签名和加密的运行时频道。 裸露的现场饼干从不
替换频道.
该页面持有犬科终点密码;工人没有收到钥匙。 一个
内元信息Channel 绑定精确的顶层外壳, 单用初始 Iframe
导航,以及浏览器拥有的儿童客户端ID. 它返回解密的响应
当地到iframe。 它从不直接获取网站内容或存储内容
或缓存Storage、索引DB或服务人员缓存中的密钥。 答复使用情况
no-store 和同一来源的 CSP; 外部内容请求失败。 这个
工人只离开保留网关 /_sites/* 财务报告和审定财务报表 /remote-access/api/*
向现有的经认证的处理人员提出请求.
坚固的外壳必须活下来 一个封闭的外壳,拒绝会员资格, 缺少端点校验, 或者没有加密返回一个错误 而不是简洁的背面。 工人重新开始失去委托人监护权,所以贝壳 重新连接并重新装入新拥有的 Iframe 。 网站文件共享 来源和代码信任; iframe 是渲染表面, 没有 隔离 站点本身的脚本与其Aglit SDK能力之间的边界.
Shell 链接使用 /_sites/bootstrap#path=<encoded-local-path> 因此应用
路径和查询在工人导航时保持浏览器本地化。 保密 保密 保密
在工人控制页面之前输入的普通 URL 的首页
网络URL必然是路由元数据.
第一个版本支持被绑定的 HTTP 请求机构最多 1 MiB 和个人 不超过8个米B的响应。 无限媒体范围被限定为1个米B部分. 网站饼干、工人登记、外部资源、WebSockets和无限制 HTTP流不是由内容桥传输的. 使用直接的 WebRTC 下面原始的用于活应用/桌面视频和输入.
私人网站应用程序和桌面流
浏览器应用程序可以导入 @aglit-ai/sdk/browser 不装入本地
证书文件或IPC助手. 本地默认 SDK 条目仍然保留
桌面/服务器集成.
createDirectRemoteStreamTransport(binding, { baseUrl, runtimeFetch }) 连接
到已认证的WebRTC运行时间. mountAppStream, (中文(简体) ),
mountDesktopStream,以及 mountRemoteStream 提供框架中立的视频,
连接状态,和可选指针/键盘控制. 他们使用现有的
OpenAPI生成的信号路由和直通ICE/TURN介质,相同
aglit-input-reliable 财务报告和审定财务报表 aglit-input-volatile 输入频道为 Aglit .
import { createAuthenticatedSiteRuntimeFetch, createDirectRemoteStreamTransport, mountAppStream } from '@aglit-ai/sdk/browser';
// binding comes from your authorized backend's exact persisted game chat/window:
// binding: { agentId, deviceId, sessionId, streamId,
// target: { streamType: 'app', appId, windowId } }
const response = await fetch('/_sites/context', { credentials: 'same-origin', cache: 'no-store' });
if (!response.ok) throw new Error('Sign in to this site’s team');
const context = await response.json();
if (context.site.deviceId !== binding.deviceId) throw new Error('Game device changed');
const encryptedRuntimeFetch = await createAuthenticatedSiteRuntimeFetch({
deviceId: context.site.deviceId,
authenticatedEmail: context.user.email,
runtimeSessionId: binding.sessionId,
});
const surface = mountAppStream(document.querySelector('#game')!, {
title: "slurp's up!",
interactive: true,
transport: createDirectRemoteStreamTransport(binding, {
baseUrl: window.location.origin,
runtimeFetch: encryptedRuntimeFetch,
captureSpeakerAudio: true,
}),
});
await surface.connect();
// During component/page cleanup:
await surface.destroy();
对于桌面, 使用 mountDesktopStream 与
target: { streamType: 'desktop', displayId } 并省略 interactive。 。 。 .
此版本的桌面流只查看: 交互式桌面安装为
拒绝,直接传输则拒绝桌面控制/输入。 显示视频
像素可以不同于Retina上的逻辑原生坐标或缩放捕获;
桌面控制需要cononic验证的逻辑显示范围映射.
提供真正的持续聊天
、 原始注册设备, 以及精确列出的应用程序窗口或
显示后端授权的显示。 ID 选择一个目标; 他们从来不允许访问 .
原始人不会推出应用或创建账户,团队,或设备赠款.
createAuthenticatedSiteRuntimeFetch 通过已有的浏览器录入此浏览器
运行时间 auth/ key 流量 。 从经认证的账户和设备获取
/_sites/context,从不要求URL。 它重新使用可重复的可复制浏览器
密钥、设备身份验证和现有有管理的指针或指纹
证实UI。 请求通过配置的计算机验证代码
一个真正的代码对话框; 被拒绝的访问和 API- key 要求仍然失败 .
分开的现场饼干只留下来 没有 cookie 或设备密钥被复制到
应用程序 JavaScript. 可选 runtimeSessionId 是一个已有的任务/聊天
用于选择服务运行时生成; 认证流分配自己的
单独的加密会话.
结果 经认证、加密的运行时间 接收未更改的
生成 /remote-access/api/... 网站的 URL
源代码。 网站网关保存其准确路径和查询,包括
URL绑定的加密证明;它从不重写在另一个API前缀后.
通过普通 fetch 使用站点 cookie 不确定运行时间
届会。 本地没有宽 SDK 令牌、 浏览器 cookie 导出或提供者终止
媒体倒置被引入.
适配器在精确的加密字节和URL上签有"Cononic v2"的证明, 然后只接受经认证的非限制性成功答复。 它有一个 账户/设备范围每页; 账户、设备或证书更改后重新加载.
App 输入默认关闭 。 与 interactive: true,用户明确选择
掌权 在授权的直接输入通道打开后。 指针输入
被映射到包含的视频而不是其信箱。 默认模式
发送犬科完整 keyEvent: press 手势,包括
浏览器键盘重复,并在指针上完成点击或左键拖动
释放。 中断的指针手势在当地被取消. 从不离开
原生密钥或按钮等待从已消失的取景器中释放出后.
对于需要连续移动的游戏,明确设置 keyboardMode: 'hold'。 。 。 .
连接然后需要实际包装的本地助手的广告应用
握有钥匙的能力。 它发送现有 down编号 :up 一个事件 keyHoldId
每一实际持有; keyHoldRenew: true 更新保留了这种身份,从不重复按键
召回电话。 同时键保持并存. 更新运行每250 ms
只当视频有焦点时,页面可见,而这个表面有控制.
模糊,隐藏的页面,按键上下拆解在发送发布前停止更新.
在本地入境前已排出/ 更新的包已过期; 无法续签
创建一个控件。 原生倒置/更新也需要保留被捕获的窗口
未来应用的精确焦点窗口, 不聚焦或改变窗口.
本地的帮助者拥有一个独家的应用键盘拥有者 每个进程,
被捆绑在过程的诞生 并承认准确的窗口。 应用输入和全局
来自另一个查看器的键盘事件无法释放或中断这些键.
现有授权的桌面指针控制可能改变焦点; 停止应用
键更新。 缺失的更新将到期 其两秒本土
租赁,每100米检查一次;帮助者EOF/有秩序地关闭也放行. 清理使用
抓取的进程身份,从不聚焦或解决替换应用程序.
过期/解除扣留的身份证不能被重新扣押。 旧运行时间
拒绝控件模式;它们继续支持取景并完成压力.
原生活化和真正的游戏接受仍然需要新的被签名的帮助.
突然帮助崩溃、SIGKILLL或已中止的本地进程无法进行清理;
到期保障要求当地援助者保持预定时间和健康.
直播按钮控件拖放和独立的修改器拖放仍然不支持 .
音频开始变音以遵守浏览器的回放要求; 网站可以曝光
使用 surface.video.muted。目前所有观众共享
相同运行的应用程序和玩家状态。 本地控件模式允许一个输入拥有者, 而
键被持有; Kake 控制按钮本身不赋予额外权限 .
打电话 surface.destroy() 卸载以中止信号,取消待输入,以及
只删除此精确的查看器会话。 认证/信号失败会关闭
pal; 在恢复授权的运行时会话后创建新的表面.
提供创建和当地的社民党准备状态在全部内分开
60秒启动最后期限,匹配网页浏览器的浏览器兼容路径.
见 examples/site-game.ts 为最小的游戏包装.
安装
pnpm add @aglit-ai/sdk
# or: npm install @aglit-ai/sdk
快速启动( TypeScript)
import { createDesktopClient, executeTool } from '@aglit-ai/sdk';
const SERVER_PORT = process.env.SERVER_PORT ?? '49117';
const baseUrl = `http://127.0.0.1:${SERVER_PORT}`;
const agentId = 'root-agent';
const desktop = createDesktopClient({ baseUrl });
// Call REST endpoints (typed from OpenAPI)
const tasks = await desktop.GET('/tasks');
console.log(tasks.data?.tasks?.length);
// Execute tools via IPC (requires x_aglit_ai_tool_reason)
const response = await executeTool({
agentId,
request: {
jsonrpc: '2.0',
id: 'sdk-run-terminal',
params: {
name: 'p1_terminal',
arguments: {
action: 'open',
x_aglit_ai_tool_reason: 'SDK example: open terminal via IPC',
},
},
context: {
sessionId: `sdk-terminal-${Date.now()}`,
agentId,
},
},
});
console.log('tool response', response.data?.result);
快速启动 (JavaScript)
const { executeTool } = require('@aglit-ai/sdk');
(async () => {
const response = await executeTool({
agentId: 'root-agent',
request: {
jsonrpc: '2.0',
id: 'sdk-ipc-example',
params: {
name: 'p1_todo',
arguments: {
action: 'list',
x_aglit_ai_tool_reason: 'SDK IPC example: list todos',
},
},
context: {
agentId: 'root-agent',
sessionId: 'sdk-ipc-session',
},
},
});
console.log(JSON.stringify(response, null, 2));
})();
IPC 工具执行
本地工具执行运行于 IPC 经纪人之上, 所以回回回路上没有未经认证的 HTTP 表面 .
如果您将 IPC 配置存储到自定义的某处, 设置 AGLIT_SDK_IPC_CONFIG_PATH 因此( 默认 :
<user-data>/ipc/sdk-ipc.json时 <user-data> 实值 ~/Library/Application Support/Aglit AI/ (原始内容存档于2018-09-28). on macOS.
在macOS上,SDK线路通过一个签名的助手请求进入XPC经纪人. 经纪人只接受
信任的应用程序的请求, 如果新应用程序请求访问, 则会在桌面应用程序中提示 。 套接字
结束点从未写入磁盘 。 用于地方发展 AGLIT_SDK_XPC_ONLY=0 保留遗产
套接字配置 .
总是包含 x_aglit_ai_tool_reason 并传递结构化的参数,而不是生壳字符串。 IPC经纪人
也执行UI中看到的相同的工具政策,包括批准流和记录.
从 Aglit 聊天终端继承开始的脚本 AGLIT_AGENT_ID, (中文(简体) ), AGLIT_SESSION_ID,以及
AGLIT_SDK_MODULE_PATH。将捆绑的 SDK 装入 require(process.env.AGLIT_SDK_MODULE_PATH)
以避免旧的工作空间副本. executeTool 自动使用所继承的会话ID; a
明确请求 _meta.sessionId 以优先为准.
实例
SDK飞船即时运行的通用自动化表面实例. 总是包含 x_aglit_ai_tool_reason 解释为什么使用这一工具.
终端命令
await executeTool({
agentId: 'root-agent',
request: {
jsonrpc: '2.0',
id: 'open-terminal',
params: {
name: 'p1_terminal',
arguments: {
action: 'open',
x_aglit_ai_tool_reason: 'SDK example: open terminal',
},
},
context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
},
});
await executeTool({
agentId: 'root-agent',
request: {
jsonrpc: '2.0',
id: 'type-ls',
params: {
name: 'p1_terminal',
arguments: {
action: 'type',
windowId: '<window-id-from-open>',
text: 'ls -la /tmp',
submit_command: true,
x_aglit_ai_tool_reason: 'SDK example: list temp files',
},
},
context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
},
});
浏览器自动化
使用SDK兼容适配器进行结构化浏览器动作. 适配器执行
仅限 p1_codex_browser 登记电话,保留聊天授权和批准,
并返回准确的本地标签 ID。 页面评价为只读; 使用本地
点击/填充动作以更改页面.
import { executeNativeControl, unwrapNativeControlResult } from '@aglit-ai/sdk';
const call = (args: Record<string, unknown>, reason: string) => executeNativeControl({
toolName: 'p1_codex_browser', agentId: 'root-agent', sessionId: 'sdk-browser', args, reason,
});
const nav = unwrapNativeControlResult(await call(
{ action: 'navigate', url: 'https://example.com' }, 'Open example.com'
));
if (!nav?.tabId) throw new Error('Native browser returned no exact tab ID');
await call({ action: 'execute_javascript', tabId: nav.tabId, code: 'document.title' },
'Read the page title');
创建聊天会话
import { createDesktopClient } from '@aglit-ai/sdk';
const desktop = createDesktopClient({ baseUrl });
const chat = await desktop.POST('/chats', {
body: {
agentId: 'root-agent',
initialText: 'Say hello from the SDK',
},
});
console.log('chat id', chat.data?.chat?.id);
运行组合示例
请确定桌面应用程序/ API 正在本地运行, 然后 :
pnpm --filter @aglit-ai/sdk run build # if you haven't built yet
pnpm --filter @aglit-ai/sdk run test:examples
通过环境配置 :
AGLIT_DESKTOP_BASE_URL(管理主机/端口)SERVER_PORT或者说PORT(默认 49117 prod; 49217 为本地 dev)AGLIT_AGENT_ID(默认)root-agent(中文(简体) )
OpenAPI 光谱
SDK 解析当前 OpenAPI 源文件 @aglit-ai/types数字 :
- 桌面 API :
@aglit-ai/types/schema/api.openapi.yaml - 工具构建器 API :
@aglit-ai/types/schema/tools-api.openapi.yaml - 提供方 SPI API :
@aglit-ai/types/schema/provider-spi.openapi.yaml
本土控制移徙
executeNativeControl({toolName, args, reason, agentId, sessionId}) 调整结构
自定义工具浏览器/应用程序动作 p1_codex_browser 财务报告和审定财务报表 p1_codex_computer现有
本地执行/抓捕/流/焦点呼叫通过. 退休的身份证仍然被拒绝.
import { executeNativeControl } from '@aglit-ai/sdk';
const result = await executeNativeControl({
toolName: 'p1_codex_browser',
args: {action: 'navigate', url: 'https://example.com'},
reason: 'Open the requested example page',
agentId, sessionId,
});
适配器保存精确的本地目标, 保存打字/ 提交标记, 返回原始
证明和熟悉的结果字段,永远不要重放不确定的变异。 页面评价
只读。 授权 DOM 输入计划使用 aglitNativeClick(element) 财务报告和审定财务报表
aglitNativeFill(element, text) 检查期间;适配器执行这些行动
之后通过本地输入 API. 不使用页面突变,CDP或终端倒置.
本地自定义运行时间包这个相同的SDK适配器,所以不需要新的SDK依赖.
原生控制仍然需要代理商现有的不受限制的剖面图和明确 进入。 上传/备案权限仍然是单独的本地赠款。 下载返回已保存 直接路径; 旧的下载进度流 ID 不支持。 App 窗口请求为 根据输入前的私人捕获收据进行核查;模棱两可/匹配目标 失败。 被编码的录音和一些遗留下来的只使用桌面的API没有本土的等效.
建设和部署
运行 pnpm run build 在此之前 pnpm run deploy. 部署需要汇编
输入点和捆绑的 OpenAPI 计划,然后发布已经建成的 SDK
使用 package.json 和现有的登记册全权证书.
部署不会重建、突起版本或启动交互式登记册登录.