@ diedglass/ sdk (英语)
把德德格拉斯放在你经纪人的工具前 每一次通话都是由政策决定的,当规则规定时,由一个人批准,封为契约,你可以检查下线.
import { Deedglass, wrapTool } from '@deedglass/sdk';
const dg = new Deedglass(); // reads DEEDGLASS_API_KEY and DEEDGLASS_SERVER
const refund = wrapTool(refundCustomer, { client: dg, tool: 'billing.refund_customer' });
await refund({ customer: 'cus_123', amount: 2000 }); // runs only if policy allows it
与Vercel AI SDK,OpenAI代理SDK,LangChain.js和克洛德代理SDK合作. 没有运行时间依赖 。 节点22.12+, Bun, Deno和边缘跑道.
它没有做什么: 它不保存您的功能( 它决定它是否运行), 结果您的代码报告被记录为已报告( L0) 。 需要L1或L2时使用Dedglass连接器.
安装
npm install @deedglass/sdk
设定 DEEDGLASS_API_KEY (代理密钥, dg_test_… 或者说 dg_live_…,来自Console QQ代理)和 DEEDGLASS_SERVER (默认) http://127.0.0.1:8080) (中文(简体) ). 一揽子措施是无害环境管理;在22.12节点和较新的节点上, require('@deedglass/sdk') 还行.
三个用法
1. 本人的职能: wrapTool (代理模式). Dedglass 决定;您的功能只在动作被授权后运行,最多一次;其结果被报告和封存.
const refund = wrapTool(refundCustomer, {
client: dg,
tool: 'billing.refund_customer',
onPending: 'throw', // or 'wait' for a person to decide
failureMeans: 'unknown', // a thrown error means "it may have run" (the default)
});
- 拒绝掷出
PolicyDeniedError与保单的句子。 你的职能从来没有运行. - 等待批准的掷出
ApprovalPendingError(与approvalId财务报告和审定财务报表expiresAt) (中文(简体) ). 在一个人批准你运行一次之后,用同样的论据再次召唤;它不再问了. - 如果您的函数抛出, 证书上写着“ 它可能已经运行 ”
ToolExecutionError原文为:cause。通过failureMeans: 'not_applied'仅当函数在任何副作用之前失败时.
2. 连接工具: act (出道模式). 戴德格拉斯用连接器的证书来运行工具,它永远不会离开.
const a = await dg.act('stripe.create_refund', { charge: 'ch_3QxZ8f2L', amount: 2000 });
a.status; // 'executed' · 'pending_approval' · 'failed'
a.witness?.verdict; // 'VERIFIED' at L1: Stripe's own record was read back
a.deed; // 'deed_01j9…'
运行失败的工具返回 status: 'failed' 行动已经发生 所以也并非例外.
3. 检查下线的契约: @deedglass/sdk/verify。 。 。 . 不需要密钥, 答案与 deedglass verify。 。 。 .
import { fetchKeys, verifyDeeds, splitLines } from '@deedglass/sdk/verify';
const { keys } = await fetchKeys('https://deedglass.example/.well-known/deedglass/keys.json');
const report = await verifyDeeds(splitLines(bytes), keys, { keysPinned: true });
report.result; // 'valid' · 'invalid' · 'cannot_determine'
框架
| 导入 | 打开工具( 代理) | 连接工具(出入口) |
|---|---|---|
@deedglass/sdk/ai-sdk | governTools(tools, { client }) | deedglassTools(client) |
@deedglass/sdk/openai-agents | governTool(tool, { client }) | deedglassTools(client) |
@deedglass/sdk/langchain | governTool(tool, { client }) | deedglassTools(client) |
@deedglass/sdk/claude-agent-sdk | deedglassHooks({ client }), (中文(简体) ), governSdkTool(def, { client }) | deedglassMcpServer(client) |
适配器默认情况下将拒绝执行或待执行的判决退回模型(onDenied: 'message', (中文(简体) ), onPending: 'message'),因为框架反馈工具输出回模型,而抛出会结束一些运行.
错误
每个错误都是 DeedglassError 与 type, (中文(简体) ), code, (中文(简体) ), message (服务器的,逐字记录), param, (中文(简体) ), status, (中文(简体) ), requestId 财务报告和审定财务报表 docUrl; 拒绝带封口 action启用 isDeedglassError(e);它的工作跨越包的复制.
| 类 | 何时 |
|---|---|
AuthenticationError | invalid_api_key, (中文(简体) ), api_key_revoked, (中文(简体) ), api_key_expired |
PermissionDeniedError | agent_stopped, (中文(简体) ), org_stopped, (中文(简体) ), insufficient_scope, (中文(简体) ), intent_* |
PolicyDeniedError | policy_denied |
BudgetExceededError | 429个 budget_exceeded (从来没有再试) |
RateLimitError | 429个 rate_limited,在复试后 |
InvalidRequestError | validation_failed, (中文(简体) ), not_found, (中文(简体) ), conflict, (中文(简体) ), idempotency_conflict |
APIError | 5 (简体中文) |
ConnectionError, (中文(简体) ), TimeoutError | 网络; 超时表示动作可能仍在运行 |
ApprovalPendingError, (中文(简体) ), ToolExecutionError | wrapTool |
失职和重审
每个POST都带一个 Idempotency-Key,每次重试都使用同样的一个,所以服务器从未运行过两次工具. 网络错误, 408, 429 rate_limited, 500, 502, 503 和 504 默认情况下两次重审, 以指数反射, 以纪念 Retry-After 最多10 s 永远不要过你的 signal 或者说 timeoutMs (每项请求30 s).
签名意图
给客户端一个 Ed25519 键(deedglass agent intent keygen 写一个),每通电话都与 deedglass.intent/1数字 :
const dg = new Deedglass({ intentKey: { privateKeyPem: process.env.DEEDGLASS_INTENT_KEY! } });
signIntent, (中文(简体) ), argsDigest, (中文(简体) ), intentKid 财务报告和审定财务报表 generateIntentKey 用于自用。 2^53 - 1 参数中的整数被拒绝: 把它们作为字符串发送 .
运行时间
节点22.12和较新, Bun, Deno, Cloudflare工人和Vercel Edge (Ed25519 in WebCrypto). 客户端拒绝从浏览器页面开始,因为代理密钥是秘密:从您的服务器上呼叫Deedglass. 过 dangerouslyAllowBrowser: true 只有你接受这种风险. @deedglass/sdk/verify 到处跑.
它不会做什么
wrapTool决定您的代码是否运行; 它不是沙盒 它做什么.- 代理模式结果为L0(对接报告). 独立的L1/L2检查需要戴德格拉斯连接器.
- Claude钩子只看到通过钩子的SDK特工路线的工具.
- 离线核查检查封条和链条,而不是动作是否明智.
阿帕奇2.0 (英语).