@constal/sdk

在Constal上建造的公用TypeScript SDK.

npm install @constal/sdk

软件包有一个支持的导入路径 :

import { agent, gateway, credentialProvider } from "@constal/sdk";

深进口不属于API.

公众表面

根导出包含作者所需的合同 :

• 代理、子任务、工具、耐用状态、等待、阶段和分类账视图
• 频道和 Auth 提供者
• 政策和治理方面的制约因素
• 连接软件包通过 gateway(...)包括模式、MCP和培训提供者连接
• 认证提供者包通过 credentialProvider(...)
• Evals,分数器,训练食谱,内存操作和沙盒手柄
• CRN、选择器、资源要求、计划、散列和复原意识错误

收到连接代码 GatewayContext编号 :IntegrationContext: 已申报的证书、受限的进取、包裹状态、不可改变的文物储存和审计排放。 认证提供者代码通过 CredentialProviderContext。 。 。 .

gateway(...) 财务报告和审定财务报表 credentialProvider(...) 返回验证的、适合有管理的部署的软件包。 用户执行包合同;Constal提供其执行环境.

示例连接

import { gateway } from "@constal/sdk";

export default gateway({
  id: "ticket-connection",
  version: "1.0.0",
  kind: "service",
  displayName: "Ticket connection",
  description: "Read tickets from the configured account.",
  credentialSlots: { account: { title: "Account Credential" } },
  capabilities: [{
    id: "example.ticket-read",
    version: "1",
    hash: "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  }],
  billing: { upstreamPayer: "tenant" },
  configSchema: { type: "object", additionalProperties: false },
  egress: { rules: [{
    operations: ["ticket.get"],
    origin: "https://api.example.com",
    pathPrefix: "/tickets/",
    methods: ["GET"],
  }] },
  catalog: () => [{
    op: "ticket.get",
    description: "Read one ticket.",
    schema: { type: "object" },
    resultSchema: { type: "object" },
    effect: "read-only",
    recovery: { kind: "repeat" },
    async: false,
    usage: { meter: "none", priceTable: null },
  }],
  async invoke(request, context) {
    const credential = await context.secret("account");
    return context.egress({
      url: `https://api.example.com/tickets/${encodeURIComponent(String((request.args as { id: string }).id))}`,
      method: "GET",
      headers: { authorization: `Bearer ${credential.value}` },
      maximumResponseBytes: 1_048_576,
      maximumRedirects: 0,
    });
  },
});

资源合同

const bindings = Object.keys(ctx.resources);
const model = await ctx.describeResource("model");
const operations = (await ctx.describeResource("api"))?.operations;

访问者记录对一个被接受的资源绑定的局部步骤的观察. 它不需要资源或提供者查询。 重放该位置返回 同样的观察;以后的呼叫可以观察到安全点绑定的更新.

成果包括公共运营合同、证书档名和广告 标注模型的元数据。 他们省略了证书参考/材料,私人 配置 控制飞机操作 返回对象是独立的 副本。 配置的操作不是授权的保证: 政策仍然 被援引时适用.

对于模型选择的操作,添加可选 resourceTools 给探员的 普通工具目录 :

import { resourceTools } from "@constal/sdk";

export const tools = { ...resourceTools };

resource_list 返回已接受的绑定名称和 CNN,而不装入每张 目录. resource_describe 带 { binding } 返回资源 公共运营. resource_invoke 接受描述的操作及其 参数 :

await resourceTools.resource_invoke.run({
  binding: "tickets",
  operation: "tool.find",
  arguments: { query: "Open support requests" },
}, ctx);

这些工具使用正常的引用、授权和同步处理 合同。 结果和错误得到保留。 他们不安装软件包, 创建资源、 更改约束、 获取证书本身或重试 操作失败 。 使用 Constal API 资源进行安装并重新组合; 被接受的再组合收件不能证明当前框架有新接头.

技能

一个技能资源是一个代理技能库,通过部署一个 保存的归档 constal.skills.json。 。 。 . skills(binding, sandbox) 返回时 3个工具在库里 代理绑定为 binding (默认) skills, (中文(简体) ), 从绑定中取出 . 财务报告和审定财务报表 - 作为 _数字 :

import { agent, skills } from "@constal/sdk";

const library = skills("skills", "sandbox");

export default agent({
  id: "maintainer", version: "1.0.0", model: "model",
  tools: library,
  async onMessage(request, ctx) {
    return ctx.turn({ system: "You maintain the project's software.", context: { request }, tools: Object.keys(library) });
  },
});

skills_find 财务报告和审定财务报表 skills_read 是图书馆的 find 财务报告和审定财务报表 read 操作; 他们的策略和描述来自部署时的目录. skills_run 捆绑技能,每捆复制一次文件夹 沙盒池的工作空间 sandbox (默认) sandbox页:1 /workspace/skills/<ref>,然后运行一个命令;它回答文件夹的 路径和命令的结果。 它需要图书馆的 bundle 和游泳池的吗 exec 财务报告和审定财务报表 putFile在游泳池自己的政策下 打电话 skills() 单次 绑定的图书馆 .

编辑地址和交付

一个分类账地址名 一个会话的主要分类账, agent:<agent>/session:<session>或者一个产出回路的, agent:<agent>/session:<session>/spawn:<handle>在Run的房客内部, 名称空间,和客户. ctx.run.ledger 是当前运行的自己的地址( 否) 对于操作分支, eval分叉, 补偿, 或循环其中之一 并运行一个现有会议,其编号为 / 或控制器 字符或超过 256 个字符, 入侵者不再接受 一个新的,和处理 ctx.spawn 返回其循环中的名称 ledger,同样跨过产卵 重试. 运行省略 of 财务报告和审定财务报表 to 用于自己的分类账; session:<id> 实值 拒绝.

const notes = await ctx.ledger.view("notes", { of: "agent:memory/session:team" });
await ctx.commit({ text: "Fix the failing build", data: { issue: 7 } },
  { to: "agent:task/session:fix-7", deliver: "live", delegate: true });
const investigation = ctx.spawn(investigate, { issue: 7 });
await ctx.commit("Also check the flaky test", { to: investigation.ledger, deliver: "live" });
const woken = ctx.await("next", { afterRun: "delivery", timeout: 3_600_000 });

ctx.ledger.view 读另一个分类账在它的头上. ctx.commit 与 to 实值 代理代码交付到另一个分类账的一种方式: deliver: "queue",则 默认, 队列项目; "live" 引导地址运行或启动 。 A 类 活项是非空字符串或 { text, data? }和送去产卵 现场直播. delegate: true 使这个会话成为接收会话的主人, 它只夺走了它的主人 在它的第一个运行之前。 出席会议的代表团 live Run的取消正在等待它的驱动程序在 Run 后面等待,然后开始下一个 一;任何其他活生生的快递都引导着跑. 平台随后交付给 主人,作为一个 RunReport,该会话根运行的每端(complete 及其结果, failed, (中文(简体) ), stopped但一站店主的分类账 以物抵偿,或以物抵偿held)),每个都拒绝了 或放弃活动不是来自主人会的开始 (单位:千美元)refused) (中文(简体) ). 送达时拒绝交货 向发送者报告其届会,或永久失效 RunReport 有状态 refused。 。 。 . ctx.await(label, { afterRun: "delivery" }) 当送货者引导等待者运行并解决 { seq, eventId } 被唤醒的方向盘 交付本身留在分类账里 运行一个 发送或报告开始属于发送者的端到端运行,如同 运行开始通过 Constal API 从一个运行: 性能读取一个频道的, 一个时刻表或API的呼叫"跑" 和每一个运行它引导在一起.

