Agentic Tools Configuration Guide

1. Introduction 

1.1 Overview 

The agentic tools configuration is the core input structure that enables the AI Agent to interact with external systems, databases, and APIs. This guide will help you understand and create your own tool configurations. 

Purpose: Define what actions the AI Agent can perform, including: 

•  API calls to external services 
•  Database operations (queries, inserts, updates) 
•  Integration with third-party platforms (Jira, CRM, etc.) 
•  Custom business logic execution 

2. Complete Structure Overview 

{ 
  "action_agent_user_instructions": "<instructions for how agent should behave>", 
  "connections": [ 
    { 
      "id": <unique_connection_id>, 
      "base_url": "<base URL for API>", 
      "auth_type": "<authentication method>", 
      "auth_credentials": { <auth configuration> }, 
      "db_login": "<database username>", 
      "db_password": "<database password>", 
      "src_type": "<database type>", 
      "connection_string": "<JDBC connection string>" 
    } 
  ], 
  "commands": [ 
    { 
      "id": <unique_command_id>, 
      "connection_id": <reference to connection>, 
      "name": "<tool_name>", 
      "description": "<what this tool does>", 
      "parameters": ["param1", "param2"], 
      "connector_type": "<api|jdbc|ai_agent>", 
      "http_method": "<GET|POST|PUT|DELETE>", 
      "api_path": "<endpoint path>", 
      "api_headers": { <headers> }, 
      "api_query_params": { <query parameters> }, 
      "api_body_template": { <request body structure> }, 
      "db_query": "<SQL query>", 
      "saws_id": <1 or null> 
    } 
  ] 
} 

2.1  Action Agent User Instructions 

Field: `action_agent_user_instructions` 

Type: String (multi-line text) 

Required: No (Only if any agent behavior need to be controlled) 

Purpose: Provides behavioral guidelines for the AI Agent when using tools 

Description: These instructions guide the AI Agent's decision-making process when selecting and executing tools. They define rules for tool usage, verification, and error handling. 

Example 

{ 
  "action_agent_user_instructions": "Follow below instructions related to tool utilization:\n1. If question is related to analyze a customer using HFC or FTTH tool, then **strictly** always return exactly detailed answer available in the tool output in same order and markdown without any modification.\n2. You can invoke a follow-up tool only when required and strictly to verify the outcome of the immediately preceding action only.\n3. After verification, you must stop.\n   If the outcome is unresolved or requires any further action, strictly always ask the user how they want to proceed instead of invoking another tool.\n4. If the user asks for suggestions, provide options and let them choose; if no tool matches or the request is unclear, do not invoke any tool and instead recommend suitable tools and proceed only after user confirmation" 
} 

Best Practices 

•  Set boundaries for autonomous actions 
•  Include user confirmation requirements 
•  Define response formatting rules 
•  Don't leave too open-ended (agent may over-invoke tools) 
•  Don't make rules contradictory 

2.2 Connections Configuration 

Field: connections 

Type: Array of connection objects 

Required: Yes 

Purpose: Define authentication and connection details for external systems 

Connection Object Structure 

Each connection represents credentials and configuration for accessing an external system (API, database, etc.) 

Common Fields (All Connection Types) 

2.2.1 Connection Type 1 - API Connections 

Used for REST APIs, HTTP endpoints, and web services. 

Required Fields 

Auth Type: API_KEY 

{ 
  "id": 2, 
  "base_url": "https://apis-dev.dvsum.ai", 
  "auth_type": "API_KEY", 
  "auth_credentials": { 
    "auth_placement": "header", 
    "api_headers": { 
      "x-api-key": "YOUR_API_KEY_HERE" 
    } 
  } 
} 

How it works 

•  `auth_credentials`: This is the main container that holds all authentication-related settings 
•  `auth_placement`: Tells the system whether to put the API key in the HTTP headers or as a URL query parameter 
•  `api_headers`: When using header placement, this object contains the actual header name and value pairs 

Note: Whatever passed in API headers will be send in the headers of the API request.  

Example with query placement 

{ 
  "auth_credentials": { 
    "auth_placement": "query", 
    "api_query_params": { 
      "api_key": "YOUR_API_KEY_HERE", 
      "client_id": "your_client_id" 
    } 
  } 
} 

 Auth Type: BASIC 

{ 
  "id": 3, 
  "base_url": "https://nxt.example.com:8443", 
  "auth_type": "BASIC", 
  "auth_credentials": { 
    "auth_placement": "header", 
    "credentials": { 
      "username": "your_username", 
      "password": "your_password" 
    } 
  } 
} 

Field Definitions 

How it works 

