Version: v5.0

Tools

The Tools API allows you to list, create, update, retrieve, and delete tools.

List tools#

Endpoints#

GET aisvc/api/v1/tools

Request#

Query parameters#

Parameter	Type	Description	Required
`_offset`	Integer	Number of results to skip	Optional
`_pageSize`	Integer	Number of results per page	Optional
`_userType`	String	Filter by the tool's unique identifier (`_userType`)	Optional
`_type`	String	Filter by the tool type (`user_tool` or `system_tool`)	Optional
`query`	String	Wildcard search on the name and description of tools	Optional

Request example#

None

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

{  "_list": [    {      "_name": "AggregateReadingsTool",      "_description": "Helps to execute an aggregation query on Reading objects.",      "_userType": "AggregateReadingsTool",      "_namespaces": [        "default"      ],      "_id": "77b7f4db-c8e7-40a2-bac0-9e964c5620e9",      "_type": "system_tool",      "_irn": "aisvc:tool:77b7f4db-c8e7-40a2-bac0-9e964c5620e9",      "_metadata": {}    },    {      "_name": "Get Assets Tool",      "_description": "Get assets",      "_userType": "GetAssetsTool",      "_namespaces": [        "autotesting1_leT0AMOg"      ],      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",      "_toolClass": "GetAssetsTool",      "_type": "user_tool",      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",      "_metadata": {        "_createdAt": "1757178319536",        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_updatedAt": "1757178319536"      }    }  ],  "_offset": 0,  "_pageSize": 25,  "_total": 50}

Create tool#

Endpoints#

POST aisvc/api/v1/tools

Request#

Request body#

Parameter	Type	Description	Required
`_namespaces`	Array of String	The namespace(s) of the tool resource	Required
`_name`	String	The tool name	Required
`_description`	String	A short description of what the tool does	Optional
`_userType`	String	Unique identifier of the tool	Required
`_toolClass`	String	Class name of the custom tool implementation	Optional

Request body example#

[  {    "_name": "Get Assets Tool",    "_description": "Get assets",    "_userType": "GetAssetsTool",    "_namespaces": [      "autotesting1_leT0AMOg"    ],    "_toolClass": "GetAssetsTool"  }]

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_name": "Get Assets Tool",      "_description": "Get sasets",      "_userType": "GetAssetsTool",      "_namespaces": [        "autotesting1_leT0AMOg"      ],      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",      "_toolClass": "GetAssetsTool",      "_type": "user_tool",      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",      "_metadata": {        "_createdAt": "1757178319536",        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_updatedAt": "1757178319536"      }    }  ]}

Get tool by ID#

Endpoints#

