# 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.

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

## Before you call

First [query the tool list](list-tools.md) 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

```bash
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.

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](get-github-connection.md).