• Basic Auth automatically encodes the username and password in Base64 format 
•  The system creates an `Authorization: Basic <base64_encoded_credentials>` header 
•  You only need to provide plain text username and password - encoding is automatic 

2.2.2 Connection Type 2 - Database Connections (JDBC) 

Used for all DVSUM supported data source(MySQL, PostgreSQL, Snowflake, S3 etc.) 

{ 
  "id": 123, 
  "db_login": "Username", 
  "db_password": "your_db_password", 
  "src_type": "SNF", 
  "connection_string": "<Connection string>" 
} 

Required Fields 

Field Definitions 

Supported Database Types (`src_type`) 

2.3 Commands Configuration 

Field: `commands` 

Type: Array of command objects 

Required: Yes 

Purpose: Define individual tools/actions the AI Agent can execute 

Command Object Structure 

Each command represents one tool that the AI Agent can invoke. 

Common Fields (All Command Types) 

2.3.1 Command Type 1 -  API Commands (GET Request) 

Used for retrieving data from APIs. 

{ 
  "id": 1, 
  "connection_id": 2, 
  "name": "reboot_modem", 
  "description": "Reboot the customer's modem remotely to restore connectivity", 
  "parameters": ["mac_address"], 
  "connector_type": "api", 
  "http_method": "GET", 
  "api_path": "mock/nxt/reset-modem", 
  "api_query_params": {}, 
  "api_body_template": {}, 
  "saws_id": 42528774 
} 

API Command Fields 

Detailed Field Definitions 

How each field works 

`http_method` 

• `GET`: Retrieve data (no body required) 
•  `POST`: Create new resources (usually requires body) 

`api_path` 

• Combined with connection's `base_url` to form complete URL 
•  If `base_url = "https://api.example.com"` and `api_path = "/v1/users"` 
• Final URL: `https://api.example.com/v1/users` 

`api_headers` 

•  Overrides or adds to connection-level headers 
•  Common headers: `Content-Type`, `Accept`, `X-Custom-Header` 
•  These are merged with `auth_credentials` headers 

`api_query_params` 

•  Adds parameters to the URL 
•  Object format: `{"key": "value"}` becomes `?key=value` 
•  Can use placeholders: `{"user_id": "{{user_id}}"}` becomes `?user_id=123` 

`api_body_template` 

•  Only used with POST, PUT, PATCH methods 
•  Supports nested objects and arrays 
•  Use `{{placeholders}}` for dynamic values 

URL Path Parameters 

You can include dynamic path parameters using placeholders. 

Syntax: `{{parameter_name}}` or `{parameter_name}` 

Example 

{ 
  "api_path": "/nxt-api/xray/v1.2/cm/{{mac_address}}/poll?parameters=cmCollectStatus", 
  "parameters": ["mac_address"] 
}

When the AI Agent calls this tool with `mac_address = "AA:BB:CC:DD:EE:FF"`, mac_address will be replaced. 

2.3.2 Command Type 2 -  API Commands (POST Request) 

Used for creating/updating data via APIs. 

{ 
  "id": 4, 
  "connection_id": 4, 
  "name": "create_ticket", 
  "description": "Create a new support ticket in Jira.", 
  "parameters": ["summary", "description"], 
  "connector_type": "api", 
  "http_method": "POST", 
  "api_path": "rest/api/3/issue", 
  "api_headers": { 
    "Accept": "application/json", 
    "Content-Type": "application/json" 
  }, 
  "api_query_params": {}, 
  "api_body_template": { 
    "fields": { 
      "project": { 
        "key": "AA" 
      }, 
      "summary": "{{summary}}", 
      "description": { 
        "type": "doc", 
        "version": 1, 
        "content": [ 
          { 
            "type": "paragraph", 
            "content": [ 
              { 
                "type": "text", 
                "text": "{{description}}" 
              } 
            ] 
          } 
        ]
      }, 
      "issuetype": { 
        "name": "Task" 
      }, 
      "assignee": { 
        "id": "61c1a68d9ee70a0068a4d6fa" 
      } 
    } 
  }, 
  "saws_id": null 
} 

Request Body Template (`api_body_template`) 

Purpose: Define the JSON structure for POST/PUT requests with parameter placeholders. 

Placeholder Syntax: `{{parameter_name}}` 

How it works 

1. Define your JSON structure 

2. Use `{{parameter_name}}` where dynamic values should be inserted 

3. AI Agent will replace placeholders with actual values at runtime 

Example - Simple Body 

{ 
  "api_body_template": { 
    "customer_id": "{{customer_id}}", 
    "action": "reset", 
    "timestamp": "{{timestamp}}" 
  }, 
  "parameters": ["customer_id", "timestamp"] 
} 

