@ godspideai/ cognate- runtime- api
Cognate的运输独立运行时间合同: RuntimeService 界面(运行、事件、续作、文物、预测、共享状态)、代理作者表面(AgentDefinition 编号 : RunContext),以及运行时间和客户端都使用的cononical share-state折叠.
何时使用此软件包 : 或执行 RuntimeService应用程序从
@godspeedai/cognate-runtime-bun
和一位现成的呼叫者 @godspeedai/cognate-client。 。 。 .
安装
bun add @godspeedai/cognate-runtime-api
要求数 阿宝 >= 1.4.0.
授权代理
一种剂是其输入和记录结果的确定性函数:
import type { AgentDefinition } from "@godspeedai/cognate-runtime-api";
export const refundAgent: AgentDefinition = {
id: "agent.refund",
version: "1.0.0",
async run(input, ctx) {
const { amount } = input as { amount: number };
const quote = await ctx.step("quote", () => ({ total: amount * 2 }));
await ctx.emit("message.delta", { text: `Total: ${quote.total}` });
const decision = (await ctx.waitFor("approval", {
type: "refund-approval",
condition: { kind: "human_approval" },
payload: quote,
})) as { approved: boolean };
return { approved: decision.approved, total: quote.total };
},
};
每个 RunContext 方法具有耐用性和回放安全性:结果记录为运行流上的事件,中止或重启后返回记录的结果,而不是重复工作。 因此,鉴于这些结果,代理代码必须是决定性的.
step(id, fn)——一次运行一个非决定性单元(一个模型调用,一个API读取)并记录其JSON结果.emit(eventType, payload)——记录了一次完全通过回放的跑入范围的事实.invoke(capability, input)通过政策调用内核能力InvocationFailedError输入失败.waitFor(id, spec)- 暂停,直到永久延续问题得到解决;取消或到期延续失败ContinuationClosedError。 。 。 .artifact({ name, mediaType, bytes })——出产耐用文物;还原其标识.state(id)编号 :sharedState(id)编号 :updateSharedState(id, update)——读取并解剖地更新了跑行和线程共享状态.recall(id, { text, k })- 回顾先前授权的知识;返回{ status: "degraded" }当无法识别时.
呼叫服务
每个 RuntimeService 操作需要 Caller ——运输的认证人身份成立,从未从请求机构读出过任何内容: 1
import type { Caller } from "@godspeedai/cognate-runtime-api";
const alice: Caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };
const run = await service.startRun(alice, {
agent: "agent.refund",
input: { amount: 21 },
idempotencyKey: "refund-1",
});
失败的是 ServiceError 输入 code数字 : not_found, (中文(简体) ), permission_denied, (中文(简体) ), invalid_argument, (中文(简体) ), failed_precondition, (中文(简体) ), unavailable, (中文(简体) ), deadline_exceeded, (中文(简体) ), already_exists, (中文(简体) ), unauthenticated,或 resource_exhausted。 。 。 .
共享状态
运行状态是它的折叠 state.changed 事件按存储位置顺序排列 。 此套件拥有 Canonical 折叠 : applyStateUpdate 应用一个更新(完整) snapshot 或RFC 6902飞机 patch, (中文(简体) ), foldState 折叠出一系列事件,运行时间和无头客户端都使用它们——因此每个读者都获得同样的状态. 应用不匹配丢入的补丁 StatePatchError;在折叠代理发送事件时,此补丁被跳过而不是隐藏后期更新.
前端能力
invokeFrontend(ctx, id, capability, input) 将客户端提供的能力转变为持久的延续:运行暂停,直到注册该能力的连接客户端执行并用一个值解决续作. 它能像任何续作一样在断开和重启中幸存下来;在失败时它会抛出 FrontendCapabilityError。 。 。 .
合规子路径
@godspeedai/cognate-runtime-api/conformance 整个服务合同在加工过程中和任何运输过程中均保持不变——同一套货包都证明这一点。 出口 runtimeServiceConformance (及其剂/工具固定装置),加现成 Caller 身份可以在自己的测试和实例中使用:
import { alice, mallory, bob } from "@godspeedai/cognate-runtime-api/conformance";
// alice and mallory are users in tenant "tenant-a"; bob is a user in "tenant-b".
限制
- 只有合同:没有服务器,也没有电线运输。 用Bun runtime这样的执行来对等, 或者把它映射到您所选择的运输上.
RunContext是代理代码到达外部世界的唯一支持方式;它记录的任何东西必须作为JSON进行回转.
相关软件包
@godspeedai/cognate-runtime-bun- 参考执行RuntimeService。 。 。 .@godspeedai/cognate-client无头客户端在任何RuntimeService。 。 。 .@godspeedai/cognate-events——服务被确定为与耐用商店合同相对抗的.@godspeedai/cognate——SDK伞;为运行时间安装一款,客户端,以及本合同.
许可证
阿帕奇 - 2.0