API Reference | gbz185-sdk

运行时工厂

`createAgentInterconnectRuntime()`

function createAgentInterconnectRuntime(): AgentInterconnectRuntime

创建一个完整的内存参考运行时，包含身份、凭证、描述、发现、交互、消息分发、工具服务、工具访问、transport 和 client。

输入: 无。
返回: AgentInterconnectRuntime，可直接用于本地开发和测试。
适用: 快速原型、单进程测试、国标流程 smoke test。

`AgentInterconnectRuntime`

工厂返回的组合对象。

属性	类型	用途
`credentials`	开发凭证仓库、状态仓库、issuer、verifier	本地凭证签发、状态更新、验签。
`agentIdentityMaintenance`	`AgentIdentityMaintenance`	智能体侧身份维护门面。
`agentDescriptionMaintenance`	`AgentDescriptionMaintenance`	智能体侧描述维护门面。
`interconnectionAuthorization`	`InterconnectionAuthorizationRuntime`	过程凭证包、对端鉴别、互鉴权。
`identityRegistry`	`IdentityRegistryRuntime`	管理服务侧身份账户运行时。
`descriptionRegistry`	`AgentDescriptionRegistry`	描述注册、审核、发布和撤销。
`discoveryService`	`DiscoveryService`	发现服务。
`interactionRuntime`	`InteractionRuntime`	会话、任务、消息。
`messageDistribution`	`MessageDistributionRuntime`	群组消息分发和收件箱。
`toolRuntime`	`ToolRuntime`	资源侧工具注册和执行。
`toolAccess`	`ToolAccessRuntime`	智能体侧工具访问。
`transport`	`InProcessJsonTransport`	内存 operation 路由。
`client`	`AgentInterconnectClient`	统一客户端。

AgentInterconnectClient

new AgentInterconnectClient(transport: JsonTransport)

客户端只依赖 JsonTransport，因此同一套调用可以走内存、HTTP 或自定义协议。

方法	输入	返回	说明
`registerIdentity(input)`	`RegisterIdentityInput`	`RegisterIdentityResult`	注册身份账户，可同时发行开发凭证。
`getIdentity(agentId)`	`AgentIdentityCode`	`IdentityAccount \| undefined`	按身份码读取账户。
`issueCredential(agentId, input)`	subject、audience、scope、expiresAt	`IssuedCredential`	给已有身份账户发行凭证。
`lockIdentity(agentId, reason?)`	身份码、原因	`IdentityAccount`	锁定身份账户，并联动锁定已发行凭证。
`unlockIdentity(agentId, reason?)`	身份码、原因	`IdentityAccount`	恢复身份账户和凭证状态。
`revokeIdentity(agentId, reason?)`	身份码、原因	`IdentityAccount`	注销身份账户，并联动注销凭证。
`registerDescription(description)`	`AgentDescription`	`DescriptionRecord`	注册并校验智能体描述。
`reviewDescription(agentId, review)`	reviewerId、approved、reason、riskLevel	`DescriptionRecord`	追加描述审核记录。
`issuePublicationCertificate(agentId, input)`	issuer、publicKeyDigest、metadata	`PublicationCertificate`	签发描述发布证书元数据。
`publishDescription(agentId)`	身份码	`DescriptionRecord`	发布描述，使其默认可被发现。
`publishDescriptionWithInfo(agentId, publication?)`	身份码、发布信息	`DescriptionRecord`	发布并携带区域、权限、版权等发布元数据。
`unpublishDescription(agentId)`	身份码	`DescriptionRecord`	下架描述，并标记不可用。
`revokeDescription(agentId, reason?)`	身份码、原因	`DescriptionRecord`	撤销描述，并标记不可发现、不可用。
`discover(query)`	`DiscoveryQuery`	`DiscoveryResult[]`	按文本、身份码、名称、技能、标签和 IO 类型发现。
`createSession(input)`	`CreateSessionInput`	`Session`	创建点对点、群组或混合会话。
`submitTask(input)`	`SubmitTaskInput`	`Task`	在会话内创建任务，初始状态为 `accepted`。
`sendMessage(input)`	`SendMessageInput`	`Message`	发送消息，可关联任务、分块和最终结果。
`distributeMessage(input, recipients?)`	消息输入、收件人列表	`DistributionReceipt[]`	群组消息分发，未传收件人时从会话推断。
`listTools(toolRequestList?)`	可选工具 ID 列表	`ToolSyncData`	获取全部或部分工具描述。
`syncToolUpdates()`	无	`ToolUpdateData`	拉取工具更新摘要，读取后清空更新集合。
`invokeTools(request)`	`ToolInvokeRequest`	`ToolInvokeResult`	批量调用工具，逐项返回成功或失败。