Example - Nested Body 

{ 
  "api_body_template": { 
    "user": { 
      "name": "{{username}}", 
      "email": "{{email}}", 
      "settings": { 
        "notifications": true, 
        "theme": "{{theme}}" 
      } 
    } 
  }, 
  "parameters": ["username", "email", "theme"] 
} 

Auto-Mapping 

The system can intelligently map parameters to nested structures by matching field names. 

Command Type 3: Database Commands (JDBC) 

Used for executing SQL queries on databases. 

{ 
  "id": 5, 
  "connection_id": 123, 
  "name": "Update_CRM_DB", 
  "description": "Update customer information in the CRM database. Use this tool ONLY when the request is specifically about recording or updating customer details by user.", 
  "parameters": ["customer_id", "mac_address", "issue_category", "issue_description"], 
  "connector_type": "jdbc", 
  "db_query": "insert into CADDI_DEMO.DWH.customer_report_issue (customer_id, mac_address, issue_category, issue_description, timestamp) values ({{customer_id}}, {{mac_address}}, {{issue_category}}, {{issue_description}}, CURRENT_TIMESTAMP())", 
  "saws_id": 1
} 

Note: For JDBC Connection type, Saws_id should always be 1 

JDBC Command Fields 

Field Definition 

What is `db_query` 

•  This field contains the actual SQL command that will be executed on the database 
• It can be any valid SQL statement: SELECT, INSERT, UPDATE, DELETE, or stored procedure calls 
•  Use `{{parameter_name}}` placeholders for dynamic values that will be filled at runtime 
• The system automatically handles SQL injection prevention and data type formatting 

SQL Query with Parameters 

Placeholder Syntax: `{{parameter_name}}` 

Important Security Features 

• Automatic SQL injection protection 
•  Single quotes are escaped automatically 
•  String values are wrapped in quotes automatically 
•  NULL handling built-in 

Example - INSERT 

INSERT INTO customer_report_issue (customer_id, mac_address, issue_category, issue_description, timestamp)  

VALUES ({{customer_id}}, {{mac_address}}, {{issue_category}}, {{issue_description}}, CURRENT_TIMESTAMP()) 

Example - UPDATE 

UPDATE customers  
SET status = {{status}}, last_updated = {{timestamp}} 
WHERE customer_id = {{customer_id}} 

Example - SELECT 

SELECT description FROM orders  
WHERE customer_id = {{customer_id}}  
  AND order_date >= {{start_date}} 
  AND status = {{status}} 

Data Type Handling 

•  Strings: Automatically quoted and escaped (`'value'`) 
•  Numbers: Inserted as-is (`123`, `45.67`) 
•  Booleans: Converted to SQL Boolean (`TRUE`, `FALSE`) 
•  NULL: Inserted as `NULL` 

2.4: Advanced Features 

2.4.1 Gateway Routing (saws_id) 

The `saws_id` field determines how commands are executed. 

Option 1: Gateway Execution (saws_id provided) 

{ 
  "saws_id": 1 
} 

• Command is routed through SAWS Gateway 
•  Enables enterprise features (auditing, monitoring, security) 
• Requires gateway infrastructure 
•  Supports asynchronous responses via WebSocket 

Option 2: Direct Execution (saws_id = null) 

{ 
  "saws_id": null 
} 

• Command executes directly from the AI Agent 
•  Faster for simple operations 
•  No gateway infrastructure required 
•  Synchronous responses 

When to use each 

•  Gateway: Enterprise deployments, secured, regulated environments, complex workflows 
•  Direct: Development, testing, simple integrations, external APIs like Jira 
• Expected Value: 1/ Null  (1 For gateway execution) 

2.4.2 Parameter Validation 

The AI Agent automatically validates parameters before execution. 

Example 

{ 
  "parameters": ["customer_id", "mac_address", "issue_category"]
} 

Validation Rules 

• All listed parameters must be provided by the user 
•  AI Agent will ask user if parameters are missing 
•  Parameter names must match placeholder names exactly 
•  Extra parameters are ignored (no error) 

2.5 Complete Examples 

Example 1: Simple API GET with Path Parameter 

{ 
  "connections": [ 
    { 
      "id": 100, 
      "base_url": "https://api.weather.com", 
      "auth_type": "API_KEY", 
      "auth_credentials": { 
        "auth_placement": "header", 
        "api_headers": { 
          "X-API-Key": "your_weather_api_key" 
        } 
      } 
    } 
  ], 
  "commands": [ 
    { 
      "id": 1, 
      "connection_id": 100, 
      "name": "get_weather", 
      "description": "Get current weather for a city", 
      "parameters": ["city"], 
      "connector_type": "api", 
      "http_method": "GET", 
      "api_path": "/v1/weather/{{city}}", 
      "api_query_params": {}, 
      "api_body_template": {}, 
      "saws_id": null 
    } 
  ] 
} 

