Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

feat(toolcalls): implement toolcall management features via REST API

Dmitry Ngc5a7df74389d
diff --git a/backend/migrations/sql/20260511_120000_toolcalls_privileges.sql b/backend/migrations/sql/20260511_120000_toolcalls_privileges.sql
new file mode 100644
index 00000000..20ace10f
--- /dev/null
+++ b/backend/migrations/sql/20260511_120000_toolcalls_privileges.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+-- +goose StatementBegin
+
+INSERT INTO privileges (role_id, name) VALUES
+ (1, 'toolcalls.admin'),
+ (1, 'toolcalls.view'),
+ (2, 'toolcalls.view')
+ ON CONFLICT DO NOTHING;
+
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+
+DELETE FROM privileges WHERE name IN ('toolcalls.admin', 'toolcalls.view');
+
+-- +goose StatementEnd
diff --git a/backend/pkg/server/docs/docs.go b/backend/pkg/server/docs/docs.go
index ea9f801e..b1561c30 100644
--- a/backend/pkg/server/docs/docs.go
+++ b/backend/pkg/server/docs/docs.go
@@ -3880,6 +3880,207 @@ const docTemplate = `{
}
}
},
+ "/flows/{flowID}/toolcalls/": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcalls list by flow id",
+ "parameters": [
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "flow id",
+ "name": "flowID",
+ "in": "path",
+ "required": true
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Filtering result on server e.g. {\"value\":[...],\"field\":\"...\",\"operator\":\"...\"}\n field is the unique identifier of the table column, different for each endpoint\n value should be integer or string or array type, \"value\":123 or \"value\":\"string\" or \"value\":[123,456]\n operator value should be one of \u003c,\u003c=,\u003e=,\u003e,=,!=,like,not like,in\n default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'",
+ "name": "filters[]",
+ "in": "query"
+ },
+ {
+ "type": "string",
+ "description": "Field to group results by",
+ "name": "group",
+ "in": "query"
+ },
+ {
+ "minimum": 1,
+ "type": "integer",
+ "default": 1,
+ "description": "Number of page (since 1)",
+ "name": "page",
+ "in": "query",
+ "required": true
+ },
+ {
+ "maximum": 1000,
+ "minimum": -1,
+ "type": "integer",
+ "default": 5,
+ "description": "Amount items per page (min -1, max 1000, -1 means unlimited)",
+ "name": "pageSize",
+ "in": "query"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Sorting result on server e.g. {\"prop\":\"...\",\"order\":\"...\"}\n field order is \"ascending\" or \"descending\" value\n order is required if prop is not empty",
+ "name": "sort[]",
+ "in": "query"
+ },
+ {
+ "enum": [
+ "sort",
+ "filter",
+ "init",
+ "page",
+ "size"
+ ],
+ "type": "string",
+ "default": "init",
+ "description": "Type of request",
+ "name": "type",
+ "in": "query",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcalls list received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/services.toolcalls"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid query request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcalls not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcalls",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
+ "/flows/{flowID}/toolcalls/{toolcallID}": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcall info by id and flow id",
+ "parameters": [
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "flow id",
+ "name": "flowID",
+ "in": "path",
+ "required": true
+ },
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "toolcall id",
+ "name": "toolcallID",
+ "in": "path",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcall info received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/models.Toolcall"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcall not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "404": {
+ "description": "toolcall not found",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcall",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
"/flows/{flowID}/usage": {
"get": {
"security": [
@@ -6604,6 +6805,121 @@ const docTemplate = `{
}
}
},
+ "/toolcalls/": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcalls list",
+ "parameters": [
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Filtering result on server e.g. {\"value\":[...],\"field\":\"...\",\"operator\":\"...\"}\n field is the unique identifier of the table column, different for each endpoint\n value should be integer or string or array type, \"value\":123 or \"value\":\"string\" or \"value\":[123,456]\n operator value should be one of \u003c,\u003c=,\u003e=,\u003e,=,!=,like,not like,in\n default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'",
+ "name": "filters[]",
+ "in": "query"
+ },
+ {
+ "type": "string",
+ "description": "Field to group results by",
+ "name": "group",
+ "in": "query"
+ },
+ {
+ "minimum": 1,
+ "type": "integer",
+ "default": 1,
+ "description": "Number of page (since 1)",
+ "name": "page",
+ "in": "query",
+ "required": true
+ },
+ {
+ "maximum": 1000,
+ "minimum": -1,
+ "type": "integer",
+ "default": 5,
+ "description": "Amount items per page (min -1, max 1000, -1 means unlimited)",
+ "name": "pageSize",
+ "in": "query"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Sorting result on server e.g. {\"prop\":\"...\",\"order\":\"...\"}\n field order is \"ascending\" or \"descending\" value\n order is required if prop is not empty",
+ "name": "sort[]",
+ "in": "query"
+ },
+ {
+ "enum": [
+ "sort",
+ "filter",
+ "init",
+ "page",
+ "size"
+ ],
+ "type": "string",
+ "default": "init",
+ "description": "Type of request",
+ "name": "type",
+ "in": "query",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcalls list received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/services.toolcalls"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid query request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcalls not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcalls",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
"/usage": {
"get": {
"security": [
@@ -9411,6 +9727,59 @@ const docTemplate = `{
}
}
},
+ "models.Toolcall": {
+ "type": "object",
+ "required": [
+ "args",
+ "call_id",
+ "flow_id",
+ "name",
+ "status"
+ ],
+ "properties": {
+ "args": {
+ "type": "string"
+ },
+ "call_id": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "string"
+ },
+ "duration_seconds": {
+ "type": "number",
+ "minimum": 0
+ },
+ "flow_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "name": {
+ "type": "string"
+ },
+ "result": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "subtask_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "task_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "updated_at": {
+ "type": "string"
+ }
+ }
+ },
"models.ToolcallsStats": {
"type": "object",
"properties": {
@@ -9991,6 +10360,20 @@ const docTemplate = `{
}
}
},
+ "services.toolcalls": {
+ "type": "object",
+ "properties": {
+ "toolcalls": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/models.Toolcall"
+ }
+ },
+ "total": {
+ "type": "integer"
+ }
+ }
+ },
"services.users": {
"type": "object",
"properties": {
diff --git a/backend/pkg/server/docs/swagger.json b/backend/pkg/server/docs/swagger.json
index 13c616ff..803e56ac 100644
--- a/backend/pkg/server/docs/swagger.json
+++ b/backend/pkg/server/docs/swagger.json
@@ -3872,6 +3872,207 @@
}
}
},
+ "/flows/{flowID}/toolcalls/": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcalls list by flow id",
+ "parameters": [
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "flow id",
+ "name": "flowID",
+ "in": "path",
+ "required": true
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Filtering result on server e.g. {\"value\":[...],\"field\":\"...\",\"operator\":\"...\"}\n field is the unique identifier of the table column, different for each endpoint\n value should be integer or string or array type, \"value\":123 or \"value\":\"string\" or \"value\":[123,456]\n operator value should be one of \u003c,\u003c=,\u003e=,\u003e,=,!=,like,not like,in\n default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'",
+ "name": "filters[]",
+ "in": "query"
+ },
+ {
+ "type": "string",
+ "description": "Field to group results by",
+ "name": "group",
+ "in": "query"
+ },
+ {
+ "minimum": 1,
+ "type": "integer",
+ "default": 1,
+ "description": "Number of page (since 1)",
+ "name": "page",
+ "in": "query",
+ "required": true
+ },
+ {
+ "maximum": 1000,
+ "minimum": -1,
+ "type": "integer",
+ "default": 5,
+ "description": "Amount items per page (min -1, max 1000, -1 means unlimited)",
+ "name": "pageSize",
+ "in": "query"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Sorting result on server e.g. {\"prop\":\"...\",\"order\":\"...\"}\n field order is \"ascending\" or \"descending\" value\n order is required if prop is not empty",
+ "name": "sort[]",
+ "in": "query"
+ },
+ {
+ "enum": [
+ "sort",
+ "filter",
+ "init",
+ "page",
+ "size"
+ ],
+ "type": "string",
+ "default": "init",
+ "description": "Type of request",
+ "name": "type",
+ "in": "query",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcalls list received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/services.toolcalls"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid query request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcalls not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcalls",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
+ "/flows/{flowID}/toolcalls/{toolcallID}": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcall info by id and flow id",
+ "parameters": [
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "flow id",
+ "name": "flowID",
+ "in": "path",
+ "required": true
+ },
+ {
+ "minimum": 0,
+ "type": "integer",
+ "description": "toolcall id",
+ "name": "toolcallID",
+ "in": "path",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcall info received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/models.Toolcall"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcall not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "404": {
+ "description": "toolcall not found",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcall",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
"/flows/{flowID}/usage": {
"get": {
"security": [
@@ -6596,6 +6797,121 @@
}
}
},
+ "/toolcalls/": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Toolcalls"
+ ],
+ "summary": "Retrieve toolcalls list",
+ "parameters": [
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Filtering result on server e.g. {\"value\":[...],\"field\":\"...\",\"operator\":\"...\"}\n field is the unique identifier of the table column, different for each endpoint\n value should be integer or string or array type, \"value\":123 or \"value\":\"string\" or \"value\":[123,456]\n operator value should be one of \u003c,\u003c=,\u003e=,\u003e,=,!=,like,not like,in\n default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'",
+ "name": "filters[]",
+ "in": "query"
+ },
+ {
+ "type": "string",
+ "description": "Field to group results by",
+ "name": "group",
+ "in": "query"
+ },
+ {
+ "minimum": 1,
+ "type": "integer",
+ "default": 1,
+ "description": "Number of page (since 1)",
+ "name": "page",
+ "in": "query",
+ "required": true
+ },
+ {
+ "maximum": 1000,
+ "minimum": -1,
+ "type": "integer",
+ "default": 5,
+ "description": "Amount items per page (min -1, max 1000, -1 means unlimited)",
+ "name": "pageSize",
+ "in": "query"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "collectionFormat": "multi",
+ "description": "Sorting result on server e.g. {\"prop\":\"...\",\"order\":\"...\"}\n field order is \"ascending\" or \"descending\" value\n order is required if prop is not empty",
+ "name": "sort[]",
+ "in": "query"
+ },
+ {
+ "enum": [
+ "sort",
+ "filter",
+ "init",
+ "page",
+ "size"
+ ],
+ "type": "string",
+ "default": "init",
+ "description": "Type of request",
+ "name": "type",
+ "in": "query",
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "toolcalls list received successful",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/SuccessResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/services.toolcalls"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "invalid query request data",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "getting toolcalls not permitted",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ },
+ "500": {
+ "description": "internal error on getting toolcalls",
+ "schema": {
+ "$ref": "#/definitions/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
"/usage": {
"get": {
"security": [
@@ -9403,6 +9719,59 @@
}
}
},
+ "models.Toolcall": {
+ "type": "object",
+ "required": [
+ "args",
+ "call_id",
+ "flow_id",
+ "name",
+ "status"
+ ],
+ "properties": {
+ "args": {
+ "type": "string"
+ },
+ "call_id": {
+ "type": "string"
+ },
+ "created_at": {
+ "type": "string"
+ },
+ "duration_seconds": {
+ "type": "number",
+ "minimum": 0
+ },
+ "flow_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "name": {
+ "type": "string"
+ },
+ "result": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "subtask_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "task_id": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "updated_at": {
+ "type": "string"
+ }
+ }
+ },
"models.ToolcallsStats": {
"type": "object",
"properties": {
@@ -9983,6 +10352,20 @@
}
}
},
+ "services.toolcalls": {
+ "type": "object",
+ "properties": {
+ "toolcalls": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/models.Toolcall"
+ }
+ },
+ "total": {
+ "type": "integer"
+ }
+ }
+ },
"services.users": {
"type": "object",
"properties": {
diff --git a/backend/pkg/server/docs/swagger.yaml b/backend/pkg/server/docs/swagger.yaml
index e1725cd6..ef648a1a 100644
--- a/backend/pkg/server/docs/swagger.yaml
+++ b/backend/pkg/server/docs/swagger.yaml
@@ -1506,6 +1506,44 @@ definitions:
- text
- type
type: object
+ models.Toolcall:
+ properties:
+ args:
+ type: string
+ call_id:
+ type: string
+ created_at:
+ type: string
+ duration_seconds:
+ minimum: 0
+ type: number
+ flow_id:
+ minimum: 0
+ type: integer
+ id:
+ minimum: 0
+ type: integer
+ name:
+ type: string
+ result:
+ type: string
+ status:
+ type: string
+ subtask_id:
+ minimum: 0
+ type: integer
+ task_id:
+ minimum: 0
+ type: integer
+ updated_at:
+ type: string
+ required:
+ - args
+ - call_id
+ - flow_id
+ - name
+ - status
+ type: object
models.ToolcallsStats:
properties:
total_count:
@@ -1902,6 +1940,15 @@ definitions:
total:
type: integer
type: object
+ services.toolcalls:
+ properties:
+ toolcalls:
+ items:
+ $ref: '#/definitions/models.Toolcall'
+ type: array
+ total:
+ type: integer
+ type: object
services.users:
properties:
total:
@@ -4581,6 +4628,144 @@ paths:
summary: Retrieve termlogs list by flow id
tags:
- Termlogs
+ /flows/{flowID}/toolcalls/:
+ get:
+ parameters:
+ - description: flow id
+ in: path
+ minimum: 0
+ name: flowID
+ required: true
+ type: integer
+ - collectionFormat: multi
+ description: |-
+ Filtering result on server e.g. {"value":[...],"field":"...","operator":"..."}
+ field is the unique identifier of the table column, different for each endpoint
+ value should be integer or string or array type, "value":123 or "value":"string" or "value":[123,456]
+ operator value should be one of <,<=,>=,>,=,!=,like,not like,in
+ default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'
+ in: query
+ items:
+ type: string
+ name: filters[]
+ type: array
+ - description: Field to group results by
+ in: query
+ name: group
+ type: string
+ - default: 1
+ description: Number of page (since 1)
+ in: query
+ minimum: 1
+ name: page
+ required: true
+ type: integer
+ - default: 5
+ description: Amount items per page (min -1, max 1000, -1 means unlimited)
+ in: query
+ maximum: 1000
+ minimum: -1
+ name: pageSize
+ type: integer
+ - collectionFormat: multi
+ description: |-
+ Sorting result on server e.g. {"prop":"...","order":"..."}
+ field order is "ascending" or "descending" value
+ order is required if prop is not empty
+ in: query
+ items:
+ type: string
+ name: sort[]
+ type: array
+ - default: init
+ description: Type of request
+ enum:
+ - sort
+ - filter
+ - init
+ - page
+ - size
+ in: query
+ name: type
+ required: true
+ type: string
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: toolcalls list received successful
+ schema:
+ allOf:
+ - $ref: '#/definitions/SuccessResponse'
+ - properties:
+ data:
+ $ref: '#/definitions/services.toolcalls'
+ type: object
+ "400":
+ description: invalid query request data
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "403":
+ description: getting toolcalls not permitted
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "500":
+ description: internal error on getting toolcalls
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ security:
+ - BearerAuth: []
+ summary: Retrieve toolcalls list by flow id
+ tags:
+ - Toolcalls
+ /flows/{flowID}/toolcalls/{toolcallID}:
+ get:
+ parameters:
+ - description: flow id
+ in: path
+ minimum: 0
+ name: flowID
+ required: true
+ type: integer
+ - description: toolcall id
+ in: path
+ minimum: 0
+ name: toolcallID
+ required: true
+ type: integer
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: toolcall info received successful
+ schema:
+ allOf:
+ - $ref: '#/definitions/SuccessResponse'
+ - properties:
+ data:
+ $ref: '#/definitions/models.Toolcall'
+ type: object
+ "400":
+ description: invalid request data
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "403":
+ description: getting toolcall not permitted
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "404":
+ description: toolcall not found
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "500":
+ description: internal error on getting toolcall
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ security:
+ - BearerAuth: []
+ summary: Retrieve toolcall info by id and flow id
+ tags:
+ - Toolcalls
/flows/{flowID}/usage:
get:
description: Get comprehensive analytics for a single flow including all breakdowns
@@ -6343,6 +6528,90 @@ paths:
summary: Update API token
tags:
- Tokens
+ /toolcalls/:
+ get:
+ parameters:
+ - collectionFormat: multi
+ description: |-
+ Filtering result on server e.g. {"value":[...],"field":"...","operator":"..."}
+ field is the unique identifier of the table column, different for each endpoint
+ value should be integer or string or array type, "value":123 or "value":"string" or "value":[123,456]
+ operator value should be one of <,<=,>=,>,=,!=,like,not like,in
+ default operator value is 'like' or '=' if field is 'id' or '*_id' or '*_at'
+ in: query
+ items:
+ type: string
+ name: filters[]
+ type: array
+ - description: Field to group results by
+ in: query
+ name: group
+ type: string
+ - default: 1
+ description: Number of page (since 1)
+ in: query
+ minimum: 1
+ name: page
+ required: true
+ type: integer
+ - default: 5
+ description: Amount items per page (min -1, max 1000, -1 means unlimited)
+ in: query
+ maximum: 1000
+ minimum: -1
+ name: pageSize
+ type: integer
+ - collectionFormat: multi
+ description: |-
+ Sorting result on server e.g. {"prop":"...","order":"..."}
+ field order is "ascending" or "descending" value
+ order is required if prop is not empty
+ in: query
+ items:
+ type: string
+ name: sort[]
+ type: array
+ - default: init
+ description: Type of request
+ enum:
+ - sort
+ - filter
+ - init
+ - page
+ - size
+ in: query
+ name: type
+ required: true
+ type: string
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: toolcalls list received successful
+ schema:
+ allOf:
+ - $ref: '#/definitions/SuccessResponse'
+ - properties:
+ data:
+ $ref: '#/definitions/services.toolcalls'
+ type: object
+ "400":
+ description: invalid query request data
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "403":
+ description: getting toolcalls not permitted
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ "500":
+ description: internal error on getting toolcalls
+ schema:
+ $ref: '#/definitions/ErrorResponse'
+ security:
+ - BearerAuth: []
+ summary: Retrieve toolcalls list
+ tags:
+ - Toolcalls
/usage:
get:
description: Get comprehensive analytics for all user's flows including usage,
diff --git a/backend/pkg/server/models/toolcalls.go b/backend/pkg/server/models/toolcalls.go
new file mode 100644
index 00000000..c7160fa9
--- /dev/null
+++ b/backend/pkg/server/models/toolcalls.go
@@ -0,0 +1,75 @@
+package models
+
+import (
+ "fmt"
+ "time"
+
+ "github.com/jinzhu/gorm"
+)
+
+type ToolcallStatus string
+
+const (
+ ToolcallStatusReceived ToolcallStatus = "received"
+ ToolcallStatusRunning ToolcallStatus = "running"
+ ToolcallStatusFinished ToolcallStatus = "finished"
+ ToolcallStatusFailed ToolcallStatus = "failed"
+)
+
+func (s ToolcallStatus) String() string {
+ return string(s)
+}
+
+// Valid is function to control input/output data
+func (s ToolcallStatus) Valid() error {
+ switch s {
+ case ToolcallStatusReceived,
+ ToolcallStatusRunning,
+ ToolcallStatusFinished,
+ ToolcallStatusFailed:
+ return nil
+ default:
+ return fmt.Errorf("invalid ToolcallStatus: %s", s)
+ }
+}
+
+// Validate is function to use callback to control input/output data
+func (s ToolcallStatus) Validate(db *gorm.DB) {
+ if err := s.Valid(); err != nil {
+ db.AddError(err)
+ }
+}
+
+// Toolcall is model to contain tool call information
+// nolint:lll
+type Toolcall struct {
+ ID uint64 `form:"id" json:"id" validate:"min=0,numeric" gorm:"type:BIGINT;NOT NULL;PRIMARY_KEY;AUTO_INCREMENT"`
+ CallID string `form:"call_id" json:"call_id" validate:"required" gorm:"type:TEXT;NOT NULL"`
+ Status ToolcallStatus `form:"status" json:"status" validate:"valid,required" gorm:"type:TOOLCALL_STATUS;NOT NULL;default:'received'"`
+ Name string `form:"name" json:"name" validate:"required" gorm:"type:TEXT;NOT NULL"`
+ Args string `form:"args" json:"args" validate:"required" gorm:"type:JSON;NOT NULL"`
+ Result string `form:"result" json:"result" validate:"omitempty" gorm:"type:TEXT;NOT NULL;default:''"`
+ DurationSeconds float64 `form:"duration_seconds" json:"duration_seconds" validate:"min=0" gorm:"type:DOUBLE PRECISION;NOT NULL;default:0"`
+ FlowID uint64 `form:"flow_id" json:"flow_id" validate:"min=0,numeric,required" gorm:"type:BIGINT;NOT NULL"`
+ TaskID *uint64 `form:"task_id,omitempty" json:"task_id,omitempty" validate:"omitnil,min=0" gorm:"type:BIGINT"`
+ SubtaskID *uint64 `form:"subtask_id,omitempty" json:"subtask_id,omitempty" validate:"omitnil,min=0" gorm:"type:BIGINT"`
+ CreatedAt time.Time `form:"created_at,omitempty" json:"created_at,omitempty" validate:"omitempty" gorm:"type:TIMESTAMPTZ;default:CURRENT_TIMESTAMP"`
+ UpdatedAt time.Time `form:"updated_at,omitempty" json:"updated_at,omitempty" validate:"omitempty" gorm:"type:TIMESTAMPTZ;default:CURRENT_TIMESTAMP"`
+}
+
+// TableName returns the table name string to guaranty use correct table
+func (tc *Toolcall) TableName() string {
+ return "toolcalls"
+}
+
+// Valid is function to control input/output data
+func (tc Toolcall) Valid() error {
+ return validate.Struct(tc)
+}
+
+// Validate is function to use callback to control input/output data
+func (tc Toolcall) Validate(db *gorm.DB) {
+ if err := tc.Valid(); err != nil {
+ db.AddError(err)
+ }
+}
diff --git a/backend/pkg/server/response/errors.go b/backend/pkg/server/response/errors.go
index f2964042..8db4e89c 100644
--- a/backend/pkg/server/response/errors.go
+++ b/backend/pkg/server/response/errors.go
@@ -151,6 +151,12 @@ var ErrKnowledgeUnauthorized = NewHttpError(403, "Knowledge.Unauthorized", "not
var ErrKnowledgeStoreUnavail = NewHttpError(503, "Knowledge.StoreUnavailable", "knowledge store (embedding provider) is not configured")
var ErrKnowledgeInvalidData = NewHttpError(500, "Knowledge.InvalidData", "invalid knowledge document data")
+// toolcalls
+
+var ErrToolcallsInvalidRequest = NewHttpError(400, "Toolcalls.InvalidRequest", "invalid toolcall request data")
+var ErrToolcallsNotFound = NewHttpError(404, "Toolcalls.NotFound", "toolcall not found")
+var ErrToolcallsInvalidData = NewHttpError(500, "Toolcalls.InvalidData", "invalid toolcall data")
+
// anonymize
var ErrAnonymizeInvalidRequest = NewHttpError(400, "Anonymize.InvalidRequest", "invalid anonymize request data")
diff --git a/backend/pkg/server/router.go b/backend/pkg/server/router.go
index 8e475386..4c685a1d 100644
--- a/backend/pkg/server/router.go
+++ b/backend/pkg/server/router.go
@@ -182,6 +182,7 @@ func NewRouter(
taskService := services.NewTaskService(orm)
subtaskService := services.NewSubtaskService(orm)
containerService := services.NewContainerService(orm)
+ toolcallService := services.NewToolcallService(orm)
assistantService := services.NewAssistantService(orm, providers, controller, subscriptions)
agentlogService := services.NewAgentlogService(orm)
assistantlogService := services.NewAssistantlogService(orm)
@@ -281,6 +282,7 @@ func NewRouter(
setTasksGroup(privateGroup, taskService)
setSubtasksGroup(privateGroup, subtaskService)
setContainersGroup(privateGroup, containerService)
+ setToolcallsGroup(privateGroup, toolcallService)
setAssistantsGroup(privateGroup, assistantService)
setAgentlogsGroup(privateGroup, agentlogService)
setAssistantlogsGroup(privateGroup, assistantlogService)
@@ -482,6 +484,19 @@ func setContainersGroup(parent *gin.RouterGroup, svc *services.ContainerService)
}
}
+func setToolcallsGroup(parent *gin.RouterGroup, svc *services.ToolcallService) {
+ toolcallsViewGroup := parent.Group("/toolcalls")
+ {
+ toolcallsViewGroup.GET("/", svc.GetToolcalls)
+ }
+
+ flowToolcallsViewGroup := parent.Group("/flows/:flowID/toolcalls")
+ {
+ flowToolcallsViewGroup.GET("/", svc.GetFlowToolcalls)
+ flowToolcallsViewGroup.GET("/:toolcallID", svc.GetFlowToolcall)
+ }
+}
+
func setAssistantsGroup(parent *gin.RouterGroup, svc *services.AssistantService) {
flowCreateGroup := parent.Group("/flows/:flowID/assistants")
{
diff --git a/backend/pkg/server/services/toolcalls.go b/backend/pkg/server/services/toolcalls.go
new file mode 100644
index 00000000..80c866b1
--- /dev/null
+++ b/backend/pkg/server/services/toolcalls.go
@@ -0,0 +1,290 @@
+package services
+
+import (
+ "errors"
+ "net/http"
+ "slices"
+ "strconv"
+
+ "pentagi/pkg/server/logger"
+ "pentagi/pkg/server/models"
+ "pentagi/pkg/server/rdb"
+ "pentagi/pkg/server/response"
+
+ "github.com/gin-gonic/gin"
+ "github.com/jinzhu/gorm"
+)
+
+type toolcalls struct {
+ Toolcalls []models.Toolcall `json:"toolcalls"`
+ Total uint64 `json:"total"`
+}
+
+type toolcallsGrouped struct {
+ Grouped []string `json:"grouped"`
+ Total uint64 `json:"total"`
+}
+
+var toolcallsSQLMappers = map[string]any{
+ "id": "{{table}}.id",
+ "call_id": "{{table}}.call_id",
+ "status": "{{table}}.status",
+ "name": "{{table}}.name",
+ "args": "{{table}}.args",
+ "result": "{{table}}.result",
+ "duration_seconds": "{{table}}.duration_seconds",
+ "flow_id": "{{table}}.flow_id",
+ "task_id": "{{table}}.task_id",
+ "subtask_id": "{{table}}.subtask_id",
+ "created_at": "{{table}}.created_at",
+ "updated_at": "{{table}}.updated_at",
+ "data": "({{table}}.name || ' ' || {{table}}.call_id || ' ' || {{table}}.args::text || ' ' || {{table}}.result)",
+}
+
+type ToolcallService struct {
+ db *gorm.DB
+}
+
+func NewToolcallService(db *gorm.DB) *ToolcallService {
+ return &ToolcallService{
+ db: db,
+ }
+}
+
+// GetToolcalls is a function to return toolcalls list
+// @Summary Retrieve toolcalls list
+// @Tags Toolcalls
+// @Produce json
+// @Security BearerAuth
+// @Param request query rdb.TableQuery true "query table params"
+// @Success 200 {object} response.successResp{data=toolcalls} "toolcalls list received successful"
+// @Failure 400 {object} response.errorResp "invalid query request data"
+// @Failure 403 {object} response.errorResp "getting toolcalls not permitted"
+// @Failure 500 {object} response.errorResp "internal error on getting toolcalls"
+// @Router /toolcalls/ [get]
+func (s *ToolcallService) GetToolcalls(c *gin.Context) {
+ var (
+ err error
+ query rdb.TableQuery
+ resp toolcalls
+ )
+
+ if err = c.ShouldBindQuery(&query); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error binding query")
+ response.Error(c, response.ErrToolcallsInvalidRequest, err)
+ return
+ }
+
+ uid := c.GetUint64("uid")
+ privs := c.GetStringSlice("prm")
+ var scope func(db *gorm.DB) *gorm.DB
+ if slices.Contains(privs, "toolcalls.admin") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.
+ Joins("INNER JOIN flows f ON f.id = toolcalls.flow_id")
+ }
+ } else if slices.Contains(privs, "toolcalls.view") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.
+ Joins("INNER JOIN flows f ON f.id = toolcalls.flow_id").
+ Where("f.user_id = ?", uid)
+ }
+ } else {
+ logger.FromContext(c).Errorf("error filtering user role permissions: permission not found")
+ response.Error(c, response.ErrNotPermitted, nil)
+ return
+ }
+
+ query.Init("toolcalls", toolcallsSQLMappers)
+
+ if query.Group != "" {
+ if _, ok := toolcallsSQLMappers[query.Group]; !ok {
+ logger.FromContext(c).Errorf("error finding toolcalls grouped: group field not found")
+ response.Error(c, response.ErrToolcallsInvalidRequest, errors.New("group field not found"))
+ return
+ }
+
+ var respGrouped toolcallsGrouped
+ if respGrouped.Total, err = query.QueryGrouped(s.db, &respGrouped.Grouped, scope); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error finding toolcalls grouped")
+ response.Error(c, response.ErrInternal, err)
+ return
+ }
+
+ response.Success(c, http.StatusOK, respGrouped)
+ return
+ }
+
+ if resp.Total, err = query.Query(s.db, &resp.Toolcalls, scope); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error finding toolcalls")
+ response.Error(c, response.ErrInternal, err)
+ return
+ }
+
+ for i := range resp.Toolcalls {
+ if err = resp.Toolcalls[i].Valid(); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error validating toolcall data '%d'", resp.Toolcalls[i].ID)
+ response.Error(c, response.ErrToolcallsInvalidData, err)
+ return
+ }
+ }
+
+ response.Success(c, http.StatusOK, resp)
+}
+
+// GetFlowToolcalls is a function to return toolcalls list by flow id
+// @Summary Retrieve toolcalls list by flow id
+// @Tags Toolcalls
+// @Produce json
+// @Security BearerAuth
+// @Param flowID path int true "flow id" minimum(0)
+// @Param request query rdb.TableQuery true "query table params"
+// @Success 200 {object} response.successResp{data=toolcalls} "toolcalls list received successful"
+// @Failure 400 {object} response.errorResp "invalid query request data"
+// @Failure 403 {object} response.errorResp "getting toolcalls not permitted"
+// @Failure 500 {object} response.errorResp "internal error on getting toolcalls"
+// @Router /flows/{flowID}/toolcalls/ [get]
+func (s *ToolcallService) GetFlowToolcalls(c *gin.Context) {
+ var (
+ err error
+ flowID uint64
+ query rdb.TableQuery
+ resp toolcalls
+ )
+
+ if flowID, err = strconv.ParseUint(c.Param("flowID"), 10, 64); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error parsing flow id")
+ response.Error(c, response.ErrToolcallsInvalidRequest, err)
+ return
+ }
+
+ if err = c.ShouldBindQuery(&query); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error binding query")
+ response.Error(c, response.ErrToolcallsInvalidRequest, err)
+ return
+ }
+
+ uid := c.GetUint64("uid")
+ privs := c.GetStringSlice("prm")
+ var scope func(db *gorm.DB) *gorm.DB
+ if slices.Contains(privs, "toolcalls.admin") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.
+ Joins("INNER JOIN flows f ON f.id = toolcalls.flow_id").
+ Where("f.id = ?", flowID)
+ }
+ } else if slices.Contains(privs, "toolcalls.view") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.
+ Joins("INNER JOIN flows f ON f.id = toolcalls.flow_id").
+ Where("f.id = ? AND f.user_id = ?", flowID, uid)
+ }
+ } else {
+ logger.FromContext(c).Errorf("error filtering user role permissions: permission not found")
+ response.Error(c, response.ErrNotPermitted, nil)
+ return
+ }
+
+ query.Init("toolcalls", toolcallsSQLMappers)
+
+ if query.Group != "" {
+ if _, ok := toolcallsSQLMappers[query.Group]; !ok {
+ logger.FromContext(c).Errorf("error finding toolcalls grouped: group field not found")
+ response.Error(c, response.ErrToolcallsInvalidRequest, errors.New("group field not found"))
+ return
+ }
+
+ var respGrouped toolcallsGrouped
+ if respGrouped.Total, err = query.QueryGrouped(s.db, &respGrouped.Grouped, scope); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error finding toolcalls grouped")
+ response.Error(c, response.ErrInternal, err)
+ return
+ }
+
+ response.Success(c, http.StatusOK, respGrouped)
+ return
+ }
+
+ if resp.Total, err = query.Query(s.db, &resp.Toolcalls, scope); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error finding toolcalls")
+ response.Error(c, response.ErrInternal, err)
+ return
+ }
+
+ for i := range resp.Toolcalls {
+ if err = resp.Toolcalls[i].Valid(); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error validating toolcall data '%d'", resp.Toolcalls[i].ID)
+ response.Error(c, response.ErrToolcallsInvalidData, err)
+ return
+ }
+ }
+
+ response.Success(c, http.StatusOK, resp)
+}
+
+// GetFlowToolcall is a function to return toolcall info by id and flow id
+// @Summary Retrieve toolcall info by id and flow id
+// @Tags Toolcalls
+// @Produce json
+// @Security BearerAuth
+// @Param flowID path int true "flow id" minimum(0)
+// @Param toolcallID path int true "toolcall id" minimum(0)
+// @Success 200 {object} response.successResp{data=models.Toolcall} "toolcall info received successful"
+// @Failure 400 {object} response.errorResp "invalid request data"
+// @Failure 403 {object} response.errorResp "getting toolcall not permitted"
+// @Failure 404 {object} response.errorResp "toolcall not found"
+// @Failure 500 {object} response.errorResp "internal error on getting toolcall"
+// @Router /flows/{flowID}/toolcalls/{toolcallID} [get]
+func (s *ToolcallService) GetFlowToolcall(c *gin.Context) {
+ var (
+ err error
+ flowID uint64
+ toolcallID uint64
+ resp models.Toolcall
+ )
+
+ if flowID, err = strconv.ParseUint(c.Param("flowID"), 10, 64); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error parsing flow id")
+ response.Error(c, response.ErrToolcallsInvalidRequest, err)
+ return
+ }
+ if toolcallID, err = strconv.ParseUint(c.Param("toolcallID"), 10, 64); err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error parsing toolcall id")
+ response.Error(c, response.ErrToolcallsInvalidRequest, err)
+ return
+ }
+
+ uid := c.GetUint64("uid")
+ privs := c.GetStringSlice("prm")
+ var scope func(db *gorm.DB) *gorm.DB
+ if slices.Contains(privs, "toolcalls.admin") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.Where("f.id = ?", flowID)
+ }
+ } else if slices.Contains(privs, "toolcalls.view") {
+ scope = func(db *gorm.DB) *gorm.DB {
+ return db.Where("f.id = ? AND f.user_id = ?", flowID, uid)
+ }
+ } else {
+ logger.FromContext(c).Errorf("error filtering user role permissions: permission not found")
+ response.Error(c, response.ErrNotPermitted, nil)
+ return
+ }
+
+ err = s.db.Model(&resp).
+ Joins("INNER JOIN flows f ON f.id = toolcalls.flow_id").
+ Scopes(scope).
+ Where("toolcalls.id = ?", toolcallID).
+ Take(&resp).Error
+ if err != nil {
+ logger.FromContext(c).WithError(err).Errorf("error on getting toolcall by id")
+ if gorm.IsRecordNotFoundError(err) {
+ response.Error(c, response.ErrToolcallsNotFound, err)
+ } else {
+ response.Error(c, response.ErrInternal, err)
+ }
+ return
+ }
+
+ response.Success(c, http.StatusOK, resp)
+}