客户端语言版本

同一组标准 operation 在不同 SDK 里使用各自语言习惯的方法名。切换示例语言可以直接看调用形态。

TypeScript Beta

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

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

const matches = await client.discover({ text: "calendar schedule" });
const result = await client.invokeTools({
  sessionId: "session-1",
  toolInvokeList: [{ toolId: "calendar.add", toolVersion: "1.0.0", toolInputParam: {} }]
});

Python Alpha 实验中

from gbz185_sdk import AgentInterconnectClient, HttpJsonTransport

client = AgentInterconnectClient(HttpJsonTransport("https://api.example.com/gbz185"))

matches = client.discover({"text": "calendar schedule"})
result = client.invoke_tools({
    "sessionId": "session-1",
    "toolInvokeList": [{"toolId": "calendar.add", "toolVersion": "1.0.0", "toolInputParam": {}}],
})

Go Alpha 实验中

client := gbz185.NewAgentInterconnectClient(&gbz185.HttpJsonTransport{
    Endpoint: "https://api.example.com/gbz185",
})

var matches []gbz185.JSONObject
err := client.Discover(context.Background(), gbz185.JSONObject{"text": "calendar schedule"}, &matches)

var result gbz185.JSONObject
err = client.InvokeTools(context.Background(), gbz185.JSONObject{
    "sessionId": "session-1",
    "toolInvokeList": []gbz185.JSONObject{{"toolId": "calendar.add", "toolVersion": "1.0.0", "toolInputParam": gbz185.JSONObject{}}},
}, &result)

Rust Alpha 实验中

use gbz185_sdk::{AgentInterconnectClient, HttpJsonTransport};
use serde_json::json;

let client = AgentInterconnectClient::new(
    HttpJsonTransport::new("https://api.example.com/gbz185")
);

let matches = client.discover(json!({ "text": "calendar schedule" }))?;
let result = client.invoke_tools(json!({
    "sessionId": "session-1",
    "toolInvokeList": [{ "toolId": "calendar.add", "toolVersion": "1.0.0", "toolInputParam": {} }]
}))?;

Java Alpha 实验中

AgentInterconnectClient client =
    new AgentInterconnectClient(new HttpJsonTransport("https://api.example.com/gbz185"));

JsonNode matches = client.discover(Map.of("text", "calendar schedule"));
JsonNode result = client.invokeTools(Map.of(
    "sessionId", "session-1",
    "toolInvokeList", List.of(Map.of("toolId", "calendar.add", "toolVersion", "1.0.0", "toolInputParam", Map.of()))
));

身份码

`formatIdentityCode(parts)`

formatIdentityCode(parts: Omit<AgentIdentityCodeParts, "oid" | "version"> & Partial<Pick<AgentIdentityCodeParts, "oid" | "version">>): AgentIdentityCode

格式化 GB/Z 185.2 身份码。默认 OID 为 1.2.156.3088，版本为 1，业务节点会转成大写。

校验: 注册服务方和注册请求方最长 6 位；本体序列号和实例序列号最长 9 位；节点必须是 base36 字符。
异常: 非法 OID、版本、空节点、过长节点或非法字符会抛错。

`parseIdentityCode(code)`

parseIdentityCode(code: AgentIdentityCode): AgentIdentityCodeParts

解析身份码并返回结构化字段。要求完整 9 段点分结构：OID 四段、版本一段、业务节点四段。

`validateIdentityCode(code)`

validateIdentityCode(code: AgentIdentityCode): boolean

布尔校验包装器。适合表单校验或过滤输入，不会向调用方抛错。

`validateIdentityCodeParts(parts)`

validateIdentityCodeParts(parts: AgentIdentityCodeParts): void

校验结构化身份码字段。非法时抛错，合法时无返回值。

身份账户

