API docs by Redocly

函数 (0.1.3)

Download OpenAPI specification:

执行工厂（服务名 agent-operator-integration）的函数面：写一段 Python、 在沙箱里跑起来、看输出。围绕它还有依赖查询、代码模板与 AI 生成三组辅助接口。

函数是执行工厂里最基础的能力形态——算子（operator）、工具箱里的工具、Skill 最终都可能落到一次沙箱内的函数执行。本文件只描述直接执行任意代码这条路径； 把函数注册成可复用的算子见 operator.yaml。

执行是隔离的、无状态的：每次调用从会话池取一个沙箱会话，跑完即释放， 不保证同一会话被复用，也不要依赖上次执行留下的文件或全局变量。

函数怎么写（三条硬约定，写错就跑不起来）：

  1. 每份代码必须导出一个名为 handler 的函数，它是唯一入口，改名无效。
  2. 平台把请求里的 event 作为唯一入参传给它，取值用 event.get("key", 默认值)。
  3. handler 的返回值出现在响应的 result 里，print 出来的内容进 stdout。
from typing import Dict, Any

def handler(event: Dict[str, Any]) -> Any:
    name = event.get("name", "default")
    return {"message": f"Hello, {name}"}

完整骨架（含注释）随 GET /template/{template_type} 返回，文案会按请求语言本地化。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ 前缀的 AppKey）。执行类接口要求调用方具备算子的 execute 权限，AI 生成类要求 create 权限。

Function

在沙箱中执行函数代码

把 code 送进沙箱执行，event 作为入参传给入口函数。用于调试期直接跑代码， 不需要先把它注册成算子。

timeout 的单位是秒（注意：内部面的 POST /internal-v1/function/exec/{version} 用的是毫秒，两者不一致）。

dependencies 会触发装包：声明的第三方库在执行前于沙箱内安装， 因此首次调用会明显变慢。可用 dependencies_url 换安装源（默认 https://pypi.org/simple/），内网环境建议指向私有镜像。已经预装在沙箱基础 镜像里的库不用声明——用 GET /function/dependencies 看有哪些。

响应永远是 200：代码自身抛异常不算接口失败，异常栈在 stderr 里， exit_code 非 0，result 为 null。只有参数不合法、无权限、沙箱不可用 才返回 4xx/5xx——判断执行成败看 exit_code，不要看 HTTP 状态码。

Authorizations:
OAuth2AppKey
header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
code
required
string

要执行的代码。必须导出一个名为 handler 的函数，签名 handler(event: Dict[str, Any]) -> Any；event 是请求里的同名字段， 返回值出现在响应的 result 里。骨架见 GET /template/{template_type}。

required
object

传给入口函数的事件对象。无入参时传 {}，不能省略。

language
string
Default: "python"

执行语言。目前只支持 python。

timeout
integer

执行超时，单位秒。不传走沙箱默认值。 注意与内部面 function/exec/{version} 的毫秒单位区分。

Array of objects (DependencyInfo)

执行前需要在沙箱内安装的第三方库。会显著拉长首次执行耗时； 已预装的库（见 GET /function/dependencies）不用声明。

dependencies_url
string <uri>
Default: "https://pypi.org/simple/"

安装源地址。内网环境改成私有镜像。

source
string

执行来源标记，写进沙箱环境变量供追踪用。不传则记为 function_debug。

task_id
string

任务 ID，写进沙箱环境变量，用于把本次执行关联到上游任务。

capability_id
string

能力 ID，写进沙箱环境变量。

capability_name
string

能力名称，写进沙箱环境变量。

user_id
string

用户 ID，写进沙箱环境变量。仅作追踪标记，不参与鉴权。

user_name
string

用户名，写进沙箱环境变量。同样只作追踪标记。

bkn_token
string <password>

调用方令牌，写进沙箱的进程级环境变量 BKN_TOKEN，供沙箱内的 sandbox_sdk.bkn 以调用方身份访问 BKN。

与上面几个追踪标记不同，这是真凭据，参与鉴权。走环境变量而不是 event： event 是用户函数的业务入参，凭据混在里面既污染参数命名空间，也逼着 每个想调 BKN 的人知道该往 event 里塞什么。

生命周期与 event 相同——executor 为每次执行现组一份环境再注入，随进程 消亡，不会留在池化复用的容器里。

bkn_conversation_id
string

会话 ID，写进 BKN_CONVERSATION_ID。取自 bkn_start_interaction 的返回。

bkn_interaction_id
string

交互 ID，写进 BKN_INTERACTION_ID。与 bkn_conversation_id 同源，两者一起决定沙箱内的调用挂在哪次交互下。

Responses

Request samples

Content type
application/json
Example
{
  • "code": "from typing import Dict, Any\n\ndef handler(event: Dict[str, Any]) -> Any:\n a = event.get(\"a\", 0)\n b = event.get(\"b\", 0)\n return {\"sum\": a + b}\n",
  • "event": {
    }
}

Response samples

Content type
application/json
Example
{
  • "stdout": "greeting BKN\n",
  • "stderr": "",
  • "result": {
    },
  • "metrics": {
    },
  • "exit_code": 0,
  • "execution_time_ms": 0,
  • "artifacts": [ ],
  • "session_id": "sess_aoi_0"
}

从函数代码推导参数定义

把代码送进沙箱执行，向 SDK 取它登记的 schema，从而免去在界面上把入参 / 出参 再手填一遍——@tool 函数的签名、类型注解与 docstring 已经描述了同样的信息， 这里让签名成为唯一事实源。

