gbz185-sdk

Get Started

这一页用一个日历智能体示例跑通核心链路：身份注册、描述发布、发现、会话、任务、工具调用、最终结果消息。

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

完整链路

  1. 创建内存参考运行时：createAgentInterconnectRuntime()。
  2. 给请求方和服务方准备 GB/Z 185 身份码。
  3. 注册服务方身份并可选发行开发凭证。
  4. 注册并发布智能体描述。
  5. 注册资源侧工具。
  6. 通过发现服务找到服务方智能体。
  7. 创建点对点会话和任务。
  8. 调用工具并把结果作为 work_result 消息写回会话。

当前语言的最小链路

TypeScript Beta：完整内存运行时

TypeScript 可以在一个进程里直接创建身份、描述、发现、会话和工具运行时。下面各步骤展开完整流程。

import { createAgentInterconnectRuntime } from "gbz185-sdk";

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

1. 注册身份

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"]
});

registration.account.id 是服务方智能体身份码。开启 issueCredential 时，内存运行时也会返回一张开发凭证。

2. 发布智能体描述

const description: AgentDescription = {
  agentId: registration.account.id,
  name: "Calendar Agent",
  version: "1.0.0",
  description: "Creates calendar events from natural language task requests",
  provider: "Example Org",
  accessAddress: "local://calendar",
  accessMethod: [{ type: "url", address: "local://calendar" }],
  authentication: { type: "x509" },
  capabilities: { asyncMessages: true, taskStateHistory: true },
  defaultInputTypes: ["text", "json"],
  defaultOutputTypes: ["json"],
  skills: [
    {
      skillId: "schedule.add",
      skillName: "add_schedule",
      skillDescription: "Add one calendar schedule item",
      tags: ["calendar", "schedule"],
      inputTypes: ["text", "json"],
      outputTypes: ["json"]
    }
  ]
};

await runtime.client.registerDescription(description);
await runtime.client.publishDescription(description.agentId);

注册会校验描述和技能必填字段；发布后才能被默认发现流程检索到。

3. 注册工具

await runtime.toolRuntime.registerTool(
  {
    toolId: "calendar.add",
    toolName: "add_schedule",
    toolDescription: "Add one calendar event",
    toolVersion: "1.0.0",
    toolInputParam: { date: "string", time: "string", event: "string" },
    toolOutputParam: { eventId: "string", accepted: "boolean" }
  },
  (input) => ({
    eventId: `evt-${input.date}-${input.time}`,
    accepted: true
  })
);

ToolRuntime 是资源侧工具服务，ToolAccessRuntime 是智能体侧工具访问门面。内存运行时已经把二者连在一起。

4. 发现智能体

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

if (!match) {
  throw new Error("Calendar agent was not discovered");
}

发现服务会按文本、名称、技能、标签、输入输出类型、可发现性和可用性过滤，并返回 score 与 matchedBy。

5. 建会话与任务

const session = await runtime.client.createSession({
  mode: "point_to_point",
  sender: { agentId: requesterId },
  receivers: [
    {
      agentId: match.description.agentId,
      mode: "point_to_point",
      accessAddress: match.description.accessAddress
    }
  ]
});

const task = await runtime.client.submitTask({
  sessionId: session.id
});

mode 可以是 point_to_point、group 或 hybrid。任务初始状态为 accepted。

6. 调用工具并回写最终结果

const toolResult = await runtime.client.invokeTools({
  sessionId: session.id,
  toolInvokeList: [
    {
      toolId: "calendar.add",
      toolVersion: "1.0.0",
      toolInputParam: {
        date: "2026-06-26",
        time: "10:00",
        event: "GB/Z 185 SDK review"
      }
    }
  ]
});

await runtime.client.sendMessage({
  senderRole: "service",
  senderId: match.description.agentId,
  sessionId: session.id,
  taskId: task.id,
  artifact: "work_result",
  final: true,
  lastChunk: true,
  dataItems: [
    {
      type: "application/json",
      metadata: {},
      payload: toolResult.toolResultList[0] ?? null
    }
  ]
});

工具调用不会因为某个工具失败而让整个批次抛错；失败项会以 ok: false 和 statusCode 出现在结果列表里。

运行仓库内示例

git clone https://github.com/IchenDEV/gbz185-sdk.git
cd gbz185-sdk
pnpm install
pnpm build
pnpm example:calendar

说明： 仓库使用 tsx 执行 TypeScript 示例。业务项目里也可以直接从 gbz185-sdk 导入同样 API。