API	签名/成员	说明
`IdentityRegistryRuntime`	`new IdentityRegistryRuntime(store?, credentialIssuer?)`	管理服务侧身份账户生命周期运行时。
`register`	`register(input: RegisterIdentityInput): Promise<RegisterIdentityResult>`	分配身份码，创建 active 账户，可选发行凭证。
`update`	`update(agentId, patch): Promise<IdentityAccount>`	更新描述或证据，并写入 audit log。
`issueCredential`	`issueCredential(agentId, input): Promise<IssuedCredential>`	给 active 账户发行凭证；locked/revoked 账户会抛错。
`lock`	`lock(agentId, reason?): Promise<IdentityAccount>`	锁定账户，并锁定该账户凭证。
`unlock`	`unlock(agentId, reason?): Promise<IdentityAccount>`	恢复账户和凭证为 active。
`revoke`	`revoke(agentId, reason?): Promise<IdentityAccount>`	注销账户，并注销该账户凭证。
`get`	`get(agentId): Promise<IdentityAccount \| undefined>`	读取单个账户。
`list`	`list(): Promise<IdentityAccount[]>`	列出账户。
`IdentityAccountStore`	`save`, `get`, `list`	身份账户存储接口，生产环境替换内存实现。
`InMemoryIdentityAccountStore`	内存 Map 实现	开发、测试使用。
`AgentIdentityMaintenance`	`register`, `refresh`, `update`, `issueCredential`, `lock`, `unlock`, `revoke`	智能体侧身份维护门面，保存当前 active account 和本地凭证。

凭证与鉴别

API	签名/成员	说明
`CredentialIssuer`	`issueCredential`, `updateCredential`, `lockCredential`, `unlockCredential`, `revokeCredential`, `getCredential`	凭证签发和生命周期接口。
`DevelopmentCredentialIssuer`	`new DevelopmentCredentialIssuer(repository?, statusStore?, issuerId?)`	开发实现：生成 Ed25519 key pair，保存 public key 和 private key，默认一年有效。
`CredentialVerifier`	`verifyPresentation(input): Promise<AuthenticationAssertion>`	过程凭证包验证接口。
`DevelopmentCredentialVerifier`	`new DevelopmentCredentialVerifier(statusStore?, chainVerifier?)`	校验证书状态、有效期、受众、scope、签名和 X.509 public key 匹配。
`CredentialStatusStore`	`getStatus`, `setStatus`	凭证状态查询接口。
`InMemoryCredentialStatusStore`	内存状态实现	保存 active、locked、revoked。
`InMemoryCredentialRepository`	`save`, `get`, `listByAgent`	凭证存储实现。
`CertificateChainVerifier`	`verifyCertificateChain(credential, now?)`	X.509 证书链验证扩展点。
`NodeX509CertificateChainVerifier`	Node.js `X509Certificate` 检查	验证证书有效期和证书 public key 是否匹配凭证 public key。
`createProcessCredentialPackage`	`createProcessCredentialPackage(input): ProcessCredentialPackage`	用私钥签名 audience、scope、timestamp、payload 等内容，生成过程凭证包。
`canonicalJson`	`canonicalJson(value): string`	稳定 JSON 序列化，用于签名载荷。

`InterconnectionAuthorizationRuntime`

new InterconnectionAuthorizationRuntime(verifier: CredentialVerifier)

智能体互联授权运行时，把凭证验证结果转为可执行的授权决策。

方法	返回	说明
`createPresentation(input)`	`ProcessCredentialPackage`	创建过程凭证包。
`authenticatePeer(pkg, policy)`	`AuthorizationDecision`	验证对端凭证包并套用授权策略。
`authorizeAssertion(assertion, policy)`	`AuthorizationDecision`	把鉴别断言转为 allow/deny。
`mutualAuthenticate(input)`	`MutualAuthenticationResult`	同时验证请求方和服务方。

描述管理

