API docs by Redocly

行动召回与执行 (0.1.3)

Download OpenAPI specification:

知识网络里的「行动」（Action）是绑定在对象类上的可执行能力。本文件是 Agent 侧的 完整闭环：

get_action_info      → 拿到行动的可执行定义与动态参数 schema
execute_action       → 填入真实参数触发执行，拿到 execution_id
get_action_execution → 按 execution_id 查这次执行的状态与逐对象结果
list_action_executions → 翻历史执行记录

执行是异步的：execute_action 立刻返回 execution_id，不等结果。参数完整性 校验与真正的执行都在下游 ontology-query 完成，本服务只做转发与裁剪。

实例标识不能自己拼：所有接口的 _instance_identities 必须来自 object-instance.yaml 或 instance-subgraph.yaml 结果里的 _instance_identity。

响应做过裁剪：执行详情与历史列表都剥掉了 Agent 决策用不上的重货 （action_type_snapshot、重复的 executor / action_source、结果集分页元数据 等），只留状态、计数与逐对象结果，以压低 token 占用。需要完整记录时直接查 ontology-query 的 action-executions / action-logs 端点。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

Action

召回行动的可执行定义

按行动类 ID（可选再加对象实例标识）召回行动，返回符合 Function Call 规范的 工具定义 _dynamic_tools。Agent 可以直接把它塞进自己的工具列表。

不传 _instance_identities 时召回的是行动类级别的定义；传了则返回已就该批 实例实例化过的参数。

工具声明了输出契约时，还会带上 output_schema——执行结果的形状，供 Agent 把 get_action_execution 拿到的 result 复述成自然语言。

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

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

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
required
string

知识网络 ID。

at_id
required
string

行动类 ID（从 Schema 检索结果里取）。

Array of objects (InstanceIdentity)

目标对象实例标识列表。不传则返回行动类级别的定义。

object (InstanceIdentity)

一个对象实例的主键键值对。必须从上游查询结果里取： query_object_instance 或 query_instance_subgraph 结果里的 _instance_identity。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical",
  • "at_id": "at_generate_treatment_plan",
  • "_instance_identities": [
    ]
}

Response samples

Content type
{
  • "headers": {
    },
  • "_dynamic_tools": [
    ]
}

触发行动执行（异步）

对一批对象实例执行某个行动类。异步：返回 execution_id 即代表已受理， 执行结果用 get_action_execution 轮询。

dynamic_params 填 get_action_info 返回的 schema 里 value_from=input 的那些参数。_instance_identities 留空表示按行动类自身的条件扫描目标实例 （由下游决定命中范围），不是「不执行」。

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

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

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
required
string

知识网络 ID。

at_id
required
string

行动类 ID。

Array of objects (InstanceIdentity)

目标对象实例。留空表示按行动类自身的条件扫描目标实例。

object

动态参数取值，对应行动定义中 value_from=input 的参数。完整性校验在 下游 ontology-query 完成。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_ops",
  • "at_id": "at_restart_pod",
  • "_instance_identities": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
{
  • "execution_id": "string",
  • "status": "string",
  • "message": "string",
  • "created_at": 0
}

查询单次行动执行

按 execute_action 返回的 execution_id 查这次执行的状态与逐对象结果。

status 为 pending / running 时结果尚未齐全；completed 表示执行流程 结束，不代表全部成功——逐对象成败看 success_count / failed_count 与 results[].status。

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

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

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
required
string

知识网络 ID。

execution_id
required
string

execute_action 返回的执行 ID。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_ops",
  • "execution_id": "cqq2g8h4d2fg00fvm8dg"
}

Response samples

Content type
{
  • "id": "string",
  • "kn_id": "string",
  • "action_type_id": "string",
  • "action_type_name": "string",
  • "status": "pending",
  • "trigger_type": "manual",
  • "execution_mode": "once",
  • "target_count": 0,
  • "total_count": 0,
  • "success_count": 0,
  • "failed_count": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "duration_ms": 0,
  • "dynamic_params": { },
  • "results": [
    ]
}

列出行动执行历史

翻某张知识网络下的行动执行记录，支持按行动类、状态、触发方式与时间区间过滤。

分页两条路互斥：offset 偏移翻页，或把上一页响应的 search_after 原样回传 做游标翻页（传了 search_after 后 offset 失效）。

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

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

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
required
string

知识网络 ID。

action_type_id
string

按行动类过滤。

status
string
Enum: "pending" "running" "completed" "failed" "cancelled"

按状态过滤。

trigger_type
string
Enum: "manual" "scheduled"

按触发方式过滤。

start_time_from
integer <int64>

起始时间下界（Unix 毫秒）。

start_time_to
integer <int64>

起始时间上界（Unix 毫秒）。

offset
integer

偏移翻页。传了 search_after 后本字段失效。

limit
integer <= 1000
Default: 20

分页条数。

search_after
Array of any

游标翻页：上一页响应返回的 search_after 原样回传。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_ops",
  • "status": "failed",
  • "start_time_from": 1704067200000,
  • "limit": 50
}

Response samples

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