@ ceslestoai/ sdk

使用此软件包在 Celesto 从一个 Node.js app 运行工作 。 您的代码可以创建 云计算机,在其中运行命令,工作完成后删除.

AI代理是能够计划和运行任务的软件. 绳子是密码 启动、测试或监督代理人.

要使用此软件包时 :

• 在干净的电脑上运行一个人工智能代理或操纵器.
• 从 JavaScript 或 TypeScript 运行 shell 命令 .
• 保持代理工作与你的笔记本电脑、服务器或生产系统分开.
• 为每个用户运行一个代理,每个用户开支限额.
• 要求用户通过守门员批准Google Drive的访问权限.

守门员是塞莱斯多的出入口助手. 它让用户批准哪个外部 您的应用程序可以使用的文件或文件夹 .

所需资源

• 节点.js 18或更新.
• 来自 Celesto API 密钥 Celesto 设置 下级 设置 > 警卫。 。 。 .

安装

npm install @celestoai/sdk

签一次Celesto CLI:

pip install celesto
celesto auth login

这个 Computer API 检查明确通过的 token 或者说 apiKey 先说 CELESTO_API_KEY 在外壳中,当前工程的 .env,并保存证书 celesto auth login。您可以使用本地语言 .env 代替CLI:

CELESTO_API_KEY="your-api-key"

添加 .env 改为 .gitignore。 。 。 .

快速启动

创建名为的文件 quickstart.mjs数字 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create();
try {
  console.log(`Computer ready: ${computer.name}`);

  const result = await computer.run("uname -a");
  console.log(result.stdout);
} finally {
  await computer.delete();
}

运行它:

node quickstart.mjs

为您的用户运行代理

如果你在人工智能代理之上制造产品 每一次运行都会发生 联 合 国  用户。 Celesto 把它们分开: 每个运行都记录在用户的名下 它的作用,所以你可以看到 那个人的代理人做了什么,花费 停止它花费超过你允许的.

您用您已有的字符串识别您的每个用户 —— 数据库ID, 电子邮件,任何东西。 塞莱斯托在你寄来的时候就储存起来 没有 Celesto 用户 要抬头看的身份证, 没有地图表可以保存 .

此示例创建代理, 为一个用户运行, 打印答案 到了,然后读了用户的支出.

import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });

const agent = await celesto.agents.create({
  name: "support-bot",
  model: "openai/gpt-5.4-mini",
  instructions: "Answer order questions in one short paragraph.",
});

for await (const event of celesto.runs.stream(agent.id, {
  input: "Where is my order?",
  endUserId: "usr_8837",
})) {
  if (event.name === "message.delta") process.stdout.write(event.data.text ?? "");
}

const { budget } = await celesto.endUsers.get("usr_8837");
console.log(`\nSpent ${budget.spentUsd} of ${budget.capUsd}`);

正在打开 event.name 缩小事件,所以 event.data 输入为 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}没有别的.

等待而不是流

stream() 给您答案,因为它是写. create() 等着给你 完成运行 :

import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const run = await celesto.runs.create(agentId, {
  input: "Where is my order?",
  endUserId: "usr_8837",
});
console.log(run.output, run.usage.costUsd);

钱 是一个字符串

每一数额 -- costUsd, (中文(简体) ), spentUsd, (中文(简体) ), capUsd - 是小数字符串,例如 "0.000450"从来没有 number单一个答案可以花费几百万分之一 美元, JavaScript 数字不能准确持有。 显示和比较 字符串; 如果您需要算术, 请使用小数库而不是 parseFloat。 。 。 .

写作也是弦. budgetCapUsd 输入 string,因此数字失败 编译,通过一个反正扔,而不是寄出去—— 0.1 + 0.2 字符串为 "0.30000000000000004",唯一一个仍然可以 固定在离开程序之前.

设置支出限制

给一个用户一个盖子, 或者为每个人设置默认值 :

import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });

await celesto.endUsers.update("usr_8837", { budgetCapUsd: "5.00" });
await celesto.settings.update({ defaultEndUserBudgetUsd: "0.50" });

