Query the agent that references this tool¶

Lists the agents in the current workspace that are effectively bound to the specified tool. This interface returns the display summary of the agent, but does not return the complete definition of the agent.

GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools/{tool_id}/referencing-agents

Before you call¶

First query the tool list to obtain the tool ID. Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$TOOL_ID: Referenced tool ID.

Request example¶

curl "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools/$TOOL_ID/referencing-agents?limit=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Query the current workspace ID of the reference relationship.
`tool_id`	string	Yes	The tool ID being referenced.

Query parameters¶

Parameters	Type	Is it required	Description
`tool_workspace_id`	string	No	The workspace the tool belongs to; can only be the current workspace or `system`. If not provided, if a tool with the same name does not exist in the current workspace, the service will continue to search for system tools.
`limit`	integer	No	Quantity per page. Default `50`, maximum `200`.
`cursor`	string	No	`next_cursor` from the previous page response. Cursors must be used with the same workspace and tool combination.

Successful response¶

Returns 200 on success. If there is still data later, use next_cursor to query the next page.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "agent_01",
        "workspace_id": "ws_01",
        "name": "数据助手",
        "status": "active"
      }
    ],
    "limit": 20,
    "next_cursor": "cursor_01"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.items`	array	A summary of the agent display that references this tool.
`data.items[].id`	string	Agent ID and workspace.
`data.items[].workspace_id`	string	Agent ID and workspace.
`data.items[].name`	string	Agent name and status.
`data.items[].status`	string	Agent name and status.
`data.limit`	integer	The actual page size used by this page.
`data.next_cursor`	string	Next page cursor; does not return when there is no more data.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The tool ID, `tool_workspace_id`, or cursor is invalid, or the cursor does not belong to the current tool scope.	Use the cursor returned as is, and check the path and query parameters.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to read tools or candidate agents.	Check workspace authorization.
`404`	`3`（`NOT_FOUND`）	The tool does not exist in the current or specified tools directory.	Check tool ID and `tool_workspace_id`.
`503`	`15`（`UNAVAILABLE`）	Tool or agent reference services are temporarily unavailable.	Try again later.

Follow-up operations¶

Save the identification of the target item and then Query GitHub tool connection.

Last updated on Sep 3, 2026