Tools

In Zia Agents, tools are what enable your agent to do things actually. A Zia Agent can understand queries and decide what to do, but it can’t directly act on your business systems until it has tools.

Tools are the agent’s action layer — every time your agent fetches data, updates a record, or triggers an action, it does so by calling an API you’ve allowed it to use.

For instance, if you're building a Sales Assistant for Zoho CRM, the agent would need tools to get deal records, update deal stages, or fetch contact information. These tools are essentially API-based actions that allow your agent to interact with your services, whether it's CRM, Desk, Projects, or anything else.

Without tools, your agent would just be answering questions without the ability to take meaningful actions.

Tool Groups: Organizing the tools

A Tool Group is a collection of tools your agent can use to take action. You can add APIs from one or multiple Zoho services in the same group. This lets you design workflows that span across products — for example:

• Read deal data from Zoho CRM 
• Create tickets in Zoho Desk 

Organizing tools into groups keeps things manageable and ensures your agent uses the right APIs for the right purpose.

Ways to build a Tool Group:

You can build tool groups in two methods.

Understanding API methods and endpoints

Every tool is based on an API, and each API has two important parts:

• Method: The type of action the API performs. 
• Endpoint: The location where the action happens.

Endpoint example:

1. GET /crm/v8/Leads/{record_id}

This means the API will fetch the details of a specific lead, using its ID.

Best practices:

• Group tools that belong to the same workflow (e.g., “Lead-to-Ticket Handoff”) instead of adding unrelated actions. 
• Select only the scopes your tools need. 
• Use descriptive tools and tool group names for easy identification. 
• Test before publishing: Ensure each tool works with sample data. 
• Re-test and adjust if a service updates its API.

YAML File

The YAML file is where you define the structure of the APIs your agent will use. It’s like giving your agent a blueprint of the actions it can perform.

For the agent to work, every action it performs—like getting a deal record, updating a contact, or creating a ticket—must be defined in this YAML. You can include multiple APIs in the same file, depending on what actions your agent needs to cover.

Let's say your agent needs to fetch a record from Zoho CRM. The YAML file defines:

• API endpoints your agent can access. 
• The parameters those endpoints need (like which module and which record to work with). 
• The authentication required to call them (ensuring secure access). 
• The responses the agent should expect when the call succeeds or fails so the agent knows how to handle the reply. 

All of this is written in OpenAPI 3.0 format.

OpenAPI 3.0 is an open specification for defining and documenting REST APIs, enabling both humans and machines to understand and interact with them without needing to access source code, documentation, or network traffic inspection. It's a language-agnostic interface that uses a standard format, typically YAML or JSON, to describe API details like available endpoints, operations, parameters, and data models.

The system parameters you see in the YAML, like module_api_name and record_id, help the agent dynamically work with different modules and records. Without these, the agent wouldn’t know which record or which module to target.

Create a new tool group

To create a new tool group, follow the steps below.

1. On your Zia Agents account, navigate to the Tools tab on the left. 
2. Click New Tool Group. 
3. Enter the tool group name 
   
4. Choose the mode of creation: 

1. Predefined: Choose a set of predefined APIs to make a tool group.  
   
2. Create from scratch (Create with your own YAML file): Create a new API tool with your own YAML file
   
   

Predefined

Zia Agents Studio comes with pre-defined tools for different Zoho Services.

1. Click on the service based on your requirement.
2. You can see a list of the supported APIs for the service, along with the description of the API.
   You can also view the Method used in the API (GET/POST) and the Path for additional details. 
3. Click Add for the required APIs.
   

Create From Scratch

To create a tools group from scratch, 

1. Click the upload icon and upload your YAML file.  
2. Under Schema, choose the service name, say, Zoho CRM. 
3. Click Validate.
   The selected APIs from the YAML file will be listed. Once the validation is successful, click Next.
   

5. Under Description, add a description about the Tools Group for reference.
   

Predefined APIs are marked as Ready, whereas APIs from uploaded YAML files added as Draft and require testing before being Ready.

6. Select the APIs and click Test API.
   

1. You can either associate with the existing connection or create a new connection and then associate it.
   
2. Provide the parameter values from your service. 
   For example, for the selected getRecordById API in our example, set the module parameter's value as Leads, and provide the record ID for the test lead. 
3. Click Test.
   

7. Once the test is successful, the APIs will have Test Status as Success.
   
   
   
   You can select the tested APIs and click Mark as Ready.
   This can now be associated with the agents.
8. Click Save to save the tool group.
   
   

The tool group gets created. The same process can be repeated for creating multiple Tool groups.

Connections

A connection is used to authenticate and enable access to a specific service, such as CRM or Desk, when a tool is executed. For a connection to be valid, its associated service and OAuth scopes must align with the Tool Group’s service and the scopes required by the selected tools. Only when this alignment is ensured can the connection be associated with those tools. A tool can only be executed once it is properly linked to a valid connection.

Connections are listed under the Connections tab in the Settings page. You can see the connections created by you or the administrator of your organization under the My Connections tab. Services which are active will be marked with a green dot, while the inactive ones will be grayed.

Create a Connection,

1. Navigate to Settings > Connections. 
2. In the My Connection slide-out panel, click the Create Connection button and do the following: 

1. Pick Your Service: You will find the default services and the custom services; choose the one, which you want to connect to the API, or create a new custom Service.
   
2. Connection Details:  

1. Connection name: Set a unique name for the connection. The connection link name will get automatically updated.
2. Turn off the Yes toggle under Use Credentials of Login User if you want 
3. Select the scopes as per your requirement.
   
   

Refer here to choose the right scopes for CRM.

3. Click Create and Connect. 
   You can now connect with your credentials. In the next page, you can reuse an existing connection that has the selected service and scopes, or create a new one.
   
4. For new connection, choose one of the organizations that you want and click Submit.
   
5. Acknowledge Deluge's authorization prompt seeking consent to allow Deluge to perform CRUD operations by clicking Accept.
   
   
   

Once the authentication is done, the connection is created. 

The panel will now include sample codes in Deluge and Json to test how the agent uses the connection.