API docs by Redocly

知识网络浏览 (0.1.3)

Download OpenAPI specification:

Context Loader（服务名 agent-retrieval）的知识网络浏览接口：从「有哪些知识网络」 到「这张网里有哪些对象类 / 关系类」，再按需下钻取完整定义。

与 schema-search.yaml 的分工：search_schema 是语义入口 （给一句话，猜相关概念）；本文件是确定性入口（列全量、按 ID 精确取）。

渐进式披露：get_kn_detail 默认 detail_level=summary，只返回骨架加属性名， 把属性的字段映射、可用算子、关系映射规则等重货剥掉——一张中等规模的网，summary 比 full 少四分之一以上的 token。需要这些细节时，再用 get_object_types / get_relation_types 按 ID 批量下钻。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ 前缀的 AppKey）。所有端点均为 POST，无请求体的也走 POST。

KnExplore

列出知识网络

列出当前账户可见的知识网络，用于发现 kn_id。请求体可选；不传按默认分页 （limit=20，按更新时间倒序）返回。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
optional
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

name_pattern
string

按名称模糊过滤。

limit
integer
Default: 20

单页数量。

offset
integer

偏移，用于翻页。

sort
string
Default: "update_time"

排序字段。

direction
string
Default: "desc"
Enum: "asc" "desc"

排序方向。

Responses

Request samples

Content type
application/json
{
  • "name_pattern": "医药",
  • "limit": 10
}

Response samples

Content type
{
  • "entries": [
    ],
  • "total_count": 0
}

获取知识网络详情

返回一张知识网络的概念全景：概念组、对象类、关系类、行动类。

detail_level 决定返回多少：

级别 保留 剥掉
summary（默认） 骨架 + 每个属性的 name / type 属性的 display_name / comment / mapped_field / condition_operations，逻辑属性的 data_source / parameters，关系类的 mapping_rules 与起终点对象类详情
full 全部 ——

两种级别都会去掉 concept_groups 里嵌套的对象类 / 关系类 / 行动类副本： 这些是顶层数组的重复拷贝，概念组只保留 object_type_ids 作为分组边界。

被剥掉的细节按需用 get_object_types / get_relation_types 取回。 对象类条目带 related_metric_count（该对象类下已建模指标数），>0 才值得 为取指标下钻。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
optional
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

detail_level
string
Default: "summary"
Enum: "summary" "full"

详情级别，见端点说明。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical"
}

Response samples

Content type
{
  • "id": "string",
  • "name": "string",
  • "comment": "string",
  • "concept_groups": [
    ],
  • "object_types": [
    ],
  • "relation_types": [
    ],
  • "action_types": [
    ]
}

按 ID 批量取对象类完整定义

取 get_kn_detail 在 summary 级别剥掉的对象类细节：属性的 mapped_field （写 run_sql 要的物理列名）、condition_operations（该属性可用的查询算子）、 逻辑属性的 data_source 与 parameters。

同时返回 related_metrics——挂在该对象类下的指标，包括没绑到逻辑属性、 因而在 logic_properties 里根本看不见的那些。这是 Agent 选指标的权威清单， 选定后走 logic-property.yaml 的 logic-property-resolver（实例 + 已绑逻辑属性）或 query_metric（其余）。

ids 里既可以传对象类 ID，也可以传对象类名（ID 优先，名称仅作兜底）； 匹配不到的 ID 原样回填在 missing 里，不报错。属性的 display_name （纯 UI 标签）在本接口也会被去掉。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

ids
required
Array of strings

要下钻的概念 ID 列表（取自 get_kn_detail）。也接受概念名称作为兜底匹配。 为空时返回 400。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_medical",
  • "ids": [
    ]
}

Response samples

Content type
{
  • "kn_id": "string",
  • "object_types": [
    ],
  • "missing": [
    ]
}

按 ID 批量取关系类完整定义

get_object_types 的关系类版本：取回 summary 级别剥掉的 mapping_rules 与起终点对象类详情。同样支持按名称兜底匹配，未命中的 ID 落 missing。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

ids
required
Array of strings

要下钻的概念 ID 列表（取自 get_kn_detail）。也接受概念名称作为兜底匹配。 为空时返回 400。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_medical",
  • "ids": [
    ]
}

Response samples

Content type
{
  • "kn_id": "string",
  • "relation_types": [
    ],
  • "missing": [
    ]
}