盖盖覆盖一个开始用户第一次运行的30天窗口 任何东西。 当它耗尽时, 下一跑抛出 BudgetExceededError运行 已经在飞行中停了下来 run.failed 活动.

安全重试

过 idempotencyKey 使重试安全:再次发送相同的密钥返回 已经发生的运行 而不是运行代理 - 并充电您 用户——两次.

import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const run = await celesto.runs.create(agentId, {
  input: "Where is my order?",
  endUserId: "usr_8837",
  idempotencyKey: "order-status-42",
});

一次谈话一个代理。 如果第二次跑来的时候 先是继续,塞莱斯多扔 SessionBusyError。通过 maxRetries: 2 改为 等待并再次尝试; SDK 为您创建了一等键 .

继续对话

每次运行都属于一个会话,这就是用户的笔录. 离开 sessionId celesto开始一个; 传回去继续:

import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const first = await celesto.runs.create(agentId, {
  input: "Hello",
  endUserId: "usr_8837",
});
const followUp = await celesto.runs.create(agentId, {
  input: "And the one before that?",
  endUserId: "usr_8837",
  sessionId: first.sessionId,
});

更改代理

更新代理保存新版本, 并让旧版本可以读取 。 运行 记住他们用过的版本,所以一个变化永远不会重写已经 发生了. celesto.agents.activateVersion(agent.id, 1) 回头看.

计算机

电脑是您的应用或代理的可支配云机。 默认, Celesto 创建 scratch 电脑,是一种最小的Ubuntu电脑.

用自定义资源创建

创建名为的文件 create-computer.mjs数字 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({
  cpus: 2,
  memory: 2048,
  disk: "15gb",
});

try {
  console.log(computer.name, computer["name"]);
} finally {
  await computer.delete();
}

Omit CPU,内存,或磁盘字段可以使用默认大小. disk 接受 MB 为 整数或字符串,例如 "2gb"。 。 。 .

计算机默认为麻黄. 留着 /home/ohm 停止并恢复, 当创建计算机时, 启用一个持久家:

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ persistentHome: true });

此设置以后无法更改 .

控制互联网接入

互联网默认开通. 创建外部连接时禁用 计算机 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ networkPolicy: { mode: "off" } });
try {
  console.log((await computer.run("uname -a")).stdout);
} finally {
  await computer.delete();
}

命令和终端会话仍然无法上网。 政策 幸存的停止/ 启动和快照还原, 并且在 创建。 恒活家庭使用外部体积,所以不能结合 networkPolicy: { mode: "off" } 与 persistentHome: true域和 IP 允许列表不支持 .

模板

需要安装额外工具的计算机时使用模板. 譬如说, coding-agent 包括用于编码任务的通用工具.

列出可用的模板 :

创建名为的文件 list-templates.mjs数字 :

import { Computer } from "@celestoai/sdk";

const templates = await Computer.listTemplates();
for (const template of templates) {
  console.log(template.id, template.defaultRamMb);
}

从模板创建计算机 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ templateId: "coding-agent" });
try {
  console.log(computer.name);
} finally {
  await computer.delete();
}

运行命令

创建名为的文件 run-command.mjs数字 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create();
try {
  const result = await computer.run("ls -la", {
    timeout: 60,
  });

  console.log(result.exitCode);
  console.log(result.stdout);
  console.error(result.stderr);
} finally {
  await computer.delete();
}

命令运行时流出输出 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const controller = new AbortController();

for await (const event of computer.runStream("npm test", {
  timeout: 300,
  signal: controller.signal,
})) {
  if (event.type === "stdout") process.stdout.write(event.data);
  if (event.type === "stderr") process.stderr.write(event.data);
  if (event.type === "exit") console.log(`Exit code: ${event.exitCode}`);
}

打电话 controller.abort() 以阻止溪流和远程命令.

管理计算机

computerId 可能会是 computer.id 从 Computer.create() 或计算机名称 由 Celesto 命令行工具显示 : celesto computer list。 。 。 .

发布端口

当计算机内部的服务需要公共 URL 时, 发布端口 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const url = await computer.publishPort(8000);
console.log(url);

