@chaitin-ai/代理编程时速

节点Js SDK用于在代理编导的来宾运行时间内运行的脚本.

软件包既提供命名导出, 也提供默认值 runtime 对象 :

const { runtime } = require("@chaitin-ai/agent-compose-runtime-sdk");

import runtime, { exec, shell, agent, llm, workflowFile, ssh } from "@chaitin-ai/agent-compose-runtime-sdk";

安装

从 npm 公共登记册安装 :

npm install @chaitin-ai/agent-compose-runtime-sdk

来宾图像也可以从离线柏油球上安装 SDK :

npm install --offline /opt/agent-compose/npm/agent-compose-runtime-sdk.tgz

快速启动

const { runtime } = require("@chaitin-ai/agent-compose-runtime-sdk");

async function main() {
  const result = await runtime.shell("echo hello");
  runtime.log("command completed", { success: result.success });
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

运行时路径

runtime.paths 曝光由环境变量解析的运行时路径 :

workspace, (中文(简体) ), stateRoot,以及 runtimeRoot 也接受遗产的别名 AGENT_COMPOSE_WORKSPACE, (中文(简体) ), AGENT_COMPOSE_STATE_ROOT,以及 AGENT_COMPOSE_RUNTIME_ROOT 当主变量未设置时. home 没有别名.

API 密码

runtime.exec(command, args?, options?)

不扩展 shell 直接运行命令.

const result = await runtime.exec("node", ["-e", "console.log(process.cwd())"]);

选项 :

返回值:

{
  stdout: string;
  stderr: string;
  output: string;
  exitCode: number;
  success: boolean;
  stdoutTruncated: boolean;
  stderrTruncated: boolean;
  outputTruncated: boolean;
}

默认, runtime.exec() 串流命令日志,这样代理编组可以在脚本仍在运行时显示活输出. 过 { streamOutput: false } 静静地处决.

runtime.shell(script, options?)

通过 shell 脚本运行 bash -lc。 。 。 .

const result = await runtime.shell("echo shell:$AGENT_COMPOSE_TEST_VALUE", {
  env: { AGENT_COMPOSE_TEST_VALUE: "works" },
});

选项和返回值与 runtime.exec()启用 runtime.shell() 当您需要可变扩展、管道、方向调整或复合命令时.

runtime.agent(prompt, options?)

在代理编导运行时间呼叫代理桥.

const result = await runtime.agent("Inspect the workspace and summarize the project.");

过 outputSchema 当你需要结构化的JSON。 建议采用Zod schema:SDK将其转换为JSON Schema用于运行时代理桥并验证解析 json 以相同的 Zod 计划值.

import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.agent("Inspect the workspace and return risk.", {
  provider: "codex",
  outputSchema: RiskSummary,
});

console.log(result.json.summary);

当Zod计划通过时,类型 result.json 根据计划推断:

import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.agent("Inspect the workspace and return risk.", {
  provider: "claude",
  outputSchema: RiskSummary,
});

if (result.json) {
  console.log(result.json.risk);
}

您也可以通过一个平坦的 JSON Schema 对象,并以通则声明返回类型 :

type RiskSummary = {
  summary: string;
  risk: "low" | "high";
};

const result = await runtime.agent<RiskSummary>("Inspect the workspace and return risk.", {
  outputSchema: {
    type: "object",
    additionalProperties: false,
    properties: {
      summary: { type: "string" },
      risk: { type: "string", enum: ["low", "high"] },
    },
    required: ["summary", "risk"],
  },
});

选项 :

返回值:

{
  provider: string;
  threadId: string;
  stopReason: string;
  finalText: string;
  json: unknown | null;
  transcript: string;
  stderr: string;
}

finalText 总是保存代理桥返回的原始文本。 何时 outputSchema 已经设定, finalText 一定是JSON的绳子 SDK运行 JSON.parse(finalText) 并存储结果 json如果 outputSchema sDK也用这个方法验证解析结果。 无 outputSchema, (中文(简体) ), json 实值 null。 。 。 .

错误行为 :

runtime.workflow(script, options?) 财务报告和审定财务报表 runtime.workflowFile(path, options?)

通过嘉宾运行时间CLI运行动态工作流程. workflow() 接受 源文本并管理一个临时脚本文件; workflowFile() 通过 直接调用文件 .

const result = await runtime.workflowFile("workflows/inspect.js", {
  args: { area: "api" },
  provider: "codex",
  concurrency: 4,
  onUpdate(event) {
    if (event.type === "phase") {
      console.error(`phase: ${event.title}`)
    }
  },
})

console.log(result.result)

选项包括 args, (中文(简体) ), provider, (中文(简体) ), model, (中文(简体) ), concurrency, (中文(简体) ), tokenBudget, (中文(简体) ), runId, (中文(简体) ), resumeRunId, (中文(简体) ), stateRoot, (中文(简体) ), workspace, (中文(简体) ), home, (中文(简体) ), timeoutMs,以及 onUpdate。事件由 Stderr 逐渐解码,所以 onUpdate 运行 当工作流程活动时。 非事件 Stderr 返回为 result.stderr。 。 。 .

工作流程有效载荷抛出失败或中止 RuntimeWorkflowError; 其编号 outcome 字段保留运行的ID、代理、事件和 stderr。 无效的 CLI 协议抛出 RuntimeWorkflowProtocolError. SDK 超时抛出 RuntimeWorkflowTimeoutError 并保留部分事件和标准.

runtime.llm(prompt, options?)

呼叫代理编组LLM服务. 守护进程通过 LLM_API_PROTOCOL (单位:千美元)responses 默认,或 chat_completions 页:1 OpenAI-兼容的聊天补全后端). 与 outputSchema, (中文(简体) ), chat_completions 使用即时指导 response_format: json_object没有 API严格JSON Schema反应.

