跳转到内容

委托

aidy 自己不持有任何权限。它对你 API 的每次调用都代表发起请求的用户,你的 API 像对待自己 UI 的请求一样鉴权。

POST /api/vm/vm-42/stop HTTP/1.1
Host: console.example.com
Authorization: Bearer <the user's own credential, as aidy received it>
Aidy-Assertion: <compact JWS>
Content-Type: application/json
{"forced":false}
  • Authorization(以及用户用 cookie 登录时的 Cookie)是用户的凭据,原样透传。你的 API 照常鉴权。
  • Aidy-Assertion 证明这个确切的请求来自 aidy、代表这个用户、发生在某次运行中;对于需要审批的操作,还证明用户批准了这些确切的参数。

不带 Aidy-Assertion 的请求就是普通的用户请求。aidy 拉取 OpenAPI 文档和调用身份操作时,发出的也是普通请求。

断言是用 EdDSA(Ed25519)签名的 compact JWS。它的 protected header 为:

{ "alg": "EdDSA", "kid": "aidy-2026-11", "typ": "aidy-call+jwt" }

claims 如下:

Claim 含义
iss aidy 实例的 URL。
aud 宿主的 origin,https://console.example.com。
sub 用户身份中的 subject。
ten 用户的 tenant(如果有)。
sid、rid、cid 会话、运行和工具调用的 id,用于审计。通过 MCP 调用时,cid 是 MCP 请求 id。
op 目录操作名,stop_vm。
htm HTTP 方法。
htu 宿主的公开源加上请求路径和查询串。
bsh 请求体原始字节 SHA-256 的 base64url;没有请求体时为空内容的哈希。
apr 审批 id,用户批准了此次调用时出现。
iat、exp 签发时间和过期时间,单位为秒。exp - iat 不超过 60。
jti 唯一 id,用于防重放。

请求带有断言时,除非以下各项全部成立,宿主都必须返回 401 和 aidy_assertion_invalid:

  1. 签名能用按 kid 选出的、预先固定的 aidy 公钥验证。公钥来自你的配置,绝不来自请求。
  2. aud 是你的 origin,exp 未过期(时钟偏差最多 60 秒),且 jti 在其 exp 之前没有出现过。
  3. htm、htu 和 bsh 与实际收到的请求一致。
  4. sub 和 ten 等于宿主根据 Authorization 解析出的身份。
  5. op 正是提供这个方法和路径的目录操作。
  6. 当 op 为 approval: always 时,apr 存在。

各语言的 host kit 都用一次调用完成这些检查:

宿主 Kit
Python(FastAPI) aidy.fastapi.AidyHost 中间件,或 verify_assertion 加 check_call
TypeScript @aidy-dev/spec/delegation 中的 verifyAssertion 和 checkCall
Go 在代码库内实现,并通过 conformance/delegation/vectors.json 中的共享测试向量验证
from aidy import check_call, verify_assertion
claims = verify_assertion(
token,
keys=keys,
audience="https://console.example.com",
method="POST",
url=full_url_as_sent,
body=raw_body,
remember=lambda jti, until: cache.add(jti, until), # 见过时返回 False
)
check_call(claims, subject=user.id, tenant=user.tenant_id, op="stop_vm", approval="always")

在审计日志中记录 actor = aidy、rid 和 apr,让每个 agent 动作都能追溯到一次运行和一次审批。

调用需要审批时,aidy 冻结已校验的参数,按 RFC 8785 的 JCS 计算 argsHash = base64url(SHA-256(JCS(arguments))),并连同哈希持久化审批。恢复时,aidy 只执行冻结的参数,且仅在存储的哈希仍然匹配时执行。每个审批最多执行一次,即使两个 worker 竞争也是如此。该调用的断言以 apr 携带审批 id。见审批。

aidy 在一次运行期间把用户凭据保存在内存中,从不持久化。凭据在运行中途过期时,调用以 credential_expired 失败,运行暂停,直到用户的下一个请求带来新的凭据。延迟任务由宿主完成,不需要用户凭据。

终端窗口
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk

aidy keys generate 生成一对 Ed25519 密钥。私钥 JWK 是 aidy 的签名密钥,属于配置机密,会写入一个权限为 0600 的新文件,从不打印。公钥 JWK 会被打印出来,用于宿主配置:

{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "aidy-2026-11" }

