gbz185-sdk

Examples

这些示例覆盖开发者最常见的集成点。示例优先展示可组合的 SDK 调用，而不是隐藏在框架代码里。

示例语言
TypeScript Beta；Python / Go / Rust / Java Alpha 实验中

端到端日历智能体

仓库内置 examples/calendar.ts，覆盖注册身份、发布描述、发现、建会话、调用工具、发送最终结果。

pnpm install
pnpm build
pnpm example:calendar
import {
  createAgentInterconnectRuntime,
  formatIdentityCode,
  type AgentDescription
} from "gbz185-sdk";

const runtime = createAgentInterconnectRuntime();
const requesterId = formatIdentityCode({
  registrationServiceProvider: "A1",
  registrationRequester: "REQ001",
  ontologySerial: "ASSISTANT",
  instanceSerial: "1"
});

const registration = await runtime.client.registerIdentity({
  delegatorId: "example-org",
  subject: "Calendar Agent",
  registrationServiceProvider: "A1",
  registrationRequester: "REQ001",
  ontologySerial: "CALENDAR",
  instanceSerial: "1",
  issueCredential: true,
  credentialAudience: [requesterId],
  credentialScope: ["agent:interact", "tool:invoke"]
});

完整代码见仓库示例文件；Get Started 页面逐段解释了每一步。

身份码工具

import {
  formatIdentityCode,
  parseIdentityCode,
  validateIdentityCode
} from "gbz185-sdk";

const code = formatIdentityCode({
  registrationServiceProvider: "abc123",
  registrationRequester: "req001",
  ontologySerial: "bot000001",
  instanceSerial: "0"
});

console.log(code);
// 1.2.156.3088.1.ABC123.REQ001.BOT000001.0

console.log(validateIdentityCode(code));
// true

console.log(parseIdentityCode(code).registrationRequester);
// REQ001

凭证鉴别与授权

import {
  DevelopmentCredentialIssuer,
  DevelopmentCredentialVerifier,
  InMemoryCredentialRepository,
  InMemoryCredentialStatusStore,
  InterconnectionAuthorizationRuntime
} from "gbz185-sdk";

const repository = new InMemoryCredentialRepository();
const statusStore = new InMemoryCredentialStatusStore();
const issuer = new DevelopmentCredentialIssuer(repository, statusStore);
const verifier = new DevelopmentCredentialVerifier(statusStore);
const auth = new InterconnectionAuthorizationRuntime(verifier);

const issued = await issuer.issueCredential({
  agentId: "1.2.156.3088.1.A1.REQ001.DEMO.1",
  subject: "Demo Agent",
  audience: ["service-agent"],
  scope: ["agent:interact"]
});

const pkg = auth.createPresentation({
  credential: issued.credential,
  privateKeyPem: issued.privateKeyPem,
  audience: "service-agent",
  scope: ["agent:interact"],
  payload: { sessionId: "session-1" }
});

const decision = await auth.authenticatePeer(pkg, {
  expectedAudience: "service-agent",
  requiredScope: ["agent:interact"]
});

console.log(decision.allowed);

生产提醒： 这个示例使用开发 issuer/verifier。生产环境应实现 CredentialIssuer、CredentialVerifier、CertificateChainVerifier 和 CredentialStatusStore。

HTTP Transport

HttpJsonTransport 不规定 REST 路径。它只向一个 endpoint POST { operation, payload }，服务端自行路由。

import {
  AgentInterconnectClient,
  HttpJsonTransport
} from "gbz185-sdk";

const client = new AgentInterconnectClient(
  new HttpJsonTransport({
    endpoint: "https://api.example.com/gbz185",
    headers: { authorization: "Bearer token" }
  })
);

const results = await client.discover({
  text: "calendar schedule",
  requiredSkills: ["schedule.add"]
});

服务端收到的 body 形态如下。

{
  "operation": "discovery.discover",
  "payload": {
    "text": "calendar schedule",
    "requiredSkills": ["schedule.add"]
  }
}

群组消息分发

const runtime = createAgentInterconnectRuntime();

const session = await runtime.client.createSession({
  mode: "group",
  sender: { agentId: requesterId },
  receivers: [
    { agentId: serviceAId, mode: "group" },
    { agentId: serviceBId, mode: "group" }
  ]
});

const receipts = await runtime.client.distributeMessage({
  senderRole: "requester",
  senderId: requesterId,
  sessionId: session.id,
  dataItems: [
    { type: "text/plain", metadata: {}, payload: "hello group" }
  ]
});

console.log(receipts.map((receipt) => receipt.recipientId));

未显式传 recipients 时，分发运行时会从会话中推断所有参与方，并排除发送方。

多轮工具调用

const rounds = await runtime.toolAccess.invokeUntilComplete({
  initialRequest: {
    sessionId: "session-counter",
    toolInvokeList: [
      {
        toolId: "counter",
        toolVersion: "1.0.0",
        toolInputParam: { count: 0 }
      }
    ]
  },
  isComplete: (result) =>
    Number(result.toolResultList[0]?.toolOutputParam?.count ?? 0) >= 2,
  nextRequest: (result) => ({
    sessionId: "session-counter",
    toolInvokeList: [
      {
        toolId: "counter",
        toolVersion: "1.0.0",
        toolInputParam: {
          count: Number(result.toolResultList[0]?.toolOutputParam?.count ?? 0)
        }
      }
    ]
  }),
  maxRounds: 3
});

console.log(rounds.length);

这个模式适合工具返回“还没完成，需要下一轮输入”的场景。SDK 不规定完成判断，你用 isComplete 写业务条件。