# Agents

ZBrain Builder'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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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 the 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://api.zbrain.ai/workerms/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://api.zbrain.ai/workerms/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 URL: **<https://api.zbrain.ai/workerms/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
}
```