API docs by Redocly

上下文加载 · 行动召回与执行 API (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 复述成自然语言。

权限：调用方需具备该行动类的 view_detail 权限，以及绑定对象类的 query_data 权限；无需另行授予底层工具或 MCP 的权限。调用方无权直接读取绑定 工具时，服务先核验其行动类 view_detail 权限，再以知识网络托管代理账号读取该 行动当前发布绑定的工具定义，仅取名称、描述与参数和输出 schema，不包含源码与 服务地址，也不授予执行权限。读取绑定工具定义被拒绝时返回 403，而非依赖服务 不可用。

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

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

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

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

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 留空表示按行动类自身的条件扫描目标实例 （由下游决定命中范围），不是「不执行」。 必须提供有效的 bkn_context；缺失或传空时，执行前返回 400 conversation_required，附 required_action: create_conversation。 平台明确关闭证据采集时，bkn_start_interaction 不签发 ID，本接口可不带 bkn_context 执行，且不生成受管 Trace 记录。 Trace Core 基础设施故障时，本接口经只读探测确认后可不带上下文执行， 并标记本次调用未记录 Trace。

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

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

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

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

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
{
  • "bkn_context": {
    },
  • "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 查这次执行的状态与逐对象结果。

不传分页参数时沿用原有查询路径（最多返回 1000 条结果）。传入 results_limit 或 results_offset 时按结果分页；每页默认 100 条， results_limit > 1000 会钳制为 1000，且偏移量与实际页大小之和 不得超过 10000。比较 results_offset + len(results) 与 results_total 可判断是否还有下一页；超过 10000 条时当前接口 无法继续翻页。

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
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
required
string

知识网络 ID。

execution_id
required
string

execute_action 返回的执行 ID。

results_limit
integer >= 0

逐条结果每页条数；传 0 时默认 100，超过 1000 时钳制为 1000。

results_offset
integer >= 0

逐条结果偏移量，默认 0；传入后启用分页查询。

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,
  • "results_total": 0,
  • "results_offset": 0,
  • "results_limit": 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
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

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": [
    ]
}