绑定运行环境

创建或更新一个智能体版本的运行环境绑定。调用前请确认版本和提供商配置已存在，并准备与绑定状态匹配的请求字段。

PUT https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}/runtime-bindings/{provider}/{profile}

调用前准备

先确认智能体版本和运行提供商配置已存在。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID、智能体 ID、版本号、提供商和配置文件标识。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

• $AGENT_ID：智能体 ID。

• $VERSION：智能体版本。

• $PROVIDER：运行提供商。

• $PROFILE：提供商配置文件。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。
agent_id	string	是	智能体 ID。
version	string	是	智能体版本。
provider	string	是	运行提供商。
profile	string	是	提供商配置文件。

请求体

若请求体同时提供 workspace_id、agent_id、agent_version、provider 或 profile，其值必须与路径一致。

字段	类型	是否必填	说明
status	string	是	绑定状态：pending、active、binding_failed 或 disabled。
provider_binding_id	string	条件必填	status 为 active 时必填。
provider_binding_name	string	条件必填	status 为 active 时必填。
provider_binding_hash	string	条件必填	status 为 active 时必填，格式为 sha256:<hex>。
last_error	string	条件必填	status 为 binding_failed 时必填；其他状态不能传入。

请求示例

curl -X PUT "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/versions/$VERSION/runtime-bindings/$PROVIDER/$PROFILE" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "pending"
  }'

成功响应

成功时返回 200。

{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_version": "1",
    "provider": "matrixone",
    "profile": "default",
    "status": "pending",
    "registered_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

响应字段如下。

字段	类型	说明
code	integer	成功时为 0。
data.workspace_id	string	绑定所属的工作区、智能体和智能体版本。
data.agent_id	string	绑定所属的工作区、智能体和智能体版本。
data.agent_version	string	绑定所属的工作区、智能体和智能体版本。
data.provider	string	运行提供商和配置文件。
data.profile	string	运行提供商和配置文件。
data.status	string	保存后的绑定状态。
data.provider_binding_id	string	激活绑定时的运行提供商绑定标识、名称和摘要。
data.provider_binding_name	string	激活绑定时的运行提供商绑定标识、名称和摘要。
data.provider_binding_hash	string	激活绑定时的运行提供商绑定标识、名称和摘要。
data.last_error	string	仅状态为 binding_failed 时返回。
data.registered_at	string	创建和最近更新时间，使用 RFC 3339 格式。
data.updated_at	string	创建和最近更新时间，使用 RFC 3339 格式。

错误响应

{
  "code": 2,
  "message": "<错误信息>"
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	2（INVALID_ARGUMENT）	字段与状态规则不匹配、摘要格式错误、请求体与路径范围不一致，或运行环境准入校验失败。	根据 status 补全或删除条件字段，并检查提供商和配置文件。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。	检查 API Key。
403	5（PERMISSION_DENIED）	当前调用者没有更新智能体的权限。	检查工作区中的智能体授权。
404	3（NOT_FOUND）	目标智能体版本或运行提供商配置不存在。	先查询智能体版本并检查提供商和配置文件。
503	15（UNAVAILABLE）	版本服务、操作记录服务或授权依赖暂不可用。	稍后重试。

后续操作

绑定完成后，用同一智能体标识查询智能体详情确认运行环境已关联。

最后更新于 2026 年 8 月 22 日