政策决定对另一届会议的看法ledger:read; 页光标 然后读取无需进一步核对),并送交另一届届会 实施(agent:invoke 在接收代理人, session:steer 当生活, run:cancel 在授权时。 拒绝的视图或 递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递件 在同一位置出错: 政策拒绝为 PolicyDecisionFailed 联合国 decisionHash,以及任何其他拒绝 Error 与平台的信息和 status。 。 。 .

届会时间表

安排今后援引现任代理人和届会:

await ctx.schedule("check-pr-42", {
  after: "10m",
  input: { kind: "check-pr", repository: "acme/api", pullRequest: 42 },
});

当前的运行可以完成 。 会议保留时间表,并交付 到期时对新运行的输入不变 。 使用 every: "15m" 用于固定凸起,或 every: "day", at: "09:00", timezone: "America/Los_Angeles" 每日检查. 经常性时间表默认保存错失的事件; 明确要求 missed: "coalesce" 当一次检查应涵盖累积的积压.

ctx.listSchedules() 页面显示自有会话的日程; 调用 schedule() 以同一名称取代今后的工作. ctx.cancelSchedule(name) 停下来 未来工作,确定已接受或未解决的交货。 使用 ctx.await() 因为睡在目前的运行.

见 调度代理跟踪 重复播放, 发送、授权和取消语义.

示范评价

ctx.evaluate 通过评估对打出的问题进行评分 模式,例如: typesafe-ai/jev。每个问题都单独回答 受限的价值和概率,从未产生出传言, 呼唤是 日记和定价 就像一个模型调用 不消耗转弯.

import { agent, noulDecision } from "@constal/sdk";

export default agent({
  id: "triage", version: "1.0.0", model: "model",
  async onMessage(ticket, ctx) {
    const { answers } = await ctx.evaluate({
      model: "judge",
      state: { ticket },
      questions: {
        team: { type: "choice", instructions: "Which team owns `ticket`?",
          criteria: { billing: "Charges, invoices, refunds", technical: { what: "Bugs and outages", not_for: "Charges" } } },
        severity: { type: "score", instructions: "How severe is the problem in `ticket`?",
          criteria: ["Cosmetic", "Degraded", "Customer is blocked"] },
        urgent: { type: "noul", instructions: "Does `ticket` convey urgency?" },
      },
    });
    if (answers.team.confidence < 0.5) return { route: "human" };
    return { route: answers.team.choice, severity: answers.severity.score, urgent: noulDecision(answers.urgent, 0.7) };
  },
});

与其他评价模式一样将评价模式捆绑起来("judge": "crn:...:model/jev"),或 通过 gateway 明确 model 标识符. instructions选择选项 说明,分数级,和努尔标准都接受JSON结构. 选择 答案保留其标准的字面选项键,分数答案带有一个 legend,而诺尔答案是一种概率.

见 用模型评估状态 用于完整包单、答案形状和核查步骤.