Usage: User says "What's the weather in London?" 

• AI Agent extracts `city = "London"` 
•  Calls: `GET https://api.weather.com/v1/weather/London` 

Example 2: API POST with Complex Body 

{ 
  "connections": [ 
    { 
      "id": 200, 
      "base_url": "https://api.crm.com", 
      "auth_type": "API_KEY", 
      "auth_credentials": { 
        "auth_placement": "header", 
        "credentials": { 
          "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." 
        } 
      } 
    } 
  ], 
  "commands": [ 
    { 
      "id": 2, 
      "connection_id": 200, 
      "name": "create_customer", 
      "description": "Create a new customer in the CRM system", 
      "parameters": ["first_name", "last_name", "email", "phone"], 
      "connector_type": "api", 
      "http_method": "POST", 
      "api_path": "/v2/customers", 
      "api_headers": { 
        "Content-Type": "application/json", 
        "Accept": "application/json" 
      }, 
      "api_query_params": {}, 
      "api_body_template": { 
        "customer": { 
          "name": { 
            "first": "{{first_name}}", 
            "last": "{{last_name}}" 
          }, 
          "contact": { 
            "email": "{{email}}", 
            "phone": "{{phone}}", 
            "preferred": "email" 
          }, 
          "status": "active", 
          "created_at": "{{uuid}}" 
        } 
      }, 
      "saws_id": null 
    } 
  ] 
}  

Example 3: Database Query with Multiple Parameters 

{ 
  "connections": [ 
    { 
      "id": 300, 
      "db_login": "report_user", 
      "db_password": "SecurePass123!", 
      "src_type": "PST", 
      "connection_string": "jdbc:postgresql://db.example.com:5432/analytics" 
    } 
  ], 
  "commands": [ 
    { 
      "id": 3, 
      "connection_id": 300, 
      "name": "get_customer_orders", 
      "description": "Retrieve all orders for a customer within a date range", 
      "parameters": ["customer_id", "start_date", "end_date"], 
      "connector_type": "jdbc", 
      "db_query": "SELECT order_id, order_date, total_amount, status FROM orders WHERE customer_id = {{customer_id}} AND order_date BETWEEN {{start_date}} AND {{end_date}} ORDER BY order_date DESC", 
      "saws_id": 1 
    } 
  ] 
}  

Example 4: Multiple Tools with Shared Connection 

{ 
  "connections": [ 
    { 
      "id": 400, 
      "base_url": "https://api.telecom.com", 
      "auth_type": "BASIC", 
      "auth_credentials": { 
        "auth_placement": "header", 
        "credentials": { 
          "username": "admin", 
          "password": "admin123" 
        } 
      } 
    } 
  ], 
  "commands": [ 
    { 
      "id": 10, 
      "connection_id": 400, 
      "name": "check_modem_status", 
      "description": "Check if customer's modem is online or offline", 
      "parameters": ["mac_address"], 
      "connector_type": "api", 
      "http_method": "GET", 
      "api_path": "/api/v1/modems/{{mac_address}}/status", 
      "api_query_params": {}, 
      "api_body_template": {}, 
      "saws_id": 1 
    }, 
    { 
      "id": 11, 
      "connection_id": 400, 
      "name": "reboot_modem", 
      "description": "Remotely reboot customer's modem", 
      "parameters": ["mac_address"], 
      "connector_type": "api", 
      "http_method": "POST", 
      "api_path": "/api/v1/modems/{{mac_address}}/reboot", 
      "api_headers": { 
        "Content-Type": "application/json" 
      }, 
      "api_query_params": {}, 
      "api_body_template": { 
        "action": "reboot", 
        "force": true 
      }, 
      "saws_id": 1 
    }, 
    { 
      "id": 12, 
      "connection_id": 400, 
      "name": "reset_modem_config", 
      "description": "Reset modem to factory settings", 
      "parameters": ["mac_address"], 
      "connector_type": "api", 
      "http_method": "POST", 
      "api_path": "/api/v1/modems/{{mac_address}}/reset", 
      "api_headers": { 
        "Content-Type": "application/json" 
      }, 
      "api_query_params": {}, 
      "api_body_template": { 
        "action": "factory_reset", 
        "preserve_settings": false 
      }, 
      "saws_id": 1 
    } 
  ] 
}  

Benefit: All three tools share the same authentication (connection 400).