@开放代理id/sdk
JavaScript/TypeScript SDK 打开代理ID --在链上注册、签名和验证AI代理身份。
安装
npm install @open-agent-id/sdk需要Node.js>=18。
快速开始
最常见的用例是向出站请求添加代理身份验证标头：
import { signAgentAuth } from "@open-agent-id/sdk";
const headers = signAgentAuth(
"did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
privateKey, // Uint8Array (32 bytes)
);
// Returns object with:
// "X-Agent-DID": "did:oaid:base:0x1234..."
// "X-Agent-Timestamp": "1708123456"
// "X-Agent-Nonce": "a3f1b2c4d5e6f7089012abcd"
// "X-Agent-Signature": ""
const res = await fetch("https://api.example.com/v1/tasks", {
method: "POST",
headers,
body: JSON.stringify({ task: "search" }),
});注册表客户端
import { RegistryClient } from "@open-agent-id/sdk";
const client = new RegistryClient(); // defaults to https://api.openagentid.org所有方法
| 方法 | 需要授权 | 描述 |
|---|---|---|
client.requestChallenge(walletAddress) | 否 | 请求钱包身份验证挑战 |
client.verifyWallet(walletAddress, challengeId, signature) | 否 | 验证钱包签名，返回身份验证令牌 |
client.registerAgent(token, opts) | 是 | 注册新代理(opts: { name, publicKey, capabilities? }) |
client.getAgent(did) | 否 | 通过DID查找代理 |
client.listAgents(token, opts?) | 是 | 列出经过身份验证的钱包所拥有的代理 |
client.updateAgent(did, auth, updates) | 是 | 更新代理元数据 |
client.revokeAgent(did, token) | 是 | 撤销代理身份 |
client.rotateKey(did, token, publicKey) | 是 | 旋转代理的公钥 |
client.deployWallet(did, token) | 是 | 为代理部署链上智能钱包 |
client.getCredit(did) | 否 | 查询代理人的信用评分 |
client.verifySignature(did, domain, payload, signature) | 否 | 根据代理的注册密钥验证签名 |
钱包身份验证流程
// 1. Request challenge
const { challengeId, challengeText } = await client.requestChallenge(walletAddress);
// 2. Sign the challenge text with your wallet (e.g. via ethers.js)
// const walletSignature = await wallet.signMessage(challengeText);
// 3. Verify and get auth token
const token = await client.verifyWallet(walletAddress, challengeId, walletSignature);注册代理
const agent = await client.registerAgent(token, {
name: "my-agent",
publicKey: base64urlPublicKey,
capabilities: ["search", "summarize"],
});查找并列出代理商
const info = await client.getAgent("did:oaid:base:0x1234...");
const { agents, nextCursor } = await client.listAgents(token);管理代理
await client.updateAgent(did, { token }, { name: "new-name" });
await client.rotateKey(did, token, newPublicKey);
await client.revokeAgent(did, token);
await client.deployWallet(did, token);信用评分
const credit = await client.getCredit("did:oaid:base:0x1234567890abcdef1234567890abcdef12345678");
console.log(credit.credit_score); // 300
console.log(credit.level); // "verified"HTTP签名
签署HTTP请求
import { signHttpRequest, verifyHttpSignature } from "@open-agent-id/sdk";
const headers = await signHttpRequest(
privateKey, // Uint8Array (32 bytes)
"POST",
"https://api.example.com/v1/tasks",
new TextEncoder().encode('{"task":"search"}'),
);
// headers = {
// "X-Agent-Timestamp": "1708123456",
// "X-Agent-Nonce": "a3f1b2c4d5e6f7089012abcd",
// "X-Agent-Signature": ""
// }验证HTTP签名
const valid = verifyHttpSignature(
publicKey, // Uint8Array (32 bytes)
"POST",
"https://api.example.com/v1/tasks",
bodyBytes, // Uint8Array | null
timestamp, // number (unix seconds)
nonce, // string
signature, // Uint8Array
);使用签名守护进程
import { Signer, Agent } from "@open-agent-id/sdk";
const signer = await Signer.connect("/tmp/oaid-signer.sock");
const agent = new Agent({
keyId: "default",
signer,
did: "did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
});
const res = await agent.http.post("https://api.example.com/v1/tasks", {
task: "search",
});消息签名
签署P2P消息
import { signMessage, verifyMessageSignature } from "@open-agent-id/sdk";
const signature = await signMessage(
privateKey,
"task.request", // message type
"msg-001", // message ID
"did:oaid:base:0xaaaa...aaaa", // from DID
["did:oaid:base:0xbbbb...bbbb"], // to DIDs
null, // ref
null, // timestamp (auto)
null, // expiresAt
{ task: "summarize", url: "https://..." }, // body
);E2E加密
import { encryptFor, decryptFrom } from "@open-agent-id/sdk";
// Encrypt for another agent (NaCl box: X25519-XSalsa20-Poly1305)
const ciphertext = encryptFor(plaintext, recipientEd25519Pub, senderEd25519Priv);
// Decrypt
const decrypted = decryptFrom(ciphertext, senderEd25519Pub, recipientEd25519Priv);DID实用程序
import { validateDid, parseDid, formatDid } from "@open-agent-id/sdk";
validateDid("did:oaid:base:0x1234...abcd"); // true
parseDid("did:oaid:base:0x1234...abcd");
// { method: "oaid", chain: "base", agentAddress: "0x1234...abcd" }
formatDid("base", "0x1234...abcd");
// "did:oaid:base:0x1234...abcd"规范助手
import { canonicalUrl, canonicalJson } from "@open-agent-id/sdk";
canonicalUrl("https://API.example.com/path?b=2&a=1");
// "https://api.example.com/path?a=1&b=2"
canonicalJson({ z: 1, a: 2 });
// '{"a":2,"z":1}'测试
npm install
npm run build # compile TypeScript
npm test # run tests with vitest许可证
阿帕奇-2.0