aidy 还在 /.well-known/aidy-keys.json 提供公钥,供查看。宿主在配置中固定公钥,校验时不去拉取。两个 JWK 都是可移植的:{kty, crv, x, kid} 和 {kty, crv, x, d, kid},不含 alg、key_ops 或 ext,Node、Bun、Deno 和 workerd 都能导入。在代码中加载私钥用 @aidy-dev/spec/delegation 的 importSigningKey,它也接受 Node 导出的带 alg 的 JWK。

轮换。 用新的 kid 生成密钥,先把公钥发布到所有宿主,再切换 aidy 的签名密钥。等旧密钥签发的断言都不可能再被接受时(断言最长 60 秒,另加 60 秒时钟偏差),再从宿主中移除旧公钥。

有两类调用方向相反,由宿主发给 aidy:完成延迟任务(POST /aidy/v0/tasks/{taskId})和宿主任务(POST /aidy/v0/generate)。宿主为每个请求签发 Aidy-Host-Assertion:用固定在 aidy hostKeys(aidy-server 中为 AIDY_HOST_KEYS)里的宿主密钥签名的 EdDSA JWS,claims 与上面相同:

  • aud 是 aidy 的 URL,iss 是宿主的 URL;
  • htu 是 aidy 公开 URL 的源加上宿主请求的路径和查询串,即使代理把请求转发到内部地址也不变,因此在代理后面也能工作;
  • bsh 是请求体原始字节的哈希;exp - iat 不超过 60 秒;每个 jti 只接受一次;
  • op 是延迟的操作名,或 generate;sub(和 ten)表示调用为谁执行。

校验失败返回 401 aidy_assertion_invalid。见 HTTP API。

宿主任务是后端在对话之外请求的一次模型补全:定时报告的摘要、导入条目的标题等。POST /aidy/v0/generate 使用与运行相同的模型链执行它,没有工具,也没有会话。

import { importSigningKey, sha256, signAssertion } from '@aidy-dev/spec/delegation';
const key = await importSigningKey(JSON.parse(process.env.HOST_PRIVATE_JWK!)); // 公钥配置在 aidy 的 hostKeys 中
const url = 'https://console.example.com/aidy/v0/generate'; // aidy 的公开 URL
const body = JSON.stringify({
instructions: "Write the weekly report's summary.",
input: 'Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).',
schema: { type: 'object', properties: { headline: { type: 'string' } }, required: ['headline'] },
});
const now = Math.floor(Date.now() / 1000);
const assertion = await signAssertion(
{
iss: 'https://console.example.com',
aud: 'https://console.example.com',
sub: 'u_1', // 任务为谁执行
sid: 'weekly-report',
rid: 'weekly-report-2026-47',
cid: 'weekly-report-2026-47',
op: 'generate',
htm: 'POST',
htu: url,
bsh: await sha256(body),
iat: now,
exp: now + 60,
jti: crypto.randomUUID(),
},
key,
);
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Aidy-Host-Assertion': assertion },
body,
});
const { object } = await response.json(); // { headline: "…" }
  • 请求体为 {instructions?, input, schema?, maxOutputTokens?},input 必填。
  • 不带 schema 时返回 {text}。带 schema 时,aidy 要求模型输出 JSON(服务商支持 JSON 模式时也会启用),返回 {object},一个符合该 schema 的值。不符合的回答会连同问题说明发回同一端点重试一次;第二次仍不符合则返回 422 invalid_output。
  • 请求中的 maxOutputTokens 优先于端点的设置。任务受运行超时限制(504 timeout);503 model_unavailable 表示没有端点能回答。

Python kit 没有签名辅助函数。Python 宿主可以用任意 Ed25519 JWS 库签发同样的 claims,也可以直接用 kit 依赖的 cryptography:

import base64, hashlib, json, time, uuid
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
def b64url(data: bytes) -> str:
return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
def host_assertion(key: Ed25519PrivateKey, kid: str, url: str, body: bytes, sub: str) -> str:
now = int(time.time())
header = {"alg": "EdDSA", "kid": kid, "typ": "aidy-call+jwt"}
claims = {
"iss": "https://console.example.com", "aud": "https://console.example.com",
"sub": sub, "sid": "job", "rid": "job", "cid": "job", "op": "generate",
"htm": "POST", "htu": url, "bsh": b64url(hashlib.sha256(body).digest()),
"iat": now, "exp": now + 60, "jti": str(uuid.uuid4()),
}
signing_input = f"{b64url(json.dumps(header).encode())}.{b64url(json.dumps(claims).encode())}"
return f"{signing_input}.{b64url(key.sign(signing_input.encode()))}"