列出并删除已公布的端口 :

import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
console.log(await computer.listPublishedPorts());
await computer.unpublishPort(8000);

终端连接

使用 createTerminalSession() 当您正在建立一个交互式终端时. Celesto 返回一个可以直接连接到快终端的短寿命 URL 网关而不是通过控制平面发送终端流量. 创建 a 终端会话需要写入计算机.

对于Node.js,首先安装了WebSocket客户端:

npm install ws

然后连接到认证的 URL :

import { Computer } from "@celestoai/sdk";
import WebSocket from "ws";

const computer = await Computer.get("curie");
const connection = await computer.createTerminalSession();
const ws = new WebSocket(connection.url);

ws.on("message", (data) => process.stdout.write(data));
ws.on("open", () => ws.send("pwd\n"));

connection.url 包含一个短寿命的终端符号。 把它当作一个秘密 之后创建一个新的终端会话 connection.expiresAt。 。 。 .

浏览器自动化连接

使用 browser-agent 当应用程序需要已有时,模板 Chromium浏览器. createBrowserConnection() 返回短寿命的克罗姆 DevTools 协议(CDP) WebSocket URL,Playwright可以附加.

在运行此代码的应用程序中安装 Playwright Core :

npm install playwright-core

然后连接已经运行在 Celesto 计算机中的浏览器 :

import { Computer } from "@celestoai/sdk";
import { chromium } from "playwright-core";

const computer = await Computer.create({ templateId: "browser-agent" });
try {
  const connection = await computer.createBrowserConnection();
  const browser = await chromium.connectOverCDP(connection.url);
  const context = browser.contexts()[0];
  if (!context) throw new Error("Celesto browser did not provide a context");
  const pages = context.pages();
  const page = pages[0] ?? await context.newPage();

  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await computer.delete();
}

显示连接

使用 createDisplayConnection() 当远程帧缓冲( RFB) 客户端时, 例如 基于浏览器的 NoVNC 查看器,需要查看图形桌面. 连接默认只读 。 过 { mode: "read_write" } 当查看器还需要指针和键盘控制时:

import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const display = await computer.createDisplayConnection({ mode: "read_only" });
console.log(display.mode, display.expiresAt);

过 display.url 在 RFB 客户端到期前将其删除 。 浏览并显示 URL 包含短寿的秘密标志,所以不要记录、坚持或共享。 创建 断开或过期后的新连接。 浏览器自动化和 读写显示连接需要写入计算机.

守门员

当您的应用程序需要用户批准访问外部资源时使用门卫, 例如谷歌驱动器.

创建名为的文件 gatekeeper-connect.mjs数字 :

import { GatekeeperClient } from "@celestoai/sdk/gatekeeper";

const client = new GatekeeperClient({ token: process.env.CELESTO_API_KEY });

const connect = await client.connect({
  subject: "customer_123",
  provider: "google_drive",
  projectName: "Default",
});

if (connect.status === "redirect") {
  console.log(connect.oauthUrl);
} else {
  console.log(connect.status);
}

如果响应打印出一个URL,打开后用户就可以批准访问.

完整守门员文件 : https://docs.celesto.ai/celesto-sdk/守门员

配置

将这些选项作为第二个参数传递给 Computer.create() 或者说 Computer.get()明确 token 或者说 apiKey 优于当地证书的发现。 守门员客户在其构建器中接受相同的选项,并需要明确标志.

JWT是一个签名的登录符. 大多数用户应该使用 Celesto API 键.

错误

SDK导出这些错误类别 :

经理员会增加一个错误等级 每一个原因都可以拒绝操作,所以你 能够对特定的一个作出反应。 每个扩展 ManagedAgentError,扩展 CelestoApiError。 。 。 .

本地开发

如果你有贡献 npm 运行这些命令 存储器 ts 目录 :

npm install
npm test
npm run lint
npm run build

许可证

阿帕奇2.0 (英语). SDK开源. Celesto平台的使用由以下规范: 《塞莱斯托服务条件》: https://celesto.ai/legal/terms (法语)