查询资源绑定

读取智能体有效的工具、技能、知识库和通道绑定，并返回解析后的模型与运行提供商信息。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/bindings

调用前准备

先查询智能体列表取得智能体 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和智能体 ID。

请求参数

请求示例

curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	当前工作区 ID。
agent_id	string	是	要查看的智能体 ID。

查询参数

字段	类型	必填	说明
agent_workspace_id	string	否	智能体定义所属的工作区 ID。未提供时使用当前工作区；只能指定当前工作区或系统工作区。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_version": 2,
    "runtime": {
      "provider": "matrixone",
      "profile": "default"
    },
    "model": {
      "model_config_ref": "mc_01"
    },
    "tools": [],
    "skills": [],
    "knowledge_bases": [],
    "channel_bindings": [],
    "warnings": []
  }
}

字段说明

成功时返回 200。warnings 表示某些绑定引用未能解析，不表示整个读取请求失败。

通用字段

字段	类型	说明
code	integer	成功时为 0。

响应数据

字段	类型	说明
data.workspace_id	string	调用所在的工作区 ID。
data.agent_workspace_id	string	智能体定义所属的工作区 ID。
data.agent_id	string	智能体 ID 和资源版本。
data.agent_version	integer	智能体 ID 和资源版本。
data.runtime	object	解析后的运行目标和模型配置。
data.model	object	解析后的运行目标和模型配置。
data.provider	object	解析后的运行提供商配置。
data.tools	array	各类已解析资源绑定。每项可包含资源 ID、所属工作区、类别、状态和配置。
data.skills	array	各类已解析资源绑定。每项可包含资源 ID、所属工作区、类别、状态和配置。
data.knowledge_bases	array	各类已解析资源绑定。每项可包含资源 ID、所属工作区、类别、状态和配置。
data.channel_bindings	array	通道能力范围及该范围内可用的通道实例 ID。
data.warnings	string（字符串数组）	无法解析的资源引用说明。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

字段	类型	说明
400	2（INVALID_ARGUMENT）	路径参数或 agent_workspace_id 无效。建议：检查路径和查询参数。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。建议：检查 API Key。
403	5（PERMISSION_DENIED）	当前调用者没有读取智能体的权限。建议：检查工作区中的智能体授权。
404	3（NOT_FOUND）	智能体或其运行提供商配置不存在。建议：检查智能体 ID、所属工作区和运行目标。
503	15（UNAVAILABLE）	智能体资源服务或其授权依赖暂不可用。建议：稍后重试。

后续操作

需要调整绑定范围时更新资源绑定；需要换模型时更新模型绑定。

最后更新于 2026 年 9 月 9 日