const result = await runtime.llm("Summarize the workspace risk.", {
  model: "gpt-5.4",
});

console.log(result.text);

runtime.llm() 支持同样的 outputSchema 机制作为 runtime.agent()。建议使用 Zod schema : SDK 将其转换为 JSON Schema 进行 LLM 服务并验证解析 json 以相同的 Zod 计划值.

import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.llm("Inspect the workspace and return risk.", {
  model: "gpt-5.4",
  outputSchema: RiskSummary,
});

console.log(result.json.risk);

您也可以通过一个平坦的 JSON Schema 对象,并以通则声明返回类型 :

type RiskSummary = {
  summary: string;
  risk: "low" | "high";
};

const result = await runtime.llm<RiskSummary>("Inspect the workspace and return risk.", {
  outputSchema: {
    type: "object",
    additionalProperties: false,
    properties: {
      summary: { type: "string" },
      risk: { type: "string", enum: ["low", "high"] },
    },
    required: ["summary", "risk"],
  },
});

选项 :

返回值:

{
  text: string;
  model: string;
  responseId: string;
  finishReason: string;
  json: unknown | null;
}

text 总是保存 LLM 服务返回的原始文本。 何时 outputSchema 已经设定, text 一定是JSON的绳子 SDK运行 JSON.parse(text) 并存储结果 json如果 outputSchema sDK也用这个方法验证解析结果。 无 outputSchema, (中文(简体) ), json 实值 null。 。 。 .

runtime.env.get(name)

读取环境变量。 回返 undefined 当变量未设定时.

const value = runtime.env.get("WORKSPACE");

runtime.env.require(name)

读取所需的环境变量。 缺少变量或空字符串时抛出.

const token = runtime.env.require("API_TOKEN");

runtime.env.all()

返回所有定义的环境变量为普通对象.

const environment = runtime.env.all();

runtime.log(message, payload?)

写入一个结构化的运行时日志行到 stdout。 。 。 .

runtime.log("step completed", { step: "build", ok: true });

输出 JSON 形状 :

{
  type: "agent-compose.runtime.log";
  message: string;
  payload: unknown;
  createdAt: string;
}

runtime.report.writeMarkdown(name, content, options?)

写入 Markdown 报告文件并返回创建的文件路径.

const reportPath = await runtime.report.writeMarkdown("summary.md", "# Summary\n\nDone.");

选项 :

文件名称与 path.basename(),所以呼叫者应该通过一个文件名而不是一个嵌入路径.

runtime.ssh.prepareConfig(options)

写入 SSH 客户端配置以达到主机并返回解析路径 。 它创建了 SSH 目录,可选地写出一个私钥,并维持一个标记块在 ~/.ssh/config 指一个 known_hosts 文档.

const sshConfig = await runtime.ssh.prepareConfig({
  hostAlias: "sandbox",
  hostName: "10.0.0.5",
  user: "root",
  privateKey: process.env.SANDBOX_SSH_KEY,
});