推导不出来不是错误：代码没用 @tool、有语法错误、import 失败，都返回 200 且 supported: false，其余字段为空，调用方据此回退到手工填写。 真正的 4xx/5xx 只在参数不合法、无权限、沙箱不可用时出现。

这会真的执行你的代码，因此与 /function/execute 用同一套 execute 授权。

Authorizations:
OAuth2AppKey
header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
code
required
string

用户函数代码。用 @tool 装饰并写好类型注解与 docstring 才推导得出， 否则返回 supported: false。

Responses

Request samples

Content type
application/json
{
  • "code": "from sandbox_sdk import tool\n\n@tool\ndef add(a: int, b: int) -> int:\n \"\"\"把两个整数相加。\"\"\"\n return a + b\n"
}

Response samples

Content type
application/json
Example
{
  • "supported": true,
  • "name": "add",
  • "description": "把两个整数相加。",
  • "inputs": [
    ],
  • "outputs": [
    ]
}

列出沙箱中已安装的依赖库

返回当前沙箱环境里已装好的第三方库。写函数前先看这里——列表里有的直接 import 即可，不必在 dependencies 里再声明一遍（声明了会触发一次无谓的 装包检查）。

本接口会从池里取一个会话来查询，响应里的 session_id 就是被查询的那个会话。

Authorizations:
OAuth2AppKey
header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Responses

Response samples

Content type
application/json
{
  • "dependencies": [
    ],
  • "session_id": "string"
}

查询某个包的可用版本

向 PyPI 源查询指定包的可用版本，供前端做版本选择。这是实时向上游源发请求， 源不可达时会失败——内网环境记得用 pypi_repo_url 指向可达的私有镜像。

python_version 用于过滤与该 Python 版本兼容的发行版。

Authorizations:
OAuth2AppKey
path Parameters
package_name
required
string
Example: requests

包名，如 requests。

query Parameters
pypi_repo_url
string <uri>
Default: "https://pypi.org/simple"

PyPI 源地址。内网环境改成私有镜像。

python_version
string
Default: "3.10"

目标 Python 版本，用于过滤兼容的发行版。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Responses

Response samples

Content type
application/json
{
  • "package_name": "requests",
  • "versions": [
    ]
}

获取函数代码模板

返回可直接填空的入口函数骨架，说明 event 怎么进、返回值怎么出。 模板文案随请求语言本地化（Accept-Language 头）。

目前只支持 python。

Authorizations:
OAuth2AppKey
path Parameters
template_type
required
string
Default: "python"
Value: "python"

模板类型。目前只有 python，传其他值返回 400。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Responses

Response samples

Content type
application/json
{
  • "template_type": "python",
  • "code_template": "from typing import Dict, Any\n\ndef handler(event: Dict[str, Any]) -> Any:\n \"\"\"\n 通用Python工具处理函数。\n\n 每个文件都需要导出一个名为 `handler` 的函数。这个函数是工具的入口点。\n\n Parameters:\n event: dict\n 表示函数执行的主要输入参数。\n 可以通过 event.get(\"key\", default_value) 获取具体的输入值。\n\n Return:\n Any data object\n 函数的返回数据，应根据用户需求定义具体的输出格式。\n 返回的数据应与声明的输出参数匹配。\n\n 请记得在元数据中填写input/output，这有助于LLM识别和使用工具。\n \"\"\"\n\n # TODO: 根据需求插入实际逻辑\n # 示例：\n # name = event.get(\"name\", \"default\")\n # return {\"message\": f\"Hello, {name}\"}\n\n result = {}\n return result\n"
}

用大模型生成函数代码或参数定义

两种生成方向，由路径上的 type 决定，必填字段也随之不同：

type 做什么 必填
python_function_generator 由自然语言描述生成 Python 函数代码 query
metadata_param_generator 由已有代码反推出入参 / 出参定义 code

必填字段缺失时返回 400，报文里直接写明缺的是 query 还是 code。

stream=true 走 SSE：响应变成 text/event-stream 而不是 JSON， 按事件流逐段读取生成内容。默认非流式，一次性返回完整结果。

用的是系统默认大模型，不在本接口指定模型名。

Authorizations:
OAuth2AppKey
path Parameters
type
required
string
Enum: "python_function_generator" "metadata_param_generator"

生成方向。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Request Body schema: application/json
required
query
string

自然语言需求描述。type=python_function_generator 时必填。

code
string

已有的函数代码。type=metadata_param_generator 时必填， 用于反推参数定义。

Array of objects (ParameterDef)

已知的入参定义，作为生成时的约束。

Array of objects (ParameterDef)

已知的出参定义，作为生成时的约束。

stream
boolean
Default: false

是否流式返回。为 true 时响应是 text/event-stream，不是 JSON。

Responses

Request samples

Content type
application/json
Example
{
  • "query": "写一个函数，接收一个订单列表，返回总金额和订单数",
  • "inputs": [
    ]
}

Response samples

Content type
{
  • "content": null
}

查看 AI 生成使用的提示词模板

返回 /ai_generate/function/{type} 内部使用的提示词模板（system prompt 与 user prompt 模板）。用于排查生成效果不佳的原因，或在外部复现同一套生成逻辑。

Authorizations:
OAuth2AppKey
path Parameters
type
required
string
Enum: "python_function_generator" "metadata_param_generator"

提示词模板类型，与生成接口的 type 一致。

header Parameters
Accept-Language
string

可选的 RFC 9110 语言偏好。服务从支持的 zh-CN、en-US 中选择响应错误文本语言。

Responses

Response samples

Content type
application/json
{
  • "prompt_id": "string",
  • "name": "string",
  • "description": "string",
  • "system_prompt": "string",
  • "user_prompt_template": "string"
}