Create a Tool in Gen AI Builder

Suggest edits

Who is this for

Platform users building advanced AI-powered applications in Gen AI Builder in Hybrid Manager AI Factory. Typical users include developers, AI architects, and system integrators.

What you will accomplish

You will create a Tool in Gen AI Builder by deploying a packaged component that enables Assistants and Structures to perform specific actions.

Why create a Tool

  • Tools allow Assistants and Structures to:
  • Query external APIs.
  • Perform calculations.
  • Fetch live data.
  • Interact with databases and internal services.
  • Execute business logic.
  • Tools extend AI Factory capabilities beyond text generation — enabling true AI agents.

For background, see:

Complexity and time to complete

  • Complexity: Moderate
  • Estimated time: 10–20 minutes

When to create a Tool

  • When you want Assistants to fetch live data.
  • When AI agents need to query APIs or run business logic.
  • When building reusable components for multiple Assistants or Structures.
  • When implementing process automation or integration patterns.

Pre-requisites

  • Tool packaged as a Zip file:
  • Includes Tool code and dependencies.
  • Contains Tool configuration (typically YAML or Python).
  • Uploaded to your configured Data Lake.

How to create a Tool

1. Navigate to Tools

  • In Gen AI Builder UI, go to Tools.

2. Create a new Tool

  • Click Create Tool.

3. Select creation method

  • Choose Griptape Tool from Data Lake.

4. Configure Tool fields

Name (required)

  • Provide a clear, unique name.
  • Example: PG_Financial_Stock_Ticker

Description (optional)

  • Describe what the Tool does.
  • Example: Fetches live stock ticker prices from external API.

5. Configure Data Lake parameters

Bucket Id (required)

  • Select the Data Lake bucket where your Tool Zip file is stored.

Asset Path (required)

  • Provide the full path to your Zip file inside the selected bucket.
  • Example: tools/stock_ticker_tool.zip

6. Configure Tool Config parameters

  • Enter the relative path inside the Zip to your Tool Config file.
  • Example: tool_config.yaml

7. Configure environment variables (optional)

You can define environment variables that will be available to the Tool.

Add individual variables

  • Type: Variable or Secret.
  • Name: Example: STOCK_API_KEY
  • Value: Example: your_actual_api_key_here

Import .env file

  • Optionally paste contents of a .env file to bulk import variables.

8. Finalize creation

  • Click Create.

The system will:

  • Unzip your file.
  • Set up the runtime environment.
  • Make the Tool available in AI Factory.

9. Verify deployment

  • Your Tool will appear in the Tools list.
  • Monitor deployment status.
  • You can now:
  • Assign the Tool to Assistants.
  • Use the Tool in a Structure.
  • Test the Tool (if direct test is supported).

Example scenario: Deploy a PG Financial FX Rate Tool

  1. Package Griptape Tool FxRateTool.
  2. Upload to Data Lake:
  • Bucket: pgai-tools
  • Path: fx_rate_tool/fx_rate_tool.zip
  1. Create Tool:
  • Name: PG_Financial_FX_Rate_Tool
  • Description: Fetches live FX rates from external API.
  • Bucket Id: pgai-tools
  • Asset Path: fx_rate_tool/fx_rate_tool.zip
  • Tool Config File: tool_config.yaml
  1. Add env variables:
  • Name: FX_API_KEY
  • Value: your_key_here
  1. Click Create.

Next steps:

  • Test the Tool.
  • Assign the Tool to Assistants as needed.

Troubleshooting

Tool deploy fails

  • Verify Zip file contents:
  • Tool code is valid.
  • Tool Config file is present and correctly referenced.
  • Confirm the Data Lake path is correct and accessible.

Environment variables not working

  • Confirm variables are entered correctly.
  • If using Secrets, ensure Secrets are properly configured.

Tool not appearing for Assistant selection

  • Verify the Tool implements proper interface and is published.
  • Confirm the Tool status is active.

Tool errors at runtime

  • Review Tool logs in Gen AI Builder UI.
  • Verify external API endpoints and credentials.
  • Check Tool Config settings.

Best practices

  • Implement Tools as modular, single-responsibility components.
  • Externalize API keys and credentials via environment variables.
  • Implement robust error handling.
  • Test Tools in isolation before assigning to Assistants.
  • Monitor Tool usage and performance.
  • Version your Tool artifacts in Data Lake.

Related topics

← Prev

Create a Structure in Gen AI Builder

↑ Up

Gen AI How-To Guides

Next →

Configure an Atlassian Confluence data source

Could this page be better? Report a problem or suggest an addition!