const command = runtime.ssh.command(sshConfig);

选项 :

返回值:

{
  hostAlias: string;
  hostName: string;
  user: string;
  port: string;
  proxyJump?: string;
  privateKeyPath?: string;
  configPath: string;
  knownHostsPath: string;
  blockName: string;
  strictHostKeyChecking: "accept-new" | "yes" | "no";
}

返回的配置可转换为 shell 命令 runtime.ssh.command(config) (单位:千美元)ssh …, (中文(简体) ), runtime.ssh.scpCommand(config) (单位:千美元)scp …),以及 runtime.ssh.options(config) (共享资源) -F, (中文(简体) ), UserKnownHostsFile,以及 StrictHostKeyChecking 旗帜).

自定义脚本中的 OctoBus 能力

runtime.capabilities 允许使用已有的脚本或 Codex 兼容的运行程序 沙盒宣布的OctoBus能力没有应用侧接器. 它读取了守护进程生成的 RUNTIME_ROOT/mpi/capabilities.json 简介和 使用来宾图像 grpcurl 可执行文件通过 CAP_GRPC_TARGET。 。 。 .

import { runtime } from "@chaitin-ai/agent-compose-runtime-sdk";

const tools = await runtime.capabilities.list();
// Select an explicitly intended tool; identical methods on different
// instances/capsets have different IDs.
const selected = tools.find((tool) => tool.id === requestedToolID);
if (!selected) throw new Error("Requested tool is unavailable");
const definition = await runtime.capabilities.describe(selected.id);
// definition.method/request/response contain reflected Protobuf text.
const result = await runtime.capabilities.call(selected.id, params, {
  timeoutMs: 30_000,
  maxOutputBytes: 256 * 1024,
  signal: abortController.signal,
});

list() 返回时 id, (中文(简体) ), capset, (中文(简体) ), instance, (中文(简体) ), method, (中文(简体) ), request_type 财务报告和审定财务报表 response_type它拒绝失踪、畸形、外出或不完整 示意图. 当守护进程准备能力时, 快照会被刷新 指南;它不是活的目录或赠款。 重新准备运行,或创建 新建沙盒,在恢复一个没有可用的目录后.

describe() 返回无用的 RPC,顶级请求/应答 Protobuf 文本, 财务报告和审定财务报表 descriptorSetBase64: 标准二进制 google.protobuf.FileDescriptorSet 被编码为 Base64,包括被导入的信件/enum定义. 消费者可能 用他们自己的Protobuf 库装入;它不是 JSON Schema 或被钉住的图案 核准。 临时描述文件在成败时被删除. call() 接受Protobuf JSON并返回 解码的JSON反应; grpcurl 进行反射和标准线编码. 熟知消息可能使用scalar、数组或无效的JSON格式;输入包含 未定义,非无限数字或其他非JSON值在引用前失败. 在援引商业理由之前,拒绝采用流动方法。 没有发现 或SDK验证取代近似/OctoBus授权或业务核准. 从方法名称中不推断出只读分类.

每个选项 grpcurl 操作. describe() 进行三次反省 操作; call() 检查一下方法,并引用一次。 使用 signal (单位:千美元) 共享端到端截止日期 。 电话没有被重审。 JSON请求仅限于 256 KiB;输出默认为256 KiB并可能设置为1个米B. 超过 限制失败, 而不是返回已截断的 JSON 。 相同的产出限制适用 到Base64编码前设置的二进制描述符。 上游诊断不是 已转发或附上错误。 CAP 证书使用信头环境 请求JSON被发送到Stdin, 避免两者在argv之外.

现有的 Codex 事件输出和业务路由可能被保留. 这个API 不执行模式/工具循环。 脚本仍然拥有自己的商业决定权 和预测.

守护进程发布完整的目录和带有原子的Markdown快照 重命名仅限于沙盒目录 。 来宾创建的符号链接无法重定向 这些主机在目录外写。 来源 URL 保留其默认端口 当转换为 grpcurl 地址时.

错误

何时 rejectOnFailure 启用,从 runtime.exec() 或者说 runtime.shell() 掷出 CommandError。错误对象包含:

const { runtime, CommandError } = require("@chaitin-ai/agent-compose-runtime-sdk");

try {
  await runtime.shell("exit 1", { rejectOnFailure: true });
} catch (error) {
  if (error instanceof CommandError) {
    runtime.log("command failed", { exitCode: error.result.exitCode });
  }
}