🤖Agents

ZBrain's robust API simplifies agent management, enabling seamless operations for your enterprise AI solutions. With endpoints designed for tasks like retrieving, updating, deploying, and testing agents, this guide provides the essential details to streamline your workflow and maximize efficiency. Whether you're fetching templates, managing agent records, or generating reports, ZBrain's APIs ensure smooth integration and powerful capabilities.

Get Agent Templates

To retrieve a list of agent templates, send a GET request to the specified URL with optional query parameters for the category, skip, limit, sorting key, and sorting order. Ensure that the necessary headers are included as required by your service.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-templates

Request Method: GET

Query Strings (optional):

  • category: <<Specify the category of the templates to filter>>

  • skip: <<Specify how many templates to skip in the list>>

  • limit: <<Enter the number of templates to return>>

  • sortingKey: <<Key for sorting the templates, e.g., name, addedOn etc.>>

  • sortingOrder: <<Specify sorting order (1 or -1)>>

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request Query Parameters:

{
    "category": "",
    "skip": 0,
    "limit": 10,
    "sortingKey": "name",
    "sortingOrder": "1"
}

Sample Response:

{
    "responseData": {
        "templates": [
            {
                "_id": "66e1423a7e6cc1d2aa61448c",
                "name": "Invoice Extraction Worker",
                "description": "Extract key details from invoices, ensuring accuracy and consistency, while organizing and categorizing them for streamlined processing and easy reference.",
                "image": "https://d3tfuasmf2hsy5.cloudfront.net/assets/worker-templates/contract-clause-extraction.png",
                "icon": "",
                "sourceType": "FILE",
                "categories": [
                    "operations"
                ],
                "addedOn": 1725612653936,
                "modifiedOn": 1725612653936
            }
        ],
        "total": 3
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Get a List of Agents

To retrieve a list of agents associated with a specific tenant, send a GET request to the specified URL with the required query parameters. You can also include optional query parameters such as order, sortKey, skip, and limit for better control over the results.

Request URL: https://app.zbrain.ai:3012/v2/api/workers

Request Method: GET

Query Parameters:

  • Optional Query Parameters:

    • order: <<Order of the results (e.g., ascending/descending)>>

    • sortKey: <<Key to sort the agents (e.g., name, date)>>

    • skip: <<Number of agents to skip for pagination>>

    • limit: <<Number of agents to retrieve per request>>

Sample Request Query Parameters:

{
    "order": "asc",
    "sortKey": "addedOn",
    "skip": 0,
    "limit": 10
}

Sample Response:

{
    "responseData": {
        "data": [
            {
                "_id": "66da9e9e085b54c7268c48e0",
                "name": "test worker",
                "description": "",
                "workerTemplateId": "66dab62557b5d4a3aacc968f",
                "categories": [],
                "sourceType": "FILE",
                "addedOn": 1725603382434,
                "modifiedOn": 1725605985928
            }
        ],
        "total": 1
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Update an Agent

To update an agent, send a PUT request to the specified endpoint with the required agent ID in the URL and the body containing the fields you want to update (e.g., description, name, etc.).

Request URL: https://app.zbrain.ai:3012/v2/api/workers/:id

Request Method: PUT

Request Payload:

Replace :id in the URL with the specific agent _id you wish to update.

  • Optional Body Parameters (can update multiple fields):

    • description: <<Description of the agent>>

    • name: <<Name of the agent>>

    • categories: <<Categories for the agent>>

    • sourceType: <<Source type (e.g., FILE)>>

Sample Request Body Payload:

{
    "description": "This is test worker"
}

Sample Response:

{
    "responseData": {
        "flows": {
            "trigger": "",
            "worker": ""
        },
        "name": "test worker",
        "description": "",
        "workerTemplateId": "",
        "categories": [],
        "sourceType": "FILE",
        "isDeleted": false,
        "isActive": true,
        "_id": "66da9e9e085b54c7268c48e0",
        "source": {},
        "addedOn": 1725603382434,
        "modifiedOn": 1725605985928
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Delete an Agent

To delete an agent, send a DELETE request to the specified endpoint with the required query parameter and the agent's _id in the URL path.

Request URL: https://app.zbrain.ai:3012/api/workers/:id

Request Method: DELETE

Query Parameters:

  • In Params:

    • Replace :id with the worker’s _id to specify which agent to delete.

Sample Request:

  • Request URL: https://app.zbrain.ai:3012/api/workers/66da9e9e085b54c7268c48e0

Sample Response:

{
    "responseData": "Worker deleted successfully",
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Test an Agent

To test an agent by uploading a file or content, send a POST request to the specified endpoint with the necessary parameters.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-trigger

Request Method: POST

Request Payload:

  • Required Body Parameters:

    • workerId: <<ID of the worker to be tested>>

    • file: <<The file or content to be uploaded for testing the agent>>

Sample Request Body Payload:

{
    "workerId": "66da9e9e085b54c7268c48e0",
    "file": "path_to_your_file_or_file_content"
}

Sample Response:

{
    "responseData": {
        "status": "Test successful",
        "workerId": "66da9e9e085b54c7268c48e0",
        "result": "Processed successfully"
    },
    "message": "Test completed successfully",
    "success": true,
    "responseCode": 200
}

Get Agent Record

To retrieve the agent records using a worker's record ID, send a GET request to the specified endpoint, including the required parameters.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-records/:id

Request Method: GET

Required Parameters

  • Replace :id in the URL with the specific agent record _id.

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request:

https://app.zbrain.ai:3012/api/worker-records/:id

Sample Response:

{
    "responseData": {
        "_id": "66d9ae907a00f9d6894f346d",
        "workerId": "66deaf7dc006563ba5b559c4",
        "addedOn": 1725541962233,
        "modifiedOn": 1725616061632,
        "startTime": 1725541962233,
        "status": "COMPLETED",
        "endTime": 1725616061632,
        "output": {
            "response": "test result"
        },
        "timeTaken": 74099.399,
        "description": "Heyy",
        "name": "test record"
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Get Agent Details with its Records

To retrieve the agent details and its associated records using the agent ID, send a GET request to the specified URL with the required parameters.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-records/:id

Request Method: GET

Required Parameters

Replace :id in the URL with the specific agent's _id.

Optional Parameters

  • skip: (Number) Skip number of records

  • limit: (Number) Limit number of records

  • sortKey: (String) Sort the results by a specific key

  • order: (String) Ascending/Descending order

  • searchQuery: (String) Query to search records by name or description

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request Query Parameters:

{
  "skip": 0,
  "limit": 10,
  "sortKey": "addedOn",
  "order": "desc",
  "searchQuery": "test"
}

Sample Response:

{
    "responseData": {
        "_id": "66deaf7dc006563ba5b559c4",
        "name": "Test worker",
        "description": "",
        "workerTemplateId": "66dab62557b5d4a3aacc968f",
        "categories": [],
        "sourceType": "FILE",
        "addedOn": 1725644818174,
        "modifiedOn": 1725871425256,
        "records": [
            {
                "_id": "66d9ae907a00f9d6894f346d",
                "workerId": "66deaf7dc006563ba5b559c4",
                "addedOn": 1725541962233,
                "modifiedOn": 1725616061632,
                "startTime": 1725541962233,
                "status": "COMPLETED",
                "endTime": 1725616061632,
                "timeTaken": 74099.399,
                "description": "Heyy",
                "name": "test record"
            }
        ],
        "totalRecords": 1
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Get Report of an Agent

To retrieve the report of an agent by using its ID, send a GET request with the necessary query parameters.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-reports/:id

Request Method: GET

Required Parameters

Replace :id in the URL with the specific agent's _id.

Optional Parameters

  • skip: (Number) Number of records to skip

  • limit: (Number) Number of records to limit

  • sortingKey: (String) Key to sort the results by

  • sortingOrder: (String) Sort order (1 or -1)

  • searchQuery: (String) Search filter for records by name or description

  • startDate: (String) Start date for the report filter (format: YYYY-MM-DD)

  • endDate: (String) End date for the report filter (format: YYYY-MM-DD)

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request Query Parameters:

{
  "skip": 0,
  "limit": 10,
  "sortingKey": "addedOn",
  "sortingOrder": "-1",
  "searchQuery": "test record",
  "startDate": "2024-12-01",
  "endDate": "2024-12-06"
}

Sample Response:

{
    "responseData": {
        "records": [
            {
                "_id": "66d9ae907a00f9d6894f346d",
                "addedOn": 1725541962233,
                "modifiedOn": 1725616061632,
                "startTime": 1725541962233,
                "status": "COMPLETED",
                "endTime": 1725616061632,
                "timeTaken": 40,
                "name": "test record",
                "reaction": "OPEN",
                "isDisliked": false
            }
        ],
        "totals": {
            "totalRecords": 2,
            "totalTokenUsed": 0,
            "totalTimeTaken": 100,
            "totalLikes": 1,
            "totalDislikes": 1,
            "averageTimeTaken": 50,
            "totalCost": 0,
            "satisfactionScore": 50
        }
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Get All Categories of Agent Template

To retrieve the list of all categories for agent templates, send a GET request with the necessary query parameters.

Request URL: https://app.zbrain.ai:3012/v2/api/worker-template-categories

Request Method: GET

Query Parameters:

  • Optional:

    • skip: (Number) Number of records to skip

    • limit: (Number) Number of records to limit

    • sortingKey: (String) Key to sort the results by

    • sortingOrder: (String) Sort order (1 or -1)

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request Query Parameters:

{
  "skip": 0,
  "limit": 10,
  "sortingKey": "name",
  "sortingOrder": "1"
}

Sample Response:

{
    "responseData": {
        "categories": [
            {
                "_id": "66e1884f8b749938401dac50",
                "name": "Marketing"
            },
            {
                "_id": "66e1923a8b749938401dac55",
                "name": "Sales"
            }
        ],
        "total": 2
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}

Get Agent Template Details

To retrieve the details of an agent template, send a GET request with the required query parameters.

Request: https://app.zbrain.ai:3012/v2/api/worker-template

Request Method: GET

Query Parameters:

  • Required (at least one of the following):

    • id: (String) The ID of the agent template.

    • route: (String) The route of the agent template.

Request Headers:

  • "Authorization": "Bearer <your_access_token>"

  • "Content-Type": "application/json"

Sample Request Query Parameters:

{
  "id": "<template_id>"
}

or

{
  "route": "<template_route>"
}

Sample Response:

{
    "responseData": {
        "_id": "template_id",
        "name": "Example Template",
        "description": "Description of the template",
        "image": "image_url",
        "icon": "icon_url",
        "sourceType": "FILE",
        "categories": ["operations"],
        "steps": [
            {
                "step": 1,
                "displayName": "Worker Overview",
                "description": "Step description",
                "stepName": "OVERVIEW"
            },
            {
                "step": 2,
                "displayName": "Configure Workers",
                "description": "Step description",
                "stepName": "CONFIGURE_WORKERS",
                "fields": {
                    "trigger": {
                        "displayName": "Trigger",
                        "name": "trigger_name",
                        "type": "trigger_type",
                        "toolTip": "Trigger tooltip",
                        "description": "Trigger description",
                        "required": true,
                        "connections": []
                    }
                }
            },
            {
                "step": 3,
                "displayName": "Test Worker",
                "description": "Test worker description",
                "stepName": "TEST_WORKER"
            }
        ],
        "connections": [
            {
                "_id": "connection_id",
                "displayName": "Connection Display Name",
                "name": "connection_name",
                "toolTip": "Connection Tooltip",
                "description": "Connection description",
                "icon": "icon_url",
                "piece": {},
                "flowFile": {},
                "auth": {},
                "fields": {
                    "path": {
                        "displayName": "Path Display Name",
                        "toolTip": "Path Tooltip",
                        "description": "Path description",
                        "type": "path_type",
                        "required": true
                    }
                },
                "addedOn": 1726061261316,
                "modifiedOn": 1726061261316
            }
        ],
        "addedOn": 1725612653936,
        "modifiedOn": 1725612653936
    },
    "message": "Information fetched successfully",
    "success": true,
    "responseCode": 200
}
PreviousAPP

Last updated