API	签名/成员	说明
`AgentDescriptionRegistry`	`new AgentDescriptionRegistry(store?)`	描述注册、审核、发布、变更、下架、撤销运行时。
`register`	`register(description): Promise<DescriptionRecord>`	校验并注册描述，默认 `discoverable` 和 `available` 为 true。
`review`	`review(agentId, review): Promise<DescriptionRecord>`	追加审核记录。
`issuePublicationCertificate`	`issuePublicationCertificate(agentId, input): Promise<PublicationCertificate>`	生成发布证书元数据。
`publish`	`publish(agentId, publication?): Promise<DescriptionRecord>`	发布描述；revoked 描述不可发布。
`change`	`change(agentId, patch): Promise<DescriptionRecord>`	合并修改描述并重新校验。
`unpublish`	`unpublish(agentId): Promise<DescriptionRecord>`	状态变为 unpublished，available 变为 false。
`revoke`	`revoke(agentId, reason?): Promise<DescriptionRecord>`	状态变为 revoked，discoverable 和 available 变为 false。
`get`	`get(agentId): Promise<DescriptionRecord \| undefined>`	读取描述记录。
`list`	`list({ publishedOnly? }): Promise<DescriptionRecord[]>`	列出全部或已发布记录。
`DescriptionStore`	`save`, `get`, `list`	描述存储扩展点。
`AgentDescriptionMaintenance`	`register`, `requestReview`, `publish`, `change`, `unpublish`, `revoke`	智能体侧描述维护门面。

发现服务

API	签名/成员	说明
`PresetDiscoverySource`	`new PresetDiscoverySource(descriptions?)`, `list()`	预置发现源，可表示缓存、用户配置或 well-known 派生描述。
`DiscoveryService`	`new DiscoveryService(registry, presetSources?)`	组合已发布描述和预置源，并按查询条件排序。
`discover`	`discover(query: DiscoveryQuery): Promise<DiscoveryResult[]>`	支持 `text`、`agentId`、`name`、`requiredSkills`、`tags`、`inputTypes`、`outputTypes`、`includeUndiscoverable`、`requireAvailable`、`limit`。

交互与消息

API	签名/成员	说明
`InteractionRuntime`	`createSession`, `submitTask`, `updateTaskState`, `sendMessage`, `listMessages`, `getSession`, `getTask`	GB/Z 185.6 会话、任务、消息内存运行时。
`createSession`	`createSession(input): Promise<Session>`	创建会话；至少需要一个 receiver。
`submitTask`	`submitTask(input): Promise<Task>`	创建任务，状态为 accepted，可带初始消息和产物。
`updateTaskState`	`updateTaskState(taskId, state): Promise<Task>`	更新任务状态。
`sendMessage`	`sendMessage(input): Promise<Message>`	写入会话消息；可设置 `artifact`、`final`、`chunkIndex`、`lastChunk`。
`MessageDistributionRuntime`	`distribute`, `listInbox`	群组消息分发。默认从会话中推断除发送方外的收件人。
`DistributionReceipt`	recipientId、sessionId、messageId、deliveredAt、message	分发回执。

工具调用

API	签名/成员	说明
`ToolRuntime`	`registerTool`, `listTools`, `getUpdates`, `invoke`	资源侧工具服务。
`registerTool`	`registerTool(descriptor, handler): Promise<ToolDescriptor>`	校验工具描述并注册 handler。
`listTools`	`listTools(requestedToolIds?): Promise<ToolSyncData>`	返回全部工具或指定 ID 工具。未传 ID 时 `syncType` 为 1。
`getUpdates`	`getUpdates(): Promise<ToolUpdateData>`	返回注册后发生更新的工具摘要，并清空更新集合。
`invoke`	`invoke(request): Promise<ToolInvokeResult>`	批量调用工具。缺失工具返回 `TOOL_NOT_FOUND`，handler 抛错返回 `TOOL_EXECUTION_FAILED`。
`ToolAccessRuntime`	`getToolList`, `syncToolUpdates`, `invokeTools`, `invokeUntilComplete`	智能体侧工具访问门面。
`invokeUntilComplete`	`invokeUntilComplete({ initialRequest, isComplete, nextRequest, maxRounds? })`	循环调用工具，直到完成或达到最大轮次，默认最多 8 轮。
`ToolHandler`	`(input, context) => JsonObject \| Promise<JsonObject>`	工具实现函数，context 带 sessionId 和当前调用项。

Transport

API	签名/成员	说明
`JsonTransport`	`request<TRequest, TResponse>(operation, payload)`	所有 client 调用的唯一传输抽象。
`JsonOperationHandler`	`(payload) => TResponse \| Promise<TResponse>`	进程内 operation handler 类型。
`InProcessJsonTransport`	`register(operation, handler)`, `request(operation, payload)`	本地 operation 路由。未注册 operation 会抛错。
`HttpJsonTransport`	`new HttpJsonTransport({ endpoint, fetchImpl?, headers? })`	向 endpoint POST `{ operation, payload }`，响应 body 按 JSON 解析。

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

