Create a Tool in Gen AI Builder v1.3

Suggest edits

Prerequisite: Access to the Hybrid Manager UI with AI Factory enabled. See /edb-postgres-ai/1.3/hybrid-manager/ai-factory/.

Create a Tool in Gen AI Builder

This guide demonstrates deploying custom tools that enable AI assistants to interact with external systems, perform calculations, and execute business logic within Gen AI Builder.

Prerequisites

Required Components

  • Tool packaged as ZIP file containing implementation code and dependencies
  • Tool configuration file (YAML or Python format)
  • ZIP file uploaded to configured Data Lake bucket
  • Gen AI Builder access with appropriate permissions

Development Dependencies

  • Tool implementation using pgai-ai-builder SDK
  • External API credentials or database access (if applicable)
  • Testing environment for tool validation

Implementation Steps

1. Access Tool Management

Navigate to the Tools section within Gen AI Builder console.

2. Initialize Tool Creation

  1. Click Create Tool to begin the deployment process
  2. Select Griptape Tool from Data Lake as the creation method

3. Configure Tool Identity

Tool Name (Required)

  • Provide descriptive, unique identifier
  • Use clear naming convention: Organization_Category_Function
  • Example: PGAI_Financial_StockTicker

Description (Optional)

  • Document tool functionality and use cases
  • Include integration details and expected behavior
  • Example: Retrieves real-time stock prices from external financial API

4. Configure Data Lake Integration

Bucket Selection (Required)

  • Select Data Lake bucket containing your tool package
  • Verify bucket accessibility and permissions

Asset Path (Required)

  • Specify complete path to ZIP file within selected bucket
  • Path format: category/tool_name/package.zip
  • Example: financial_tools/stock_ticker/stock_ticker_v1.2.zip

5. Configure Tool Parameters

Tool Configuration File (Recommended)

  • Specify relative path within ZIP to configuration file
  • Standard configuration files: tool_config.yaml or config.py
  • Configuration defines tool parameters, validation rules, and execution settings

Example Configuration Structure:

# tool_config.yaml
name: "stock_ticker_tool"
version: "1.2.0"
description: "Retrieves stock market data"
parameters:
  - name: "symbol"
    type: "string"
    required: true
    description: "Stock ticker symbol"
  - name: "period"
    type: "string"
    default: "1d"
    options: ["1d", "5d", "1mo"]

6. Environment Configuration

Environment Variables Configure runtime environment for tool execution:

Individual Variable Configuration

  • Type: Select Variable (plain text) or Secret (encrypted storage)
  • Name: Environment variable identifier
  • Value: Configuration value or credential

Common Variable Examples:

API_KEY = your_api_key_here
BASE_URL = https://api.example.com
TIMEOUT_SECONDS = 30
RETRY_ATTEMPTS = 3

Bulk Import Option

  • Import multiple variables using .env file format
  • Paste complete .env file contents for batch configuration

7. Deploy Tool

Click Create to initiate deployment process.

Deployment Process:

  1. System validates ZIP file structure and contents
  2. Tool configuration parsing and validation
  3. Runtime environment preparation
  4. Tool registration in Gen AI Builder catalog

8. Verify Deployment

Post-Deployment Validation:

  • Tool appears in Tools catalog with Active status
  • Configuration parameters display correctly
  • Environment variables configured appropriately
  • Tool available for assistant assignment

Practical Example: Financial Exchange Rate Tool

Tool Package Structure

fx_rate_tool.zip
├── fx_rate_tool.py          # Tool implementation
├── requirements.txt         # Python dependencies
├── tool_config.yaml        # Tool configuration
└── README.md               # Documentation

Deployment Configuration

Basic Information:

  • Name: PGAI_Financial_FXRate
  • Description: Retrieves current foreign exchange rates from external API

