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.

HTTP
GET $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/tools/{tool_id}/referencing-agents

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the tool list to obtain the tool ID.

Set the operation-specific values used in the request:

$TOOL_ID: Referenced tool ID.

Request¶

Input examples

Shell
curl "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/tools/$TOOL_ID/referencing-agents?limit=20" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Parameter reference

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.

Response example

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

Field reference

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¶

Response example

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

Field reference

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 15, 2026