const client = new AgentInterconnectClient(transport);
const results = await client.discover({ text: "calendar schedule" });

校验

API	返回	说明
`isJsonObject(value)`	`value is JsonObject`	判断普通 JSON 对象。
`validateSkillDescription(skill, path?)`	`ValidationResult`	校验技能 ID、名称、描述、标签、输入输出类型、示例和依赖。
`validateAgentDescription(description)`	`ValidationResult`	校验身份码、名称、版本、provider、capabilities、默认 IO、skills、accessMethod。
`assertAgentDescription(description)`	`void`	校验失败时抛出聚合错误。
`validateToolDescriptor(tool)`	`ValidationResult`	校验工具 ID、名称、描述、版本、输入输出 JSON 对象。
`assertToolDescriptor(tool)`	`void`	校验失败时抛错。

核心模型与接口

类型	关键字段	说明
`AgentIdentityCodeParts`	oid、version、registrationServiceProvider、registrationRequester、ontologySerial、instanceSerial	身份码结构化字段。
`AgentIdentityCode`	`string`	身份码字符串别名。
`IdentityAccount`	id、delegatorId、subject、status、credentialIds、evidence、auditLog、createdAt、updatedAt	身份账户记录。
`RegisterIdentityInput`	delegatorId、subject、registrationServiceProvider、registrationRequester、ontologySerial、instanceSerial、issueCredential、credentialAudience、credentialScope	注册身份输入。
`AgentCredential`	credentialId、agentId、issuerId、subject、publicKeyPem、certificatePem、audience、scope、issuedAt、expiresAt	智能体凭证。
`ProcessCredentialPackage`	credential、audience、scope、nonce、timestamp、payload、signature	过程凭证包。
`AuthenticationAssertion`	assertionId、result、agentId、credentialId、verifiedAt、reason、verifiedAttributes、policyAdvice	鉴别断言。
`AuthorizationPolicy`	expectedAudience、requiredScope、allowNeedsMoreVerification、metadata	授权策略。
`AgentDescription`	agentId、name、version、description、provider、accessMethod、authentication、capabilities、defaultInputTypes、defaultOutputTypes、skills、discoverable、available	智能体描述。
`SkillDescription`	skillId、skillName、skillDescription、tags、examples、inputTypes、outputTypes、dependencies	智能体技能描述。
`DescriptionRecord`	description、status、published、reviews、publication、publicationCertificate、revokedAt、revokeReason	描述生命周期记录。
`DiscoveryQuery`	text、agentId、name、requiredSkills、tags、inputTypes、outputTypes、includeUndiscoverable、requireAvailable、limit	发现查询。
`DiscoveryResult`	description、score、matchedBy	发现结果和匹配原因。
`Session`	id、mode、sender、receivers、context、createdAt	会话。
`Task`	id、sessionId、state、stateChangedAt、messages、artifacts	任务。
`Message`	senderRole、senderId、sessionId、taskId、id、artifact、final、chunkIndex、lastChunk、dataItems、createdAt	消息。
`DataItem`	type、metadata、payload	消息数据项。
`ToolDescriptor`	toolId、toolName、toolDescription、toolVersion、toolInputParam、toolOutputParam、metadata	工具描述。
`ToolInvokeRequest`	sessionId、timestamp、toolInvokeList	工具调用请求。
`ToolInvokeResult`	sessionId、timestamp、toolResultList	工具调用结果。
`JsonObject` / `JsonValue`	JSON 兼容值	传输和模型扩展字段的基础类型。

国标覆盖常量

常量	类型	说明
`GBZ185_FUNCTIONS`	`Gbz185FunctionDescriptor[]`	12 个 GB/Z 185.1 功能域到 SDK surface 的映射。
`GBZ185_FRAI_INTERFACES`	`Gbz185FraiInterfaceDescriptor[]`	FRAI-01 到 FRAI-10 参考接口映射。
`GBZ185_CONFORMANCE_MATRIX`	`Gbz185ConformanceItem[]`	GB/Z 185.1-185.7 条款级覆盖矩阵。