GET aisvc/api/v1/tools/{id}

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

    {      "_name": "Get Assets Tool",      "_description": "Get assets",      "_userType": "GetAssetsTool",      "_namespaces": [        "autotesting1_leT0AMOg"      ],      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",      "_toolClass": "GetAssetsTool",      "_type": "user_tool",      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",      "_metadata": {        "_createdAt": "1757178319536",        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_updatedAt": "1757178319536"      }    }

Update tool by ID#

Endpoints#

PUT aisvc/api/v1/tools/{id}

Request#

Request body#

Parameter	Type	Description	Required
`_name`	String	The tool name	Required
`_description`	String	A short description of what the tool does	Optional
`_userType`	String	Unique identifier of the tool	Required
`_toolClass`	String	Class name of the custom tool implementation	Optional

Request body example#

    {      "_name": "Get Assets Tool",      "_description": "Get assets",      "_userType": "GetAssetsTool",      "_namespaces": [        "autotesting1_leT0AMOg"      ],      "_toolClass": "GetAssetsTool",    }

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

{  "_name": "Get Assets Tool",  "_description": "Get assets",  "_userType": "GetAssetsTool",  "_namespaces": [    "autotesting1_leT0AMOg"  ],  "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",  "_toolClass": "GetAssetsTool",  "_type": "user_tool",  "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",  "_metadata": {    "_createdAt": "1757178319536",    "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",    "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",    "_updatedAt": "1757178319536"  }}

Delete tool by ID#

Endpoints#

DELETE aisvc/api/v1/tools/{id}

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

// empty response body

Upload Tool Source Code#

Endpoints#

PUT aisvc/api/v1/tools/{id}/sourcecodes

Request#

Request body#

{    "_content":"import { AbstractTool } from '@dtplatform/agent-core';\nimport * as PlatformAPI from '@dtplatform/platform-api';\nconst { IafItemSvc } = PlatformAPI;\nimport { z } from 'zod';\n\nconst toolSchema = z.object({\n  name: z.string().optional().nullable().describe('Filter by asset name. Supports regex'),\n  dtCategory: z.string().optional().nullable().describe('Filter by the dtCategory property. Supports regex'),\n  dtType: z.string().optional().nullable().describe('Filter by dtType property. Supports regex'),\n  _pageSize: z.string().optional().nullable().describe('Sets the number of results to return per Page in the response'),\n  _offset: z.string().optional().nullable().describe('Sets the number of results to skip in the Page response. For example, set to `10` to skip the first 10 results.')\n});\n\nexport default class GetAssetsTool extends AbstractTool {\n  name: string = 'GetAssetsTool';\n  description: string = 'Helps to retrieve Assets based on the provided criteria.';\n  requestContext: any = {};\n  schema: any = toolSchema;\n\n  constructor(...args: any[]) {\n    super(...args);\n    const [{ requestContext }] = args;\n    this.requestContext = requestContext;\n  }\n\n  async _call(args: z.infer<typeof toolSchema>) {\n    let criteria: any = { '$or': [] };\n    let options: any = {};\n    let response: any = {};\n\n    if (args.name || args.dtCategory || args.dtType) {\n      if (args.name) {\n        criteria['$or'].push({\n          'Asset Name': {\n            '$regex': this.toRegexString(args.name),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtCategory) {\n        criteria['$or'].push({\n          'properties.dtCategory.val': {\n            '$regex': this.toRegexString(args.dtCategory),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtType) {\n        criteria['$or'].push({\n          'properties.dtType.val': {\n            '$regex': this.toRegexString(args.dtType),\n            '$options': 'i'\n          }\n        });\n      }\n\n      if (args._pageSize) {\n        options['_pageSize'] = parseInt(args._pageSize, 10);\n      }\n      if (args._offset) {\n        options['_offset'] = parseInt(args._offset, 10);\n      }\n\n      let colQuery = {\n        query: {\n          _userType: 'iaf_ext_asset_coll',\n          _itemClass: 'NamedUserCollection'\n        }\n      };\n\n      const colOptions = {\n        project: { _userType: 1, _itemClass: 1 },\n        sort: { _name: 1 },\n        page: { _offset: 0, _pageSize: 1 }\n      };\n\n      const colResponse = await IafItemSvc.getNamedUserItems(\n        colQuery,\n        this.requestContext,\n        colOptions\n      );\n\n\n\n      let assetCollection: any = null;\n      if (colResponse && Array.isArray(colResponse._list) && colResponse._list.length > 0) {\n        assetCollection = colResponse._list[0];\n        if (assetCollection && assetCollection._id) {\n          response = await IafItemSvc.getRelatedItems(\n            assetCollection._id,\n            {query: criteria},\n            this.requestContext,\n            options            \n          );\n        }\n      }\n    }\n    return response;\n  }\n\n  toRegexString(str) {\n    const quoted = str.match(/^'(.*)'$/);\n    if (quoted) {\n      const escaped = quoted[1].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');\n      return `.*(${escaped}).*`;\n    }\n    const terms = str\n      .split(/\s+/)\n      .map(term => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));\n    return `.*(${terms.join('|')}).*`;\n  }\n}\n"}

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Get Tool Source Code#

Endpoints#

GET aisvc/api/v1/tools/{id}/sourcecodes

Response#

Codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body#

    [    {        "_content": "import { AbstractTool } from '@dtplatform/agent-core';\nimport * as PlatformAPI from '@dtplatform/platform-api';\nconst { IafItemSvc } = PlatformAPI;\nimport { z } from 'zod';\n\nconst toolSchema = z.object({\n  name: z.string().optional().nullable().describe('Filter by asset name. Supports regex'),\n  dtCategory: z.string().optional().nullable().describe('Filter by the dtCategory property. Supports regex'),\n  dtType: z.string().optional().nullable().describe('Filter by dtType property. Supports regex'),\n  _pageSize: z.string().optional().nullable().describe('Sets the number of results to return per Page in the response'),\n  _offset: z.string().optional().nullable().describe('Sets the number of results to skip in the Page response. For example, set to `10` to skip the first 10 results.')\n});\n\nexport default class GetAssetsTool extends AbstractTool {\n  name: string = 'GetAssetsTool';\n  description: string = 'Helps to retrieve Assets based on the provided criteria.';\n  requestContext: any = {};\n  schema: any = toolSchema;\n\n  constructor(...args: any[]) {\n    super(...args);\n    const [{ requestContext }] = args;\n    this.requestContext = requestContext;\n  }\n\n  async _call(args: z.infer<typeof toolSchema>) {\n    let criteria: any = { '$or': [] };\n    let options: any = {};\n    let response: any = {};\n\n    if (args.name || args.dtCategory || args.dtType) {\n      if (args.name) {\n        criteria['$or'].push({\n          'Asset Name': {\n            '$regex': this.toRegexString(args.name),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtCategory) {\n        criteria['$or'].push({\n          'properties.dtCategory.val': {\n            '$regex': this.toRegexString(args.dtCategory),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtType) {\n        criteria['$or'].push({\n          'properties.dtType.val': {\n            '$regex': this.toRegexString(args.dtType),\n            '$options': 'i'\n          }\n        });\n      }\n\n      if (args._pageSize) {\n        options['_pageSize'] = parseInt(args._pageSize, 10);\n      }\n      if (args._offset) {\n        options['_offset'] = parseInt(args._offset, 10);\n      }\n\n      let colQuery = {\n        query: {\n          _userType: 'iaf_ext_asset_coll',\n          _itemClass: 'NamedUserCollection'\n        }\n      };\n\n      const colOptions = {\n        project: { _userType: 1, _itemClass: 1 },\n        sort: { _name: 1 },\n        page: { _offset: 0, _pageSize: 1 }\n      };\n\n      const colResponse = await IafItemSvc.getNamedUserItems(\n        colQuery,\n        this.requestContext,\n        colOptions\n      );\n\n\n\n      let assetCollection: any = null;\n      if (colResponse && Array.isArray(colResponse._list) && colResponse._list.length > 0) {\n        assetCollection = colResponse._list[0];\n        if (assetCollection && assetCollection._id) {\n          response = await IafItemSvc.getRelatedItems(\n            assetCollection._id,\n            {query: criteria},\n            this.requestContext,\n            options            \n          );\n        }\n      }\n    }\n    return response;\n  }\n\n  toRegexString(str) {\n    const quoted = str.match(/^'(.*)'$/);\n    if (quoted) {\n      const escaped = quoted[1].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');\n      return `.*(${escaped}).*`;\n    }\n    const terms = str\n      .split(/\s+/)\n      .map(term => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));\n    return `.*(${terms.join('|')}).*`;\n  }\n}\n"    }]