Data Lake Configuration:

  • Bucket: pgai-financial-tools
  • Asset Path: fx_tools/fx_rate_tool_v2.1.zip
  • Config File: tool_config.yaml

Environment Variables:

FX_API_KEY = abcd1234-your-api-key-here
FX_API_URL = https://api.exchangerate-api.com/v4/latest
CACHE_DURATION = 300
MAX_RETRIES = 3

Tool Configuration File

name: "fx_rate_tool"
version: "2.1.0"
description: "Foreign exchange rate retrieval tool"
parameters:
  - name: "base_currency"
    type: "string"
    required: true
    description: "Base currency code (USD, EUR, etc.)"
  - name: "target_currency"
    type: "string"
    required: true
    description: "Target currency for conversion"
  - name: "amount"
    type: "number"
    default: 1.0
    description: "Amount to convert"

Troubleshooting

Deployment Issues

ZIP File Validation Errors

  • Verify ZIP file contains required implementation files
  • Confirm tool configuration file path accuracy
  • Validate Python dependency specifications in requirements.txt

Data Lake Access Problems

  • Verify bucket selection and permissions
  • Confirm asset path accuracy including file extension
  • Check Data Lake connectivity and authentication

Configuration Issues

Environment Variable Problems

  • Verify variable names match tool implementation expectations
  • Confirm Secret-type variables for sensitive credentials
  • Validate variable values and formatting

Tool Configuration Errors

  • Review configuration file syntax (YAML formatting)
  • Verify parameter definitions match tool implementation
  • Check required parameter specifications

Runtime Issues

Tool Execution Failures

  • Review tool logs in Gen AI Builder console
  • Validate external API endpoints and credentials
  • Verify network connectivity for external integrations
  • Check tool implementation error handling

Assistant Integration Problems

  • Confirm tool status shows as Active in catalog
  • Verify tool permissions and availability
  • Check assistant configuration for tool assignment

Best Practices

Tool Development

Implementation Guidelines

  • Develop tools as single-purpose, modular components
  • Implement comprehensive error handling and timeout management
  • Use pgai-ai-builder SDK for consistent interfaces and utilities
  • Include detailed logging for debugging and monitoring

Configuration Management

  • Externalize all credentials and API keys through environment variables
  • Use descriptive parameter names and comprehensive documentation
  • Implement parameter validation and default value handling
  • Version tool packages systematically for deployment tracking

Security Considerations

Credential Management

  • Store sensitive information using Secret-type environment variables
  • Rotate API keys and credentials regularly
  • Implement least-privilege access for external system integration
  • Monitor tool usage for unusual activity patterns

Access Control

  • Limit tool availability to appropriate user groups
  • Implement audit logging for tool execution tracking
  • Validate input parameters to prevent injection attacks
  • Use secure communication protocols for external API calls

Operational Excellence

Testing Procedures

  • Test tools independently before assistant integration
  • Validate functionality across expected input ranges
  • Verify error handling under various failure conditions
  • Monitor performance characteristics and resource utilization

Monitoring and Maintenance

  • Monitor tool execution logs and error rates
  • Track performance metrics and usage patterns
  • Plan regular updates for dependency management
  • Maintain version control for tool artifacts in Data Lake

SDK reference

Next Steps

After successful tool deployment:

  1. Test Tool Functionality
  • Use tool testing capabilities within Gen AI Builder
  • Validate parameter handling and response formatting
  • Verify error handling under various conditions
  1. Integrate with Assistants
  • Assign tool to appropriate assistants based on use cases
  • Configure tool usage policies through rulesets
  • Test assistant interactions with tool capabilities
  1. Monitor Performance
  • Track tool execution metrics and success rates
  • Monitor resource utilization and response times
  • Establish alerting for tool failures or performance degradation

Related Documentation

Implementation Resources

Integration Guides

← Prev

Create a Structure in Gen AI Builder

↑ Up

Gen AI Builder

Next →

Create an Assistant in Gen AI Builder